向量库维度不一致报错时怎么检查 embedding 配置

向量库报“维度不一致”时，通常不是向量库随机出错，而是同一条链路里的模型输出和集合 schema 没有对齐。先记下报错中的 expected 与 actual，再分别测量 embedding 服务返回向量、批处理拼装后的向量，以及集合声明的 size。三处数字相同，才能继续排查距离度量或数据内容；只改一个请求参数往往会把旧数据变成新的问题。

先把 expected 和 actual 对上

假设错误是“集合要求 1536 维，但收到 3072 维”。这已经给出方向：expected 多半来自集合配置，actual 来自本次请求。不要先修改数据库字段，也不要用截断数组的方式“修复”；截断会破坏模型训练出的坐标空间，检索结果即使能返回也没有可解释性。

先在 embedding 客户端边界打印长度和模型名，批量请求要检查每一项，而不是只检查第一项：

def check_embeddings(texts, embedder, expected_dim):
    # 统一检查模型输出，避免把错误留到向量库写入阶段
    vectors = embedder.embed_documents(texts)
    if len(vectors) != len(texts):
        raise ValueError("文本数量与向量数量不一致")
    for index, vector in enumerate(vectors):
        # 每个向量都必须落在同一个固定维度空间
        if len(vector) != expected_dim:
            raise ValueError(f"第 {index} 条向量维度为 {len(vector)}，期望 {expected_dim}")
    return vectors

这里的重点不是语言，而是检查位置：模型返回后立刻失败，能把“配置错”“批处理漏字段”和“向量库拒绝写入”区分开。

核对模型配置和批量请求

同一项目常有导入任务、在线问答和重建脚本三个入口。它们可能读取不同的 EMBEDDING_MODEL，也可能一个服务启用了降维参数，另一个服务仍使用默认输出。把模型名、输出维度、是否归一化和批量接口字段放在一张清单里逐项比较。

不要只根据模型名称猜维度。实际请求一个固定短句并记录返回长度，尤其要注意 SDK 升级后参数名或响应结构变化。

再看集合的 size 和向量空间

以 Qdrant 为例，dense vector 的 size 是集合创建时定义的维度；官方示例也明确把它与 embedding 模型的输出维度绑定。若使用 named vectors，还要核对请求写入的是哪个向量名，因为同一点可以拥有多个不同配置的向量。稀疏向量不能用 dense 的长度规则直接套用。

检查时至少记录集合名称、向量名、size、distance 和模型标识。若库端是 1536，而新模型稳定返回 1024，正确方案通常是新建 1024 维集合并重建，或在支持 named vectors 的库中增加新的向量定义后渐进回填；不是把 1024 补零成 1536。

选择修复方式并加启动检查

数据量小且可以重复读取原文时，统一模型后重建最干净；已有线上流量时，先建立新集合或新命名向量，双写并灰度查询，确认结果稳定后再切换；无法重建的旧数据则必须继续使用原模型，直到迁移完成。修复后用同一批固定文本分别测试入库和查询，并把维度断言放进服务启动或发布前检查。

最后检查三个数字：模型实际输出维度、批处理最终向量维度、集合 schema 的维度。三者一致只是必要条件，距离度量、归一化策略和文本切分仍需保持一致，但维度错误本身就应在进入向量库前被拦住。

常见问题

换成同系列模型后为什么仍然报错？

模型名称相近不代表输出维度相同；以实际响应长度和集合 schema 为准。

可以把短向量补零吗？

不建议。补零改变了向量空间的语义，除非模型和库厂商明确提供兼容的投影方案。

只有查询时报错，写入却正常是什么原因？

通常是查询服务读取了另一套模型配置，或查询的向量名与写入的命名向量不同。