Versioning Embeddings

In this lesson, you will learn how to maintain search consistency and application reliability when upgrading the embedding models that power your vector database.

The Challenge of Model Drift

When you switch from an old embedding model (e.g., text-embedding-ada-002) to a new one (e.g., text-embedding-3-large), the resulting vector spaces are mathematically incompatible. You cannot compare an embedding vector from Model A with one from Model B; doing so will result in "garbage" similarity scores that break your retrieval features.

Maintaining Consistency

To handle this transition without downtime, you must treat your embeddings as versioned artifacts. Simply overwriting your existing database will result in a period where your index contains a mix of "stale" and "new" vectors.

The standard architectural pattern is to store the Model Version ID as metadata alongside every embedding. When performing a query, your application logic must look up the correct embedding model to use for the user's query vector based on the database version.

-- Schema design for versioned embeddings
CREATE TABLE document_vectors (
    id UUID PRIMARY KEY,
    content TEXT,
    embedding VECTOR(1536),
    model_version VARCHAR(50), -- Identifies the embedding generation
    created_at TIMESTAMP
);

-- Querying only the current, active version
SELECT id, cosine_similarity(embedding, $query_vec) 
FROM document_vectors 
WHERE model_version = 'v2.0.0'
ORDER BY 1 DESC;

The Migration Strategy

When rolling out a new model version, follow these three steps:

1. Dual-Write: Update your ingestion pipeline to compute embeddings using both the old and new models. Store both vectors in the database (or in separate collections/tables).
2. Backfill: Run an asynchronous job to re-process your existing document corpus with the new model, updating the model_version tag for those rows.
3. Cutover: Once the backfill is complete, update your application layer to point to the new model version for all search operations, and eventually deprecate the old vectors to reclaim storage space.

By versioning your embeddings, you prevent "semantic mismatch," ensuring that your vector search results remain mathematically sound and contextually accurate as your machine learning models evolve.

Key Takeaway: Never mix embedding versions in a single search space; always associate every vector with a metadata version tag to ensure mathematical compatibility and facilitate safe model migrations.