qdrant-model-migration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

What to Do When Changing Embedding Models

更换Embedding模型时的操作指南

Vectors from different models are incompatible. You cannot mix old and new embeddings in the same vector space. You also cannot add new named vector fields to an existing collection. All named vectors must be defined at collection creation time. Both migration strategies below require creating a new collection.

Understand collection aliases before choosing a strategy Collection aliases

不同模型生成的向量互不兼容。你不能在同一个向量空间中混合使用新旧Embedding，也无法向已存在的Collection中添加新的命名字段。所有命名向量必须在Collection创建时就完成定义，下文介绍的两种迁移策略都需要创建新的Collection。

选择策略前请先了解Collection别名机制 Collection别名

Can I Avoid Re-embedding?

我可以避免重新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), incompatible dimension counts across different models, or adding sparse vectors to dense-only collection.

You CAN avoid re-embedding if: using Matryoshka models (use

dimensions

parameter to output lower-dimensional embeddings, learn linear transformation from sample data, some recall loss, good for 100M+ datasets). Or changing quantization (binary to scalar): Qdrant re-quantizes automatically. Quantization

适用场景：在决定执行全量迁移前想要寻找捷径方案。

出现以下情况时你必须重新Embedding：更换模型提供商（比如从OpenAI切换到Cohere）、更换模型架构（比如从CLIP切换到BGE）、不同模型的向量维度互不兼容，或者要向仅支持稠密向量的Collection中添加稀疏向量。

出现以下情况时你可以避免重新Embedding：使用Matryoshka模型（可通过

dimensions

参数输出更低维度的Embedding，从样本数据中学习线性变换，会存在少量召回率损失，适合1亿条以上的数据集）。或者更改量化方式（比如从二值量化切换为标量量化）：Qdrant会自动执行重新量化。量化

Need Zero Downtime (Alias Swap)

需要零停机迁移（别名切换方案）

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

Create a new collection with the new model's dimensions and distance metric
Re-embed all data into the new collection in the background
Point your application at a collection alias instead of a direct collection name
Atomically swap the alias to the new collection Switch collection
Verify search quality, then delete the old collection

Careful, the alias swap only redirects queries. Payloads must be re-uploaded separately.

适用场景：生产环境必须保持可用，推荐用于大规模模型替换场景。

按照新模型的维度和距离度量指标创建新的Collection
在后台将所有数据重新Embedding后写入新Collection
将你的应用请求指向Collection别名，而非直接指向Collection名称
原子化地将别名切换到新Collection 切换Collection
验证搜索质量符合预期后，删除旧的Collection

请注意，别名切换仅会重定向查询请求，Payload需要单独重新上传。

Need Both Models Live (Side-by-Side)

需要两个模型同时运行（并行部署方案）

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

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.

适用场景：对模型进行A/B测试、多模态场景（稠密+稀疏向量），或者在正式切换前评估新模型效果。

你无法向已有的Collection中添加命名向量，需要预先创建同时定义了两种向量字段的新Collection：

创建同时定义了新旧命名向量的新Collection 多向量Collection
从旧Collection迁移数据，将现有向量保留在旧命名字段中
使用
```
UpdateVectors
```
接口增量回填新模型生成的Embedding 更新向量
通过分别指定
```
using: "old_model"
```
和
```
using: "new_model"
```
查询，对比两个模型的效果
效果符合预期后将别名切换到新Collection

将大型多向量（尤其是ColBERT）与稠密向量共同存储会降低所有查询的性能，哪怕是仅使用稠密向量的查询也会受影响。有用户反馈在百万级数据规模下，移除ColBERT后查询延迟从13秒下降到2秒。并行迁移期间请将大型向量存储在磁盘上。

如果你预计未来会进行模型迁移，可以在创建Collection时就预先定义好两种向量字段。

Dense to Hybrid Search Migration

从稠密搜索迁移到混合搜索

Use when: adding sparse/BM25 vectors to an existing dense-only collection. Most common migration pattern.

You cannot add sparse vectors to an existing dense-only collection. Must recreate:

Create new collection with both dense and sparse vector configs defined
Re-embed all data with both dense and sparse models
Migrate payloads, swap alias

Sparse vectors at chunk level have different TF-IDF characteristics than document level. Test retrieval quality after migration, especially for non-English text without stop-word removal.

适用场景：向现有的仅支持稠密向量的Collection中添加稀疏/BM25向量，这是最常见的迁移模式。

你无法向已有的仅支持稠密向量的Collection中添加稀疏向量，必须重建Collection：

创建同时定义了稠密和稀疏向量配置的新Collection
使用稠密和稀疏两种模型对所有数据重新Embedding
迁移Payload，切换别名

Chunk级别的稀疏向量和文档级别的稀疏向量具有不同的TF-IDF特征，迁移后请测试检索质量，尤其是针对未做停用词移除的非英文文本。

Re-embedding Is Too Slow

重新Embedding速度过慢

Use when: dataset is large and re-embedding is the bottleneck.

Use
```
update_mode: insert
```
(v1.17+) for safe idempotent migration Update mode
Scroll the old collection with
```
with_vectors=False
```
, re-embed in batches, upsert into new collection
Upload in parallel batches (64-256 points per request, 2-4 parallel streams) Bulk upload
Disable HNSW during bulk load (set
```
indexing_threshold_kb
```
very high, restore after)
For Qdrant Cloud inference, switching models is a config change, not a pipeline change Inference docs

For 400GB+ datasets, expect days. For small datasets (<25MB), re-indexing from source is faster than using the migration tool.

适用场景：数据集过大，重新Embedding成为迁移瓶颈。

（v1.17及以上版本）使用
```
update_mode: insert
```
实现安全的幂等迁移更新模式
使用
```
with_vectors=False
```
参数遍历旧Collection，分批重新Embedding后写入新Collection
并行批量上传（每个请求包含64-256条数据，2-4个并行流）批量上传
批量写入期间禁用HNSW索引（将
```
indexing_threshold_kb
```
设置为极高的值，写入完成后恢复）
如果你使用Qdrant Cloud的推理服务，切换模型仅需要修改配置，无需修改推理流水线推理文档

400GB以上的数据集预计需要数天时间完成迁移。对于小于25MB的小型数据集，从源数据重新索引比使用迁移工具速度更快。

What NOT to Do

禁止操作

Assume you can add named vectors to an existing collection (must be defined at creation time)
Delete the old collection before verifying the new one
Forget to update the query embedding model in your application code
Skip payload migration when using alias swap (aliases redirect queries, they do not copy data)
Keep ColBERT vectors co-located with dense vectors during a long migration (I/O cost degrades all queries)
Migrate to hybrid search without testing BM25 quality at chunk level

假设你可以向已存在的Collection中添加命名向量（命名向量必须在创建时定义）
在验证新Collection可用性之前删除旧Collection
忘记更新应用代码中的查询Embedding模型
使用别名切换时跳过Payload迁移（别名仅重定向查询，不会复制数据）
长期迁移期间将ColBERT向量和稠密向量放在一起存储（I/O开销会降低所有查询的性能）
未测试Chunk级别的BM25效果就迁移到混合搜索