Embedding 向量维度变化时的索引迁移方案

Embedding 模型从 1536 维换成 3072 维时，最容易踩的坑是把它当成一次普通配置修改。向量的维度参与存储布局、距离计算和索引构建，旧索引通常不能直接接收新向量。更稳妥的方案是创建带版本号的新索引，从原始文本重新生成向量，回填完成后双写一段时间，再用固定查询集灰度切换。

先把维度变化当成索引版本迁移

迁移前先写下四个不可混淆的字段：模型标识、向量维度、距离度量、索引参数。Qdrant 的集合创建接口会声明向量的 size，pgvector 的 vector(n) 也会约束列的维度；即使底层允许无长度向量存放不同维度，索引表达式仍然需要同维度的数据。换句话说，维度不是可以随意覆盖的元数据。

官方资料：https://qdrant.tech/documentation/manage-data/collections/

官方资料：https://github.com/pgvector/pgvector

因此不要直接删除旧集合，也不要把 1536 维数组尾部补零。新模型产生的是新的向量空间，补零只是改变数组长度，并没有完成重新编码。

用原始文本回填新索引，双写补上时间差

先创建 docs_v2 或 embedding_v2，并把模型名、维度和距离度量写进元数据。回填时按稳定主键分批读取原始文本，生成新向量后写入新索引；每批保存游标和成功数，失败记录单独重试。不要只从旧向量导出，因为那样无法得到新模型的语义表示。

# 迁移示例：用原始文本生成 v2 向量，并保存可恢复游标
for doc in load_documents_after(cursor, batch_size=128):
    # 真实项目中这里应调用已固定版本的 embedding 模型
    vector = embed_v2(doc.text)
    # 写入新索引时保留原文主键，避免重复生成孤儿向量
    new_index.upsert(id=doc.id, vector=vector)
    cursor = doc.id
save_checkpoint(cursor)  # 中断后从最后成功的主键继续

回填期间，新写入的数据不能只进入 v1，否则切流时尾部数据会消失。做法是把写路径改成双写：先生成一次 v2 向量，再按需要写入 v1 和 v2；如果两边写入并非原子操作，就记录 outbox 或补偿任务，直到两边的主键集合对齐。

用固定查询集决定什么时候切流

“新索引写满了”不等于“可以切换”。准备一组能代表真实业务的查询，固定查询文本、过滤条件和 topK，分别请求 v1 与 v2，记录结果集合、首字节延迟、空结果率和资源占用。不要用一次偶然的相似度分数下结论，模型变化可能让排序变化本身就是预期结果。

灰度切换后保留一条能走回去的路

先让少量读请求走 v2，比较业务指标和错误日志；确认没有明显退化后再扩大比例。路由层保留 embedding_version=v1 的开关，旧索引至少保留一个观察窗口。只有当回填计数、双写延迟、查询结果和成本都稳定，才安排清理。

维度迁移的真正边界是“模型变了，数据就需要重新编码”。如果只是更换存储精度、索引算法或副本数量，应单独设计容量和索引重建方案，别把不同变更混在一次切流里。

常见问题

新旧维度能放在同一个集合吗？

取决于产品的 schema 能力。更通用的做法是两个版本化索引；支持命名向量的系统也可以在同一条记录中配置不同维度，但查询和回填仍要分别管理。

能不能给旧向量补零来兼容？

不建议。补零只满足数组长度，不能替代新模型对原始文本的重新编码，召回质量和语义边界都没有可解释性。

什么时候可以删除旧索引？

至少等回填与双写对账完成、灰度指标稳定，并确认有可恢复的原始文本和模型版本记录；否则旧索引就是最直接的回滚入口。