以下 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']
三条输出对应三件事:
- totals:4 次调用(不含根)、840 prompt + 325 completion = 1165 token、4980 毫秒、0 失败、1 次重试。一次旅行规划任务的总账——花了多少、慢不慢、有没有重试,全在这里。
- per_model:claude-opus 1 次调用花 460 token,claude-haiku 2 次调用花 705 token,flights_api 是工具调用不花 token。成本归属按模型看清——贵的模型用了几次、便宜的模型承担了多少。
- 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) | 2100ms | 42% |
| search_flights | 850ms | 17% |
| summarize (haiku) | 980ms | 20% |
| summarize_retry | 1050ms | 21% |
追踪与 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 确定性评估:把输出变断言 。
常见错误与边界
- 调用不可追踪。 没有 span,一次任务花了什么永远说不清。
- 只看总量。 总量掩盖成本归属,贵模型用了多少次看不见。
- 重试隐藏。 重试是额外调用,不入追踪就漏掉一笔成本。
- 延迟说不清来源。 总延迟不拆 span,瓶颈永远定位不到。
- 容错不入链。 熔断与失败不记录,故障复盘只能考古。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。