RAG

检索增强生成（Retrieval-Augmented Generation, RAG）允许语言模型根据检索到的相关信息，并将其填充进模型提示词中，从而能够对外部内容（如文档、知识库等）进行推理和问答。当系统表现未达预期（例如模型“胡言乱语”或遗漏了相关内容）时，这通常不是模型本身的问题——而是上下文填充存在偏差。

本页面涵盖了最常见的 RAG 问题及其解决方案。

针对不同场景的推荐配置

RAG 的性能很大程度上取决于您的模型配置。系统的默认值较为保守以确保能够在任何设备上工作，但针对您的特定部署进行微调可以获得极佳的产出质量。所有这些参数都可以在 Admin Panel（管理员面板） > Settings（设置） > Documents（文档） 中进行配置。

针对 context 受限（≤ 8K tokens）的本地模型

这通常适用于在消费级硬件上通过 Ollama 部署的模型（如 Llama 3.1 8B、Qwen 2.5 7B、Gemma 3 4B、Phi-3 Mini 等），这些模型的 context 窗口大小通常有限。

设置选项	推荐值	对应考量与原理
Text Splitter	`token`	确保切片大小与实际 token 数量保持一致
Markdown Header Splitting	开启 (On)	保留文档原有的段落结构
Chunk Size	`1000`	较小的切片可以确保召回结果能轻松装入 context 中
Chunk Overlap	`100`	标准的重叠度
Top K	`3–5`	较少的切片数，以防撑爆有限的 context 预算
Full Context Mode	关闭 (Off)	无法承受直接将整篇文档发送给模型

Context 预算算账

当切片大小为 1000 个 token、Top K 设置为 5 时，RAG 会往模型里注入大约 5,000 个 token 的召回内容。再算上系统提示词以及历史对话——如果您的模型 context 窗口只有 8K 大小，那这只剩大约 2–3K 留给新的对话交互了。如果发现后续追问被截断，请将 Top K 往下调。

针对拥有大 context（32K+ tokens）的云端模型

这通常适用于 OpenAI（GPT-4o、GPT-5）、Anthropic（Claude）、Google（Gemini）、DeepSeek 等外部 API 服务商，它们的 context 窗口大小在 32K 至 1M+ tokens。

设置选项	推荐值	对应考量与原理
Text Splitter	`token`	保持稳定的切片尺寸
Markdown Header Splitting	开启 (On)	保留文档原有的段落结构
Chunk Size	`2000`	较大的切片尺寸可以在每次召回时保留更多周边的上下文
Chunk Overlap	`200`	更多的重叠度可以防止长难句被切碎
Top K	`15–25`	尽可能网罗更全的上下文——毕竟您有足够的 context 预算
Full Context Mode	针对小文档可考虑开启	如果文档在 ~20K tokens 以下，全文本直接注入的效果通常会好于切片召回

何时使用全文本模式（Full Context Mode）

当您使用的是一份中小型文档（小于 ~50 页）且配合大 context 模型时，开启全文本模式（Full Context Mode）的产出质量通常比切片检索更好，因为模型能够通读全文，不存在任何检索遗漏。您可以在聊天设置中针对每个对话单独切换此功能。

混合部署环境（本地 + 云端）

如果您同时混用本地和云端模型，请针对兼容性下限进行配置，并在特定模型或特定聊天中单独进行覆盖重写：

设置选项	推荐值	对应考量与原理
Text Splitter	`token`	兼容两者
Markdown Header Splitting	开启 (On)	兼容两者
Chunk Size	`1500`	折中方案——对于本地模型不算太大，对于云端模型也不算太小
Chunk Overlap	`200`	安全的默认值
Top K	`10`	适中——混合模型架构下的理想平衡点

向量嵌入模型推荐

向量嵌入（Embedding）模型直接决定了检索召回的质量。正确的选择取决于您的实际部署：

适用部署场景	推荐使用模型	对应考量与原理
单用户，刚入门	`all-MiniLM-L6-v2`（默认）	在本地直接运行，无需进行额外设置
多用户，配有 Ollama 算力支持	通过 Ollama 运行 `nomic-embed-text`	将计算分担至 Ollama，释放 Open WebUI 服务器的内存
生产环境，配有 API 预算	通过 OpenAI 运行 `text-embedding-3-small`	性价比极高的顶级召回质量
局域网/纯内网自托管	通过 Ollama 运行 `nomic-embed-text` 或 `mxbai-embed-large`	100% 离线运行，无需发起外部 API 调用

