Embedding Model Migration and Reindexing

An embedding-model migration changes the representation used by retrieval. Treat it as a coordinated data and query migration: document vectors, query vectors, preprocessing, index settings, evaluation, and routing must remain compatible throughout the transition.

Start by defining a representation version that covers more than the model name. Include model revision, dimensions, normalization, chunking, preprocessing, and any relevant query/document modes. Equal dimensions permit arithmetic, but they do not establish that two models use the same meaningful coordinate space.

TL;DR

Quick Example

This complete Python illustration rotates a fictional two-dimensional representation. Old-to-old and new-to-new cosine scores are one, while an old document compared with a new query scores zero despite matching dimensions. Inputs are nonzero vectors.

The arithmetic and fictional cutover-gate assertions passed. No real embedding model, corpus, index, vector service, live query, migration, or rollback was exercised. The gate checks declared fields only; it does not prove evaluation quality or data freshness.

Core Concepts

Representation compatibility

The example demonstrates why shape validation is weaker than semantic compatibility. A vector database can accept matching dimensions without knowing whether document and query vectors came from compatible preprocessing and models.

Separate collections or representations

Qdrant documents dimension/metric constraints and named-vector options. Those are storage capabilities; the application must choose meaningful representation boundaries and query routing. Collection structure

Routing cutover

Qdrant also documents collection aliases and atomic alias operations, useful for changing the collection behind a name. Atomic alias change does not coordinate every application cache, query encoder, or source-data write. Collection aliases

Define the migration manifest

This manifest is an editorial planning structure, not a database API. Use it to expose the assumptions a simple model-name change would hide.

Record document and query encoders separately when the model requires different prefixes or modes. Keep chunking and normalization changes visible too: a ranking difference may come from a new document boundary rather than the neural model alone.

Use stable source and chunk identities with a clear revision policy. If identifiers change during re-chunking, document how old records are reconciled and how deletions propagate. Counts alone can match while the wrong chunks remain.

Do not assume unrelated raw similarity scores are directly comparable. If results from several representations are combined, choose and evaluate a suitable ranking/fusion approach under the actual task. Simply concatenating scores can favor whichever system happens to emit larger numbers.

Backfill while preserving source changes

Choose an approved source snapshot or revision boundary for the initial backfill. Track progress and failures without silently skipping difficult documents. A partially generated index needs an explicit query policy.

Plan how updates and deletions during backfill reach the candidate representation. A change stream, bounded replay, dual processing, or a controlled pause can be appropriate in different systems. Define the authoritative source, ordering, deduplication, and reconciliation rather than prescribing one universal zero-downtime recipe.

Keep writes idempotent under stable operation or content identity where the actual storage supports that design. A worker retry should not create duplicate chunks or revive content that was deleted after the initial snapshot.

Check readiness at the retrieval boundary: vectors accepted by an ingestion API may still be unavailable to the intended query path or missing required payload/filter fields. Verify indexing and query behavior under the deployed system’s documented semantics.

Protect content and permissions during migration. A candidate index should not expose restricted documents merely because it is labeled staging. Preserve access filters and handling of removed or changed authorization data.

Evaluate and coordinate the switch

Use an approved representative query set with expected useful results or task outcomes. Include rare terms, long queries, important languages, changed content, restricted content, and known difficult cases where relevant. Keep evaluation data independent enough to avoid tuning only to a small familiar set.

Measure more than one aggregate relevance score. Examine critical slices, latency, embedding/serving cost, error rates, and downstream answer or task quality. A higher average can conceal a damaging regression for a required audience.

Shadow or pilot traffic only under the appropriate data and operational policy. Sending a query to a second provider or index can change its data flow and cost. Use approved sources and destinations rather than assuming evaluation traffic is exempt from handling rules.

Coordinate the query encoder and index routing. An atomic alias operation can switch one database reference while application instances still use old encoders. Version requests or deploy compatible routing so each query reaches the intended representation.

Keep rollback data current for the promised rollback window. Retaining yesterday’s old index is not a complete recovery plan after today’s content changes. Rehearse the actual switch, failure detection, and reversal in an approved environment before relying on it.

Best Practices

Version the full representation

Record model revision, preprocessing, dimensions, metric, chunking, and query/document modes. Use that identity in generation and routing.

Reconcile coverage and changes

Verify source revisions, deletions, failed items, and query readiness. Do not use equal counts as the only integrity check.

Test cutover and rollback

Exercise compatible query/index pairing and current fallback data. Evaluate meaningful slices before expanding traffic.

Common Mistakes

Bad: Equal dimensions mean vectors are interchangeable.

Correct: Verify representation compatibility and retrieval behavior; shape alone does not establish meaning.

Bad: An atomic alias switch completes the migration.

Correct: Coordinate query encoders, application instances, caches, writes, and recovery data.

Bad: Keeping the old collection guarantees rollback.

Correct: Maintain its required freshness, permissions, routing compatibility, and tested reversal procedure.

FAQ

Must every migration use a second collection?

No. Choose a supported representation strategy that preserves compatibility, isolation, evaluation, and recovery. A second collection is one useful option.

Can scores from two models be mixed directly?

Do not assume their scales or semantics align. Evaluate an appropriate normalization or fusion method for the actual retrieval task.

Did the example migrate an index?

No. It checks fictional vector arithmetic and declared readiness fields without any model or service interaction.

Related Topics

References