本地RAG项目里ChromaDB报“维度不一致”或“嵌入维度不匹配”，大多不是ChromaDB本身算错，而是同一批文档被不同模型、不同参数或不同预处理流程生成了不同长度的向量。处理方向不是去强行截断或补零，而是先确认embedding函数在所有写入和查询路径上是否完全一致，再把维度校验前置到调用embedding函数之前。
嵌入维度不一致的根因通常出在embedding模型或参数不一致，而不是ChromaDB存储层。建议先统一embedding模型与调用参数，在每次调用embedding函数前主动校验维度并做缓存或重建，随后用集合元数据记录维度。任何跳过校验直接写库的做法都可能让脏数据留在集合里，后续检索相似度会一并失真。
维度不一致通常出现在哪几个环节
ChromaDB的collection在首次写入时会确定维度，之后写入的向量必须与该维度一致。用同一个collection处理不同来源的文档时，常见的原因是：
- embedding函数在不同代码路径上不一致，比如一部分用了OpenAI的text-embedding-ada-002，另一部分用了本地模型或更新后的模型版本；
- 同一个模型但调用参数不同，比如max_tokens、dimensions这类参数改变了输出尺寸；
- 文本预处理后传给embedding函数的内容不一样，比如一个路径保留了摘要，另一个路径传了全文；
- 代码更新后模型或tokenizer被替换，但旧collection仍在复用。
这类问题在本地项目里很常见，因为开发时经常切换模型来试效果，但collection没有同步清理。可以先从ChromaDB的日志或报错信息里拿到期望维度和实际维度，再对照生成这两批向量的代码路径，逐条排查。
先定位是哪个环节产生维度漂移
不要急着改embedding函数或重建collection。建议先用下面几步确认漂移位置：
- 找出报错时实际生成的向量维度，打印该向量长度；
- 找出目标collection里已存的向量维度，可以通过读取collection的metadata或抽样一条记录来确认；
- 检查所有调用embedding函数的位置，把模型名、模型版本、参数和输出维度打印出来；
- 如果同一段文本在不同位置生成的维度不同，问题在embedding调用本身；如果维度一致但写入仍报错，问题可能在ChromaDB的collection创建方式。
这一步做完，基本能判断是“模型级不一致”还是“流程级不一致”。模型级不一致需要统一模型，流程级不一致需要统一调用前的处理。
调用embedding函数前统一维度的做法
目标是让所有写入和查询在调用embedding函数前就进入同一条路径。建议做一个统一的embedding封装，内部固定模型和参数，并对外暴露维度校验逻辑。下面是一个通用骨架，具体模型名和请求格式需要按你实际使用的服务替换：
# 统一的embedding封装，固定模型和参数
class FixedEmbedding:
def __init__(self, api_client, model_name="text-embedding-model", dimension=768):
self.client = api_client
self.model_name = model_name
self.dimension = dimension # 预期维度，写入collection前确认
def embed(self, texts):
# 实际调用模型前，先确认输出维度
vectors = self.client.embed(texts, model=self.model_name)
for v in vectors:
if len(v) != self.dimension:
raise ValueError(f"实际维度 {len(v)} != 预期维度 {self.dimension}")
return vectors
# 使用示例
embedder = FixedEmbedding(api_client, dimension=768)
vecs = embedder.embed(["文档内容"])
# 只有维度校验通过后才写入ChromaDB
collection.add(
ids=["doc-1"],
documents=["文档内容"],
embeddings=vecs
)这个封装的核心作用是把“调用embedding函数”和“写入ChromaDB”之间的维度校验固定下来。如果模型换了，只需要改一处配置，同时在写入前会直接抛出错误，避免脏数据落库。
进一步校验collection已有维度
如果collection已经存在，建议在写入前先读取collection的metadata里的维度信息。没有存维度信息的话，可以取一条已有记录来判断：
# 读取collection现有维度，作为校验基准
if collection.count() > 0:
sample = collection.get(limit=1, include=["embeddings"])["embeddings"][0]
existing_dim = len(sample)
if existing_dim != embedder.dimension:
print(f"现有维度 {existing_dim}，新向量维度 {embedder.dimension}，需要重建collection")
# 建议删除原collection或新建一个，而不是混写如果现有维度与新的预期维度不一致，通常不建议在旧collection上继续写入。更稳妥的方式是新建collection并指定新维度，再重新写入全部文档。本地项目数据量不大时，重建成本通常可以接受。
验证方式与回滚边界
修改完embedding封装后，验证可以分为两层：
- 写前验证：任意文档在调用embedding函数后、写入collection前，检查向量长度等于collection维度，不一致就中止写入；
- 查询验证：查询时也使用同一个embedding封装，不能出现查询向量维度与collection维度不一致的情况。
实际操作中可以先写一条测试文档，确认能正常add后再批量处理。如果历史collection已经混入了错误维度的向量，ChromaDB的删除操作通常不能仅按维度筛选，最稳妥的做法是导出原有文档重新embedding并重建collection。若业务上不能重建，就只能保留旧collection用于旧向量查询，新写入另开一个collection，这种做法需要额外维护两套集合。
风险边界在于：统一维度只解决“维度不一致”问题，不保证语义检索质量。两个不同模型即使维度相同，向量空间也不可混用。因此统一维度的前提是统一模型和参数，而不是单纯让向量长度对齐。
常见问题
是否可以对维度不足的向量补零来对齐？
不建议。补零后的向量与原有向量不在同一语义空间，检索时会产生无意义的相似度。维度不一致通常意味着模型或参数不同，先统一embedding来源才是正解。
换模型后必须重建collection吗？
只要新模型输出维度不同，就必须重建。如果新模型与旧模型维度恰好相同，理论上可以继续写，但语义空间仍然可能不一致，检索效果会受影响。稳妥做法是固定模型版本和参数后，重新生成全部向量。