Qdrant Model Migration

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 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 dimensions parameter 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 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
  • 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 UpdateVectors Update 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 UpdateVectors 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 dropping to 2s after removing ColBERT. Put large vectors on disk during side-by-side migration.

If you anticipate future model migrations, define both vector fields upfront at collection creation.