Embedding 模型换版本后向量维度不一致：索引重建与灰度切换怎么验收

替换Embedding模型版本后，最先出问题的一般不是接口直接报错，而是检索结果悄无声息地变差：旧文档向量还是 1536 维，新模型输出的查询向量变成 1024 维，上层业务不会立刻出现故障告警，却已经无法用同一套索引做公平的相似度比对。处理这类迁移，关键不是临时把列类型改宽凑合用，而是先固定向量维度相关的契约，再让新旧结果经过一段可回退的灰度验证流程。

先确认到底改了什么

“换模型”与“缩短维度”是两个容易被混在一起的动作。Embedding 服务可能因为模型升级改变默认输出长度，也可能仍使用同一模型，只通过 dimensions 参数返回更短的向量。OpenAI 的公开说明把 shortening 作为接口能力，但这并不意味着旧索引会自动适配；向量数据库仍然只认识它收到的数值数组和列约束。

上线前先把下面四项写到版本配置里，形成可审计的维度契约：

• 模型标识：例如 text-embedding-3-small 或团队实际使用的模型版本。
• 输出维度：明确写出 1536、1024 等整数，不用“默认维度”代替。
• 距离度量：余弦、内积或 L2 必须和历史评测时选定的规则完全一致。
• 索引归属：新向量存到哪张表、哪个分区、哪套索引，以及对应的回退方案要明确。

维度不一致时，为什么不能直接复用旧索引

固定维度的向量列本质上是一个边界检查。以 PostgreSQL 的 pgvector 为例，vector(n) 约束了每行向量的长度，HNSW 或 IVFFlat 索引也围绕这组数据建立。把 1024 维的新向量硬塞进 1536 维列，通常会在写入或查询时被拒绝；把数组补零到 1536 维虽然能绕过长度检查，却改变了距离分布，不能当作等价迁移。

先跑一次小样本校验，比等全量批量导入后再排查错误要省很多时间：

-- 新旧向量分开存放，示例表名为合成名称
CREATE TABLE knowledge_embedding_v2 (
  doc_id bigint PRIMARY KEY,
  embedding vector(1024) NOT NULL,
  model_name text NOT NULL,
  dimension integer NOT NULL CHECK (dimension = 1024)
);

-- 入库前检查元数据与实际长度
SELECT doc_id, model_name, dimension
FROM knowledge_embedding_v2
WHERE dimension  1024;

如果查询侧仍在使用旧列生成向量，应用要在生成查询向量后立刻校验长度，不要等数据库返回一条模糊的类型错误才发现迁移出了问题。

用双写把迁移变成可回退的检查清单

稳定做法是保留旧读路径，同时给新向量准备独立列或独立表。文档更新时，新旧模型各生成一次向量；历史文档则用可控批次补齐。双写期间记录 doc_id、模型标识、维度、生成时间和失败原因，缺失一侧的记录不要悄悄当成“已迁移”。

1. 小样本核验：抽取覆盖不同长度、语言和业务标签的文档，确认新列没有出现截断、错位或者空数组的问题。
2. 离线对比：固定一批测试查询语句，对比旧、新索引的 Top-K 结果重叠率、命中位置和人工判断的相关性得分。
3. 影子读取：线上请求依然返回旧索引的结果，但是后台并行计算新索引的返回结果，只匿名记录两者的排名差异，不影响线上业务。
4. 灰度切换：先按租户或者流量比例切走一部分请求到新读路径，旧索引全程保留，同时配好一键回退的开关。

验收不能只看“向量都生成成功”

向量生成接口返回 200 状态码，只能说明成功拿到了结果数组，不代表搜索匹配的质量和之前版本一致。至少要准备三类验收数据：有明确答案的事实类查询、需要跨段落组合信息的查询，以及容易混淆的近义词查询。对每类数据同时保存旧、新两套索引的 Top-K 结果，检查候选结果重叠度、第一相关结果的排位和人工标注的匹配度。

可以把切换的验收门槛写成可配置的规则，不要临时凭主观感觉决定。比如要求新索引写入成功率必须为 100%；查询向量维度不匹配率必须为 0；关键查询集的第一相关结果不能整体往后偏移；如果灰度期间错误率或者人工相关性得分低于预设门槛，立刻把读请求开关切回旧索引。具体阈值要按照自身业务的基线设定，下面的数字只是演示验收字段：

migration:
  model: embedding-model-v2
  dimension: 1024
  shadow_overlap_at_k: 0.80
  query_dimension_error_rate: 0
  rollback_on_relevance_drop: true

三个常见误区

只改数据库列的维度

直接改索引维度数字的操作，会让旧数据、新数据和查询向量的语义版本失去边界。迁移需要新列或新表、元数据和索引同步变更，不能只单独修改配置里的一个数字。

把补零或截断当成兼容层

补零、截断、线性压缩这些操作都有可能改变相似度排序的结果。除非你已经用固定评测集验证过，调整后的结果质量和资源成本都符合预期，否则不要把这类操作当成不需要重建向量的捷径。

只比较接口延迟

新模型的推理速度可能更快，却可能把用户要的关键答案排到了靠后的位置。接口延迟、请求失败率、索引占用大小和检索质量，应该放在同一张验收表里同步核对。

常见问题

Embedding 模型换了，必须全部重算吗？

如果模型本身、输出维度或者语义版本发生变化，一般建议把历史文档向量全部重算之后放到独立的新索引里，经过多轮对比确认没问题之后再切读路径。要不要全量重算要结合业务数据更新频率和质量基线来决定。

dimensions 变小后，向量就一定更省钱吗？

维度变小之后存储和索引的开销通常会下降，但向量生成费用、查询侧负载和检索质量仍要单独做测试评估，不能只看数组长度变短就默认全量收益成立。

新旧向量可以暂时混在一张表吗？

历史旧向量可以在不限制维度的原始存储介质里留底，但是检索索引、模型标识和查询路由必须完全隔离，不要让同一套索引把不同维度或者不同语义版本的向量当成同一个向量空间处理。

什么时候算迁移完成？

等新索引完成全量补齐和一致性检查，离线查询集的表现达到预设基线，灰度运行期间没有出现维度不匹配的报错，而且旧读路径的回退能力完全可用之后，才适合关闭新旧双写逻辑。

把维度当成发布契约

Embedding 迁移最容易踩坑的地方，是“向量数组生成成功”这个正常反馈，很容易掩盖“检索语义已经悄悄变化”的问题。把模型标识、维度规则、度量方式、索引位置和回退开关绑定到同一份配置里，再通过双写、影子读取和固定查询集的方式做全流程验收，新旧版本的切换就能控制在可观测、可撤回的安全范围内。