Embeddings Cheatsheet: Models, Metrics, Chunking and Cost

# Hosted providers
pip install openai cohere voyageai

# Local / OSS
pip install sentence-transformers      # CPU/GPU, huggingface
pip install fastembed                  # ONNX runtime, no torch
pip install "ollama"                   # client for local Ollama server

# Plumbing
pip install numpy tiktoken

# Env
export OPENAI_API_KEY=sk-...
export COHERE_API_KEY=...
export VOYAGE_API_KEY=...

from openai import OpenAI

client = OpenAI()

# Single
resp = client.embeddings.create(
    model="text-embedding-3-small",
    input="The quick brown fox",
)
vec = resp.data[0].embedding   # list[float], dim=1536

# Batched — much cheaper than a loop
resp = client.embeddings.create(
    model="text-embedding-3-small",
    input=["doc one", "doc two", "doc three"],
)
vecs = [d.embedding for d in resp.data]

# Matryoshka — truncate to a smaller dim
short = client.embeddings.create(
    model="text-embedding-3-large",
    input="hello",
    dimensions=512,         # 3072 → 512, preserves quality
).data[0].embedding

from sentence_transformers import SentenceTransformer

model = SentenceTransformer("BAAI/bge-small-en-v1.5")

# Encode — returns np.ndarray of shape (n, dim)
vecs = model.encode(
    ["query text", "another doc"],
    batch_size=64,
    normalize_embeddings=True,   # cosine ≈ dot product
    show_progress_bar=False,
)

# Asymmetric retrieval: prefix queries (model-specific)
q_vec = model.encode(
    "Represent this sentence for searching: what is RAG?",
    normalize_embeddings=True,
)

# Move to GPU
model = SentenceTransformer("BAAI/bge-large-en-v1.5", device="cuda")

import numpy as np

def cosine(a, b):
    a, b = np.asarray(a), np.asarray(b)
    return float(np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b)))

def dot(a, b):
    return float(np.dot(np.asarray(a), np.asarray(b)))

def euclidean(a, b):
    a, b = np.asarray(a), np.asarray(b)
    return float(np.linalg.norm(a - b))

# Top-k over a corpus matrix (rows = normalized vectors)
def top_k(query, matrix, k=5):
    q = np.asarray(query)
    scores = matrix @ q              # dot == cosine when normalized
    idx = np.argpartition(-scores, k)[:k]
    return idx[np.argsort(-scores[idx])], scores[idx]

from openai import OpenAI
import numpy as np

client = OpenAI()
MODEL = "text-embedding-3-small"   # 1536 dim, $0.02 / 1M tokens

def embed(texts: list[str]) -> np.ndarray:
    resp = client.embeddings.create(model=MODEL, input=texts)
    arr = np.array([d.embedding for d in resp.data], dtype=np.float32)
    return arr / np.linalg.norm(arr, axis=1, keepdims=True)   # normalize

# 1. Build the corpus
corpus = [
    "FastAPI is a Python web framework for building APIs.",
    "Ollama runs LLMs locally on your machine.",
    "Embeddings map text to dense vectors.",
]
M = embed(corpus)

# 2. Query → vector
q = embed(["how do I run a model locally?"])[0]

# 3. Top-k by cosine (== dot when normalized)
scores = M @ q
top = np.argsort(-scores)[:2]
for i in top:
    print(f"{scores[i]:.3f}  {corpus[i]}")