在更改您的向量嵌入模型后，请务必重新索引所有现有的文档（在 Admin Panel（管理员面板） > Settings（设置） > Documents（文档） 中操作），以使新的向量数据生效。

常见 RAG 问题及修复方法

1. 模型“看不到”您的内容

这是最常见的问题——且它通常是因为在解析和吸纳（ingestion）内容期间出错了。模型开始胡言乱语并不是因为它犯糊涂，而是因为它从一开始就没能拿到正确的上下文。

解决方案： 检查您的文档提取设置。

导航至：Admin Settings > Documents。
确保您选用的是更加稳健的外部解析引擎，如：
- Apache Tika
- Docling
- 自定义提取器（取决于您的文档格式）

提示

您可以尝试上传一份文档并点击预览提取出的纯文本内容。如果是空白或缺失了核心段落，您需要调整您的解析器设置或选用其他的引擎。

2. 仅有文档的极小一部分被使用

Open WebUI 默认被设计为能够兼容那些 context 窗口狭小的模型。例如，许多本地模型（如 Ollama 默认的模型）被限制在 2048 字符的 context 大小。由于这一限制，Open WebUI 会主动裁剪掉大部分检索出来的相关片段，以便其能强行塞入模型中。

解决方案：

导航至 Admin Settings > Documents。
选择以下操作之一：
- 启用 "Bypass Embedding and Retrieval"（绕过向量嵌入与检索） — 直接将全部的文档内容打包发送，而不运行任何检索过滤。
- 启用 "Full Context Mode"（全文本模式） — 将更全面的原始文档内容直接塞进提示词中。

注意

请务必留意模型自身的 context 限制——如果您的模型本身不支持长提示词，多出来的文本依然会被强行切掉。

3. Token 限制过短

即使检索正常工作，您的模型也可能无法处理其接收到的所有内容——因为它心有余而力不足。

在默认情况下，许多模型（特别是通过 Ollama 托管的本地 LLM）被强行限制在 2048 tokens 的 context 窗口。这意味着只有极小一部分召回片段能真正起到效果。

为什么网页搜索特别需要大 context 窗口支持： 网页在面对狭窄的 context 窗口时尤为吃力，因为网页往往包含了比纯文档臃肿得多的非关键数据。单个网页常常包括：

核心内容（您真正想要的文字信息）
导航菜单栏、页眉和页脚
侧边栏元素和广告内容
评论区域以及相关友情链接
元数据（Metadata）以及内嵌脚本

哪怕经过文本净化提取，网页的 token 占用也极其容易飙升至 4,000 到 8,000+。在 2048 tokens 的限制下，您其实连一半的信息都拿不到，甚至会直接漏掉出现在网页中底部的核心答案。甚至 4096 tokens 对于全面的网页文本分析而言也通常是捉襟见肘的。

解决方案：

针对 Ollama 模型：扩大模型的 context 长度参数：
- 导航至：Admin Panel > Models > Settings（选择您想要编辑的具体模型）
- 点击进入 Advanced Parameters（高级参数）
- 调大 context 长度（例如增大到 8192+，或者如果您的硬件和模型支持，理想情况下增大到 16000 字符以上）
针对 OpenAI 以及其他集成的外部 API 模型：这些外部模型通常有其自身固定的 context 上限，无法通过 Open WebUI 设置直接修改。请确保您选用的是本身就支持长 context 的模型版本。

2048 字符的默认参数是网页搜索极大的性能瓶颈。为了在网页检索中获得更好的 RAG 产出，建议至少设置 8192 tokens，对于复杂的长网页，16384+ tokens 是最佳的配置。

替代方案：使用具有更大 context 的外部托管 LLM（如 GPT-4o、Claude、Gemini 等，并配以 8K+ context）。对比它与本地模型的召回差异，可以直观地判定 Token 长度限制是否是影响效果的瓶颈。

提示

对于网页检索和复杂的文档深度分析，在生产环境下请确保选用支持 8192+ token context 的模型。

4. 嵌入向量模型质量低下或不匹配

