code

中文 | English

第 3 章 RAG 数字员工实践项目

这是《动手智能体构建》第 3 章的配套代码。你将运行一个本地网页系统，完成一个能查知识库、能显示引用资料的 RAG 数字员工。

本章你需要完成三件事：

1. 配置对话模型，让系统能正常回答。
2. 建立知识库，观察文档分块和检索结果。
3. 发布 RAG 数字员工，并用对话验证回答是否来自资料。

1. 环境准备

建议使用 Python 3.10 或以上版本。macOS 自带的 /usr/bin/python3 可能是 Python 3.9，启动时可能因为 int | None 类型标注报错。

安装依赖：

pip install -r requirements.txt

启动项目：

uvicorn app.main:app --reload

打开浏览器访问：

http://127.0.0.1:8000

首次启动会自动创建 chatbot.db，并写入演示模型、演示数字员工、示例标签和示例知识文档。

2. 页面说明

左侧有四个页面：

• 对话：和已发布的数字员工聊天。
• 知识库：管理标签、文档、分块和检索调试。
• 模型配置：填写对话模型的接口地址、模型名和 API Key。
• 数字员工：配置 ChatBot 或 RAG 数字员工，并发布使用。

3. 第一步：配置对话模型

进入“模型配置”页面，编辑预置的示例模型。

需要填写：

• provider：服务商名称，例如 deepseek、openai、qwen。
• base_url：OpenAI 兼容接口地址。
• model_name：对话模型名。
• api_key：你的 API Key。

保存后点击“测试”。测试成功后，再继续后面的步骤。

注意：API Key 会明文保存在本地 SQLite 数据库中。本项目只适合本地学习，不要提交包含真实密钥的数据库文件。

4. 第二步：配置 embedding 模型

RAG 的向量检索需要 embedding 模型。这个配置不在网页里填写，而是在本目录新建 .env 文件。

示例：

EMBEDDING_BASE_URL=https://your-compatible-endpoint
EMBEDDING_MODEL_NAME=your-embedding-model
EMBEDDING_API_KEY=your-api-key
EMBEDDING_DIMENSIONS=

EMBEDDING_DIMENSIONS 可以先留空。修改 .env 后，需要重启 uvicorn。

如果暂时没有 embedding 模型，也可以继续完成本章练习。系统会自动退回到关键词检索，只是向量检索效果无法完整体验。

5. 第三步：建立知识库

进入“知识库”页面。

你可以直接使用系统预置的示例文档，也可以新建自己的文档。

推荐操作：

1. 点击“管理标签”，创建一个标签，例如“保险条款”。
2. 点击“新建文档”。
3. 填写文档名、来源和版本。
4. 选择标签。
5. 粘贴 Markdown 或普通文本。
6. 保存。

保存后系统会自动分块并建索引。

如果文档状态是 indexed，说明分块和 embedding 都成功。

如果文档状态是 failed，通常表示 embedding 没有配置或调用失败，但文本分块仍然可以用于关键词检索。

配置好 embedding 后，可以点击“重建索引”，让已有文档重新生成向量。

6. 第四步：检索调试

在“知识库”页面点击“检索调试”。

输入一个问题，例如：

疾病责任等待期是多久？

观察系统返回的片段是否与问题相关。这里要重点看三件事：

• 是否命中了正确文档。
• 是否命中了正确片段。
• top_k 改变后，返回片段是否发生变化。

RAG 回答质量首先取决于检索是否命中正确资料。建议先做检索调试，再做对话测试。

7. 第五步：发布 RAG 数字员工

进入“数字员工”页面，编辑预置的“保险知识问答助手”，或新建一个数字员工。

关键设置：

• 类型选择“RAG 数字员工”。
• 选择可用的对话模型。
• 填写角色、任务目标、约束条件和输出要求。
• 绑定知识标签。
• top_k 可以先设为 3。
• 检索器类型可以先选“向量”，没有 embedding 时可选“关键词”。
• 保存后点击“发布”。

RAG 数字员工不建议把大段业务资料写进提示词。业务事实应放在知识库文档中，由检索动态提供。

8. 第六步：对话验证

进入“对话”页面，新建会话，选择已发布的 RAG 数字员工，然后开始提问。

建议测试三类问题。

资料能直接回答的问题

这个产品的疾病责任等待期是多久？

期望现象：模型回答等待期，并在答案下方显示引用资料。

需要综合多个片段的问题

退保和理赔材料分别有哪些注意点？

期望现象：模型综合多个资料片段回答，并展示多条引用资料。

知识库没有答案的问题

这个产品保证收益是多少？

期望现象：模型说明当前资料无法确认，并建议人工核实，而不是编造答案。

9. 本章任务清单

完成项目运行后，请至少完成以下任务：

1. 配置并测试一个对话模型。
2. 新建一份知识文档，并绑定标签。
3. 使用“检索调试”查看至少 3 个问题的命中片段。
4. 发布一个 RAG 数字员工。
5. 完成一轮对话测试，并检查答案下方是否显示引用资料。
6. 刷新浏览器，确认历史回答中的引用资料仍然存在。
7. 调整 top_k 或检索器类型，观察回答变化。

10. 常见问题

启动时报 unsupported operand type(s) for |

这是 Python 版本过低导致的。请使用 Python 3.10 或以上版本。

文档状态是 failed

通常是 embedding 没有配置或调用失败。可以先用关键词检索继续实验。配置好 .env 后，重启服务并点击“重建索引”。

对话时没有引用资料

优先检查：

• 数字员工是否为 RAG 类型。
• 数字员工是否绑定了标签。
• 标签下是否有文档。
• 文档是否已经过期。
• 检索调试是否能命中片段。

刷新后引用资料还在吗

会保留。RAG 回答的引用资料会保存到消息记录中，刷新页面后仍会显示。

可以上传 PDF 或 Word 吗

当前版本只支持 .txt、.md 和 .markdown。PDF 和 Word 解析留作后续扩展。

11. 学习重点

本章不要只看模型回答是否流畅，还要检查回答背后的依据。

• 文档是否被正确分块。
• 检索是否命中正确资料。
• 回答是否依据引用资料。
• 资料不足时是否拒绝编造。

能把这几个环节串起来，才算真正理解了 RAG 数字员工的基本工作方式。