Embedding 版本升级后旧向量是否必须重建

Embedding 版本升级后，旧向量通常不能直接“混着用”。只要模型变了，或者同一模型的输出维度、距离度量、文本切片方式发生了不兼容变化，就应把原始文本重新嵌入到新的向量空间；不能把新查询向量拿去和旧向量硬比。只有在服务方明确保证同一向量空间、维度和度量契约不变时，才可能继续复用旧索引。

官方资料入口：https://developers.openai.com/api/docs/guides/embeddings

如果使用 Qdrant，可参考：https://qdrant.tech/documentation/tutorials-operations/embedding-model-migration/

先判断：变化的是模型，还是向量空间契约

“版本升级”不是一个足够准确的判断条件。先把下面几项写成索引元数据：模型标识、输出维度、距离度量、文本归一化方式、切片规则和语言处理方式。模型升级即使维度碰巧相同，也可能改变文本在空间中的相对位置；维度不同则更直接，旧集合的向量字段通常无法接收新长度的数组。

以 OpenAI 的 Embeddings API 为例，文档说明第三代模型支持用 dimensions 缩短输出；即使长度被缩短，输出仍默认做 L2 归一化。这个事实只能帮助你选择度量，不能证明不同模型或不同维度的结果属于同一个可混检空间。

把原始文本和质量基线留在迁移边界外

重建的起点应是原始文本或可确定重放的规范化内容，而不是把旧向量再次加工。先保存每条记录的稳定 ID、正文哈希、切片规则版本、旧模型配置、维度、距离度量、元数据和更新时间。没有原文时，迁移只能复制旧向量，无法完成真正的换模型重嵌入。

同时冻结一组代表性查询，记录旧索引的 top-k、空结果比例、人工相关性或离线指标。Qdrant 的迁移指南也把向量数量、元数据样本、集合配置和基线查询结果列为迁移前应保存的内容。示意性的记录结构如下：

migration_record = {
    # 用同一份原文重放新旧向量，避免把旧向量当作输入
    "document_id": "doc-001",
    "content_sha256": "...",
    "chunking_version": "kb-v3",
    "old_embedding": {"model": "old-model", "dimensions": 1536, "distance": "cosine"},
    "new_embedding": {"model": "new-model", "dimensions": 3072, "distance": "cosine"},
    # 质量比较必须复用固定查询集，而不是临时挑好看的结果
    "baseline_query_set": "eval-2026-09",
}

生产迁移优先选双写，而不是一次性覆盖旧索引

线上写入先进入一个“新旧都能更新”的适配层。新增文档、正文修改和删除都要有明确语义：更新必须同时刷新两边，删除不能只删新集合，否则切换后会出现幽灵文档。后台回填则读取原文，调用新模型生成向量，再写入新字段或新集合。

如果向量库支持命名向量，可以在同一个集合增加例如 embedding_new 的向量定义，完成双写和回填后让查询使用新名字。Qdrant 文档把这种方式描述为：新增向量定义不会自动填充已有点，旧向量保留期间回滚更简单；但它要求集合原本采用命名向量，并且新向量必须逐点补齐。

如果现有集合是单一匿名向量，双集合蓝绿结构更稳妥：documents_v1 继续服务查询，documents_v2 使用新维度和新度量。路由层只保存当前读版本，切换时变更一个受控配置，不要让业务代码到处拼集合名。

def write_document(doc, old_store, new_store, embed_old, embed_new):
    # 同一稳定 ID 写入两套空间，避免新旧集合的文档集合发生漂移
    old_store.upsert(doc.id, embed_old(doc.text), payload=doc.payload)
    new_store.upsert(doc.id, embed_new(doc.text), payload=doc.payload)

def delete_document(doc_id, old_store, new_store):
    # 删除也必须成对执行，否则切换后可能召回已删除内容
    old_store.delete(doc_id)
    new_store.delete(doc_id)

回填完成后还要做灰度、切换和回滚

回填过程要可暂停、可续跑，并记录游标或批次状态。每批写入后至少核对 ID 数量、原文哈希、向量维度和元数据；遇到限流或单条失败时记录失败 ID，不能用“任务进度到 100%”代替数据核对。

当新空间达到覆盖率后，用冻结的查询集做影子检索或小流量灰度。比较的不是单一相似度数字，而是 top-k 重合度、人工相关性、空结果、重复结果、过滤条件、延迟和错误率。新索引未达到阈值时继续让旧版本服务；达到阈值后切换读路由，并保留旧版本一段观察期。任何异常都只需把路由指回旧版本，不要立刻删除旧向量。

最后才清理旧字段或旧集合。清理前确认：所有写入路径已经只保留新版本、删除补偿已经完成、回滚窗口结束、备份可恢复，并且新集合的计数和元数据抽样仍与源数据一致。重建索引的真正完成标准，是空间契约、数据完整性和检索质量都通过，而不是“向量已经重新生成”。

常见问题

只改了 dimensions 参数，也必须重建吗？

通常需要。输出长度变了，索引字段的维度契约已经变更；即使模型相同，也应把原文按新参数重新生成并写入兼容的新字段或集合。

模型名变了但维度相同，可以直接复用旧索引吗？

不能仅凭维度相同做结论。除非服务方明确保证向量空间兼容，否则按新空间处理，并用固定查询集验证后再切换。

没有保存原始文本怎么办？

先不要贸然覆盖旧索引。没有原文就无法可靠地按新模型重嵌入，应先从主数据库、对象存储或向量 payload 中恢复生成向量所需的规范化内容。

为什么双写后新索引仍然召回不到结果？

命名向量或新集合刚创建时可能还没有填充旧点；检查回填覆盖率、查询是否指定新向量名、维度和距离度量是否匹配，以及更新和删除是否同时落到两边。