糟糕的向量模型 = 糟糕的召回。如果文档内容的向量化映射效果很差，无论您的 LLM 底座有多强，检索器也无法帮您定位到正确的文字片段。

解决方案：

换用更高质量的向量模型（例如 all-MiniLM-L6-v2、Instructor X 或 OpenAI embeddings）
导航至：Admin Settings > Documents
切换模型后，请务必执行：重新索引所有现有的文档（reindex all existing documents），以确保新模型对全量数据生效。向量提取的质量高低直接决定了能够召回出什么内容。

5. 400: 'NoneType' object has no attribute 'encode' 错误

此错误指明了向量嵌入模型未正确配置或缺失。当 Open WebUI 试图对文本创建向量但未能加载有效的模型时，它将无法处理文本——进而抛出这一晦涩的报错。

常见诱因：

您的嵌入模型未配置妥当。
模型文件未完全下载成功。
或者如果您配置的是外部的嵌入模型，可能因为网络原因无法建立连接。

解决方案：

导航至：Admin Settings > Documents > Embedding Model
重新保存（Save）一次嵌入模型——哪怕它看起来已经被选中了。这会强行触发系统的重检与下载逻辑。
如果您使用的是远程/外部嵌入向量接口，请确保该接口服务运行正常且 Open WebUI 能够与其连通。

提示

修复配置后，尝试重新上传并向量化一份文档，确保在系统日志中不再输出该报错。

6. 上传限制与约束条件

Open WebUI 配备了多项限额机制以维护服务器的稳定。请了解这些限额在不同上传渠道下的具体应用：

对话内上传： 受到全局文件大小和数量的限制。
- 最大文件大小：由环境变量 RAG_FILE_MAX_SIZE 控制（默认无限制）。可在 Admin Panel > Settings > Documents > General > Max Upload Size 中配置。
- 最大文件数：由环境变量 RAG_FILE_MAX_COUNT 控制（默认无限制）。可在 Admin Panel > Settings > Documents > General > Max Upload Count 中配置。
- 允许的文件拓展名：由环境变量 RAG_ALLOWED_FILE_EXTENSIONS 控制（默认允许全部）。可在 Admin Panel > Settings > Documents > General > Allowed File Extensions 中配置。
文件夹上传： 受到 FOLDER_MAX_FILE_COUNT 环境变量的强行约束（默认限制为 100）。这会限制直接关联到某个文件夹下的最大文件数量。
知识库（Knowledge Base）上传：
- 文件大小限额：与对话上传一样，受到 RAG_FILE_MAX_SIZE 环境变量的约束；但它不受 RAG_FILE_MAX_COUNT 数量的限制，允许无上限地上传文件。
- RAG 逻辑应用：上传到知识库中的所有文件都会被自动进行向量化索引。但与对话上传类似，知识库也可以在**全文本模式（Full Context Mode）**下使用（可在聊天设置中找到），从而直接向模型喂入全文，而不走向量检索分流。

信息

通过分设这些限额，系统管理员可以在不同的功能入口中更细致地管理硬件资源的开销。例如，您可以允许在精心维护的共享“知识库”中上传大型的文档，而对普通用户在对话框内随手发起的临时文件夹上传设置数量上限。

7. 碎片化或微小的切片

在使用 Markdown Header Splitter（Markdown 标题切分器） 时，有时会把文档碎切成一些极端细小的片段（例如仅包含一个单独的目录项或简短的小标题）。这些袖珍切片因为字数太少，严重缺乏语义逻辑，导致向量模型无法对其生成高质量的语义向量表达，进而拖累 RAG 效果并徒增计算开销。

解决方案：

导航至 Admin Settings > Documents。
调大 Chunk Min Size Target（切片最小尺寸目标） 的值。
将其配置为如 1000（或大约为您的 CHUNK_SIZE 的 50-60% 左右）。系统会将那些极端碎小的段落与相邻的切片智能合并，实现更具语义连贯性的向量表示，并能有效精简切片总数。

8. 后续追问响应慢（KV 缓存失效）

如果您的首条对话响应很快，但随着对话轮次增加，系统的追问响应变得越来越卡顿缓慢，您大概率遇到了 KV 缓存失效（KV Cache Invalidation）。

