《AI Agent 技术原理与架构·运行时、协议与系统架构》12.1 调用链追踪与 token 成本

一次多智能体任务调用哪些模型、花多少 token 与延迟、哪里失败重试,都要能回答。调用链追踪把每次模型调用记成 span 树,聚合出总量与按模型拆分两个视角。实验模拟一次旅行规划任务,演示 4 次调用、1165 token、4980 毫秒与一次重试的完整画像,说明可观测性是智能体系统的第一诊断工具。

以下 token 与延迟数值均为教学假设,不构成对任何真实系统、供应商或生产环境的承诺。1165 token 是演示用的量级,真实系统按模型与输入实测,但"每次调用要可追踪、成本要可聚合"这一条不变。

11.3 讲了容错的收尾,这一节进入可观测性:智能体系统怎么被看见。一次任务调了哪些模型、花多少 token、多慢、失败几次——这些要能回答。调用链追踪把每次调用记成 span 树,可观测性是智能体系统的第一诊断工具。

三个必须回答的问题

追踪要回答三个问题:

问题数据价值
调了哪些模型每次调用的模型名成本归属
花了多少 token 与延迟token 数、耗时性能与预算
哪里失败或重试状态、重试标记故障定位

每个 span 就是一次调用。 一次任务从根 span 开始,每次模型调用、工具调用都记成一个子 span,挂在它的父 span 下。span 树的深度就是调用的嵌套关系,宽度就是并行的调用。

总量与按模型两个视角

追踪数据要能看两个视角。总量视角:一次任务共调用几次、多少 token、多长延迟、几次失败重试——这是"这次任务花了什么"。按模型视角:每个模型各调用几次、各花多少 token——这是"钱花在哪了"。

视角回答典型动作
总量这次任务花了什么预算控制
按模型钱花在哪了模型选型

最小实验:span 树追踪与聚合

实验提供 Tracer 与 TraceSpan:add 挂 span,totals 聚合总量,per_model 按模型拆分,chain 列出根下的调用链。

# file: agp_lab/genai_trace.py | write
# tier: 3
# verify: python3 -m unittest tests.test_genai_trace
"""追踪生成式 AI 调用:把一次多智能体任务的每次模型调用连成调用链。

可观测性需要回答三个问题:调用了哪些模型、花了多少 token 与延迟、
在哪里失败或重试。本模块用 span 树记录一次任务的完整调用链,
并聚合出总量与按模型拆分两个视角。
"""
from __future__ import annotations

from dataclasses import dataclass, field
from typing import Any


@dataclass
class TraceSpan:
    span_id: str
    kind: str
    model: str
    prompt_tokens: int
    completion_tokens: int
    latency_ms: int
    status: str = "ok"
    parent: str | None = None
    children: list["TraceSpan"] = field(default_factory=list)


class Tracer:
    def __init__(self) -> None:
        self.spans: list[TraceSpan] = []
        self.children: dict[str, list[TraceSpan]] = {}

    def add(self, span: TraceSpan) -> None:
        self.spans.append(span)
        self.children.setdefault(span.parent or "", []).append(span)

    def totals(self) -> dict[str, int]:
        active = [s for s in self.spans if s.kind != "root"]
        return {
            "calls": len(active),
            "prompt_tokens": sum(s.prompt_tokens for s in active),
            "completion_tokens": sum(s.completion_tokens for s in active),
            "total_tokens": sum(
                s.prompt_tokens + s.completion_tokens for s in active
            ),
            "latency_ms": sum(s.latency_ms for s in active),
            "errors": sum(1 for s in active if s.status == "error"),
            "retries": sum(1 for s in active if s.status == "retry"),
        }

    def per_model(self) -> dict[str, dict[str, int]]:
        grouped: dict[str, dict[str, int]] = {}
        for span in self.spans:
            if span.kind == "root":
                continue
            entry = grouped.setdefault(
                span.model,
                {"calls": 0, "prompt_tokens": 0, "completion_tokens": 0},
            )
            entry["calls"] += 1
            entry["prompt_tokens"] += span.prompt_tokens
            entry["completion_tokens"] += span.completion_tokens
        return grouped

    def chain(self, root_id: str = "root") -> list[str]:
        """从根开始按添加顺序列出直属子 span(span_id:model)。"""
        return [
            f"{span.span_id}:{span.model}"
            for span in self.children.get(root_id, [])
        ]


