Versioning Embeddings and Indexes

A common mistake in RAG is assuming your vector index is static. If you update your embedding model (e.g., from OpenAI v2 to OpenAI v3), your old vectors are incompatible. You must re-index.

The Rule of One Model

A single collection in your database must only contain vectors from the same model. If you mix them, your search results will be random noise.

Versioning Strategy

1. Naming Versions

Always include the model and version in your index name: docs_openai-v3_chunk-500_v1

2. Dual-Indexing (Migration)

During a migration:

1. Keep v1 running for production.
2. Build v2 in the background with the new model.
3. Once v2 is ready, switch the API pointer.
4. Delete v1 to reclaim storage.

The "Model-Lock" Problem

If you used a proprietary model (like text-embedding-ada-002) and that model is deprecated by the provider, your index is dead. Long-term Strategy: Use open-source local models (like Nomic or BGE) for mission-critical archives, as you control the model binary and can always regenerate vectors.

Schema Versioning

If you add a new metadata field (e.g., is_verified), you should increment your index version and backfill the data.

Exercises

1. What happens if you try to compare a 1024-dim vector with a 1536-dim vector?
2. How do you "version" a multimodal index where both an image model and a text model were used?
3. Design a "Migration Script" that moves data from a Chroma collection to an OpenSearch collection.