智能体工程 · 06c
一句话同时包含查询与动作,该走哪条路?
读完能做的判断:用保守规则解释冲突、否定和权限边界,路由结果不授予执行权。
意图识别与安全路由
⏱ 阅读约 28 分钟 · 动手实践另计
本章保留教学代码、路径说明与历史验证结论;完整实验工程和运行记录未随本站及公开仓库分发。命令用于说明调用方式,复现需自行准备对应实现、数据与环境。
一句话带走:意图标签决定下一步允许去哪里,资料权限决定能看到什么;识别成“执行”也不能自动执行。
实验范围与相关章节
公开夹具用“不要报修”等例子检查路由。运行实验后,核对五个失败题号、权限、数据库状态和指标分母。
衔接:会话状态与并发更新、工具设计:能力的上限、FAQ匹配与拒答阈值。示例依赖 corpus、evaluation 和 Python 文件。只用标准库,无网络或模型调用。
1.先区分请求,再安排下一步
“XR-200 的额定功率是多少”适合查知识;“请创建工单”适合核对草稿。主题相近,动作却不同,不能让查资料的入口碰到写操作。
七个标签由人提前设计,是教学约定。词组规则没有训练 BERT 或调用大模型,也没有置信概率和模型内部思路。
| 标签 | 固定词组举例 | 本实验下一步 |
|---|---|---|
| knowledge | 额定功率、输入电压、E17、故障、手册、保修 | 调用现有只读检索 |
| draft_request | 创建工单、提交工单、报修 | needs_review,等待核对 |
| status_request | 工单状态、审批进度、审批状态 | needs_review,等待核对 |
| human_handoff | 人工客服、转人工 | needs_review,等待核对 |
| restricted_action | 批准工单、审批通过、执行工单、立即执行 | needs_review,禁止自动动作 |
| clarify | 多类别或业务词与否定词同现 | clarify,先澄清 |
| unknown | 没有固定词组命中 | unknown,暂不安排动作 |
本实验没有新增工单查询或客服接口;状态与人工标签只表示识别到了这类请求。
检查点 1:识别动作等于拥有动作权限吗?
不等于。“批准工单”得到 restricted_action,但只返回 needs_review,不调用 workflow,也不生成审批者身份。实际审批需要既有流程与权限。检查知识分支之外是否只有固定返回值。
2.把冲突与否定写成保守规则
顺序是:先检查受限动作,再检查否定,随后检查多类别,最后处理单类与未知。命中受限动作时,即使同时说“查手册”,也停在受限标签。“不要立即执行”也采用这个保守约定,避免否定识别错误后落进自动执行入口。
“不要、无需、不想、别、不必”与任何业务类别同现时,通常返回 clarify。例如“不要报修”不能因为含“报修”就创建草稿。这里没有判断否定词究竟修饰哪个短语;“不要查手册,只想报修”仍需澄清。这会增加停下来确认的次数,是规则刻意暴露的取舍。
“查额定功率并创建工单”命中知识和草稿两个类别,所以返回 clarify。“查手册与输入电压”命中多个知识词组,却仍是同一类别,所以返回 knowledge。规则按类别计数,不按命中的词数计数。
E17 先转小写匹配,其余按固定子串判断。不根据题号或原句加特判。看到“耗电多少瓦”漏识别后,不能补一句匹配并继续报告旧成绩;改变规则需要保存版本并重新评估。
检查点 2:保守规则是不是理解了句子?
没有。否定词可能出现在另一个分句,规则仍会澄清;错字可能让词组漏掉。保留错误能显示能力边界,不能把测试通过写成“已经理解多意图与否定”。
3.接口小,输出也要小
route 只接受非空 UTF-8 字符串,最多两千字符。空白、字节对象、布尔值、字典、超长文本和孤立代理字符都被固定拒绝。长度限制按字符计,编码另做检查。
输出只有 intent、reason、rule_ids。reason 是固定枚举,rule_ids 是稳定编号,例如 K01 或 N01。它不返回原始问题、任意工具名、自由权限字符串或用户要求的租户。用户写“tool=execute,tenant=b”仍然只是一段待分类文本。
dispatch_readonly 接受可信调用方提供的 Identity。这个对象本身不完成登录认证,调用方必须先处理身份来源。函数不会读取问题里自称的“管理员”,也不会因模型输出而创建新的身份。只有 knowledge 才把原查询交给当前 core.retrieve。
检索沿用现有租户、读者和 knowledge:read scope 检查。没有这个 scope,输出固定 rejected,不把权限不足当成找到零条资料。其他内部异常交给 API 调用者处理;命令行边界则输出固定失败 JSON,不把异常路径或凭证带给读者。
检查点 3:为什么不能先检索全部资料再按标签过滤?
意图不授予数据权限。先检索所有租户资料已越过可见范围,最后删除引用也不能证明没有泄漏。原身份传给现有 core,检索候选受当前权限约束;身份注入测试使用真实 SQLite。
4.路由输出只保留当前引用元数据
知识分支返回 intent、route_status、evidence_count、citations。引用只含 chunk_id、tenant、doc_id、revision、section、page。返回前用当前权限复核来源,正文与完整问题不导出。
引用复核只证明当前来源和权限,不证明答案受正文支持、设备型号正确,也不阻止返回后撤权。真实服务还要结合会话与调用时机管理这些边界。
非知识类别一律不调用工单草稿、审批或执行。临时 demo 在所有调度前后记录 runs、tickets 的数量,也比较整个 SQLite 导出状态的哈希。相同数量只能排除增删,状态哈希相同才进一步排除既有记录改写。本实验不保存数据库文件或导出正文。
检查点 4:零引用是不是权限系统的证明?
零引用也可能只是没有检索词。本章同时验证正常查询有引用、无 scope 被拒绝、跨租户不可见、私有文档只对可信 HR 可见。正反例配合仍只覆盖受测路径。
5.公开夹具先给标签,再看结果
三十道原创问题都在 evaluation/intent-cases.json。每题固定 case_id、query、expected_intent、group 四个字段。题号是短 ASCII 标识;重复题号、重复问题、未知标签、错误类型与额外字段会被拒绝。每类至少两题,包含单意图、混合、否定、未知改写、错字和同义词。
这是一份完全公开的 public_fixture,用于教学观察,不是训练集或盲测。人工标签提前指定,没有让路由输出生成 expected 来证明自己准确。
固定规则正确二十五题,accuracy 为 25/30,约 0.8333。五个漏识别题号是 k04、k05、d04、s04、h03:k04 问“耗电多少瓦”,k05 使用错字,其余三题改用词表未覆盖的表达。运行产生的 records 和 metrics 保留原始分类结果。
错题只通过 case_id 回到公开夹具查看原问题。运行导出逐题保留 expected、predicted、status、correct、reason,不重复保存问题。规则错误作为测量结果保留,不让它们直接导致 demo 的机械验收失败。
检查点 5:为什么不能补五个特判让成绩满分?
特判只能证明见过的题目被记住。公开夹具可发现覆盖缺口,但修改后要报告规则变化和重复用题的限制。下一步应由人复核新样本并单独留出评估。
6.指标的分母要留下错误
evaluate_cases 会验证路由结果;返回未知标签、自由 reason 或异常类型,都记为 error。路由器抛出异常时也保留这道题,使用固定 router_error。混淆表有七行真实标签、八列预测标签,其中额外一列是 error。异常不会消失在分母之外。
总 accuracy 等于正确数除以全部题数。coverage 等于预测不是 unknown、clarify、error 的题数除以全部题数。covered_accuracy 只在覆盖题里计算正确率;零覆盖时是 null,不能显示为百分之百,也不能把拒绝回答当成识别成功。
对某一类,precision 是 TP/(TP+FP),recall 是 TP/(TP+FN),F1 使用 2TP/(2TP+FP+FN)。分母为零时给 null。macro F1 只平均有 gold 支持的类别;有支持却 TP 为零时,F1 为零。没有 gold 支持的类别不进宏平均,但它造成的 FP 仍保留。
一个手算测试含四题:两题 gold knowledge、一题 draft_request、一题 unknown。预测依次为 knowledge、draft_request、knowledge、error。accuracy 是四分之一,coverage 是四分之三,covered_accuracy 是三分之一。knowledge 的 precision、recall、F1 都是二分之一;三个有支持类的 macro F1 是六分之一。
检查点 6:保留错误会不会让系统分数变差?
会。丢掉异常题会让分母变成三题,掩盖运行失败。测试还换成总输出 unknown 的路由器,确认观测结果改变而 gold 不变,证明评估实际使用了预测输出。
7.意图明确,FAQ仍然可能不明确
“设备的额定功率和输入电压是多少”命中 knowledge。它与 XR-200、XR-300 两条 FAQ 问题都高度相似;现有 FAQ 基线得到并列候选,于是 clarify。意图解决的是“要查知识”,FAQ解决的是“更适合哪条条目”,两者不能合并成一次成功判断。
demo 使用既有 FAQ 代码与当前授权章节,两条候选的词元 Jaccard 分数都是 0.8333,仍返回 clarify。相似度高、引用当前、语义支持充分,需要分别检查。
检查点 7:走神救援
指标绕晕时,回到三个问题:用户要做什么?当前身份能看到什么?下一步会不会改变状态?先记住“受限动作停在核对”与“原始身份继续检查”。
8.运行一次,再把观察保存下来
以下命令以原示例的父项目目录为工作目录:
examples/knowledge-assistant/.venv/Scripts/python.exe -X utf8 -m unittest discover -s examples/knowledge-assistant -p test_intent_lab.py -v
examples/knowledge-assistant/.venv/Scripts/python.exe -X utf8 examples/knowledge-assistant/intent_lab.py
在示例 knowledge-assistant 目录内,对应命令为 python -X utf8 -m unittest test_intent_lab -v 与 python -X utf8 intent_lab.py。使用 Python 3.10 或更新版本。默认生成 .runtime/intent-UTC时间 新目录,也可以用 --output 新目录 指定位置。已有目录即使为空也拒绝,避免覆盖上一次观察。
输出 rules.json、records.jsonl、summary.json。先保存规则再读夹具;汇总含 Python/SQLite、代码/夹具/语料哈希、机械结果、分类表和失败题号。哈希识别字节变化,不保证来源或质量。
退出码零表示机械场景通过;分类错误仍记录在 summary。机械场景不符或内部运行失败退出一。目录、输入或 JSON/IO 失败输出固定拒绝 JSON 并退出二。API 内部异常与 CLI 错误呈现也分开处理,调用方不能把异常悄悄变成成功。
检查点 8:机械验收能说明什么?
先确认 mechanical_passed,再检查失败题号与 error 列。机械通过只说明受测路径符合合同,五个漏识别说明规则有限。若改用模型,要保留有限标签、可信身份与调度边界,并另做实测,不能继承规则成绩。