def demo() -> dict[str, Any]:
    tracer = Tracer()
    tracer.add(TraceSpan("root", "root", "orchestrator", 0, 0, 0))
    tracer.add(TraceSpan(
        "plan_router", "llm", "claude-opus", 320, 140, 2100, parent="root"
    ))
    tracer.add(TraceSpan(
        "search_flights", "tool", "flights_api", 0, 0, 850, parent="root"
    ))
    tracer.add(TraceSpan(
        "summarize", "llm", "claude-haiku", 260, 90, 980, parent="root"
    ))
    tracer.add(TraceSpan(
        "summarize_retry", "llm", "claude-haiku", 260, 95, 1050,
        status="retry", parent="summarize",
    ))
    return {
        "totals": tracer.totals(),
        "per_model": tracer.per_model(),
        "root_chain": tracer.chain(),
    }


if __name__ == "__main__":
    for key, value in demo().items():
        print(f"{key}: {value}")

运行:

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

输出:

totals: {'calls': 4, 'prompt_tokens': 840, 'completion_tokens': 325, 'total_tokens': 1165, 'latency_ms': 4980, 'errors': 0, 'retries': 1}
per_model: {'claude-opus': {'calls': 1, 'prompt_tokens': 320, 'completion_tokens': 140}, 'flights_api': {'calls': 1, 'prompt_tokens': 0, 'completion_tokens': 0}, 'claude-haiku': {'calls': 2, 'prompt_tokens': 520, 'completion_tokens': 185}}
root_chain: ['plan_router:claude-opus', 'search_flights:flights_api', 'summarize:claude-haiku']

三条输出对应三件事:

  1. totals:4 次调用(不含根)、840 prompt + 325 completion = 1165 token、4980 毫秒、0 失败、1 次重试。一次旅行规划任务的总账——花了多少、慢不慢、有没有重试,全在这里。
  2. per_model:claude-opus 1 次调用花 460 token,claude-haiku 2 次调用花 705 token,flights_api 是工具调用不花 token。成本归属按模型看清——贵的模型用了几次、便宜的模型承担了多少。
  3. root_chain:根的调用链是 plan_router → search_flights → summarize。任务的结构一眼可见——先路由规划、再查航班、最后汇总。

一个值得点破的细节:totals 里 retries: 1 与 per_model 里 claude-haiku calls: 2 对得上——重试就是一次额外的调用。追踪把重试从"隐藏的额外成本"变成"可见的调用":2 次 haiku 调用里 1 次是重试,预算审计时能直接看到"重试花了多少钱"。这是 11.2 熔断的观测接口——熔断后快速失败的次数,在追踪里就是 fast_fail 状态的事件。

追踪与成本预算

token 成本要挂到追踪上才有意义。每次调用的 token 数是最原始的成本信号——总量告诉你花了多少,按模型告诉你花在哪,而把两者连起来看就能控制:贵的模型调用能不能换成便宜的、重试次数能不能靠 11.2 的熔断压下来。成本控制的第一步不是省,是看得见——看不见的调用,省无可省。

追踪与延迟定位

延迟是追踪的第二张图。一次任务 4980 毫秒,拆到 span 上就能看到哪一段最慢——是模型调用慢(2100 毫秒的 opus)还是工具调用慢(850 毫秒的 flights_api)。按 span 拆延迟,是性能定位的起点:总延迟是各 span 延迟的叠加,哪个 span 是瓶颈,改哪个。

