bug: Knowledge file_ids never persists — /file/add and /update return 200 but the KB→file link is lost (backend, API-only repro, v0.9.6)

快速结论：这是一个纯后端持久化 Bug，发生在通过 REST API 向 Knowledge 集合添加文件时。POST /api/v1/knowledge/{id}/file/add 和 POST /api/v1/knowledge/{id}/update 均返回 HTTP 200，但 knowledge 表中的 data.file_ids 字段始终为 null，导致 Knowledge 集合在界面上始终显示为空。优先排查：添加文件后立即读取 Knowledge 集合可能因文件尚未处理完成而返回空状态，需等待文件处理完毕（文档提取、嵌入、写入向量数据库）后再检查。

问题场景

用户通过纯 REST API 操作 Open WebUI v0.9.6（Docker 镜像 ghcr.io/open-webui/open-webui:main）的 Knowledge 功能。后端使用 Ollama 提供嵌入模型（RAG_EMBEDDING_ENGINE=ollama，RAG_EMBEDDING_MODEL=nomic-embed-text），聊天完成使用 OpenAI 兼容接口。问题在 Linux aarch64 / Raspberry Pi 5 上复现，但架构无关。完全通过 API 复现，不涉及前端操作。

报错原文

POST /api/v1/knowledge/<KBID>/file/add
{"file_id":"<FID>"}                           -> 200
# response: files[] has 1 entry, BUT data.file_ids == null

GET  /api/v1/knowledge/<KBID>                      -> 200
# data.file_ids == null   <-- BUG
# files[]       == []       200
# response data.file_ids == null               data.file_ids == null  <-- still empty

原因分析

可能原因：应用层在写入 knowledge 行记录的 data.file_ids 字段时存在逻辑缺陷。直接通过 SQLite UPDATE knowledge.data 可以在数据库层持久化，但应用读取时仍返回空状态（且重启后失效），说明问题出在应用的 knowledge 更新/读取逻辑中，而非 SQLite/磁盘写入层。

关键差异：文件表（file）的记录可以正确持久化；嵌入/检索功能正常（向量数据存在于 Chroma 中）；DELETE 操作能正确持久化。问题仅限于 knowledge 行记录中的 data 写入/更新路径。
可能的时间竞争问题：Issue 评论指出添加文件后需要等待文件处理完成（文档提取、嵌入、写入向量数据库）才能正确读取。立即读取“尚未处理完成”的文件会导致返回空状态。

环境排查

Open WebUI 版本：v0.9.6（通过 GET /api/config 确认）
安装方式：Docker 单容器，镜像 ghcr.io/open-webui/open-webui:main
嵌入引擎：Ollama，嵌入模型 nomic-embed-text（环境变量 RAG_EMBEDDING_ENGINE=ollama）
数据库完整性检查：PRAGMA integrity_check 在 webui.db 上返回 ok
重现前提：使用全新的 Open WebUI 实例和全新的 Knowledge 集合

解决步骤

确认文件处理完成：在添加文件后，不要立即读取 Knowledge 集合。需要轮询检测文件是否已完成处理（文档提取、嵌入、写入向量数据库）。可以定期检查 GET /api/v1/files/<FID> 的状态字段，直到状态不再是 "pending"。
等待后再读取 Knowledge：文件处理完成后，再执行 GET /api/v1/knowledge/<KBID>，检查 data.file_ids 是否已正确持久化。
如果仍有问题：确认你是否正在使用 :main 最新镜像（即 v0.9.6）。该 Bug 已在后续版本中修复，建议升级到更新的版本。
验证更新端点：如果 file/add 不生效，尝试使用 POST /api/v1/knowledge/<KBID>/update 并传入完整的 KnowledgeForm，但同样需要等待文件处理完成后再验证。

验证方法

等待文件处理完成后，执行 GET /api/v1/knowledge/<KBID>，检查返回结果中的 data.file_ids 是否包含添加的文件 ID，且 files[] 数组不为空。如果一切正常，Knowledge 集合在界面上也应显示对应的文件。

参考来源

open-webui/open-webui #26222

AI 工具推荐

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

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

了解 GamsGo AI

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

bug: Knowledge file_ids never persists — /file/add and /update return 200 but the KB→file link is lost (backend, API-only repro, v0.9.6)