issue: Knowledge base search fails silently after the embedding dimension changes (Chroma error swallowed, nothing logged)

更换嵌入模型后未重建知识库索引,检索时 Chroma 会因向量维度不一致抛出异常,但该异常在 Open WebUI 中被静默吞掉,导致检索接口返回 HTTP 200 与空结果、日志也无任何提示。优先检查知识库集合维度是否与当前嵌入模型输出维度一致,并重新索引。

快速结论:更换嵌入模型后未重建知识库索引,检索时 Chroma 会因向量维度不一致抛出异常,但该异常在 Open WebUI 中被静默吞掉,导致检索接口返回 HTTP 200 与空结果、日志也无任何提示。优先检查知识库集合维度是否与当前嵌入模型输出维度一致,并重新索引。

适用环境:Open WebUI v0.13.4(ghcr.io 镜像)及 dev 分支(commit f37bab63);Docker 部署;操作系统 Pop!_OS 24.04(Ubuntu 24.04 基础);默认本地嵌入 sentence-transformers(384 维 all-MiniLM-L6-v2,切换为 768 维 all-mpnet-base-v2);向量库为 Chroma。Issue 未提供 Ollama 版本信息。

最快修复方案:在更换嵌入模型后,对整个知识库执行重新索引(生成新的 Embedding),使 Chroma 集合维度与新模型一致。Issue 中用户明确表示“更换嵌入模型后需要重新索引”,但未给出具体重建命令。

注意事项:重新索引会覆盖/重建现有向量,耗时与文档量相关;Issue 中“日志中记录异常”“切换模型时给出维度警告”属于建议修复,并非已验证方案,可优先尝试(例如在 chroma.py 的两个 except 块中加入 log.exception(e) 以便定位),但实际代码是否已合入需以对应版本为准。

问题场景

在 Open WebUI 中使用知识库(Knowledge Base)功能,将嵌入模型从 384 维的 sentence-transformers/all-MiniLM-L6-v2 切换为 768 维的 sentence-transformers/all-mpnet-base-v2(通过 Admin > Settings > Documents 或 POST /api/v1/retrieval/embedding/update),但没有对已有知识库重新索引。之后调用 POST /api/v1/retrieval/query/collection 进行语义检索时,接口返回 HTTP 200 和空结果,表面上像是“知识库失效”,实际是底层的维度不匹配错误被吞掉。该问题在 0.12.3 的 UI 中同样表现为无任何提示。

报错原文

InvalidArgumentError: Collection expecting embedding with dimension of 384, got 768

该错误仅在直接使用 chromadb 查询同一向量库时可见。Open WebUI 侧的表现是:

{"distances":[[]],"documents":[[]],"metadatas":[[]]}

"POST /api/v1/retrieval/query/collection HTTP/1.1" 200

原因分析

Chroma 集合在创建时即固定了向量维度。更换嵌入模型后,新模型输出的向量维度与已写入集合的维度不同,检索请求会被 Chroma 拒绝并抛出 InvalidArgumentError。但在 backend/open_webui/retrieval/vector/dbs/chroma.py 中,search() 和 query() 的异常处理块都以 except Exception as e: 后直接 return None(后者甚至未使用 as e),没有日志调用,因此 API 返回空结果、服务端日志只剩访问行。

可能原因还包括:切换嵌入模型时接口返回 status: true 但未校验已有集合维度,也没有任何“需要重新索引”的提示;相关 Issue #11279 显示同类维度不匹配问题在出现日志时可以直接定位,说明本次的核心问题是异常被吞而非维度校验逻辑不存在。

环境排查

  • 确认 Open WebUI 版本(v0.13.4 或 dev commit),并确认是否复现于最新版本。
  • 确认部署方式为 Docker,容器数据目录是否正确挂载(/app/backend/data)。
  • 确认当前嵌入模型及其输出维度(Issue 示例:all-MiniLM-L6-v2 为 384,all-mpnet-base-v2 为 768)。
  • 检查 data/vector_db/chroma.sqlite3 中各集合的实际维度。
  • 确认更换嵌入模型后是否已执行重新索引。
  • 确认服务端日志级别,默认级别下该异常不会出现,不能以“日志无报错”判断问题不存在。

解决步骤

  1. 在数据目录副本上执行 select name, dimension from collections;,读取每个集合的维度。
  2. 将查询结果与当前嵌入模型的输出维度逐一比对。只要存在不一致,该知识库就处于维度不匹配状态。
  3. 对维度不一致的知识库执行重新索引(重新生成 Embedding),使集合维度与当前模型一致。Issue 确认重新索引是切换嵌入模型后的必要步骤,但未给出具体重建命令。
  4. 若日志仍然无任何线索,可优先尝试在 chroma.py 的 search() 与 query() 异常块中加入 log.exception(e),以便在再次失败时看到真实的 InvalidArgumentError。此改动属于 Issue 中的建议方案,非官方已验证修复。
  5. 完成重新索引后重启服务,复测检索。

验证方法

重新索引后再次调用 POST /api/v1/retrieval/query/collection,确认返回的 documents 中包含能回答问题的文本片段,而不是空数组;若已按建议加入日志,确认服务端日志中不再出现维度不匹配异常。也可再次查询 chroma.sqlite3 的集合维度,确认与新嵌入模型输出维度一致。

参考来源

open-webui/open-webui #34761

相关 Issue:#11279、#28316、#27703、#23787(由该 Issue 讨论串中的关联检索列出)。

GamsGo AI

AI 工具推荐

想把多个 AI 模型放在一个入口?

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型,适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接:通过此链接购买,我可能获得佣金,不影响你的价格。

这个方案解决了吗?

celebrityanime
celebrityanime
文章: 36673

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注