《AI Agent 技术原理与架构·模型、推理与能力边界》6.3 工具选择错误的分类与评测

工具调用失败不能只报一个总成功率:选错工具、漏参数、多参数和危险调用是不同的问题,需要不同的防线。本节给出一个可操作的错误分类、混淆矩阵和按工具的精确率/召回率,说明为什么安全类错误不能和普通准确率混在一起平均,并给出按风险分层的评测口径。

以下数字为教学示例,不构成对任何真实模型或供应商训练结果的承诺。

工具调用的评测经常只有一个数字:成功率 87%。这个数字把“选错工具”“漏参数”“参数多余”和“执行了危险动作”混在一起,导致团队不知道下一步该改什么。87% 可能意味着选择模型需要换,也可能意味着 Schema 写得太松,或者评测集本身有标注错误。

这一节把工具调用错误拆成可操作的类型,然后用混淆矩阵和按工具的精确率/召回率,说明每一类错误应该看什么指标。重点不是追求一个更高的总分,而是让失败模式可见。

一个够用的错误分类

类型定义主要防线
correct工具和参数都符合预期无需额外防线
wrong_tool选了不该选的工具工具描述、候选排序、选择评测
missing_arg漏掉必填参数Schema 校验、重试、澄清
extra_arg带了未定义参数Schema 严格模式
wrong_value参数类型对但值错范围/存在性校验、二次确认
unsafe_call调用本身不应执行权限、沙箱、审批
no_call应该调用却没有调用触发条件、覆盖率评测

最小实验只实现前五类中的四类,wrong_value、no_call 和更细的语义错误需要领域校验器才能判定。这个简化是刻意的:分类的价值不在于名字多,而在于每一类都能绑定一个防线。 如果一类错误没有对应的改进行动,它就不该出现在报表里。

混淆矩阵比总分更有信息量

混淆矩阵的行是期望工具,列是实际工具。对角线是正确选择,非对角线是选错。它能回答“模型把什么误认成什么”,而总分只能回答“错了多少”。

例如,如果 search 经常被误判成 weather,问题可能不在模型,而在两个工具的描述都包含“查询”这个词。如果 calculator 的调用很少被正确选中,可能是触发词覆盖不足,也可能是模型倾向于用自然语言直接算。两种情况的修复方式完全不同。

混淆矩阵还能暴露评测集的问题。某一行全是零,说明这个工具在评测集里没有样本;某一列全是零,说明模型从不选它。前者是覆盖不足,后者可能是工具描述缺失或候选排序把它屏蔽了。

精确率与召回率要按工具看

对一个工具来说:

  • 精确率 = 正确选中该工具的次数 / 所有选中该工具的次数。低精确率意味着“不该调用时乱调用”。
  • 召回率 = 正确选中该工具的次数 / 所有应该调用该工具的次数。低召回率意味着“该调用时没调用”。

这两个指标经常此消彼长。把工具描述写得更宽,召回率上升,精确率可能下降;写得更窄,精确率上升,召回率下降。具体往哪边调,取决于错误的代价:检索工具误调用通常可恢复,转账工具误调用不可恢复,后者应该优先保精确率。

最小实验:分类、混淆与指标

下面的实验用五条样本演示分类、混淆矩阵、错误率和按工具的精确率/召回率。样本很小,目的是把计算口径固定下来,而不是给出可信的模型结论。

# file: agp_lab/tool_eval.py | write
# tier: 3
# verify: python3 -m unittest tests.test_tool_eval
"""工具选择错误的分类、混淆统计与评测指标。"""
from __future__ import annotations

from collections import Counter

CASES = (
    {"expected": "weather", "actual": "weather", "args": {"city": "A"}, "unsafe": False},
    {"expected": "weather", "actual": "search", "args": {"query": "A"}, "unsafe": False},
    {"expected": "search", "actual": "search", "args": {}, "unsafe": False},
    {"expected": "search", "actual": "search", "args": {"query": "q", "x": 1}, "unsafe": False},
    {"expected": "calculator", "actual": "calculator", "args": {"expression": "1+1"}, "unsafe": True},
)


def classify(case: dict[str, object]) -> str:
    if case["unsafe"]:
        return "unsafe_call"
    if case["expected"] != case["actual"]:
        return "wrong_tool"
    args = case["args"]
    if case["actual"] == "search" and "query" not in args:
        return "missing_arg"
    if case["actual"] == "search" and set(args) - {"query"}:
        return "extra_arg"
    return "correct"