问题根源：默认情况下，Open WebUI 会将 RAG 召回出来的上下文直接追加在**用户消息（user message）**中。随着对话进行，后续的新问题会不断把这一上下文的位置往后推移，迫使模型（如 Ollama、llama.cpp 或 vLLM）以及云端提供商（如 OpenAI、Vertex AI）在每一次交互时都必须重新计算这庞大上下文的注意力权重。

解决方案：

配置环境变量 RAG_SYSTEM_CONTEXT=True。
这会将 RAG 上下文改为注入到**系统消息（system message）**中，因为系统消息在每次交互中都始终雷打不动地处于整个对话的头部。
这样可以允许推理引擎完美利用其 **KV 前缀缓存（prefix caching）或提示词缓存（Prompt Caching）**机制，即使在处理几十页的长文档时，也能获得近乎秒回的追问体验。

遇到的具体问题	对应的技术修复方案
🤔 模型完全“看不到”内容	请检查并优化您的文档解析器（Extractor）设置
🧹 只有一小部分内容被读到	启用全文本模式（Full Context Mode）或绕过向量检索（Bypass Embedding）
⏱ 受到 2048 tokens 上限瓶颈制约	调大模型的 context 长度参数，或选用更长 context 的 LLM 底座
📉 召回极其不准确	切换到更高质量的 Embedding 模型，并对现有数据执行 Reindex 重新索引
❌ 无法突破文件上传限额限制	改用文件夹挂载方式（配合 `FOLDER_MAX_FILE_COUNT`）；或者利用知识库入口上传
🧩 召回片段极其碎裂/细小	调高 Chunk Min Size Target 尺寸以智能合并袖珍段落
🐌 越到后面的追问系统响应越慢	开启 `RAG_SYSTEM_CONTEXT=True` 环境变量以完美维护 KV 缓存
📄 API 接口报 "empty content" 错误	在将文件加入知识库之前，请先通过轮询确保异步文件提取已 100% 结束
💥 向量化时 CUDA 显存溢出（OOM）	调小 Batch 尺寸，将其绑定在独立的显卡上，或者重启对应的容器
📷 扫描版 PDF 中的文字无法被读取	请配置外部的 Tika/Docling 解析引擎，开启 OCR 功能，或升级 pypdf 库
💀 Worker 进程在上传时瞬间挂掉崩溃	在多 Worker 的部署下，请务必换掉 ChromaDB 默认的本地 SQLite 引擎
💀 Worker 进程在上传时因超时挂掉崩溃	升级您的 Open WebUI 版本，或者手动调高 `--timeout-worker-healthcheck` 参数
🧠 模型完全无视绑在身上的知识库	开启系统内置工具（Builtin Tools），在系统提示词中写明规则，或关闭原生工具调用

9. API 上传文件报错 "The content provided is empty"

当您通过 API 方式上传文档，并试图立刻将其归入某一知识库中时，可能会触发以下报错：

400: The content provided is empty. Please ensure that there is text or data present before proceeding.

问题根源：这其实是一个竞态条件（Race Condition），而非您的文件真的没有内容。默认情况下，文件的上传解析是异步执行的——上传接口会立即给您返回一个文件 ID，而后台提取文本和创建向量的流程还在悄悄跑着。如果您在后台流程彻底跑完前就把这个文件 ID 丢给知识库，系统就会误判定该文件不包含文本。

✅ 解决方案：轮询等待后台解析结束

在将文件归入知识库之前，请对状态查询接口发起轮询，直到状态标记为成功：

import requests
import 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.time()
    while time.time() - start_time < timeout:
        response = requests.get(url, headers=headers)
        status = response.json().get('status')
        
        if status == 'completed':
            return True
        elif status == 'failed':
            raise Exception(f"Processing failed: {response.json().get('error')}")
        
        time.sleep(2)  # 每 2 秒轮询一次
    
    raise TimeoutError("File processing timed out")

对应的状态值字典：

返回的 Status 值	代表的具体业务状态
`pending`	系统依然在后台火热解析中，请继续等待
`completed`	解析全部结束！此时可以安全将其塞入知识库
`failed`	后台提取报错失败（请查询对应的 error 字段）

提示

有关包含完善的状态轮询校验的完整 API 对接示例，请参阅 API 接口文档。

