更换嵌入模型时如何无停机迁移 Qdrant 向量数据

在 Qdrant 中切换嵌入模型、升级维度或新增稀疏向量时，实现零停机或双模型并行的迁移。

适用场景

解决思路

1. 先判断是否必须重新嵌入：更换模型提供商（如 OpenAI 换 Cohere）、更换架构（如 CLIP 换 BGE）、维度不兼容、或给纯稠密集合加稀疏向量时，必须重新嵌入。
2. 可避免重新嵌入的情况：使用 Matryoshka 模型时用 `dimensions` 参数输出低维嵌入，或从样本数据学习线性变换（有召回损失，适合 1 亿+ 数据集）；仅更换量化方式（如 binary 换 scalar）时 Qdrant 会自动重新量化。
3. 零停机迁移（v1.18+ 且集合使用命名向量）：直接在现有集合上添加新向量字段，用 `UpdateVectors` 在后台重新嵌入全部数据，验证搜索质量后删除旧向量字段。
4. 零停机迁移（v1.17 或更早，或集合无命名向量）：创建使用新模型维度和距离度量的新集合，后台重新嵌入全部数据到新集合，应用指向集合别名而非直接集合名，原子切换别名到新集合，验证搜索质量后删除旧集合。
5. 注意别名切换只重定向查询，payload 必须单独重新上传。
6. 双模型并行（v1.18+）：直接在现有集合上添加新向量字段，用 `UpdateVectors` 增量回填新模型嵌入。
7. 双模型并行（v1.17 或更早）：创建新集合时同时定义新旧两个命名向量，从旧集合迁移数据并保留旧命名字段中的现有向量，用 `UpdateVectors` 增量回填新模型嵌入，用 `using: "old_model"` 与 `using: "new_model"` 查询对比质量，满意后切换别名到新集合。
8. 并行迁移时把大向量（尤其 ColBERT）放到磁盘上，避免与稠密向量共置导致所有查询延迟恶化。
9. 若预期未来还会迁移模型，在创建集合时就预先定义好两个向量字段。
10. 稠密转混合搜索迁移：创建同时定义稠密和稀疏向量配置的新集合，用稠密和稀疏模型重新嵌入全部数据，迁移 payload 并切换别名。
11. 若集合已使用命名稠密向量且为 v1.18+，可直接添加稀疏向量字段而无需重建集合。
12. 重新嵌入太慢时：使用 `update_mode: insert`（v1.17+）实现安全幂等迁移；用 `with_vectors=False` 滚动旧集合，分批重新嵌入后 upsert 到新集合；并行分批上传（每请求 64-256 个点，2-4 个并行流）；批量加载期间禁用 HNSW（把 `indexing_threshold_kb` 设得很高，之后恢复）。
13. Qdrant Cloud inference 下切换模型只是配置变更，不是流水线变更。
14. 400GB+ 数据集预计需要数天；小于 25MB 的小数据集直接从源重新索引比用迁移工具更快。

适用边界 · 注意事项

• 不要假设在 v1.17 或更早的服务器上能给现有集合添加命名向量，先检查服务器版本。
• 不要在验证新集合之前删除旧集合。
• 不要忘记更新应用代码中的查询嵌入模型。
• 使用别名切换时不要跳过 payload 迁移（别名只重定向查询，不复制数据）。
• 长时间迁移期间不要让 ColBERT 向量与稠密向量共置（I/O 开销会拖慢所有查询）。
• 不要在未测试 chunk 级别 BM25 质量的情况下迁移到混合搜索。