Embedding versioning
Re-embedding · Embedding model migration
Tracking which model and settings produced each stored vector, so that changing the embedding model re-embeds the corpus instead of mixing incompatible vectors.
In DocSlurpGlossary entry
On this page
Embedding versioning means recording exactly how every stored vector was made, so the system never compares vectors from different recipes. The recipe is more than the model name: provider, model version, dimensions, pooling, normalization, quantization of the weights and any text added before embedding (a prefix or a contextual preamble) all change the vectors.
Why it matters: each model defines its own embedding space. Suppose growth-plan-2027.pdf was embedded last year with model A, and you switch the project to model B. New queries are embedded with B and compared against A’s vectors. If both models output 1,024 numbers, nothing errors: the database accepts the query, returns the “nearest” vectors, and they are effectively random. Search quietly gets worse and nobody gets an alert.
The safe pattern:
- Store a fingerprint of the full recipe with every vector, or keep one index per recipe.
- Embed queries with the recipe of the index being searched, never a global default.
- When the recipe changes, re-embed into a new index, switch reads over when it is complete, then drop the old one.
- Reuse vectors only when the fingerprint and the exact input text both match. Unchanged chunks then cost nothing to re-index.
The gotchas: small setting changes count. Switching from mean to CLS pooling, turning off normalization or truncating dimensions creates a new space even with the same model weights. A provider can also update a model behind the same name, so pin versions where the provider allows it. And re-embedding a large corpus takes time and money, so budget for it before changing models, and evaluate the new model on your own queries first.
In DocSlurp
In DocSlurp
Vectors are stored per project, model and dimensions (core/packages/shared/src/vector-namespace.ts). Reuse keys hash a fingerprint of runtime, provider, model, endpoint, dimensions, task, normalization and dtype with the exact input (core/worker/src/embeddings/embedding-reuse.ts), and an embedding config change reruns the embed stage.