qdrant-model-migration

更换嵌入模型时该怎么做

不同模型生成的向量彼此不兼容。你不能在同一向量空间中混用新旧嵌入。在 v1.18 及更高版本中，你可以在现有集合中添加或删除具名向量字段，因此迁移不再总是需要新建集合。在 v1.17 及更早版本中，必须在创建集合时定义所有具名向量。

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

可以避免重新生成嵌入吗？

适用场景：在决定进行完整迁移前，寻找捷径。

以下情况必须重新生成嵌入：更换模型提供商（从 OpenAI 切换到 Cohere）、更换架构（从 CLIP 切换到 BGE），或切换到维度数不同的模型。

以下情况无需为现有稠密向量重新生成嵌入：

• 在 v1.20 及更高版本中添加 BM25 以支持混合搜索：无需生成向量。在载荷字段上创建启用了 scoring 的 text 载荷索引；Qdrant 会根据存储的载荷构建索引 BM25 评分
• 添加稀疏向量以支持混合搜索：只需生成稀疏向量。在 v1.18 及更高版本中，将稀疏字段添加到现有集合，并使用 UpdateVectors 填充该字段。在 v1.17 及更早版本中，将稠密向量复制到新集合，而不是重新计算 更新向量
• 使用 Matryoshka 模型：使用 dimensions 参数输出较低维度的嵌入（召回率会略有损失，适合 1 亿条以上的数据集）
• 更改量化方式（从二值量化改为标量量化）：Qdrant 会自动重新量化 量化

需要零停机

适用场景：生产环境必须保持可用。建议在大规模更换模型时使用。

• 回填前启用双写，并保留点 ID。对写入任一目标失败的操作进行重试和对账 迁移工作流

• 如果集群版本为 v1.18 或更高，且集合使用了命名向量：

  • 直接向现有集合添加新的向量字段 更新向量架构
  • 对新写入的数据同时写入两种嵌入；仅使用 UpdateVectors 回填新字段。先暂停对现有点的更新和删除，并清空正在处理的操作；或者实现冲突处理，以防止回填写入过时数据 命名向量迁移
  • 验证完整性和质量后，同时切换查询嵌入模型和 using；别名无法选择向量字段

• 如果集群版本为 v1.17 或更低，或集合未使用命名向量：

  • 使用新模型的维度和距离度量创建新集合
  • 将实时写入的 upsert 同时写入两个集合；使用 update_mode: insert_only（v1.17+）回填嵌入和负载，以保留已实时写入的点。暂停删除和部分更新，或进行对账，以防回填使已删除的数据复活 蓝绿迁移
  • 让应用指向集合别名，而不是直接使用集合名称
  • 交换别名前，验证完整性和质量；协调查询模型的切换，确保请求使用匹配的向量空间 切换集合

在观察期内保持双写，以便回滚。只有在所有读取方都已切换且不再需要回滚后，才停用旧向量或集合。别名会重定向请求，但不会复制负载。

需要两种模型同时运行（并行使用）

适用场景：对模型进行 A/B 测试、处理多模态数据（稠密向量 + 稀疏向量），或在采用新模型前进行评估。

对于正在使用的集合，请遵循 需要零停机 中的写入一致性和切换保护措施。

• 如果集群版本为 v1.18 或更高：

  • 直接向现有集合添加新的向量字段 更新向量架构
  • 使用 UpdateVectors 逐步回填新模型的嵌入 更新向量

• 如果集群版本为 v1.17 或更低：无法向现有集合添加命名向量。创建新集合，并预先定义两个向量字段：

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

将大型多向量（尤其是 ColBERT）与稠密向量放在一起，会降低所有查询的性能，即使是仅使用稠密向量的查询也会受影响。在数百万个点的规模下，有用户反馈称，移除 ColBERT 后，延迟从 13s 降至 2s。并行迁移期间，请将大型向量存储在磁盘上。

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

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

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

• 如果集群版本为 v1.20 或更高，且文本存储在载荷中，优先使用全文索引上的 BM25，而不是稀疏向量：在文本字段上创建启用 scoring 的 text 索引（并设置对应语言的词干提取器和停用词），再在稠密查询旁添加一个 text 查询预取。无需更改架构、回填向量或使用 avg_len，且适用于任何创建时间的集合。大型集合重新索引可能需要一段时间 基于全文索引的 BM25

• 如果集群版本为 v1.19 或更早，或者文本未存储在载荷中，请使用以下稀疏向量选项。

• 如果集群版本为 v1.18 或更高，可直接添加稀疏向量字段，即使稠密向量未命名也可以 更新向量架构

  • 为现有点生成稀疏向量，并使用 UpdateVectors 回填；现有稠密向量保持不变 更新向量

• 如果集群版本为 v1.17 或更早，则无法向现有集合添加稀疏向量。请重新创建集合：

  • 创建同时定义稠密和稀疏向量配置的新集合
  • 使用 with_vectors=True 滚动读取旧集合，以复制稠密向量，并仅生成稀疏向量
  • 迁移载荷，切换别名

块级稀疏向量和全文 BM25 统计数据与文档级数据具有不同的 TF-IDF 特征。迁移后请测试检索质量，尤其是未移除停用词的非英语文本。

重新嵌入速度太慢

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

• 对新集合回填时使用 update_mode: insert_only（v1.17+）；它会跳过目标集合中已有的点，因此在向现有点添加嵌入时，不能替代 UpdateVectors 更新模式
• 使用 with_vectors=False 滚动读取旧集合，分批重新嵌入，然后写入新集合
• 以并行批次上传（每个请求 64-256 个点，使用 2-4 个并行流）批量上传
• 对于 Qdrant Cloud 推理，切换模型只需更改配置，而无需更改管道 推理文档

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

不要这样做

• 不要假设可以在 v1.17 或更早版本的服务器上向现有集合添加具名向量；请先检查服务器版本
• 验证、读者切换和回滚观察期结束前，不要删除旧向量或集合
• 不要假设仅靠双写或 insert_only 就能解决并发删除和部分更新问题
• 不要忘记在应用代码中更新查询嵌入模型
• 使用别名切换时，不要跳过载荷迁移（别名只会重定向请求，不会复制数据）
• 长时间迁移期间，不要将 ColBERT 向量与稠密向量放在一起（I/O 开销会降低所有查询的性能）
• 迁移到混合搜索时，不要跳过块级 BM25 质量测试