10. 向量嵌入时遇到 CUDA 内存溢出（OOM）

当大批量处理长难文档时，系统日志可能会输出以下 CUDA OOM 报错：

CUDA out of memory. Tried to allocate X MiB. GPU has a total capacity of Y GiB of which Z MiB is free.

常见诱因：

向量模型正在与主聊天对话模型疯狂抢占同一张显卡的显存。
PyTorch 频繁分配细小内存而引发了严重的显存碎裂。
极大型的文档在切片向量化时瞬间制造了内存尖峰。

✅ 解决方案：

将向量模型绑定在独立的显卡上（若有多卡资源）：通过配置 CUDA_VISIBLE_DEVICES 环境变量，将向量提取任务锁在另一张专用的显卡上，与主对话模型彻底隔开。
调小 Batch 批处理尺寸：降低 RAG_EMBEDDING_BATCH_SIZE 的参数（例如从 32 调小到 8 甚至 4），以平抑计算峰值显存。
启用 Expandable Segments 显存扩展段：通过配置以下环境变量以极大缓解 PyTorch 显存碎裂：
```
PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True
```
大体量吸纳任务完成后重启容器：如果因为碎裂导致显存无法回收，在大批量上传全部结束后，重启一次 Open WebUI 容器以彻底净化显存上下文。
换用更轻量的向量模型：在大体量吸纳阶段选用轻量的模型，待全部向量落库后，切换到高质量模型进行生产问答。
实现离线入库与在线对话分流：在大批量摄取期间暂时不要进行对话，待向量计算全部结束后，再拉起聊天对话模型。

10b. 429 请求超限错误

当开启了 ENABLE_ASYNC_EMBEDDING（异步向量化）并选用 远程/外部向量提供商（如 OpenAI、Azure 等）时，在大批量上传文档期间，系统日志中可能会持续输出 HTTP 429 "Too Many Requests" 报错：

Error generating embeddings: 429 Rate limit reached

问题根源：开启异步向量化后，Open WebUI 会同时发出海量的并发向量化请求。如果您的文档很多或体积庞大，这瞬间的超高并发会极易撑爆提供商给您的账号设定的 API 访问限频（尤其是处于低级套餐或免费额度的账户）。

✅ 解决方案：

给最大并发向量化请求量加锁：通过设置 RAG_EMBEDDING_CONCURRENT_REQUESTS 环境变量，硬性规定同一个时间点能够发起的最大 API 并发数。例如，根据您的账号级别将其配置为 5 或 10：
```
# docker-compose.yaml 示例
environment:
  RAG_EMBEDDING_CONCURRENT_REQUESTS: 5
```
或者直接在 Admin Panel > Settings > Documents > Concurrent Requests 界面表单中配置。默认值为 0 代表无上限并发。
降低 Batch 尺寸：调小 RAG_EMBEDDING_BATCH_SIZE 可以在单次 API 请求中发送更少的文本段。
暂时关闭异步向量化功能：如果限频依然顽固，请将 ENABLE_ASYNC_EMBEDDING 环境变量强行配为 False。虽然这样处理会变慢，但能确保逐条串行入库，彻底免除超额限频的风险。

11. PDF OCR 无法提取图像中的文本

如果上传的 PDF 中，以图片形式展现的文字无法被正确读取：

问题根源：Open WebUI 默认搭载的 "pypdf" 解析引擎对纯图片版 PDF（如扫描件）毫无招架之力，无法从底层的图像数据中抠出文本。

✅ 解决方案：

切换到更强力的外部文档解析引擎：
- 导航至 Admin Settings > Documents
- 尝试选用 Apache Tika 或 Docling 解析引擎，它们能提供极其强大的 OCR 算法支持
确保 PDF 图层识别已开启：
- 在 Admin Settings > Documents 界面下，确保 PDF Extract Images (OCR) 选项已被勾选并保存
将 pypdf 升级至最新版（如果您依然坚持想使用默认解析器）：新版的 pypdf 库（6.0.0+）已经对一些特定 PDF 格式的图片提取进行了体验修复
排除损坏的 PDF 原始文件：在上传之前，请先通过本地的标准阅读器打开该 PDF，以确认文件本身未发生损坏

12. 上传文档时 Worker 挂掉崩溃

