创建并使用知识库

这份教程带你创建一个 Milvus 知识库，上传一份文档，完成解析和索引，再让智能体回答文档中的问题。

开始前请完成快速开始，使用完整模式，并准备：

• 一个可用的聊天模型和嵌入模型；
• 一份不含敏感信息的测试文档；
• 一个管理员账号。

Dify、Notion 连接器、知识库管理 API 和图谱运维见知识库管理与 API 参考。

你会得到什么

完成后，知识库详情页中的文件应处于 indexed，检索测试应返回带来源的片段，配置了该知识库的智能体也能根据同一份文档回答问题。

选择知识库类型

类型	能做什么	适用场景
Milvus	上传、解析、索引和检索文档；支持知识导图和知识图谱	自建文档知识库
Dify	调用 Dify Dataset 的检索接口	复用已有 Dify 数据集
Notion	调用 Notion Data Source 的检索接口	复用已有 Notion 内容

Dify 和 Notion 是只读连接器，不能在 Yuxi 中上传、解析、索引或预览文档全文。本教程使用 Milvus。

1. 创建知识库

登录 Web 界面，进入“知识库”，点击“新建知识库”：

1. 填写名称和描述。
2. 选择 Milvus。
3. 选择嵌入模型和分块策略。
4. 设置读取范围和管理范围。
5. 保存并打开详情页。

知识库描述会帮助智能体判断何时检索它，建议写清资料主题、适用问题和不包含的内容。管理范围必须包含在读取范围内。

创建成功后，详情页会显示名称、类型和空文件列表。创建失败时先检查嵌入模型，再继续后面的上传步骤。

2. 上传并处理文档

在知识库详情页点击“上传”，选择测试文档并设置 OCR、解析器和分块参数。勾选“上传后自动入库”可以在解析完成后继续建立索引；不勾选时，解析和索引分开操作。

上传完成后点击“添加到知识库”。系统会创建文件记录并提交解析任务，在任务中心可以看到进度。文件状态表示具体阶段：

状态	含义	下一步
uploaded	原文件已上传，尚未完成解析	继续添加或提交解析
parsed	Markdown 已生成，可以建立索引	提交入库
indexed	分块和向量索引已完成	可以检索
error_parsing	解析失败或被取消	查看错误，调整 OCR 或解析参数后重试
error_indexing	分块、嵌入或存储失败	检查模型和参数后重新入库

不使用自动入库时，等文件变为 parsed，选择文件并提交入库。使用自动入库时，等待同一任务继续完成，最后确认状态变为 indexed。任务中心的“成功”只表示任务编排结束，文件状态和存储结果才是阶段完成的依据。

解析器和 OCR 的选择见文档处理与 OCR；状态、存储和恢复边界见知识库机制详解。

3. 验证检索

打开知识库详情页的“检索测试”，输入一个只有测试文档能回答的具体问题。成功结果至少应包含：

• 相关文本片段；
• 文件来源；
• file_id。

更可靠的做法是在测试文档中加入一个不含敏感信息的唯一短语，再用这个短语提问，并确认结果来自目标文件。宽泛问题可能命中模型常识或其他文档，不能单独证明知识库已经生效。

没有结果时，依次检查文件是否为 indexed、嵌入模型是否可用、分块参数是否合适，以及检索配置是否返回了足够的候选结果。

4. 设置共享范围

在“访问权限”中分别设置读取范围和管理范围。范围可以是全局、指定部门或指定用户。创建者和 superadmin 具有管理权限；其他用户必须同时命中相应范围，admin 角色也不会自动获得所有部门或指定用户知识库的权限。

保存后，用一个不在读取范围内的账号确认知识库不会出现在列表中，再用范围内账号确认可以检索。前端隐藏入口不是权限证明，最终结果以后端列表和检索请求为准。

5. 让智能体使用知识库

进入“智能体”配置，完成两项设置：

1. 在“知识库”中选择刚创建的知识库。
2. 确认 knowledge-base Skill 对该智能体可见；如果使用显式 Skills 列表，把它一并选中。

知识库选择只会缩小当前用户已有的可见范围，不能授予额外权限。新建对话后提出与检索测试相同的问题，并要求说明依据文件。智能体需要先激活 knowledge-base Skill，再使用知识库工具检索或打开文档。

如果回答没有使用测试文档，先检查 Agent 配置是否保存、当前账号是否有读取权限，以及 Skill 是否在运行时可激活。知识库工具不会把文档目录挂载到沙盒，详细边界见知识库机制详解。

下一步

• 文档处理与 OCR：调整解析器、OCR 和分块参数。
• 知识库管理与 API 参考：使用 API、知识导图和知识图谱。
• 知识库评估：建立检索质量基准。
• 知识库机制详解：理解状态、存储、权限和恢复。