def confusion(cases: tuple[dict[str, object], ...]) -> dict[tuple[str, str], int]:
    counts: Counter[tuple[str, str]] = Counter()
    for case in cases:
        counts[(str(case["expected"]), str(case["actual"]))] += 1
    return dict(counts)


def error_rate(cases: tuple[dict[str, object], ...], category: str) -> float:
    if not cases:
        return 0.0
    return sum(1 for case in cases if classify(case) == category) / len(cases)


def precision_recall(cases: tuple[dict[str, object], ...], tool: str) -> tuple[float, float]:
    true_positive = sum(1 for c in cases if c["expected"] == tool and c["actual"] == tool)
    selected = sum(1 for c in cases if c["actual"] == tool)
    expected = sum(1 for c in cases if c["expected"] == tool)
    precision = true_positive / selected if selected else 0.0
    recall = true_positive / expected if expected else 0.0
    return precision, recall


if __name__ == "__main__":
    print("categories:", [classify(case) for case in CASES])
    print("confusion:", confusion(CASES))
    for category in ("wrong_tool", "missing_arg", "extra_arg", "unsafe_call"):
        print(f"{category}: {error_rate(CASES, category):.1%}")
    print("search precision/recall:", precision_recall(CASES, "search"))

运行:

cd private/labs/agp-lab
python3 -m agp_lab.tool_eval

输出:

categories: ['correct', 'wrong_tool', 'missing_arg', 'extra_arg', 'unsafe_call']
confusion: {('weather', 'weather'): 1, ('weather', 'search'): 1, ('search', 'search'): 2, ('calculator', 'calculator'): 1}
wrong_tool: 20.0%
missing_arg: 20.0%
extra_arg: 20.0%
unsafe_call: 20.0%
search precision/recall: (0.6666666666666666, 1.0)

五条样本里只有一条完全正确,所以任何单一错误类型都占 20%。这个分布是人为构造的,不能用来说明真实系统的错误比例;它只说明分类逻辑能把不同失败分开。

search 的精确率是 2/3,召回率是 1.0。原因是:应该调用 search 的两次都调用了,但有一次 weather 被误调成 search,于是“选中 search”的三次里只有两次正确。这个例子说明精确率和召回率必须成对看:只看召回率 100%,会误以为 search 没有问题。

unsafe_call 被单独列为一类,而不是算作“参数错误”。这是架构上的选择:安全类错误的目标应该是零,不能和普通准确率做加权平均。一个系统可以接受 10% 的 missing_arg,但不能接受 1% 的越权调用;把两者平均会掩盖后者。

评测集怎么设计

工具调用评测集至少要覆盖四个维度:

维度要覆盖什么常见缺口
工具每个工具的正例和负例长尾工具没有样本
查询表达同义说法、口语、混合语言只测标准说法
参数完整、缺失、多余、越界、类型错只测完整参数
安全越权、不可逆、注入完全没有负例

第三个维度最容易被简化成“参数对不对”,但 Agent 的真实失败经常是“参数看起来对、值却错”。例如 city="Shanghai" 是合法字符串,但如果用户问的是北京,值就错了。这类错误只能靠任务级结果验证,不能靠 Schema。

安全维度不能只放明显恶意的样本。更常见的是“正常但高风险”的调用:删除一个真实文件、给生产环境发消息、修改权限。评测集要把这些动作标出来,并单独统计“是否被正确拦截”。

指标怎么汇报

一个可用的工具调用报表至少包含:

  • 按错误类型分的比例,而不是只有一个成功率;
  • 按工具分的精确率/召回率;
  • 安全类错误的绝对数量(不是比例);
  • 评测集规模、覆盖的工具数和标注一致性。

安全类错误用绝对数量,是因为比例会随样本量稀释。1000 次里 1 次越权,和 10 次里 1 次越权,比例差 100 倍,但风险都是“存在越权路径”。安全指标应该回答“有没有”,而不是“平均多少”。

架构含义

错误分类对架构有四个直接约束:

  1. 每一类错误绑定一个防线。 没有防线的分类只是标签,不会改进行为。
  2. 选择和参数分开评测。 选对工具但参数错,和选错工具,需要不同的修复。
  3. 安全单独统计。 越权、不可逆、注入类错误不参与普通准确率平均。
  4. 评测集覆盖负例。 只测“该调用时调用”,测不出“不该调用时也调用”。

