embeddings-expert

Files (2)

• SKILL.md
• metadata.json

SKILL.md (first lines)

# Embeddings Expert

## When to Use
- Building semantic search or similarity matching
- Setting up RAG (Retrieval-Augmented Generation) retrieval
- Clustering or classifying text by meaning
- Choosing an embedding model for a project
- Computing cosine similarity between texts
- Chunking documents for embedding

## Core Rules
1. Normalize embeddings before computing cosine similarity — most libraries return unnormalized vectors.
2. Choose embedding dimensions based on your use case: 384 (fast/small), 768 (balanced), 1536+ (high quality).
3. Chunk documents before embedding — embedding a 10k-word doc produces one vector that loses detail.
4. Match your embedding model at query time — never mix embeddings from different models.
5. For RAG, embed chunks at index time; embed queries at request time using the same model.
6. Use `sentence-transformers` locally for free, private embeddings; use APIs for managed/scalable embedding.
7. Cosine similarity ranges from -1 to 1; semantic matches are typically > 0.7 for same-topic content.
8. Hybrid search (BM25 + embeddings) outperforms either alone — use BM25 for keyword recall.
9. Store embeddings as `float32` arrays; quantize to `int8` only if storage is critical.
10. Batch embed large document sets — single-item API calls are wasteful at scale.

## Embedding Model Comparison

| Model | Provider | Dimensions | Max Tokens | Notes |
|-------|----------|-----------|------------|-------|
| `text-embedding-3-small` | OpenAI | 1536 | 8191 | Good default, cheap |
| `text-embedding-3-large` | OpenAI | 3072 | 8191 | Best OpenAI quality |
| `text-embedding-ada-002` | OpenAI | 1536 | 8191 | Legacy, use 3-small instead |
| `nomic-embed-text` | Ollama (local) | 768 | 8192 | Free, good quality |
| `mxbai-embed-large` | Ollama (local) | 1024 | 512 | High quality local |
| `all-MiniLM-L6-v2` | sentence-transformers | 384 | 256 | Fast, tiny, good |
| `all-mpnet-base-v2` | sentence-transformers | 768 | 384 | Best sentence-transformers |
| `BAAI/bge-large-en-v1.5` | sentence-transformers | 1024 | 512 | Top open-source quality |

## OpenAI Embeddings (Python)

```python
from openai import OpenAI
import numpy as np

client = OpenAI()  # Uses OPENAI_API_KEY env var

def embed_text(text: str, model: str = "text-embedding-3-small") -> list[float]:
    """Embed a single text string."""
    text = text.replace("\n", " ")  # Normalize newlines
    response = client.embeddings.create(input=text, model=model)
    return response.data[0].embedding

def embed_batch(texts: list[str], model: str = "text-embedding-3-small") -> list[list[float]]:
    """Embed multiple texts in one API call."""
    texts = [t.replace("\n", " ") for t in texts]
    response = client.embeddings.create(input=texts, model=model)
    # Results are in order
    return [item.embedding for item in sorted(response.data, key=lambda x: x.index)]

# Usage
embedding = embed_text("The quick brown fox jumps over the lazy dog")
print(f"Dimensions: {len(embedding)}")  # 1536

batch = embed_batch(["Hello world", "Goodbye world", "Python is great"])
print(f"Batch size: {len(batch)}, dims: {len(batch[0])}")
```

## Sentence-Transformers (Local, Free)

```python
from sentence_transformers import SentenceTransformer
import numpy as np

# Load model (downloads automatically on first use, cached locally)
model = SentenceTransformer("all-MiniLM-L6-v2")       # 384-dim, fast
# model = SentenceTransformer("all-mpnet-base-v2")    # 768-dim, better
# model = SentenceTransformer("BAAI/bge-large-en-v1.5")  # 1024-dim, best

# Single embedding
embedding = model.encode("Hello world")  # numpy array
print(f"Shape: {embedding.shape}")  # (384,)

# Batch embedding (much faster than one-by-one)
texts = ["First document", "Second document", "Third document"]
embeddings = model.encode(texts, batch_size=32, show_progress_bar=True)
print(f"Shape: {embeddings.shape}")  # (3, 384)

# Normalize for cosine similarity
from sentence_transformers import util
embeddings_normalized = model.encode(texts, normalize_embeddings=True)
```

## Ollama Embeddings (Local)

```python
import requests
import numpy as np

def embed_ollama(text: str, model: str = "nomic-embed-text") -> list[float]:
    response = requests.post(
        "http://localhost:11434/api/embeddings",
        json={"model": model, "prompt": text}
    )
    return response.json()["embedding"]

def embed_ollama_batch(texts: list[str], model: str = "nomic-embed-text") -> list[list[float]]:
    return [embed_ollama(t, model) for t in texts]

embedding = embed_ollama("Hello world")
print(f"Dimensions: {len(embedding)}")  # 768 for nomic-embed-text
```

## Cosine Similarity

```python
import numpy as np
from typing import Union

def cosine_similarity(a: list[float], b: list[float]) -> float:
    """Compute cosine similarity between two embedding vectors."""
    a = np.array(a, dtype=np.float32)
    b = np.array(b, dtype=np.float32)

From UltronCore/claude-skill-vault, MIT.

More from UltronCore/claude-skill-vault