FDE W4D5 学习手册 · Trace 与成本

W4 Day5 · A 级（必须掌握，面试核心）· 4h · 学会给 Agent 装上"黑匣子"：一次调用全程可观测、成本可归因、结果可评测

一、Trace 的本质：Agent 的黑匣子

Trace（追踪）是对一次完整请求从入口到出口的全过程记录，由一棵有序的 Span（跨度）树组成。对 Agent 而言，一次用户提问可能触发多次 LLM 调用、RAG 检索、工具调用、人工审批——Trace 把它们串成一条可回放的因果链。

1.1 为什么 Agent 特别需要 Trace

• 链路长、分支多：一个回答背后是 N 次 LLM + 检索 + 工具，出错难定位。
• 成本高且波动大：token 随检索结果、对话历史变化，必须按维度拆解。
• 评测依赖数据：离线评测、回归测试都要拿真实 Trace 当语料。
• 合规审计：医疗理赔要能复盘"当时模型看到了什么、人批了什么"。

二、固定 Trace 字段：全链路统一埋点

无论底层用什么框架（LangChain/LangGraph/Spring AI），都应有一组统一、必填的顶层字段，保证跨系统可聚合、可比对。

三、自定义 Span：把 Agent 的关键动作都埋进去

除了框架自动生成的 LLM Span，必须按业务手动埋点以下 Span 类型，才能覆盖 Agent 特有环节。

四、一次 Agent 调用的 Trace 层级结构

Trace 是一棵树：根 Span 是本次请求，子 Span 按调用嵌套。

Trace (trace_id=T1, user_id_hash=U*, tenant_id=HospitalA)
└─ agent.step#1            # 规划：决定先检索
   └─ rag.retrieve         # 召回 8 条，knowledge_version=v4
      └─ rerank.call       # 重排后取 top3
   └─ llm.call             # 生成工具调用参数（qwen-max, p_v2）
└─ tool.call(查询医保目录)  # 成功，12ms
└─ agent.step#2            # 规划：需人工审批
   └─ human.approval       # 等待 8min，人改金额 8w→5w，通过
└─ tool.call(放款)          # 幂等键保护，成功
└─ llm.call                # 生成最终答复（deepseek, p_v1）

五、埋点落地：在哪插、怎么传上下文

5.1 上下文传播

Agent 常跨进程/跨服务（编排层、模型网关、工具服务），trace_id 与父 Span 上下文需通过请求头/上下文对象传递，保证 Span 能正确挂到同一棵树。

5.2 自动 vs 手动

5.3 Java/Spring AI 视角

• 若用 Spring AI，可借助 Micrometer Tracing + OTel 自动出 Span。
• 工具调用处用 @Observed 或手动 tracer.nextSpan() 包裹。
• 大数据背景可复用你熟悉的"埋点 SDK + 采集 agent + 数仓"管线，Trace 进 OLAP 做聚合分析。

六、Trace 用于排错：从"慢/错"到"根因"

当一次调用异常，Trace 让你"不靠猜"地定位。

6.1 排错 checklist

1. 用 trace_id 拉出完整 Span 树，看哪个 Span status=failed 或 latency_ms 异常。
2. 若是 rag.retrieve 命中数为 0 → 知识库/检索问题，查 knowledge_version。
3. 若是 llm.call 慢 → 看 model_provider、是否排队、是否上下文过长（input_tokens 大）。
4. 若是 tool.call 失败 → 看 error_type、入参脱敏副本、下游状态码。
5. 若是 human.approval 等待极长 → 审批队列瓶颈，非模型问题。

七、Trace 用于成本归因：钱花在哪一步

成本是 Agent 上线后的头号运营指标。Trace 的 token/cost 字段让成本可按维度下钻。

7.1 成本下钻维度

7.2 成本公式与优化

• 降输入：压缩历史、精简检索片段、prompt 缓存。
• 降输出：结构化短输出、关思维链。
• 换模型：简单步用便宜小模型，仅关键步用大模型。
• 降人工：human.approval 等待与触发率直接关系人力成本。

八、Trace 用于评测：从"跑过"到"跑对"

离线和在线评测都依赖 Trace 作为数据源。

8.1 评测类型与 Trace 的关系

8.2 eval.case Span 的价值

把每个评测用例也写成一个 eval.case Span，记录 case_id、指标、期望/实际、评分。这样"评测"本身也进入可观测体系，能和线上 Trace 用同一套工具分析。

九、技术选型：Langfuse / OpenTelemetry / LangChain 回调

十、流式输出与回调：Trace 与体验的平衡

Agent 常用流式（streaming）提升体验，但流式下 Trace 的 token/latency 统计要特殊处理。

10.1 流式下的观测要点

• 首 token 延迟（TTFT）：用户感知的"快不快"，单独记一个 Span 指标。
• 完整 latency：从请求到最后一个 token，流式不改变总耗时，只是分段返回。
• token 统计：流式结束才能拿到完整 output_tokens，Span 在 end 时再落地。
• 回调钩子：LangChain 的 streaming + callbacks 可在 on_llm_new_token 里做增量处理，但别在钩子里做重逻辑（阻塞流）。

十一、特药理赔 Agent 的 Trace 实践

11.1 落地要点

• 顶层字段：trace_id 贯穿，tenant_id=医院，user_id_hash 脱敏，四个 version 全记录。
• Span：每个 agent.step 一个父 Span，下挂 rag.retrieve / rerank / llm.call / tool.call，human.approval 单独 Span 记等待时长与决定。
• 成本看板：按 tenant 出账单，按 model 看贵不贵，按 human.approval 看人力。
• 排错：答复错→查 rag 命中；慢→查 human.approval 等待或 llm 排队；贵→查 input_tokens（检索片段过多）。

十二、面试达标线①：一次 Agent 调用的 Trace 结构（字段 + Span）

十三、面试达标线②：Trace 怎么用于排错 / 成本归因 / 评测

1. 排错：用 trace_id 拉 Span 树，下钻到失败/异常慢的具体 Span；rag 命中 0→知识库问题，llm 慢→上下文/厂商，tool 失败→error_type，human.approval 久→流程瓶颈；版本字段秒定位"哪次改动引入"。
2. 成本归因：token/cost 按 tenant/模型/prompt/tool 维度下钻；端到端成本=模型+检索+工具+人工；常见反直觉根因（检索片段过多撑爆 input、人工等待引发重试）。
3. 评测：历史真实 Trace 当回归 case，线上聚合出质量看板，失败 Trace 沉淀为评测集，eval.case Span 让评测与生产同栈。

十四、W4D5 自测清单

十五、高频面试题速记卡