Embedding Functions

Default Embedding

ChromaDB uses a local Sentence Transformer model by default — no API key needed:

# Default: all-MiniLM-L6-v2 (384 dimensions)
collection = client.create_collection("docs")
collection.add(documents=["Hello world"], ids=["1"])

Using OpenAI Embeddings

from chromadb.utils.embedding_functions import OpenAIEmbeddingFunction

openai_ef = OpenAIEmbeddingFunction(
    api_key="your-key",
    model_name="text-embedding-3-small"
)

collection = client.create_collection(
    name="docs",
    embedding_function=openai_ef
)

Custom Embedding Functions

from chromadb import EmbeddingFunction

class MyEmbedding(EmbeddingFunction):
    def __call__(self, input: list[str]) -> list[list[float]]:
        # Your custom embedding logic
        return [embed(text) for text in input]

Choosing an Embedding Model

Common Pitfall: Inconsistent Embedding Functions

Once you add documents to a collection using a specific embedding function, you must use the same function for all future queries against that collection. ChromaDB does not store which embedding function was used, so there is no built-in guard against mismatched embeddings. Document the embedding function in a project README or config file.

Best Practice: Batch Embedding to Reduce API Cost

When adding large document sets, embed in batches rather than one at a time. The OpenAI embedding endpoint supports up to 2,048 inputs per request:

BATCH_SIZE = 500

for i in range(0, len(texts), BATCH_SIZE):
    batch = texts[i:i + BATCH_SIZE]
    response = openai.embeddings.create(
        model="text-embedding-3-small",
        input=batch,
    )
    embeddings = [item.embedding for item in response.data]
    collection.add(
        documents=batch,
        embeddings=embeddings,
        ids=[f"doc_{i + j}" for j in range(len(batch))],
    )

This pattern can reduce embedding API latency by 10x compared to one-at-a-time calls.

Named Product Reference: BGE Models by Beijing Academy of AI (BAAI)

The BAAI BGE (BERT General Embeddings) family — particularly BAAI/bge-large-en-v1.5 and BAAI/bge-m3 — are the best free embedding models available as of 2025. BGE-M3 supports over 100 languages and produces 1024-dimensional embeddings that rival OpenAI's paid models. You can load them via Hugging Face with ChromaDB's SentenceTransformerEmbeddingFunction — no API key required.