Open WebUI 知识库检索不生效 / embedding 配置错（上传文件报 Ollama embed 404）

你会遇到什么

给 Open WebUI 建了知识库、上传了文档，文件状态一直是 failed，报错：

Ollama embed error (404): model "nomic-embed-text" not found, try pulling it first

模型明明拉过了、Ollama 也连得上（聊天能看到模型），但 embedding 就是不走。网上教程让你设 OLLAMA_BASE_URLS、RAG_EMBEDDING_MODEL，全设了还是不行。这里有三层坑，缺一层就 404。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

embedding 链路有三层独立配置，任何一层错都会 404：

另外注意：默认 RELEVANCE_THRESHOLD=0，无关查询也会返回 top-k 结果，这不是"检索坏了"。

两种场景二选一：已有实例（99% 的情况）用管理 API 一行改；全新容器用启动参数一次给全。

embedding 链路是「模型名 → embedding 服务地址 → 存储配置」三段串联，任何一段错都表现为「上传文件 failed / 检索 404」。

三段各自的机制：①模型名带 ollama/ 前缀会被原样转发给 ollama（引擎名不是命名空间），ollama 侧查不到 ollama/nomic-embed-text 就 404；

②embedding 服务地址是独立配置键 RAG_OLLAMA_BASE_URL（DB rag.ollama.base_url），与聊天的 OLLAMA_BASE_URLS 无关——缺省回退镜像默认值（可能指向没有 embedding 模型的实例）；

③配置首次启动即落库（SQLite config 表），之后 env 不再生效，DB 优先于 env——这是「改环境变量重启无效」的根因。

确定性推论：先分清场景——已有实例用管理 API（/api/v1/retrieval/embedding/update）改 DB 配置，全新容器用启动参数一次给全；改完上传文件验证向量化成功（2s 级）而非只看配置页；RELEVANCE_THRESHOLD=0 时无关查询也返回 top-k 是正常行为，不是检索坏了。

官方排障对照（docs.openwebui.com/troubleshooting/rag/）

官方 RAG 排障文档与本页三坑链直接相关的内容，并排看更清楚：

API 上传的正确姿势（官方 wait_for_processing 思路，避免空内容竞态）：

import requests, time

def wait_for_processing(token, file_id, timeout=300):
    url = f"http://localhost:3000/api/v1/files/{file_id}/process/status"
    headers = {"Authorization": f"Bearer {token}"}
    start = time.time
    while time.time - start < timeout:
        r = requests.get(url, headers=headers).json
        if r.get("status") == "completed":
            return True
        if r.get("status") == "failed":
            raise RuntimeError(f"Processing failed: {r.get('error')}")
        time.sleep(2)          # 每 2s 轮询一次
    raise TimeoutError("file processing timed out")

本页实测与官方行为一致的一条补充：RELEVANCE_THRESHOLD 默认 0 时无关查询也返回 top-k 结果——这不是检索坏了，要过滤就调高阈值。

一步步来

1. 先直连 ollama 验证模型与命名 — 排查（30 秒定位：先分清模型问题还是配置问题）

# 裸名（正确）：应 200，返回 embeddings
curl -s http://localhost:11434/api/embed -d '{"model":"nomic-embed-text","input":["测试"]}' | head -c 200
# ollama/ 前缀（错误示范）：应 404 model "ollama/nomic-embed-text" not found
curl -s http://localhost:11434/api/embed -d '{"model":"ollama/nomic-embed-text","input":["测试"]}'

模型不在：ollama pull nomic-embed-text（274MB，官方 registry 小模型通常可达）。

2. 看文件失败的具体报错 — 排查（按报错文本分层）

文件列表里点开失败文件，错误信息里如果是 Ollama embed error (404)，就是上面的三层坑；如果是 Connection refused，才是连不上 ollama（见 open-webui-ollama-connect）。

3. 已有数据卷：用管理 API 改，别改 env — 必做（改配置；env 落库后无效）

