qdrant-model-migration

更换嵌入模型时该怎么做

不同模型生成的向量互不兼容。你不能在同一向量空间中混合新旧嵌入。你也不能向现有集合添加新的命名向量字段。所有命名向量都必须在创建集合时定义。下面两种迁移策略都需要创建新集合。

• 在选择策略前先了解集合别名 集合别名

我能避免重新嵌入吗？

适用场景：在开始完整迁移前寻找捷径。

以下情况必须重新嵌入：更换模型提供商（OpenAI 换成 Cohere）、更换架构（CLIP 换成 BGE）、不同模型之间维度数不兼容，或向仅密集向量的集合添加稀疏向量。

以下情况可以避免重新嵌入：使用 Matryoshka 模型（使用 dimensions 参数输出更低维度的嵌入，从样本数据学习线性变换，会有一定召回损失，适合 1 亿以上的数据集）。或者更改量化方式（二值改为标量）：Qdrant 会自动重新量化。量化

需要零停机（别名切换）

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

• 使用新模型的维度和距离度量创建新集合
• 在后台将所有数据重新嵌入到新集合
• 让应用指向集合别名，而不是直接的集合名称
• 原子地将别名切换到新集合 切换集合
• 验证搜索质量，然后删除旧集合

注意，别名切换只会重定向查询。载荷必须单独重新上传。

需要两个模型同时在线（并排运行）

适用场景：对模型进行 A/B 测试、多模态（密集 + 稀疏），或在正式采用前评估新模型。

你不能向现有集合添加命名向量。创建一个同时预先定义好两个向量字段的新集合：

• 创建新集合，同时定义好旧的和新的命名向量 包含多个向量的集合
• 从旧集合迁移数据，将现有向量保留在旧的命名字段中
• 使用 UpdateVectors 增量回填新模型的嵌入 更新向量
• 通过用 using: "old_model" 与 using: "new_model" 查询来比较质量
• 满意后将别名切换到新集合

将大型多向量（尤其是 ColBERT）与密集向量放在一起会降低所有查询的质量，即使是只使用密集向量的查询。在数百万个点规模下，有用户报告延迟从 13 秒降到移除 ColBERT 后的 2 秒。在并排迁移期间，将大型向量放到磁盘上。

如果你预计未来会有模型迁移，请在创建集合时预先定义好两个向量字段。

从密集检索迁移到混合搜索

适用场景：向现有的仅密集向量集合添加稀疏/BM25 向量。这是最常见的迁移模式。

你不能向现有的仅密集向量集合添加稀疏向量。必须重新创建：

• 创建新集合，同时定义好密集和稀疏向量配置
• 使用密集和稀疏模型重新嵌入所有数据
• 迁移载荷，切换别名

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

重新嵌入太慢

适用场景：数据集很大，重新嵌入是瓶颈。

• 使用 update_mode: insert（v1.17+）进行安全的幂等迁移 更新模式
• 使用 with_vectors=False 遍历旧集合，分批重新嵌入，再 upsert 到新集合
• 并行分批上传（每请求 64-256 个点，2-4 个并行流） 批量上传
• 批量加载期间禁用 HNSW（将 indexing_threshold_kb 设得很高，之后恢复）
• 对于 Qdrant Cloud 推理，切换模型是配置变更，而不是流水线变更 推理文档

对于 400GB+ 的数据集，预计需要数天。对于小数据集（<25MB），从源重新索引比使用迁移工具更快。

不要做什么

• 假设你可以向现有集合添加命名向量（必须在创建时定义）
• 在验证新集合之前删除旧集合
• 忘记在应用代码中更新查询嵌入模型
• 使用别名交换时跳过 payload 迁移（别名重定向查询，它们不复制数据）
• 在长时间迁移期间将 ColBERT 向量与稠密向量放在一起（I/O 开销会降低所有查询的性能）
• 在未测试 chunk 级别 BM25 质量的情况下迁移到混合搜索