在配置了多 Worker 进程的部署环境下，上传文件时，日志中可能会突发输出以下崩溃行：

INFO:     Waiting for child process [12]
INFO:     Child process [12] died

在多 Worker 的架构设计下，引发该崩溃的原因其实有 两种截然不同 的技术诱因：

原因 A：ChromaDB SQLite + Fork 派生进程（瞬间崩溃）

如果您在配置 UVICORN_WORKERS > 1 的同时，依然在沿用 ChromaDB 默认的本地模式（该模式使用的是底层依赖于 SQLite 的 PersistentClient 文件锁机制），该崩溃是由于 SQLite 本身不符合 fork 安全机制而引发的。当 uvicorn 派生出多个 Worker 进程时，所有的子进程都会强行继承同一个 SQLite 数据连接。只要有多个 Worker 试图在同一个瞬间向向量库写入数据，SQLite 的文件锁就会在多进程间崩溃死锁，进而导致进程被瞬间杀死——没有任何缓冲和超时，崩溃是瞬间触发的致命错误。

您通常会在同一秒内看到如下的死锁日志特征：

save_docs_to_vector_db:1619 - adding to collection file-id
INFO:     Waiting for child process [pid]
INFO:     Child process [pid] died

解决方案： 如果您决定运行多 Worker，您必须将 ChromaDB 默认的本地模式换掉：

将 VECTOR_DB 环境变量配置为专用的 pgvector、mariadb-vector、milvus 或 qdrant 架构。
或者将 ChromaDB 以独立的 HTTP 容器方式跑起来，并给 Open WebUI 配置 CHROMA_HTTP_HOST 以及 CHROMA_HTTP_PORT。

详情请参阅多副本与高可用指南。

原因 B：SentenceTransformers 健康检查超时（较旧版本）

当选用 SentenceTransformers 默认的本地嵌入引擎 配合多 Worker 运行时，uvicorn 底层会通过周期性 ping 操作来监控各子进程的健康度。系统默认的健康检查超时时长仅仅是短得可怜的 5 秒。在较旧的 Open WebUI 版本中，向量计算会把整个主事件循环彻底堵死——导致 Worker 根本无暇顾及并响应 uvicorn 发起的健康检查 ping。于是 uvicorn 就会粗暴地认为该 Worker 已丧失响应能力，强行将其直接杀死。

备注

这一技术顽疾在 Open WebUI 的后续更新中已得到了完美修复。新的向量计算底座引入了 run_coroutine_threadsafe 机制，可以在向量计算执行时完美分流，维持主事件循环畅通无阻，因而无论向量化任务多么庞大耗时，Worker 都绝不会再被健康检查机制误杀。

如果您所使用的版本已经包含了此项体验修复但依然遇到进程死掉，请优先排查上面的 原因 A（即 ChromaDB 在本地 SQLite 上的锁竞争），并确保您的 Open WebUI 已更新到最新版本。

此问题的典型受影响范围：

仅当您依然在使用 SentenceTransformers 默认的本地嵌入引擎 提取向量时。
仅当您配置了 多 Worker 运行参数。单 Worker 部署下不存在此类健康检查超时死锁。
使用外部 API 向量提取提供商（如 Ollama、OpenAI、Azure）的部署完全不受此问题影响，因为网络 API 交互本就以异步方式运行，绝不会堵塞主事件循环。

✅ 针对未升级的旧版本的技术规避方案：

升级 Open WebUI 至包含 run_coroutine_threadsafe 修复的高版本。

手动调大健康检查的超时容忍阈值作为临时的损害控制：

# docker-compose.yaml 示例
command: ["bash", "start.sh", "--workers", "2", "--timeout-worker-healthcheck", "120"]

切换到外部的向量提取服务，以从根本上杜绝本地内存与主循环的竞争：
```
RAG_EMBEDDING_ENGINE=ollama
RAG_EMBEDDING_MODEL=nomic-embed-text
```
可以考虑通过配置 RAG_EMBEDDING_TIMEOUT 环境变量，为那些严重偏离正常耗时的异常向量操作强行设定一个保护性中止阈值（该参数不会对健康检查造成干扰）。

13. 绑定在模型上的知识库未生效

您已经在 Workspace > Models > Edit 中将一个知识库挂载到了特定的模型上，但在与该模型对话时，它似乎对该知识库的内容一无所知。

