Embedding 模型更换后向量维度不一致怎么办：双索引迁移、查询路由与回滚

Embedding 模型更换后，最危险的不是新模型效果暂时不稳定，而是旧向量和新向量被当成同一种数据继续写入。维度不同会在入库或查询时直接报错；即使维度碰巧相同，语义空间也可能已经变化。稳妥的迁移方式是保留旧模型，建立新索引，先回填和对照，再让查询路由逐步切换。

不要覆盖旧向量列来“省一次迁移”：把模型标识、维度和索引一起版本化，才能在效果不满意时退回旧链路。

先确认真正变化的是维度，还是语义空间

排查时先记录一次完整的 Embedding 响应：模型标识、返回向量长度、输入文本摘要和请求时间。不要只看模型名称猜维度，也不要把“同维度”理解成“可直接混用”。两个模型即使都返回同样长度的数组，训练目标、归一化方式或版本变化也可能让距离分数失去可比性。

数据库侧至少保留 model_id、embedding_dim、document_id 和 embedding。pgvector 官方示例使用 vector(3) 表达固定维度；如果使用不带长度的 vector，不同维度可以放在同一列，但索引仍需要按相同维度建立表达式或部分索引。迁移期间，固定维度列更容易把错误挡在写入阶段。

type EmbeddingRecord struct {
    DocumentID   string
    ModelID      string
    EmbeddingDim int
    Values       []float32
}

func validateEmbedding(record EmbeddingRecord, expected int) error {
    if record.EmbeddingDim != expected {
        return fmt.Errorf("embedding dimension mismatch")
    }
    if len(record.Values) != expected {
        return fmt.Errorf("embedding length mismatch")
    }
    return nil
}

这里的 expected 来自当前索引契约，而不是请求方随意传入的数字。校验失败时保留原始文档和模型标识，方便重新生成，别把错误数组截断或补零后继续入库。

双索引迁移：旧模型和新模型先各走一条数据路径

迁移的第一步不是删除旧列，而是为新模型准备独立的存储空间。可以使用两张表，也可以在同一张表中用 model_id 区分，再为每个维度建立匹配索引。关键是让“生成向量”和“写入索引”成为一个可观测的数据路径。

CREATE TABLE document_embeddings (
    document_id text NOT NULL,
    model_id text NOT NULL,
    embedding_dim integer NOT NULL,
    embedding vector NOT NULL,
    PRIMARY KEY (document_id, model_id)
);

CREATE INDEX document_embeddings_new_hnsw
ON document_embeddings USING hnsw ((embedding::vector(1536)) vector_cosine_ops)
WHERE model_id = 'new-model';

上面的 1536 只是迁移契约示例，不能替代真实模型返回值；正式上线前应把它换成已核验的维度。旧模型和新模型的维度不同，就不能在同一条距离计算里混合排序。查询时先根据路由结果筛选 model_id，再使用对应的向量表达式。

回填不能一把梭：先让新索引具备可停止的进度

后台回填按文档游标分批执行，每批记录成功数、失败数和最后一个 document_id。遇到维度不匹配、文档删除或供应商超时，要把异常放进可重放队列，不要为了让进度条变绿而写入空向量。

for page := range pages {
    for _, doc := range page.Documents {
        vector, err := embedNewModel(doc.Text)
        if err != nil {
            recordRetry(doc.ID, err)
            continue
        }
        record := EmbeddingRecord{
            DocumentID: doc.ID, ModelID: "new-model",
            EmbeddingDim: len(vector), Values: vector,
        }
        if err := validateEmbedding(record, expectedDim); err != nil {
            recordRetry(doc.ID, err)
            continue
        }
        saveEmbedding(record)
    }
}

回填指标最好拆成 read、embedded、stored、retry 四段。只有 stored 达到目标，且抽样查询能命中新索引，才算这一阶段完成。

查询路由要能切换，也要能解释为什么切换

线上请求不要直接把模型名写死在业务分支里。让路由配置返回一个版本，例如 old-model 或 new-model，随后由检索层选择生成器、维度校验和索引。这样做的价值不只是灰度，更是出现空结果或质量回退时能快速恢复。

func search(ctx context.Context, query string, route ModelRoute) ([]Hit, error) {
    vector, err := route.Embed(ctx, query)
    if err != nil {
        return nil, err
    }
    if len(vector) != route.ExpectedDim {
        return nil, fmt.Errorf("route dimension mismatch")
    }
    return route.Index.Search(ctx, vector, 8)
}

影子查询可以把同一条查询分别送到旧索引和新索引，但只向用户返回当前版本结果。记录两个版本的命中文档、空结果率和人工抽样结论，别直接用距离分数跨模型做简单相减；分数尺度不一致时，这种比较没有意义。

切换前做三组验收，回滚按钮必须真的可用

验收新写入

新文档写入后，确认旧链路和新链路的写入策略符合预期：双写期间两边都有记录，单切换后只有新模型继续增长。随机抽查 model_id、embedding_dim 和向量长度，确保数据库约束与应用校验都在生效。

验收查询结果

准备一组固定查询，比较新旧版本的命中数量、空结果和明显不相关结果。关注业务可解释的指标，例如“同一文档是否仍能被自己的关键词召回”，不要把一次距离分数变好当成迁移成功。

验收回滚路径

保留旧索引和旧模型的路由配置，演练把流量开关改回 old-model，然后验证查询仍能返回结果。回滚后再检查新模型回填任务是否暂停，避免新旧任务同时改写同一条业务记录。

常见问题：哪些情况不适合直接换模型

维度相同就能复用旧索引吗？

不能。维度只是数组长度，不能证明两个模型的向量空间可比较。至少要使用同一模型标识和同一预处理协议生成的数据，再决定是否复用。

能不能把旧向量截断成新维度？

不建议。截断、补零或随机投影都会改变距离含义，除非你明确采用了经过验证的降维方案，并用固定评测集证明召回质量没有越过业务阈值。

回填完成后要不要马上删旧索引？

不要马上删。至少保留一段可回滚窗口，等新写入、影子查询和线上异常监控都稳定后，再按备份和恢复方案清理旧数据。

Embedding 迁移的核心不是把一列向量换成另一列，而是把模型、维度、索引和路由组成一份可验证的数据契约。双索引让新旧链路可以并存，影子查询提供对照证据，真正的回滚演练则把“理论上能退回”变成可执行动作。