《AI Agent 技术原理与架构·决策、记忆与学习》3.3 推理轨迹的失败分类

一次失败运行往往同时留下多个症状:解析失败、工具报错、任务没完成。本节把轨迹失败拆成解析、工具、推理、终止四个阶段,用八条手工轨迹比较“首个失败”和“任一失败”两种归因口径,说明为什么按症状统计会把终止问题放大,并给出按阶段归因的评测判据。

以下轨迹、计数与结论均为教学示例,不对应任何真实评测集。分类边界和归因规则只用于演示“同一批失败在不同口径下会得到不同结论”,不代表某个基准的官方定义。

失败分类听起来像报表工作:给每次运行打一个标签,然后统计哪类最多。真正困难的地方在于,一次失败通常不是单一标签。解析失败之后,工具没有被调用;工具报错之后,任务没有完成;任务没完成,又会被记录成终止失败。如果统计脚本把所有非成功标签都计入分母,终止条件会看起来是最大的问题,而真正的根因可能在前面的某一层。

这一节把失败拆成四个阶段,用同一批轨迹分别计算“首个失败”和“任一失败”,观察两种口径的差距。结论不是“哪种统计更对”,而是:归因口径必须和修复动作绑定,否则数字越精确,方向越可能错。

四个阶段

实验采用一个最小流水线:

阶段回答的问题失败示例修复动作
解析模型输出能否构成合法动作缺字段、JSON 不合法改提示、改解析器、加约束解码
工具动作是否被成功执行未知工具、异常、超时修工具、加重试、加降级
推理结论是否有证据支持引用不切题、跳步改检索、加验证器、改上下文
终止是否按预期停止死循环、提前结束调预算、改停止条件

这四个阶段是有序的。解析失败时,工具根本不会被执行;工具失败时,后续推理没有可靠输入。因此一条轨迹的事件序列天然带有因果方向:前面的失败会制造后面的症状。

形式化一点。一次运行的观测记作事件序列 $e_1, \dots, e_m$,每个事件属于一个阶段,并带有成功/失败标记。定义两个归因函数:

  • 首个失败:$\text{first}(e) = \min{i \mid e_i \text{ 失败}}$,取最早失败阶段的标签;
  • 任一失败:$\text{any}(e) = {stage(e_i) \mid e_i \text{ 失败}}$,取所有失败阶段的集合。

首个失败更接近根因候选,但它依赖阶段顺序和记录完整性;任一失败更接近“症状面”,适合看影响范围,不适合直接排优先级。

事件顺序本身要校验

在统计之前,先检查事件顺序。如果记录器把工具事件写在解析事件之前,或者出现未知阶段,说明数据管道有问题,此时任何归因都没有意义。实验中的校验器要求阶段按定义顺序出现,且不能重复;乱序直接抛出异常。

这条规则看起来苛刻,但它挡住了一类常见错误:把不同版本的轨迹格式混在一起统计。旧版本没有“推理”阶段,新版本增加了该阶段;如果不校验,统计结果会把格式差异误读成能力变化。

最小实验:同一批轨迹,两种口径

实验构造八条轨迹:

  • r1、r8:全部阶段通过。
  • r2:只有解析失败。
  • r3:解析失败,同时被记录为终止失败。
  • r4:工具失败,同时终止失败。
  • r5:工具失败,同时推理失败和终止失败。
  • r6:推理失败,同时终止失败。
  • r7:只有终止失败,即运行一直没停。
# file: agp_lab/trace_failures.py | write
# tier: 2
# verify: python3 -m unittest tests.test_trace_failures
"""推理轨迹的失败分类:按阶段归因。

一次失败运行往往同时表现出多个症状:解析失败之后工具没被调用,
工具报错之后任务没有完成。按“第一个失败阶段”归因和按“出现过的
所有失败阶段”归因,会得到不同的统计,也会导向不同的修复优先级。

本模块把一次运行表示成按阶段排列的事件序列,提供两种归因口径,
并在八条手工轨迹上比较它们。事件顺序本身也受校验:阶段乱序说明
记录器有问题,而不是策略有问题。
"""
from __future__ import annotations

from dataclasses import dataclass

PARSE = "parse"
TOOL = "tool"
REASON = "reason"
TERMINATION = "termination"
STAGES = (PARSE, TOOL, REASON, TERMINATION)
SUCCESS = "success"