问题根源：Open WebUI 提供了两种截然不同的 RAG 运作模式，它们对模型绑定的知识库的处理机制有着天壤之别：

不同的 RAG 运行模式	知识库在此模式下的运作机制
默认（非原生）模式	Open WebUI 在底层自动替您跑完 RAG 逻辑——系统会自动检索绑定的知识库，提取相关的文本切片，并在生成前直接强行注入到对话上下文（Context）中。这一系列操作属于无感注入，模型自身并不需要知道工具的存在。
原生工具调用（Native Function Calling）模式	上下文不会被自动强行注入。相反，模型会在启动时直接得到专用的检索工具（如 `query_knowledge_bases`），并必须在对话中自主做出决策去调用该工具。这属于智能体化（Agentic）RAG——由模型决定是否需要检索，以及用什么关键词检索。

如果您的模型开启了原生工具调用（Native Function Calling），模型就必须同时具备调用该工具的能力（Ability）与明确的指令引导（Instruction）。

知识库检索行为矩阵

RAG 运行模式分类	模型关联了特定知识库	模型没有关联任何知识库
默认（非原生）模式	Open WebUI 在底层自动且强制注入且仅注入这些被绑定的知识库里的检索片段	没有任何自动检索发生——用户必须手动在对话框里通过敲击 `#` 挂载对应的知识库
原生工具调用模式	模型获取的查询工具范围被死死锁定在这几个绑定的知识库内——模型必须自主调用工具进行查询	模型获取的查询工具拥有访问全量公开知识库的权限（前提是 Builtin Tools 被开启）——模型必须自主调用工具进行查询

核心技术要点：在原生（Native）模式下（官方推荐的未来演进方向），无论如何模型都必须使用其检索工具——将知识库绑定至模型，只是起到限定哪些知识库可以被该模型查到的安全隔离作用。默认（非原生）模式下的底层强行注入逻辑此处仅为遗留部署的兼容说明；非原生模式正逐步退出历史舞台，建议所有的模型都切换到原生（Native）模式下运行。

在原生模式下完美隔离知识库读取权限

如果您想让某个特定模型在原生模式下彻底丧失对所有知识库的读取权限，您其实并不需要连带把内置工具（Builtin Tools）一窝端。您只需在 Workspace > Models > Edit > Builtin Tools 选项卡下，将 Knowledge Base 这一细分分类单独关闭即可。这样处理可以在保留网页搜索、计算器、备忘录等其他内置功能的同时，干净地剥离知识库相关的全部工具权限。

✅ 技术排查步骤（请按顺序诊断）：

优先诊断全局模型参数覆盖（Global Model Settings Override）：
- 导航至 Admin Panel > Settings > Models > ⚙️（齿轮图标）
- 展开 Model Parameters 选项，检查 Function Calling 字段是否被全局配置为了 native
- 如果是，这会霸道地覆盖所有模型——即便您最初可能并没有想让特定的轻量模型去执行原生调用
- 您需要将此全局选项改回 default，或者在遇到问题的模型的 Advanced Params per-model 高级参数中，显式配置覆盖掉这一全局行为
- 同时移步 Model Capabilities 部分检查——如果全局把 File Context（文件上下文权限）关掉了，那么凡是未显式开启它的模型都将无法进行文件处理

全局设置霸道覆盖提示

此问题最常见的原因在于管理员在 Admin Panel > Settings > Models > ⚙️ > Model Parameters 中配置了全局 Function Calling: native。这会在无形中强行绑架所有的模型。每个模型的单独设置（位于 Workspace > Models > Edit > Advanced Params 下）能够覆盖此全局默认值，但也只有在被显式配置时才会生效——如果一个模型本身未设置此参数，它会直接顺从全局的默认设定。

确认模型的 Built-in Tools 权限已被下发（如果您选用的是 native 模式）：
- 导航至该模型的 Workspace > Models > Edit 界面
- 在 Builtin Tools 分类列表下，确保 Knowledge Base 这一分类确实处于启用状态（默认是开启的）
- 如果该细分分类被关闭了，模型将根本无法调度针对任何知识库的查询工具
在系统提示词中追加提示（System Prompt Hint）（如果您选用的是 native 模式）：
- 许多底座模型需要清晰的行动指南才知道如何利用它们的工具。建议在其系统提示词中追加如下清晰的指令：
  
  "When users ask questions, first use list_knowledge_bases to see what knowledge is available, then use query_knowledge_bases to search for relevant information before answering." （“当用户提出问题时，请优先调用 list_knowledge_bases 工具来探查有哪些可用的知识库，随后调用 query_knowledge_bases 工具检索出关键的上下文资料，再进行针对性的解答。”）
