# Batch embedding (efficient)
texts = ["text1", "text2", "text3"]
response = client.embeddings.create(
    model="text-embedding-3-small",
    input=texts
)
vectors = [item.embedding for item in response.data]

Model Selection

Model	Dims	Cost	Use Case
`text-embedding-3-small`	1536	$0.02/1M	General purpose
`text-embedding-3-large`	3072	$0.13/1M	High accuracy
`nomic-embed-text` (Ollama)	768	Free	Local/CI

Chunking Strategy

def chunk_text(text: str, chunk_size: int = 512, overlap: int = 50) -> list[str]:
    """Split text into overlapping chunks for embedding."""
    words = text.split()
    chunks = []

    for i in range(0, len(words), chunk_size - overlap):
        chunk = " ".join(words[i:i + chunk_size])
        if chunk:
            chunks.append(chunk)

    return chunks

Guidelines:

Chunk size: 256-1024 tokens (512 typical)
Overlap: 10-20% for context continuity
Include metadata (title, source) with chunks

Similarity Calculation

import numpy as np

def cosine_similarity(a: list[float], b: list[float]) -> float:
    """Calculate cosine similarity between two vectors."""
    a, b = np.array(a), np.array(b)
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

# Usage
similarity = cosine_similarity(vector1, vector2)
# 1.0 = identical, 0.0 = orthogonal, -1.0 = opposite

Key Decisions

Dimension reduction: Can truncate text-embedding-3-large to 1536 dims
Normalization: Most models return normalized vectors
Batch size: 100-500 texts per API call for efficiency

Common Mistakes

Embedding queries differently than documents
Not chunking long documents (context gets lost)
Using wrong similarity metric (cosine vs euclidean)
Re-embedding unchanged content (cache embeddings)

Advanced Patterns

See references/advanced-patterns.md for:

Late Chunking: Embed full document, extract chunk vectors from contextualized tokens
Batch API: Production batching with rate limiting and retry
Embedding Cache: Redis-based caching to avoid re-embedding
Matryoshka Embeddings: Dimension reduction with text-embedding-3

Related Skills

rag-retrieval - Using embeddings for RAG pipelines
hyde-retrieval - Hypothetical document embeddings for vocabulary mismatch
contextual-retrieval - Anthropic's context-prepending technique
reranking-patterns - Cross-encoder reranking for precision
ollama-local - Local embeddings with nomic-embed-text

Capability Details

text-to-vector

Keywords: embedding, text to vector, vectorize, embed text Solves:

Convert text to vector embeddings
Choose appropriate embedding models
Handle embedding API integration

semantic-search

Keywords: semantic search, vector search, similarity search, find similar Solves:

Implement semantic search over documents
Configure similarity thresholds
Rank results by relevance

chunking-strategies

Keywords: chunk, chunking, split, text splitting, overlap Solves:

Split documents into optimal chunks
Configure chunk size and overlap
Preserve semantic boundaries

batch-embedding

Keywords: batch, bulk embed, parallel embedding, batch processing Solves:

Embed large document collections efficiently
Handle rate limits and retries
Optimize embedding costs

local-embeddings

Keywords: local, ollama, self-hosted, on-premise, offline Solves:

Run embeddings locally with Ollama
Deploy self-hosted embedding models
Reduce API costs with local models

embeddings

Embeddings

Quick Reference