qdrant-model-migration
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.
qdrant · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add qdrant/skills --skill 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
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
textpayload index withscoringenabled on the payload field; Qdrant builds it from the stored payload 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 - Using Matryoshka models: use the
dimensionsparameter to output lower-dimensional embeddings (some recall loss, good for 100M+ datasets) - Changing quantization (binary to scalar): Qdrant re-quantizes automatically 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
-
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
- 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 - After validating completeness and quality, switch the query embedding model and
usingtogether; 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 - 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
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 directly to the existing collection Update vector schema
- Backfill new model embeddings incrementally using
UpdateVectorsUpdate vectors
-
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
- Migrate data from old collection, preserving existing vectors in the old named field
- Backfill new model embeddings incrementally using
UpdateVectorsUpdate vectors - Compare quality by querying with
using: "old_model"vsusing: "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,
阅读完整来源 ↗