Why must a Chroma collection keep the same embedding_function for its whole life?

## Vectors are only comparable within one model An embedding model is a learned map from text into a space of a few hundred to a few thousand dimensions. The space has no external meaning: the axes are whatever training produced, and two independently trained models put the same sentence in unrelated places. Similarity search works because *all* the vectors being compared came out of the same map, so proximity in that space corresponds to similarity in meaning. The moment a collection contains vectors from two different maps, that property is gone. A query embedded by model B is compared against records embedded by model A, and the ranking that comes back is not "less accurate" — it is meaningless, driven by incidental geometry rather than semantics. This is why a Chroma collection's embedding function is effectively part of its identity, not a runtime option. ## Why Chroma cannot catch it for you Chroma validates one structural property: dimensionality. The first write fixes the collection's vector width, and later writes that disagree are rejected with a dimension-mismatch error. That check is coarse. - **Dimensions differ** (384 vs 1536): you get a hard failure on the next write or query. This is the good outcome — the system stops and tells you. - **Dimensions match** (two different 384-dimension models, or two revisions of one model): every call succeeds. The index accepts the vectors, queries return results, distances come back as plausible-looking numbers. Nothing in the API surface hints that half your corpus is unreachable. The only symptom is that retrieval quality degrades, which you will discover through user complaints or an evaluation set, not a stack trace. The second case is the one that reaches production, and it is why "the collection has one embedding function, forever" is treated as a rule rather than a guideline. ## How the function gets attached You pass it at creation: ``` get_or_create_collection(name="docs", embedding_function=ef) ``` If you pass nothing, Chroma attaches its default — an ONNX build of `all-MiniLM-L6-v2` at 384 dimensions. That default is a genuine trap in older code: a script that created the collection with `OpenAIEmbeddingFunction` and a later script that fetched it without naming a function used to end up with two different functions on one collection, with no error if the dimensions lined up. Current Chroma closes that hole by persisting the embedding-function configuration as part of the collection, so obtaining the collection later reconstructs the same function rather than silently defaulting. For built-in functions this works out of the box. A **custom** embedding function has to be serializable for this to hold — Chroma's `EmbeddingFunction` interface exposes a `name()`, a `get_config()` and a `build_from_config()` for exactly this purpose. A hand-rolled class that only implements `__call__(self, input)` still works when you pass the instance explicitly, but it is not something Chroma can rebuild from stored configuration, so you must keep passing it. Either way, the safe habit is to construct the embedding function in exactly one place in your codebase and have every path — ingestion, query service, backfill job, notebook — import that one object. The failure mode is not a bad line of code; it is two files that each look correct in isolation. ## Same model name is not the same model Even pinning the model *name* is not always enough. A hosted embedding endpoint can be revised behind a stable name, and a locally cached model can differ between a laptop and a container image. Recording the model identifier (and, where you have it, a version or revision) in the collection's metadata costs nothing and turns "which model produced these vectors?" from archaeology into a lookup. ## Detecting a mixed collection There is no built-in audit. The practical detections are behavioural: - Keep a small golden set of queries with known-good expected documents and run it after any ingestion or deployment. A mixed collection tanks it immediately. - Watch the distance distribution of top results. Vectors from a foreign model tend to sit at distances clustered differently from native ones, so a sudden shift in the score profile is a signal. - Compare `count()` against the number of documents you believe you embedded with the current function. ## The correct response Once a collection is mixed, there is no in-place repair worth attempting: you cannot tell from the stored data which vector came from which model. The fix is to re-embed from your source of truth into a fresh collection. This is precisely why the original text should live somewhere you can replay — an object store, a database, a document pipeline — rather than only inside Chroma.