span延迟占比
plan_router (opus)2100ms42%
search_flights850ms17%
summarize (haiku)980ms20%
summarize_retry1050ms21%

追踪与 11 章、13 章的接口

追踪是观测层,连接前后两端。向后,追踪记录 11 章的容错事件——熔断的 fast_fail、失败分类的类别,都作为 span 状态记录,故障复盘按链查;向前,追踪是 13 章审计的基础——谁调了什么、花了多少,审计要能按任务回溯(13.3 的可靠性视角)。可观测性不是锦上添花,是架构的一等公民——没有追踪,智能体系统就是一匹看不见的黑马。

追踪的采样

追踪每条调用都记录,成本可能失控。调用量大的系统,全量追踪是负担——存储与聚合都要钱。采样是取舍:全量记关键路径(根 span、错误、慢调用),抽样记普通调用。采样率是配置,热点任务全量、普通任务抽样。

记录范围代价覆盖
全量高完整
关键路径全量中大部分诊断价值
抽样低统计可用

采样不能丢错误。 错误与重试事件永远全量——丢了错误记录,故障复盘就没有素材。采样只作用于普通成功调用,容错事件不入采样。

追踪的成本

追踪本身有成本。每条 span 的写入、存储、聚合都花钱——token 之外,追踪基础设施是第二张账单。成本控制:span 字段精简(只记必要字段)、存储分级(热存近期、冷存历史)、聚合预计算(按任务预先聚合总量)。

成本项控制
写入字段精简
存储热冷分级
聚合预计算

追踪成本要计入评估预算(12.3)。 12.3 说评估样本量是预算公式,追踪记录这些样本的每次调用——两个预算是一本账:跑 784 次评估,追踪要记 784 次的调用链,成本叠加。

跨任务的聚合

单任务追踪之外,要能跨任务聚合。“这周平均 token 多少、错误率多少、哪些任务最贵”——跨任务聚合把单次诊断变成趋势分析。聚合的维度:任务类型、模型、时段。趋势是调优的依据:模型选型、prompt 调优(12.2 的断言)、容量规划。

维度回答
任务类型哪类任务最贵
模型钱花在哪
时段高峰成本

跨任务聚合与 13.3 的治理接口——成本趋势写进架构评审,贵得离谱的任务类型触发重新设计。追踪不只是诊断,是治理的数据源。

架构判据

追踪是否合格,用五条判据检查:

判据合格的样子不合格的样子
每次调用有 span模型/工具调用都记录调用不可追踪
总量可聚合一次任务有总账只有零散日志
成本可归属按模型拆分 token成本一笔糊涂账
延迟可拆瓶颈 span 可定位总延迟说不清来源
容错事件入链重试/熔断记入 span容错看不见

判据第一条是"调用必须可追踪",判据第三条才是关键:成本要按模型归属,看不见的调用省无可省。判据第五条是 11 章与 12 章的接缝——容错事件不入追踪,故障复盘就只能考古。

小结

  • 一次任务调哪些模型、花多少 token、多慢、失败几次,要能回答。
  • 每个 span 是一次调用,span 树体现任务结构。
  • 总量视角看总账,按模型视角看成本归属。
  • 按 span 拆延迟,瓶颈一目了然。
  • 容错事件要入链,可观测性是第一诊断工具。

阅读导航:上一节:11.3 部分结果合成与补偿 · 下一节:12.2 确定性评估:把输出变断言 。

常见错误与边界

  1. 调用不可追踪。 没有 span,一次任务花了什么永远说不清。
  2. 只看总量。 总量掩盖成本归属,贵模型用了多少次看不见。
  3. 重试隐藏。 重试是额外调用,不入追踪就漏掉一笔成本。
  4. 延迟说不清来源。 总延迟不拆 span,瓶颈永远定位不到。
  5. 容错不入链。 熔断与失败不记录,故障复盘只能考古。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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