Embeddings & Similarity

Embeddings convert text into fixed-size vectors where semantic similarity corresponds to geometric closeness. They power semantic search, clustering, and RAG retrieval.

Recipe

Quick-reference recipe card - copy-paste ready.

from openai import OpenAI
import numpy as np
 
client = OpenAI()
emb = client.embeddings.create(model="text-embedding-3-small", input=["query text"])
vec = np.array(emb.data[0].embedding)
 
# cosine similarity
def cosine(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

When to reach for this:

• Semantic search over documents, code, or support articles.
• Clustering or deduplicating text content.
• RAG retrieval step before LLM generation.
• Recommendation systems based on text similarity.

Working Example

"""embeddings_similarity.py - embed, index, and search documents."""
from __future__ import annotations
 
import numpy as np
from openai import OpenAI
 
client = OpenAI()
MODEL = "text-embedding-3-small"
 
documents = [
    "FastAPI is a modern Python web framework for building APIs.",
    "PyTorch is a deep learning framework with dynamic computation graphs.",
    "pandas 2.2 provides DataFrame operations for tabular data analysis.",
    "pytest is the standard testing framework for Python projects.",
]
 
def embed_texts(texts: list[str]) -> np.ndarray:
    response = client.embeddings.create(model=MODEL, input=texts)
    vectors = [item.embedding for item in response.data]
    arr = np.array(vectors, dtype=np.float32)
    norms = np.linalg.norm(arr, axis=1, keepdims=True)
    return arr / norms  # L2 normalize for cosine via dot product
 
doc_embeddings = embed_texts(documents)
 
query = "How do I test my Python code?"
query_vec = embed_texts([query])[0]
 
scores = doc_embeddings @ query_vec  # cosine similarity (normalized)
ranked = sorted(zip(scores, documents), reverse=True)
for score, doc in ranked:
    print(f"{score:.3f}  {doc}")

What this demonstrates:

• Batch embedding with OpenAI text-embedding-3-small.
• L2 normalization so dot product equals cosine similarity.
• Ranking documents by relevance to a natural language query.
• Semantic match: "test Python code" ranks pytest highest.

Deep Dive

How It Works

• Embedding model encodes text into a fixed-dimension vector (e.g., 1536).
• Similar texts produce vectors with high cosine similarity.
• Normalization (L2) makes dot product equivalent to cosine similarity.
• Vector index (FAISS, pgvector) enables fast nearest-neighbor search at scale.
• Same model must be used for indexing and querying.

Embedding Models

Python Notes

# Local embeddings with sentence-transformers
from sentence_transformers import SentenceTransformer
model = SentenceTransformer("all-MiniLM-L6-v2")
vectors = model.encode(documents, normalize_embeddings=True)

Gotchas

• Mixing embedding models - different models produce incompatible vector spaces. Fix: one model per index; re-embed all documents on model change.
• Not normalizing vectors - dot product without normalization is not cosine similarity. Fix: L2-normalize before indexing and search.
• Embedding very long texts - models have token limits; long docs get truncated. Fix: chunk documents before embedding.
• Comparing across different dimensions - 384-dim vs 1536-dim vectors cannot be compared. Fix: consistent model and dimension.
• Ignoring embedding cost at scale - embedding millions of docs adds up. Fix: cache embeddings; batch requests; use smaller models.
• Keyword search expectation - embeddings miss exact keyword matches. Fix: hybrid search (embeddings + BM25).

Alternatives

FAQs

client.embeddings.create(model="text-embedding-3-small", input=texts, dimensions=512)

Related

• RAG Basics - retrieval pipeline
• Vector Databases - storage and search
• Chunking & Ingestion - document splitting
• OpenAI & Other SDKs - embedding API
• Retrieval & Re-ranking - hybrid search

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.