50 知识库 Tool：把 RAG 封装成可靠工具
知识库 Tool：把 RAG 封装成可靠工具
知识库 Tool 不是简单包装搜索函数，而是把检索范围、引用、空结果和证据结构封装成 Agent 能稳定使用的工具。
[TOC]
1. 先把 Agent 想清楚
很多人一听到 Agent，就会想到“让大模型自己决定下一步”。这个理解只对了一半。
在真实项目里，Agent 更像是一个被工程规则约束住的任务执行器：
模型负责理解自然语言、提出候选动作
代码负责权限校验、状态流转、工具执行
业务接口负责最终事实和写操作
日志审计负责事后追踪
Agent 如果只拿到一大段搜索文本，就很难判断来源、分数和是否足够回答。知识库 Tool 应返回结构化证据。
所以这一阶段的博客不要写成“模型越来越聪明”。更准确的写法是：我们正在学习如何把模型的灵活性放进一个可控的工作流里。
2. 一个业务场景
用户问“这个设备重启怎么办”。Agent 调用知识库 Tool，返回排障步骤、来源标题、章节和分数。最终回答必须引用这些来源。
这个场景里面最重要的不是模型能不能说出一段好听的话，而是：
它选了哪个工具
为什么能调用这个工具
参数从哪里来
权限在哪里校验
失败后状态怎么变
用户确认前会不会产生真实写入
把这些问题问清楚，Agent 项目才不会变成一个不可解释的聊天黑盒。
这一节要先明确知识库工具的边界。
判断顺序可以这样写：
1. 先判断用户问题是否需要制度、说明、流程或售后规则
2. 工具输入要包含 query、knowledgeBaseId、topK 和权限上下文
3. 检索结果必须返回 chunkId、文档名、来源位置和相关性分数
4. 没有命中时不能让模型自由回答，要返回资料不足或转人工建议
5. 最后用政策问答、资料不足和多知识库权限样例验证
它解决的是知识依据问题：Agent 不是背制度，而是通过知识库工具拿到可引用的来源。
3. 核心概念
1. 检索范围
知识库范围由服务端权限决定，模型只能缩小，不能扩大。
这一点在项目里要落到具体规则：范围不能交给模型。
2. 证据结构
每条证据包含 sourceId、title、location、content、score。
这一点在项目里要落到具体规则：证据要可引用。
3. 空结果
空结果不是失败，而是 found=false，需要澄清或拒答。
这一点在项目里要落到具体规则：没找到要说清楚。
4. 摘要压缩
长证据可以摘要，但必须保留来源映射。
这一点在项目里要落到具体规则：压缩不能丢来源。
4. 整体流程
graph TD;
A["Agent 判断需要资料"] --> B["调用知识库 Tool"]; B["调用知识库 Tool"] --> C["服务端注入权限范围"];
C["服务端注入权限范围"] --> D["执行检索和重排"];
D["执行检索和重排"] --> E["返回结构化证据"];
E["返回结构化证据"] --> F["Agent 基于证据回答"];
这张图里，模型只是其中一个节点。工具、状态、权限、确认和审计同样重要。
如果一个 Agent 图里只有“用户 -> 模型 -> 答案”，那它还只是 Chat，不是能进入业务系统的 Agent。
5. 落地步骤
1. 定义工具边界
说明它适合政策、手册、FAQ，不适合实时订单状态。
完成后应该能看到：工具描述。
2. 返回结构化证据
不要只返回一段拼接文本。
完成后应该能看到：Evidence DTO。
3. 处理空结果
found=false 时给出原因和建议澄清字段。
完成后应该能看到：空结果响应。
4. 记录检索日志
保存 query、范围、候选、耗时和 traceId。
完成后应该能看到：检索日志。
6. 状态、接口或工具字段
| 项目 | 说明 |
|---|---|
| found | 是否找到证据 |
| sourceId | 来源编号 |
| title | 文档标题 |
| location | 章节或页码 |
| score | 相关性分数 |
| warnings | 检索警告 |
字段设计要尽量结构化。不要让下游通过一段自然语言去猜“成功了没有”“下一步要干什么”。
7. 示例
{
"found": true, "evidence": [ { "sourceId": "S1", "title": "售后政策",
"location": "第 3 章 / 故障处理",
"content": "...", "score": 0.91 } ]}
示例里的字段不一定照搬，但思想要保留：输入、状态、输出、错误和审计信息要分开。
8. 哪些事不能交给模型自由发挥
模型不能指定任意 tenantId 或 knowledgeBaseId 来扩大检索范围。权限范围由服务端计算。
这一节特别重要。Agent 项目最容易踩坑的地方，就是把“理解意图”和“执行业务动作”混成一件事。
模型可以建议动作，但最终执行必须经过代码和业务系统的规则。
9. 测试路径
建议至少准备下面几类测试：
正常路径：输入完整，工具正常返回
缺字段路径：订单号、联系方式、问题描述不完整
权限路径：查询别人的订单、访问无权知识库
失败路径：工具超时、模型输出非法、检索为空
恢复路径：等待确认时服务重启、重复确认、超时确认
Agent 的测试不能只看最终回答。你要检查状态、工具调用、审计日志和是否产生真实副作用。
10. 工程取舍
- 直接返回证据更可控，返回生成答案更省事但难以验证。
- 证据越多越全，但上下文越吵。
- 摘要能省 Token，但要保留来源。
取舍讲清楚以后，读者才能知道你为什么这样设计，而不是以为所有问题都要上 Agent。
11. 常见坑
- 知识库 Tool 直接返回无来源答案。
- 允许模型传租户 ID。
- 空结果时让模型猜。
- 摘要后丢失限制条件。
这些坑本质上都和一个问题有关：没有把模型输出当成“不可信的候选结果”。
12. 验收清单
- ☐ 权限范围服务端注入
- ☐ 证据包含 sourceId
- ☐ 空结果语义明确
- ☐ 最终引用可校验
- ☐ 检索日志可追踪
如果这些检查项没过，先不要急着加更多工具。工具越多，边界越乱，排查越难。
13. 落地清单
- ☐ 设计 Evidence 响应结构
- ☐ 写空结果响应
- ☐ 定义工具适用和不适用场景
- ☐ 给证据添加 sourceId
练习时可以先用 Mock，不要一开始就连真实订单或工单系统。等状态、权限和幂等设计清楚后，再接真实接口。
14. 小结
知识库 Tool 的核心是证据，不是答案。Agent 基于证据回答，系统基于证据校验。
Agent 的价值来自灵活性，但安全来自边界。能把这两件事同时讲清楚，才算真正理解 Agent 工程化。