@dataclass(frozen=True)
class Event:
    stage: str
    ok: bool


@dataclass(frozen=True)
class RunTrace:
    run_id: str
    events: tuple[Event, ...]


@dataclass(frozen=True)
class Summary:
    total: int
    success: int
    first: tuple[tuple[str, int], ...]
    any_stage: tuple[tuple[str, int], ...]


def validate(trace: RunTrace) -> None:
    """阶段必须按定义顺序出现;乱序或未知阶段直接拒绝。"""
    if not trace.events:
        raise ValueError(f"{trace.run_id}: 没有事件")
    last = -1
    for event in trace.events:
        if event.stage not in STAGES:
            raise ValueError(f"{trace.run_id}: 未知阶段 {event.stage!r}")
        position = STAGES.index(event.stage)
        if position <= last:
            raise ValueError(
                f"{trace.run_id}: 阶段顺序错误 {event.stage!r}"
            )
        last = position


def first_failure(trace: RunTrace) -> str:
    """第一个失败阶段;全部通过时返回 success。"""
    validate(trace)
    for event in trace.events:
        if not event.ok:
            return event.stage
    return SUCCESS


def all_failures(trace: RunTrace) -> tuple[str, ...]:
    """所有被标记为失败的阶段,即“症状集合”。"""
    validate(trace)
    return tuple(event.stage for event in trace.events if not event.ok)


def summarize(traces: list[RunTrace]) -> Summary:
    """同时统计首个失败与任一失败,用来看两种口径的差距。"""
    first_counts = {stage: 0 for stage in STAGES}
    any_counts = {stage: 0 for stage in STAGES}
    success = 0
    for trace in traces:
        head = first_failure(trace)
        if head == SUCCESS:
            success += 1
        else:
            first_counts[head] += 1
        for stage in all_failures(trace):
            any_counts[stage] += 1
    return Summary(
        total=len(traces),
        success=success,
        first=tuple((stage, first_counts[stage]) for stage in STAGES),
        any_stage=tuple((stage, any_counts[stage]) for stage in STAGES),
    )


def sample_traces() -> list[RunTrace]:
    """八条手工轨迹;下游阶段失败是症状,首失阶段才是根因候选。"""
    def events(*failed: str) -> tuple[Event, ...]:
        return tuple(Event(stage, stage not in failed) for stage in STAGES)

    return [
        RunTrace("r1", events()),
        RunTrace("r2", events(PARSE)),
        RunTrace("r3", events(PARSE, TERMINATION)),
        RunTrace("r4", events(TOOL, TERMINATION)),
        RunTrace("r5", events(TOOL, REASON, TERMINATION)),
        RunTrace("r6", events(REASON, TERMINATION)),
        RunTrace("r7", events(TERMINATION)),
        RunTrace("r8", events()),
    ]


if __name__ == "__main__":
    traces = sample_traces()
    print(f"{'运行':<6}{'首失阶段':<14}{'症状阶段'}")
    for trace in traces:
        symptoms = ", ".join(all_failures(trace)) or "-"
        print(f"{trace.run_id:<6}{first_failure(trace):<14}{symptoms}")
    summary = summarize(traces)
    print()
    print(f"{'阶段':<14}{'首失计数':>8}{'任一失败计数':>14}")
    for (stage, first_count), (_, any_count) in zip(summary.first, summary.any_stage):
        print(f"{stage:<14}{first_count:>8}{any_count:>14}")
    print(f"总计 {summary.total} 条,成功 {summary.success} 条")

运行:

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

输出:

运行    首失阶段          症状阶段
r1    success       -
r2    parse         parse
r3    parse         parse, termination
r4    tool          tool, termination
r5    tool          tool, reason, termination
r6    reason        reason, termination
r7    termination   termination
r8    success       -

阶段                首失计数        任一失败计数
parse                2             2
tool                 2             2
reason               1             2
termination          1             5
总计 8 条,成功 2 条

最值得注意的是终止阶段:按首个失败只有 1 条,按任一失败有 5 条。差距来自 r3 到 r6——这些运行的根因在更早阶段,但因为任务最终没有完成,终止阶段也被标记为失败。如果报表只展示“任一失败”,终止会成为最大的问题,团队会去调预算和停止条件,而真正的解析或工具缺陷仍然存在。

