Qdrant Model Migration

Qdrant model migration

Choose a safe Qdrant collection migration strategy when embedding vectors change, because vectors from different models are incompatible and named vectors must be defined when a collection is created.

When to invoke

• "How do I switch embedding models in Qdrant without downtime?"
• "Can I use two embedding models at once?"
• "Migrate this collection from dense to hybrid search."
• "Re-embed my Qdrant data after changing providers."
• "A/B test old and new vectors in Qdrant."

Core constraints

Strategy map

Re-embedding decision

Migration procedures

Zero downtime with alias swap

1. Create a new collection with the new model dimensions and distance metric.
2. Re-embed all source data into the new collection in the background.
3. Point the application at a collection alias instead of a direct collection name.
4. Atomically switch the alias to the new collection.
5. Verify search quality and latency.
6. Delete the old collection only after rollback is no longer needed.

Side-by-side models

1. Create a new collection with both old and new vector fields defined upfront.
2. Migrate data from the old collection and preserve existing vectors in the old named field.
3. Backfill new embeddings incrementally using UpdateVectors.
4. Compare quality by querying with using: "old_model" versus using: "new_model".
5. Swap the alias to the new collection when satisfied.

Use the same side-by-side shape for multi-modal experiments that combine dense and sparse vectors. You MUST still create the target collection before adding those named vectors.

Large dataset tuning

• Use update_mode: insert for safe idempotent migration when supported.
• Upload in parallel batches of 64-256 points per request with 2-4 parallel streams.
• Disable HNSW during bulk load by setting indexing_threshold_kb very high, then restore it after ingestion.
• Expect days for 400GB+ datasets.
• For small datasets under 25MB, re-indexing from source is faster than using a migration tool.

Gotchas

• Do not delete the old collection before verification: alias rollback is only possible while the old collection still exists.
• Do not forget the application embedder: queries must switch to the new embedding model when the alias points at the new vector space.
• Payloads are not copied by aliases: migrate payloads explicitly.
• Chunk-level sparse vectors behave differently: BM25 and TF-IDF quality can shift, especially for non-English text without stop-word removal.
• ColBERT can dominate I/O: users have reported millions-of-points latency dropping from 13s to 2s after removing co-located ColBERT vectors.

Output template

## Qdrant model migration plan

**Status:** planned | needs data | blocked
**Current collection:** `<name>`
**Target strategy:** zero-downtime alias swap | side-by-side | dense-to-hybrid | re-index from source

### Compatibility
| Check | Result | Evidence |
| --- | --- | --- |
| Model/provider changed | yes/no | <details> |
| Dimensions changed | yes/no | <old -> new> |
| Named vectors required | yes/no | <fields> |
| Sparse vectors added | yes/no | <dense/sparse config> |

### Steps
1. <collection creation or alias step>
2. <re-embedding/backfill step>
3. <verification and rollback step>

### Risks
- <payload migration, latency, ColBERT, BM25, or rollback risk>

Quality gate

• The plan states whether re-embedding is required and why.
• The plan creates a new collection for model replacement, named-vector additions, or dense-to-hybrid migration.
• Alias use includes payload migration, verification, rollback, and delayed old-collection deletion.
• Side-by-side plans define both vector fields at collection creation and use UpdateVectors for backfill.
• Large migrations include batch size, parallel stream, and indexing_threshold_kb guidance.
• Search quality is verified before the alias switch is considered final.

References

• Collection aliases
• Switch collection
• Collection with multiple vectors
• Update vectors
• Update mode
• Quantization
• Bulk upload
• Inference docs