当你遇到 dimension 不一致的报错时,通常不是单点问题,而是至少两处配置没有对齐。常见情况有三种:一是构建索引时使用的 embedding 模型与查询时不同;二是同一个模型但服务端参数被修改,导致输出维度变化;三是向量库中已有数据的维度与当前模型输出维度不一致。建议先做两步检查:打印当前模型输出维度,查询向量库中 collection 的维度。
from transformers import AutoModel, AutoTokenizer
model_name = "BAAI/bge-small-zh-v1.5"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModel.from_pretrained(model_name)
print("hidden_size:", model.config.hidden_size)上面代码打印的 hidden_size 通常就是该模型的 embedding 维度。如果你的模型通过 HTTP 服务对外提供接口,则可以用一条请求直接看返回数组长度。
curl -X POST http://your-embedding-service/embed -H "Content-Type: application/json" -d '{"texts": ["dimension check"]}'对比两个来源的数值,如果出现差异,说明模型配置或服务端已经发生变化。对比操作是排查 dimension 不匹配的第一步。
在 LlamaIndex 中固定 embedding 模型与维度
确保 LlamaIndex 的 Settings.embed_model 只指向一个确定的模型,并且不要在索引创建后随意切换。以下配置使用 HuggingFace 开源模型作为 embedding 实现,并打印实际输出维度。
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
from llama_index.core import Settings
embed_model = HuggingFaceEmbedding(model_name="BAAI/bge-small-zh-v1.5")
Settings.embed_model = embed_model
sample_vec = embed_model.get_text_embedding("维度测试")
print("实际维度:", len(sample_vec))将 model_name 替换成你实际使用的开源模型,并建议把期望维度写成一个常量,例如 EXPECTED_DIM = 512,方便在写入向量库前校验。如果你通过 HTTP 接入某个本地模型,需要在自定义 embedding 类里固定返回维度,不要使用动态维度。
处理已有的旧索引和向量库数据
如果索引已经建立,但查询时换了模型,维度的兼容性取决于向量库本身。多数向量库允许在建表时指定维度,之后写入的向量必须与该维度一致。因此,当两端维度不一致时,最稳妥的做法是新开一个 collection,用当前模型重新写入数据。若必须保留原 collection,则需要对旧向量做降维或映射,但这类操作通常会引入偏差,不建议作为长期方案。
可以先用脚本读取任意一条旧数据,确认旧向量的维度。
old_vec = collection.get(limit=1)["embeddings"][0]
print("旧向量维度:", len(old_vec))如果旧维度与当前模型输出维度不一致,建议优先换回旧模型。如果旧模型已经不可用,再考虑重建数据。不要试图对向量做截断或补零,会破坏语义。
验证清单与常见坑
- 确认 embedding 服务端返回的维度是固定值,不随文本长度变化。
- 确认 LlamaIndex 加载的模型名称与维度打印结果一致。
- 确认查询时使用的 Settings.embed_model 与建索引时相同。
- 用一条新文本同时测试旧索引和新写入的数据,看是否出现 “Dimension mismatch” 或类似错误。
- 在向量数据库端确认 collection 的维度字段,与模型输出一致。
另外,有些项目会在环境变量或配置文件中写入 embedding 维度。如果环境变量或配置文件中的维度值与代码实际使用的不一致,也会触发 dimension 报错。建议把所有维度信息集中放在一个配置项里,每次启动时打印一次,并纳入启动日志。
以上流程覆盖了最常见的 dimension 不一致问题。如果完成这些检查后仍报错,需要把报错信息、模型名称和两端维度值记录下来,进一步缩小排查范围。