Reindex documents when an embedding model changes
Embeddings produced by different model configurations should not be assumed comparable. A vector with the same number of dimensions can still encode text in a different space. Switching only the query model can therefore leave a corpus index that returns plausible-looking but unsuitable matches.
For a synthetic handbook migration, keep two named index versions. Version A contains document vectors created with configuration A, and version B contains vectors created with configuration B. Route each query to the matching query encoder and document index.
Record the exact model identifier or revision, dimensionality and preprocessing configuration with each version. Include any query-versus-document encoding mode required by the chosen model.
The Sentence Transformers semantic-search guide explains matching query and corpus representations in the same space. pgvector's documentation describes storing and searching vectors, while model-version routing remains an application concern.
Old and new model indexes with an explicit cutover.
Build the replacement before switching traffic
Take a consistent source snapshot and encode all its active authorized chunks into B. Keep source IDs and revisions attached so A and B results can be compared. Verify missing records, unexpected dimensions and failed ingestion jobs before considering B ready.
Run the fixed question set against both versions. Compare returned source IDs and supporting passages, then measure latency and resource usage under a representative workload. A successful migration job says nothing about answer quality by itself.
Source updates can arrive during the backfill. Decide whether to pause ingestion briefly, replay an update log into B or maintain both indexes until they catch up. Record the source revision at which the new index becomes complete.
Keep rollback and cache scope explicit
Change one routing configuration to activate B only after it is ready. Retain A for a defined rollback period if policy and storage allow it. An error response should never silently search the other index using a mismatched query vector.
Response caches need the index version in their identity. Otherwise the first query after a migration can display an answer generated from old evidence. Cached query embeddings need the encoding configuration too.
Test a partial backfill, a model-loading failure and a request arriving while routing changes. Each should resolve to a complete coherent index version or an explicit error.
This article proposes a migration procedure; it does not compare particular embedding models or claim an improvement. Exact model loading, tokenizer limits and vector-index behavior must be checked for the selected versions before running the migration. Matching dimensions is a useful validation check, but it cannot establish semantic compatibility.