向量检索为什么要统一维度：OpenAI Embeddings 的 dimensions 参数与索引迁移

向量检索不是把一串浮点数写进数据库就结束了。Embedding 模型、请求里的 dimensions、索引声明的维度和查询向量必须完全一致；只要其中一项变了，写入可能直接报错，或者更隐蔽地让新旧数据无法公平比较。迁移时最稳妥的做法是保留 old_index，建立 new_index，回填完成后再切换查询路由。

把维度当成数据契约：先固定模型与 dimensions，再用双索引完成回填、验收和回滚，别在原索引上边写边改。

先把维度问题拆成四个检查点

一次请求通常有四个容易被混淆的对象：模型名决定向量生成规则，dimensions 决定请求输出的长度，文档向量写入索引，查询文本则生成 query_vector。检索时，query_vector 不能只“语义上相近”，还必须在同一个维度空间里。

因此迁移前先把下面四项记入配置或元数据，而不是散落在应用代码里：

• Embedding 模型名；
• dimensions 的实际值或默认值；
• old_index、new_index 的声明维度；
• 当前查询路由指向哪一个索引。

OpenAI 的 Embeddings API 文档是参数核对的入口；具体模型是否支持自定义 dimensions，要以对应模型文档为准，不能仅凭模型名称猜测。

为什么不能直接修改原索引

假设 old_index 已经存了 1536 维向量，现在希望改成更短的 512 维。原索引里的旧向量仍是 1536 维，新的文档向量变成 512 维，数据库通常会在写入阶段拒绝它们；即使某个存储层允许不同长度，距离计算也失去了同一空间的前提。

更麻烦的是回滚：如果应用一边回填一边把查询切到新向量，线上命中率下降时很难分辨是模型变化、数据缺失还是路由问题。双索引让这三件事分开，old_index 继续服务，new_index 单独接受回填。

用双索引完成可回退的迁移

下面的伪代码只展示迁移关系，索引创建和批量写入要替换成你所用向量数据库的 SDK。关键不是某个厂商方法名，而是先生成固定维度的文档向量，再写入与之匹配的索引。

const dimensions = 512
const old_index = "knowledge-v1"
const new_index = "knowledge-v2"

for (const doc of documents) {
  const embedding = await createEmbedding({ model, input: doc.text, dimensions })
  await newIndex.upsert({ id: doc.id, vector: embedding })
}

const query_vector = await createEmbedding({ model, input: query, dimensions })
const target = route === "new" ? new_index : old_index
return search(target, query_vector)

这段流程里有三个必须同时成立的事实：dimensions 控制生成长度，new_index 接收回填结果，查询阶段根据路由选择目标。真实项目还应保存文档版本和回填状态，避免任务重跑时把失败记录误当成成功。

回填完成后再切查询路由

不要用“回填数量接近总数”作为唯一完成条件。至少检查文档数量、向量维度、抽样查询和失败清单。抽样查询要固定一组业务问题，同时比较 old_index 与 new_index 的结果是否出现明显空召回或引用断裂。

确认 new_index 可用后，把路由从 old_index 切到 new_index。保留一段观察期；如果新结果出现大量空结果，先把路由切回 old_index，再检查模型配置、批处理失败和 query_vector 生成参数。

三个常见误区

把 dimensions 当成相似度阈值

它描述的是向量长度，不是召回阈值。阈值策略应该单独验证，不能用改维度代替调阈值。

只迁移文档，不迁移查询

文档向量换成新维度后，查询侧仍用旧配置会产生维度错误或不可比结果。文档和查询必须共享同一份配置。

覆盖旧索引后才发现无法回滚

覆盖操作会把数据恢复、路由回切和问题定位绑在一起。保留 old_index，直到新索引完成验收，是更便宜的保险。

相关问题

一定要把向量压到更低维吗？

不一定。是否降维要结合存储成本、延迟和召回质量验证；如果没有明确收益，保持模型默认维度通常更简单。

迁移时能不能只更新最近文档？

只有当检索范围明确允许新旧空间共存时才可以。普通单索引检索不应混合不同维度或不同空间的向量。

把维度、模型、索引和路由放在同一个可审计配置里，迁移就从“改一个参数碰碰运气”变成了可验收的发布流程。