第 3 条是底线。把安全错误混进总分,会让团队在“总体 95%”的报表里忽略一条真实的越权路径。

架构判据

判据合格的样子不合格的样子
分类可行动每类错误有对应防线只有“成功/失败”
选择可定位混淆矩阵按工具展开只报总准确率
参数可验证缺失、多余、越界分开统计统一算参数错误
安全可阻断危险调用独立拦截与计数混入普通准确率
评测有负例包含不该调用的样本只测正例

这些判据里,“安全可阻断”优先于“分类完整”。分类可以逐步细化,但危险调用必须在第一版就有硬拦截;否则评测越完整,越容易在真实系统里放大副作用。

按风险分层的评测口径

同一套指标不能同时服务所有工具。按风险分层更实际:

层级例子主指标可接受错误
只读检索搜索、查文档召回率、引用准确率漏调用可重试
可逆写填表、创建草稿精确率、参数正确率误调用可撤销
不可逆写删除、转账、发消息拦截率、审批覆盖率目标为零

分层之后,报表不应该再给一个跨层总分。低风险层的 95% 不能抵消高风险层的一次越权;反过来,高风险层的严格拦截也不应该被低风险层的召回率拖累。

一个误调用案例

用户问“帮我看看上海明天天气”,模型调用了 search 而不是 weather。从结果看,搜索可能也能返回天气页面,任务甚至成功了;但从评测角度,这是一次 wrong_tool。如果不单独统计,这类错误会被“任务成功”掩盖,团队就不会去修工具描述。

更危险的是反向情况:用户问“删除测试环境里的临时文件”,模型调用了 delete_file,参数正确、执行成功,但环境其实是生产。这是 wrong_value 加权限问题,不是选择问题。它说明工具调用评测必须包含“环境/范围”这一维,不能只看工具名和参数形状。

为什么不用单一 F1

F1 适合二分类,不适合工具调用。工具调用是多分类、多错误类型、带安全约束的问题:

  • 把 unsafe_call 和 missing_arg 放进同一个 F1,等于给危险错误和格式错误相同权重。
  • 把长尾工具和头部工具平均,会让高频工具的改进掩盖长尾工具的失效。
  • 把“不该调用”的负例省掉,精确率会虚高。

更合理的做法是分层报表:选择层看混淆矩阵和按工具指标,参数层看错误类型分布,安全层看绝对数量和拦截率。三层各自的结论不能互相抵消。

评测之外,还要把线上失败样本回流。线上出现的误调用、参数错误和安全拦截,应该带着上下文进入评测集;否则评测集会逐渐和真实分布脱节,报表越来越好看,线上问题却越来越多。

一个最小检查是:任取一条线上失败轨迹,问三个问题——错在选、错在参数,还是错在环境?如果三个问题里有两个答不上来,说明日志字段还不够,评测口径也无从落地。

这三个问题也决定了修复优先级:选错先改描述和路由,参数错先改 Schema 和校验,环境错先改权限和沙箱。

小结

  • 工具调用不能只报总成功率;选错、漏参数、多参数、值错、危险调用是不同问题。
  • 每一类错误必须绑定一个防线,否则分类只是标签。
  • 混淆矩阵能回答“把什么误认成什么”,比总分更有修复指向。
  • 精确率和召回率要按工具成对看;只追召回率会纵容乱调用。
  • 安全类错误用绝对数量统计,不参与普通准确率平均。
  • 评测集要覆盖负例、参数异常和高风险正常动作,不能只测标准正例。

阅读导航:上一节:6.2 Schema、约束解码与结构化输出 · 下一节:7.1 CoT:显式推理的收益与代价 。

常见错误与边界

  1. 只报总成功率。 总分掩盖失败模式;至少按选择、参数、安全三类拆开。
  2. 分类没有防线。 一类错误如果没有对应改进行动,就不该出现在报表里。
  3. 只看召回率。 召回率高可能是乱调用换来的;必须同时看精确率。
  4. 把安全错误平均掉。 越权调用应按绝对数量统计并硬拦截,不能混入普通准确率。
  5. 评测集只有正例。 没有“不该调用”的样本,测不出过度调用。
  6. 忽略参数值错误。 Schema 通过不代表值正确;任务级结果验证不可省。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图