# 确认当前生效值（DB 优先）
docker exec open-webui python3 -c "import sqlite3; con=sqlite3.connect('/app/backend/data/webui.db'); print(con.execute(\"SELECT key,value FROM config WHERE key='rag.ollama.base_url'\").fetchone)"
# 用管理 API 覆盖（图形界面等价：管理面板 → 设置 → 检索 → embedding）
curl -X POST http://localhost:3000/api/v1/retrieval/embedding/update \
  -H "Authorization: Bearer <token>" -H 'Content-Type: application/json' \
  -d '{"RAG_EMBEDDING_ENGINE":"ollama","RAG_EMBEDDING_MODEL":"nomic-embed-text","ollama_config":{"url":"http://host.docker.internal:11434","key":""}}'

4. 删除失败文件，重新上传 — 必做（旧文件不会自动重试）

上传 → 等文件状态变 completed（几秒到几十秒）。还 failed 就再看错误文本，按层排查。

5. 建库 → 加文件 → 检索验证 — 必做（验收）

# 建知识库 → 得到 kb_id
curl -X POST http://localhost:3000/api/v1/knowledge/create -H "Authorization: Bearer <token>" -H 'Content-Type: application/json' -d '{"name":"kb"}'
# 加文件（file_id 来自上传响应）
curl -X POST http://localhost:3000/api/v1/knowledge/<kb_id>/file/add -H "Authorization: Bearer <token>" -H 'Content-Type: application/json' -d '{"file_id":"<file_id>"}'
# 检索
curl -X POST http://localhost:3000/api/v1/retrieval/query/collection -H "Authorization: Bearer <token>" -H 'Content-Type: application/json' -d '{"collection_names":["<kb_id>"],"query":"文档里的关键词","k":3}'

怎么确认修好了

• 上传文件状态 completed（不再 failed），日志出现 embeddings generated ... added ... to collection。
• 检索命中文档内容，且元数据里 embedding_config 正确：{'engine': 'ollama', 'model': 'nomic-embed-text'}。
• 直连 POST /api/embed 裸名返回 200（768 维向量）；前缀返回 404 属预期。
• 注意：无关查询也返回结果 ≠ 修复失败（默认阈值 0，返回 top-k）；要过滤在管理面板调高 RELEVANCE_THRESHOLD。

其它环境的表现

症状

• 知识库文件一直 failed，错误含 Ollama embed error (404): model "nomic-embed-text" not found, try pulling it first；
• 模型列表能看到 embedding 模型、聊天正常，但知识库检索不生效；
• 按教程设了 OLLAMA_BASE_URLS / RAG_EMBEDDING_MODEL 后重启仍 404。

原因

• 模型名被写成带 ollama/ 前缀（404）；
• embedding 的 URL 是独立配置 RAG_OLLAMA_BASE_URL，没设时回退到默认实例（可能没有该模型）；
• 首次启动配置落 SQLite 后 DB 优先于 env，改 env 无效。

解法

1. 直连 POST /api/embed 裸名 200 / 前缀 404 定位；2. ollama pull 补 embedding 模型；3. 已有卷用管理 API POST /api/v1/retrieval/embedding/update 写 ollama_config.url（env 无效）；4. 删 failed 文件重传，等 completed；5. 建库+加文件+检索命中验证；6. 无关查询返回 top-k 时调高 RELEVANCE_THRESHOLD。

相关 canonical

按「前置 → 同根 / 同域 / 相关」读：

• 同根（同一根因）：
• 忘记管理员密码 / 登录不进去（同根：webui.db 是唯一事实源（config 表与 auth 表都优先于 env/注册））

• 相关（报错相近，根因不同）：
• Open WebUI 页面显示连不上 Ollama（Connection refused 类，host.docker.internal 与 OLLAMA_BASE_URLS）
• ollama pull 卡住/超时（拉 embedding 模型慢）
• 模型目录换盘（embedding 模型也在模型目录里，一起搬）

参考资料

• Open WebUI 官方 RAG 排障文档 — <https://docs.openwebui.com/troubleshooting/rag/>