📚 知识库
让您的 AI 访问文档，并找到最相关的内容。
知识库是您存储 AI 可以搜索、阅读和推理的文件和集合的地方。上传 PDF、电子表格、代码或任何基于文本的文档。围绕项目、团队或主题构建集合。当模型需要答案时，它会从您的知识库中提取，而不是靠猜测。
与将全部内容注入每条消息的笔记不同，知识库使用检索（RAG）按需找到相关片段。这使其成为注入所有内容会超出上下文窗口的大型文档集的正确选择。
为什么使用知识库？
您的文档变得可由 AI 搜索
上传一批合同、技术规格或研究论文。AI 按语义而非仅仅关键词搜索它们，并引用答案的来源。
满足不同需求的两种检索模式
选择专注检索（RAG）让 AI 高效搜索大型集合，或选择全文上下文在精度重要时逐字注入整个文档。
通过原生函数调用自主探索
启用原生函数调用后，模型不只是搜索。它们可以浏览您的知识库、逐页阅读文件，并在没有手动提示的情况下跨多个文档综合内容。
有序范围访问
将特定知识库附加到模型，使其只搜索相关内容。或不附加，让模型发现用户有权访问的所有内容。
主要功能
| 📄 9 种向量数据库 | ChromaDB 和 PGVector（官方维护），以及社区选项：Qdrant、Milvus、OpenSearch、Elasticsearch 等 |
| 🔍 混合搜索 | BM25 关键词搜索 + 向量搜索，配合交叉编码器重排序 |
| 📑 5 种提取引擎 | Tika、Docling、Azure、Mistral OCR、自定义加载器 |
| 🤖 智能体检索 | 模型自主浏览、搜索和阅读您的文档 |
| 📄 全文上下文模式 | 无分块地 注入整个文档 |
| 🗂️ 嵌套目录 | 用子目录组织文件，支持拖放重排 |
| 🔄 增量目录同步 | 把本地文件夹镜像到知识库，只上传新增和修改过的文件，删除的内容会被移除，目录结构得以保留。也可镜像远程源（Git、Confluence、S3 等），使用 oikb |
| 📦 导出和 API | 将知识库备份为 zip 文件，通过 REST API 管理 |
检索模式
将文件或知识库附加到模型时，点击已附加项在两种模式之间切换：
🔍 专注检索（默认）
使用 RAG 根据用户查询找到并注入最相关的片段。当启用混合搜索（ENABLE_RAG_HYBRID_SEARCH）时，检索结合了 BM25 关键词搜索和向量搜索，以及用于准确性的重排序。
最适合只有特定部分相关的大型文档集。
📄 全文上下文
将文件的完整内容注入每条消息。无分块，无语义搜索。无论原生函数调用设置如何，始终注入 ，因此模型无需调用任何工具来访问它。
最适合简短的参考文档、风格指南，或始终相关的上下文。
智能体知识工具
启用原生函数调用后，模型使用内置工具与您的知识库交互。显示哪些工具取决于是否有特定知识库附加到模型：
| 工具 | 已附加知识库 | 未附加知识库 | 说明 |
|---|---|---|---|
list_knowledge | ✅ | ❌ | 列出附加到模型的知识库（带文件数量）、独立文件和笔记；传入 knowledge_id（含 skip/count，最多 200）可分页查看单个知识库的文件 |
list_knowledge_bases | ❌ | ✅ | 浏览可用知识库（带文件数量） |
search_knowledge_bases | ❌ | ✅ | 按名称或描述查找知识库 |
query_knowledge_bases | ❌ | ✅ | 通过语义相似度搜索知识库名称/描述 |
search_knowledge_files | ✅（有范围） | ✅（全部） | 按文件名搜索文件 |
query_knowledge_files | ✅（有范围） | ✅ | 使用 RAG 流水线搜索文件内容 |
grep_knowledge_files | ✅（有范围） | ✅ | 在知识库文件中进行精确文本/正则搜索（返回带行号的匹配行；自动检测正则如 error|warn） |
view_file | ✅ | ❌ | 分页读取文件内容（offset/max_chars）或按行号范围（start_line/end_line，可选 line_numbers）读取 |
view_knowledge_file | ✅ | ✅ | 从任何可访问的知识库读取文件内容 |
view_note | ✅ | ❌ | 读取附加的笔记 |
关键区别：list_knowledge 和 list_knowledge_bases 互斥。附加知识库会将模型范围限定为只处理那些文档。不附加则让模型发现用户有权访问的所有内容。
何时优先使用 grep_knowledge_files 而非 query_knowledge_files
两个搜索工具互为补充：
query_knowledge_files | grep_knowledge_files | |
|---|---|---|
| 匹配方式 | 语义/向量检索（启用 ENABLE_RAG_HYBRID_SEARCH 时可叠加 BM25 + 重排序） | 精确字符串匹配——自动检测正则（如 error|warn、version \d+） |
| 返回内容 | 相关内容片段 | 带文件 ID、文件名和 1 起始行号的匹配行 |
| 适用场景 | “文档里关于 X 怎么说的？”——改写后的问题、概念性查找 | “找出所有提到 OPENAI_API_KEY 的地方”——字面标识符、错误字符串、版本号 |
| 结果上限 | Top K（默认 5） | 50 条匹配 |
| 标志 | — | case_insensitive、count_only、file_id（单文件模式） |
在智能体流程中，典型的模式是：用 query_knowledge_files 定位相关文档，然后用 grep_knowledge_files 精确定位具体行，再用 view_file（下方行号范围模式）阅读周边上下文。
用 view_file 读取
view_file 支持两种寻址模式：
- 字符分页 —
offset+max_chars（默认10000，硬上限100000）。最适合流式浏览长文档；当文件被截断时响应中会包含next_offset。 - 行号范围 —
start_line+ 可选end_line（1 起始，包含两端）。设置后覆盖offset/max_chars；与grep_knowledge_files的行号天然搭配。传line_numbers: true还会在每行前加上<n>: <line>前缀。
行号范围响应包含 total_lines、showing_lines 和 next_start_line，便于继续读取。
类文件系统访问（kb_exec）
设置 ENABLE_KB_EXEC=True 后，Open WebUI 会暴露一个 kb_exec 工具，为模型提供对知识库的类文件系统接口。
被移除的工具（其功能已被 kb_exec 命令覆盖）：
list_knowledge—— 由ls替代search_knowledge_files—— 由find "<glob>"替代grep_knowledge_files—— 由grep "<pattern>"替代view_file和view_knowledge_file—— 由cat、head、tail、sed -n '<a>,<b>p'替代
仍然与 kb_exec 并存注入的工具（因其能做 kb_exec 做不到的事）：
query_knowledge_files—— 语义/RAG 搜索（始终保留）view_note—— 当笔记被附加到模型时（kb_exec只处理文件，所以笔记需要专用读取器）query_knowledge_bases和search_knowledge_bases—— 当没有知识库附加到模型时，让模型仍能按名称/ 描述发现并搜索知识库
该功能默认关闭且仍处于实验阶段，但为了获得增强的智能体 RAG 体验，我们建议为运行原生函数调用的强模型启用它（ENABLE_KB_EXEC=True）。它面向的是那些已经“用 Shell 思考”的前沿模型：相比编排一系列专用工具的扇出，它们往往更可靠地串联 ls、grep 和 cat。它只在使用原生函数调用时生效；在默认模式下没有效果。
支持的命令
| 命令 | 用途 |
|---|---|
ls、ls <dir>/、ls -a | 列出当前层级 / 子目录 / 包含完整路径的扁平文件视图 |
tree、tree <dir>/ | 递归目录树 |
cat -n <file> | 读取文件（可选带行号） |
head -N <file> / tail -N <file> | 前 N 行或后 N 行 |
sed -n '<a>,<b>p' <file> | 输出第 <a> 到 <b> 行 |
grep "<pattern>" [<dir>/|<file>|*.ext] | 精确/正则搜索；标志 -i（不区分大小写）、-l（仅文件名）、-c（计数） |
find [<dir>/] "<glob>" | 按 glob 查找文件 |
wc <file> | 行/词/字符计数 |
stat <file> | 文件元数据 |
管道
kb_exec 解析单个流水线，因此命令可以组合：
grep "auth" | head -5
grep -l "TODO" docs/
find docs/ "*.md" | head -10文件引用
文件可以用三种方式寻址——选择最明确的那种：
- 路径 ——
docs/api/auth.md（相对于知识库根目录；可穿透目录树解析） - 文件名 ——
auth.md（当多个目录或知识库中存在同名文件时，会以“模糊的文件名”提示报错） - 文件 ID ——
ls、find或grep返回的 UUID
行为说明
kb_exec遵循与其他知识工具相同的访问控制——用户无法读取的文件会被静默地从结果中排除。- 模型仍保留
query_knowledge_files用于语义搜索；在字面命令无法找到改写后的概念时使用。 - 构建于目录模型之上——
kb_exec是唯一完整体现 UI 中创建的目录结构的工具。
自主探索在能够智能链接搜索、浏览和综合的前沿模型上效果最佳。较小的模型可能难以处理多步检索。管理员可以在工作区 > 模型 > 编辑 > 内置工具中按模型禁用知识库工具类别。
在混合知识库之间引导工具选择
启用 kb_exec 后，模型需要在两个互补的工具间选择。最简单的做法是写一段简短的系统提示词，按知识库指明应优先使用哪个工具：
- 散文与 PDF 适合用
query_knowledge_files（语义搜索）。它按意义匹配，对改写后的问题和文档处理得很好，且不依赖干净的文本提取。 - 文本文件、代码、配置和日志 适合用
kb_exec（ls、tree、grep、cat、按行号读取）。模型可以遍历目录树并拉取确切行，在字面标识符、错误字符串和结构方面胜过语义搜索。
一个按知识库明确这一划分的提示词能引导模型做出正确选择，同时仍允许它对每次调用做判断：
附加了两个知识库。Handbook 是 PDF 文档：有关它的问题请用
query_knowledge_files。Codebase 是源代码：使用kb_exec（grep、cat、ls）查找并读取精确代码。一般来说，对精确字符串、标识符和文件结构优先用kb_exec，对概念性问题优先用query_knowledge_files。
没有 kb_exec 时，同样的区分也适用于 grep_knowledge_files 和 query_knowledge_files。
有关所有内置智能体工具的完整列表，请参阅原生/智能体模式工具指南。
启用原生函数调用时，附加的知识库不会自动注入。模型必须调用知识工具来搜索和检索。如果您的模型未使用附加的知识库：
- 添加系统提示词指令，告诉模型使用
list_knowledge和query_knowledge_files。 - 禁用该模型的原生函数调用，恢复自动 RAG 注入。
- 将附件切换为全文上下文模式，完全绕过 RAG。
设置知识库
- 点击侧边栏中的工作区，然后选择知识库。
- 点击 + 新建知识库，输入名称和描述。
- 上传文件或添加现有文档。
- 在工作区 > 模型 > 编辑中将知识库附加到模型，或在对话中用
#引用它。
组织为目录
知识库支持嵌套的目录，让大型文档集保持可导航。从添加内容菜单（+ 新建目录）创建，然后自由重组。
创建与导航
- + 新建目录 位于添加内容菜单中， 与文件上传并列。同一父目录下强制名称唯一——两个同级不能同名，但不同父目录下可以重用名称。
- 点击目录可进入下一层；视图顶部的面包屑导航始终反映当前路径，可一键跳回任意上级。
- 目录可以重命名或移动到其他父目录，里面的文件不受影响。
拖放
你可以通过拖放来移动条目：
- 文件 可以拖到目录行上、打开目录的空白区域上，或任意面包屑上（包括根面包屑，可将文件送回顶层）。
- 目录 可以拖到另一个目录上以嵌套，或拖到面包屑上以向上移动。把目录移入自身或其后代会被服务端阻止。
删除语义
删除非空目录时会提示如何处理其中的内容：
- 将文件移到父目录（默认）—— 目录被移除，但其文件和子目录会上移一层。
- 删除全部 —— 永久删除该目录及其下所有文件和子目录。
对检索和工具的影响
- 检索与标准 RAG 仍然覆盖整个知识库。目录不会切分向量索引；任意子目录中的片段在单次搜索中仍然可达。
- 智能体工具 具有目录感知能力：
kb_exec（启用时）把子目录当作文件系统：ls docs/、tree、grep "x" docs/、以及路径式引用（docs/api/auth.md）都可用——参见下方的类文件系统访问（kb_exec）。- 其他知识工具（
query_knowledge_files、grep_knowledge_files、search_knowledge_files）忽略目录边界，从整个知识库返回匹配结果。
重命名文件
单个文件可以在工作区中通过文件项菜单原地重命名——无需重新上传。新名称会在所有引用该文件的地方（知识库列表、智能体工具输出、引用）反映出来。
同步本地目录
添加内容 → 同步目录 操作会增量地把本地文件夹镜像到知识库：客户端对每个本地文件做哈希（SHA-256），服务端将哈希和路径与已存储内容对比，只处理新增、修改和已删除的文件。未修改的文件（通常是大多数）原样保留——不会重新上传或重新嵌入。本地文件夹的子目录结构会镜像到知识库中；缺失的子目录会被创建，本地不再存在的子目录会被移除。
应用内的同步目录运行在浏览器中：它在客户端枚举、哈希并上传每个文件。对中等规模的文件夹没问题，但面对大量文件（数千个文件或数 GB 的资料库）时会变慢且进度反馈很少，常常要等很久才开始报告文件数。对于大型或频繁变化的资料库，我们强烈推荐使用官方的 Knowledge Base Sync (oikb) 工具：它以原生方式运行，带进度条、并行上传和重试，正是为这种场景设计的。把入口指向文件夹根，它会同步整棵树（每个子目录，递归）到一个知识库。
需要了解的行为：
- 隐藏文件和文件夹（以
.开头的任何内容）会被跳过。 - 本地修改过的文件会以新的内容哈希上传；旧的文件条目会从知识库中移除并替换。
- 本地删除的文件会在清理步骤中从知识库中删除。
- 该操作对未修改的文件是非破坏性的。早期版本中的相同菜单操作曾会清空并重新上传所有内容——自 v0.9.6 起已不再如此。
对于编程使用，相同的工作流通过下方的API 访问中两个端点暴露。
应用内的同步目录操作处理的是你机器上的本地文件夹。要镜像远程源（GitHub 仓库、Confluence 空间、S3 桶以及更多），或按计划/在每次推送时自动保持知识库最新，请使用官方的 Knowledge Base Sync (oikb) 配套工具。它会驱动这些相同的端点来完成任务。
导出
管理员可以通过项目菜单（三点）> 导出将整个知识库导出为 zip 文件。文件转换为 .txt 以确保通用兼容性。普通用户不会看到导出选项。
API 访问
知识库可以通过编程方式管理：
文件
POST /api/v1/files/— 上传文件。在上传元数据中传入knowledge_id（可选directory_id）会让后端自动关联并处理该文件到指定知识库——等价于随后调用POST /api/v1/knowledge/{id}/file/add，但不依赖上传后客户端保持连接。这是推荐的单次调用路径（v0.9.6 引入，修复了上传者中途断开导致文件未关联的问 题）。服务端会将上传字节做 SHA-256 哈希存入file.meta.file_hash；客户端可以预先计算并通过元数据传入file_hash以跳过服务端哈希（增量同步流程会用到）。GET /api/v1/files/{id}/process/status— 检查处理状态POST /api/v1/files/{id}/rename— 重命名文件POST /api/v1/knowledge/{id}/file/add— 向知识库添加文件POST /api/v1/knowledge/{id}/file/move— 在同一知识库内移动文件到其他目录（body：file_id、directory_id——null表示移到知识库根目录）
目录
POST /api/v1/knowledge/{id}/dirs/create— 创建目录（body：name，可选parent_id）POST /api/v1/knowledge/{id}/dirs/{dir_id}/update— 重命名或重新归属目录（body：name和/或parent_id）DELETE /api/v1/knowledge/{id}/dirs/{dir_id}/delete?move_files=true— 删除目录。move_files=true（默认）时，目录内文件会上移；move_files=false时，连同目录一起被删除。
增量目录同步（v0.9.6 引入）
POST /api/v1/knowledge/{id}/sync/diff— 提交本地清单（manifest: [{path, filename, checksum}]，其中checksum是文件字节的 SHA-256），返回{added, modified, deleted, mkdir, rmdir, unmodified_count}描述要上传、替换、删除的内容，以及要创建/移除的目录。只读——不会修改知识库。- 在按 diff 操作后（创建
mkdir路径，通过POST /api/v1/files/上传added+modified文件并附带哈希），调用： POST /api/v1/knowledge/{id}/sync/cleanup— body：{file_ids: [...], dir_ids: [...]}。移除陈旧的文件（从知识库、向量存储和每文件集合中）以及sync/diff返回的现已为空的目录。请最后运行，避免删除赶在上传之前。
文件处理是异步的。在将文件添加到知识库之前，必须轮询状态端点直到处理完成，否则会收到“内容为空”错误。有关工作流示例，请参阅 API 端点。
使用场景
项目文档
将团队的技术规格、架构文档和操作手册上传到知识库。将其附加到“项目助手”模型。AI 根据您的实际文档回答问题，而不是通用的训练数据。
法律和合规审查
加载合同、政策和监管文件。让 AI 查找特定条款、比较协议间的条款，或标记不一致之处。
研究综合
将数十篇论文添加到知识库。AI 在所有论文中搜索以回答问题、找到支持证据，或识别研究之间的矛盾。
局限性
全文上下文模式的上下文窗口
“使用整个文档”会注入全文。将大型文档附加到上下文窗口较小的模型，将会挤占对话历史。
API 上传的处理延迟
通过 API 上传的文件是异步处理的。在处理完成之前尝试使用文件将会静默失败或返回空结果。请注意，使用 knowledge_id 上传（见上）只是让关联在服务端完成、且对客户端断开更具鲁棒性，但并不意味着内容可以即时查询——提取和嵌入仍在后台运行，所以在依赖检索之前请轮询 GET /api/v1/files/{id}/process/status。
原生函数调用改变行为
启用原生函数调用会改变知识库的工作方式。如果你的知识库突然停止产出结果，请检查全局模型默认值中是否设置了 function_calling: native。详情请参阅知识库故障排查。