反过来,只展示首个失败也有盲点。它假设阶段顺序完全可靠;一旦记录器漏记了前面的失败,根因就会被错误地推到后面。更稳妥的做法是同时报告两个口径,并在报表里明确:首个失败用于排修复优先级,任一失败用于评估影响范围。

边界与失败模式

第一,阶段不是互斥的。 工具失败可能同时是推理失败:模型选择了错误的工具。分类器只能按观测到的第一个失败标记,不能自动判断“选错工具”算工具问题还是推理问题。边界需要人工约定,并在文档里写清楚。

第二,延迟失败。 有些错误在当前步骤看不出来,几步之后才暴露。比如检索到了过期文档,模型基于它给出答案,最后答案被用户否定。轨迹上的首个失败可能落在“终止”或“推理”,而根因在更早的检索阶段。单靠事件顺序无法解决,需要额外的证据链检查。

第三,成功轨迹也可能包含失败事件。 工具第一次调用失败,重试后成功,整条运行是成功的。如果统计把“出现过失败事件”直接当成“运行失败”,成功率会被低估。必须区分“可恢复失败”和“终止性失败”。

第四,标签依赖记录粒度。 如果解析器把所有错误都归为“解析失败”,工具阶段就没有数据;如果工具层吞掉异常,工具失败又会消失。分类的质量上限由日志设计决定,不由统计脚本决定。

第五,样本偏差。 失败轨迹通常比成功轨迹更容易被人工检查,也更容易被加入评测集。直接统计会高估某些失败类型。需要同时报告采样方式和覆盖范围。

架构含义

按阶段归因要落到系统设计上,至少需要四条约束:

  1. 错误码分层。 解析、工具、推理、终止各自有独立错误码;不允许用一个“运行失败”覆盖所有情况。
  2. 事件顺序可校验。 轨迹记录器写入阶段序号;统计前先校验顺序和完整性。
  3. 双口径报表。 同时输出首个失败和任一失败;前者排优先级,后者看影响面。
  4. 可恢复失败单独标记。 重试后成功的失败事件不应把整条运行判为失败,但必须保留在轨迹里用于分析稳定性。

在 W1 检索问答里,推理失败通常表现为引用不切题;在 W2 代码修复里,工具失败通常表现为测试命令或补丁应用异常;在 W3 运维处置里,终止失败通常表现为告警未闭环。任务不同,但“先分层、再归因、最后排优先级”的顺序相同。

判据表

判据合格线不合格的典型表现
错误码四阶段可区分统一“运行失败”
顺序校验阶段乱序会被拒绝混版本统计
归因口径首失与任一失败同时报告只报一个数字
可恢复失败与终止性失败分开重试成功仍计入失败
延迟失败有证据链回溯机制只看最后一步
采样说明报告采样偏差把评测集当全量

小结

  • 一次失败会留下多个症状;按“任一失败”统计会把下游阶段放大,按“首个失败”统计更接近根因候选。
  • 解析、工具、推理、终止是有序阶段,前面的失败会制造后面的症状。
  • 事件顺序必须先校验;乱序或未知阶段说明数据管道有问题,归因没有意义。
  • 可恢复失败不能和终止性失败混在一起;否则成功率会被系统性低估。
  • 归因口径要和修复动作绑定:首失排优先级,任一失败看影响面。

阅读导航:上一节:3.2 ReAct 闭环 · 下一节:4.1 任务分解 。

常见错误与边界

  1. 把所有失败归到终止。 任务没完成是最显眼的症状,不是根因;终止计数高往往是因为前面的阶段先失败了。
  2. 只报一个归因口径。 首失和任一失败回答不同问题;只报一个会让优先级或影响面失真。
  3. 不校验事件顺序。 乱序、缺阶段、混版本会让统计结果不可比,甚至把格式差异当成能力变化。
  4. 把重试成功算作失败。 可恢复失败是稳定性信号,不是运行失败;两者混算会低估成功率。
  5. 忽略延迟失败。 根因可能早于症状若干步;需要证据链回溯,而不是只看最后一步。
  6. 把评测集当全量。 失败样本更容易被采集;不说明采样方式,分类比例就没有外部效度。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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