Embedding 模型更换后如何先校验向量维度再迁移数据

更换 embedding 模型时，最先要确认的不是模型名字，而是它对同一段文本实际返回的向量长度。新旧模型只要维度不同，就不能把新向量直接写进旧集合或旧索引；即使维度相同，也还要确认距离度量、归一化方式和模型版本。稳妥做法是“测真实输出、写元数据、建双索引、小批量回填、最后切流”。

官方资料：https://huggingface.co/docs/

先用代表性文本读出新旧模型的真实维度

Sentence Transformers 将句子映射为固定长度向量，Hugging Face 的官方示例也直接通过编码结果的 shape 展示维度。这个维度属于模型输出契约，不是业务表可以自动“适配”的普通字段。迁移前至少准备标题、短句、长段落和包含中英文的样本，分别调用两个编码器。

from sentence_transformers import SentenceTransformer

# 用相同样本比较两个编码器，避免只凭模型名称判断维度。
texts = ["向量检索需要稳定的模型边界", "embedding migration"]
old_model = SentenceTransformer("old-model-id")
new_model = SentenceTransformer("new-model-id")

old_vectors = old_model.encode(texts, normalize_embeddings=True)
new_vectors = new_model.encode(texts, normalize_embeddings=True)

# shape 的第二项就是每条向量的维度；不一致就停止写入旧集合。
old_dim = int(old_vectors.shape[1])
new_dim = int(new_vectors.shape[1])
if old_dim != new_dim:
    raise ValueError(f"维度不兼容: old={old_dim}, new={new_dim}")

# 归一化方式和距离度量也要与索引配置保持一致。
print({"old_dim": old_dim, "new_dim": new_dim, "metric": "cosine"})

示例中的模型 ID 只是占位符，实际项目应替换成已经批准的模型仓库名。若新模型只返回 token 级 hidden states，还需要明确 pooling 规则，不能把三维张量直接当成句向量。

把模型版本、维度和距离度量写进数据边界

向量库的集合、索引或字段通常会固定维度。与其把这些信息藏在脚本参数里，不如为每个版本保存一份元数据，例如 embedding_model、embedding_dim、metric、normalized 和 created_at。写入端先比较元数据，查询端也按同一个版本读取。

这里的关键不是多存几个字段，而是让错误尽早暴露：当回填脚本拿到维度 768 的向量，却准备写入维度 1536 的集合时，应在入口处失败，而不是等检索结果悄悄变差。

回填时保留双索引，不让新向量覆盖旧链路

建议给新模型建立独立的索引版本，例如 docs_v2，并让每一批文档带上相同的版本标记。先回填少量文档，检查空文本、超长文本、编码失败、重复重试和查询返回为空等情况。小批量验证通过后再扩大范围，旧索引在整个过程中保持可读。

双索引并不意味着两个结果要强行混排。迁移验证阶段可分别查询并记录召回样本；切换阶段只让路由选择一个明确版本。若新模型改变了语义空间，旧向量和新向量的相似度分数也不宜直接横向比较。

验证通过后再切换查询路由并保留回滚点

最终切换至少要同时改三处：文档写入使用的新编码器、查询使用的新编码器、检索目标的新索引。三者若版本不一致，会出现“写入成功但查不到”或“查询维度错误”。把版本标识作为配置的一部分发布，回滚时恢复旧路由和旧编码器，而不是临时改一个模型名。

可以用一份清单收尾：新旧维度已记录；metric 与归一化规则一致；新索引可独立查询；失败批次可重放；查询和写入版本相同；旧索引仍可回滚。确认这些条件后，再逐步增加回填比例。

常见问题

维度相同就能直接替换模型吗？

不能。还要比较 pooling、归一化、距离度量、最大输入长度和语义效果；维度相同只代表存储形状兼容。

能不能在原向量字段上直接回填？

不建议。新旧模型的空间可能不同，直接覆盖会让同一集合混入两种语义，且无法可靠回滚。

为什么要先做小批量回填？

它能把空文本、超长文本、模型加载失败和索引配置错误限制在可重放范围内，便于比较新旧检索样本。