/qdrant-model-migration

name: qdrant-model-migration
description: "Guides embedding model migration in Qdrant without downtime. Use when someone asks 'how to switch embedding models', 'how to migrate vectors', 'how to update to a new model', 'zero-downtime model change', 'how to re-embed my data', or 'can I use two models at once'. Also use when upgrading model dimensions, switching providers, or A/B testing models."

What to Do When Changing Embedding Models

Vectors from different models are incompatible. You cannot mix old and new embeddings in the same vector space. On v1.18+, you can add or delete named vector fields on an existing collection — migration no longer always requires a new collection. On v1.17 or earlier, all named vectors must be defined at collection creation time.

• Understand collection aliases before choosing a strategy [Collection aliases](https://skills.qdrant.tech/md/documentation/manage-data/collections/?s=collection-aliases)

Can I Avoid Re-embedding?

Use when: looking for shortcuts before committing to full migration.

You MUST re-embed if: changing model provider (OpenAI to Cohere), changing architecture (CLIP to BGE), or switching to a model with a different dimension count.

You do NOT need to re-embed existing dense vectors if:

• Adding BM25 for hybrid search on v1.20+: no vectors to generate. Create a `text` payload index with `scoring` enabled on the payload field; Qdrant builds it from the stored payload [BM25 scoring](https://skills.qdrant.tech/md/documentation/manage-data/indexing/?s=bm25-scoring)
• Adding sparse vectors for hybrid search: generate only the sparse vectors. On v1.18+, add the sparse field to the existing collection and backfill it with `UpdateVectors`. On v1.17 or earlier, copy the dense vectors into the new collection instead of recomputing them [Update vectors](https://skills.qdrant.tech/md/documentation/manage-data/points/?s=update-vectors)
• Using Matryoshka models: request lower-dimensional embeddings from the same model (the provider's parameter, such as OpenAI's `dimensions`, or `mrl` in `options` on Qdrant Cloud Inference). Some recall loss, good for 100M+ datasets [Matryoshka models](https://skills.qdrant.tech/md/documentation/inference/matryoshka-models/)
• Changing quantization (binary to scalar): Qdrant re-quantizes automatically [Quantization](https://skills.qdrant.tech/md/documentation/manage-data/quantization/)

Need Zero Downtime

Use when: production must stay available. Recommended for model replacement at scale.

• Enable dual writes before backfill, preserving point IDs. Retry and reconcile failed writes to either destination [Migration workflow](https://skills.qdrant.tech/md/documentation/tutorials-operations/embedding-model-migration/)

• If the cluster is v1.18 or later AND the collection has named vectors:

• Add the new vector field directly to the existing collection [Update vector schema](https://skills.qdrant.tech/md/documentation/manage-data/collections/?s=update-vector-schema)
• Write both embeddings on incoming upserts; backfill only the new field with `UpdateVectors`. Pause updates/deletes to existing points and drain in-flight operations first, or implement conflict handling to prevent stale backfill [Named-vector migration](https://skills.qdrant.tech/md/documentation/tutorials-operations/embedding-model-migration/?s=migrate-using-named-vectors)
• After validating completeness and quality, switch the query embedding model and `using` together; an alias cannot select a vector field

• If the cluster is v1.17 or earlier OR the collection doesn't have named vectors:

• Create a new collection with the new model's dimensions and distance metric
• Dual-write live upserts to both collections; backfill embeddings and payloads with `update_mode: insert_only` (v1.17+) to preserve points already written live. Pause deletes/partial updates or reconcile them so backfill cannot resurrect deleted data [Blue-green migration](https://skills.qdrant.tech/md/documentation/tutorials-operations/embedding-model-migration/?s=blue-green-migration)
• Point your application at a collection alias instead of a direct collection name
• Validate completeness and quality before swapping the alias; coordinate the query-model change so requests use the matching vector space [Switch collection](https://skills.qdrant.tech/md/documentation/manage-data/collections/?s=switch-collection)

Keep dual writes through an observation period for rollback. Retire old vectors or collections only after all readers switch and rollback is no longer needed. Aliases redirect requests; they do not copy payloads.

Need Both Models Live (Side-by-Side)

Use when: A/B testing models, multi-modal (dense + sparse), or evaluating a new model before committing.

For a live collection, apply the write-consistency and cutover safeguards in **Need Zero Downtime**.

• If the cluster is v1.18 or later: add the new vector field to the existing collection and backfill it with `UpdateVectors`, as in the v1.18 branch of **Need Zero Downtime**.

• If the cluster is v1.17 or earlier: You cannot add a named vector to an existing collection. Create a new collection with both vector fields defined upfront:

• Create new collection with old and new named vectors both defined [Collection with multiple vectors](https://skills.qdrant.tech/md/documentation/manage-data/collections/?s=collection-with-multiple-vectors)
• Migrate data from old collection, preserving existing vectors in the old named field
• Backfill new model embeddings incrementally using `UpdateVectors` [Update vectors](https://skills.qdrant.tech/md/documentation/manage-data/points/?s=update-vectors)
• Compare quality by querying with `using: "old_model"` vs `using: "new_model"`
• Swap alias to new collection once satisfied

Co-locating large multi-vectors (especially ColBERT) with dense vectors degrades ALL queries, even those only using dense. At millions of points, users report 13s latency