为该模型降级回传统的非原生模式：
- 如果模型太轻量无法理解工具调用，直接在模型的高级设置中将 Native Function Calling 关掉，以退回到旧版那种由 Open WebUI 底层替它进行 RAG 强行注入的传统模式
或者直接在对话里选用全文本模式（Full Context Mode）：
- 在聊天框内点击已挂载的知识库，直接将其使用方式变更为 "Use Entire Document"（使用整篇文档）
- 这会直接跳过向量检索召回逻辑，无论您的 Native Function Calling 开启与否，都会直接强行将全文打包喂给模型

为什么会发生此演进？

Open WebUI 目前正大力朝向**智能体化 RAG（Agentic RAG）**方向上演化。在这种模式下，模型可以根据第一轮检索出来的片段质量，自主决定是否需要使用不同的关键词进行二次或多次检索，直到其满意为止，这比传统的“由系统底层死板地强行灌入一段内容”具有大得多的应用上限。但这也对模型底座自身的工具调用能力提出了硬性的要求。如果您用的是一些较小或较旧、无法很好理解工具的模型，直接为其关掉 Native Function Calling 将是更务实且能够获取 RAG 效果的策略。

关于知识库检索范围隔离及具体运作模式的深度原理解析，请参阅知识库文档以及文件上下文与内置工具差异解析。

通过在文档提取、向量创建、召回微调以及模型 Context 尺寸这四个维度上进行全面针对性的优化，您可以成倍地改善您的大语言模型在应对业务文档时的准确性表现。

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.

针对不同场景的推荐配置​

针对 context 受限（≤ 8K tokens）的本地模型​

针对拥有大 context（32K+ tokens）的云端模型​

混合部署环境（本地 + 云端）​

向量嵌入模型推荐​

常见 RAG 问题及修复方法​

1. 模型“看不到”您的内容​

2. 仅有文档的极小一部分被使用​

3. Token 限制过短​

4. 嵌入向量模型质量低下或不匹配​

5. 400: 'NoneType' object has no attribute 'encode' 错误​

6. 上传限制与约束条件​

7. 碎片化或微小的切片​

8. 后续追问响应慢（KV 缓存失效）​

9. API 上传文件报错 "The content provided is empty"​

10. 向量嵌入时遇到 CUDA 内存溢出（OOM）​

10b. 429 请求超限错误​

11. PDF OCR 无法提取图像中的文本​

12. 上传文档时 Worker 挂掉崩溃​

原因 A：ChromaDB SQLite + Fork 派生进程（瞬间崩溃）​

原因 B：SentenceTransformers 健康检查超时（较旧版本）​

13. 绑定在模型上的知识库未生效​

知识库检索行为矩阵​

针对不同场景的推荐配置

针对 context 受限（≤ 8K tokens）的本地模型

针对拥有大 context（32K+ tokens）的云端模型

混合部署环境（本地 + 云端）

向量嵌入模型推荐

常见 RAG 问题及修复方法

1. 模型“看不到”您的内容

2. 仅有文档的极小一部分被使用

3. Token 限制过短

4. 嵌入向量模型质量低下或不匹配

5. 400: 'NoneType' object has no attribute 'encode' 错误

6. 上传限制与约束条件

7. 碎片化或微小的切片

8. 后续追问响应慢（KV 缓存失效）

9. API 上传文件报错 "The content provided is empty"

10. 向量嵌入时遇到 CUDA 内存溢出（OOM）

10b. 429 请求超限错误

11. PDF OCR 无法提取图像中的文本

12. 上传文档时 Worker 挂掉崩溃

原因 A：ChromaDB SQLite + Fork 派生进程（瞬间崩溃）

原因 B：SentenceTransformers 健康检查超时（较旧版本）

13. 绑定在模型上的知识库未生效

知识库检索行为矩阵