Agent 可观测性落地手册：用 Langfuse 做全链路追踪

Agent 一旦进入生产，最先暴露的问题通常是“看不见”：

为什么同样请求有时成功有时失败？
Token 成本为何突然上涨？
是检索问题还是推理问题？

可观测性不是锦上添花，而是生产可用性的基础。

最小可用观测模型

建议先建立三层数据：

Trace：一次用户请求的完整链路
Span：链路中的子步骤（检索、工具调用、重排、生成）
Score：人工或自动评估结果（准确性、相关性、可执行性）

只要这三层打通，排障效率会有明显提升。

接入策略

1. 先追关键路径

首批只接三类节点：

主模型调用
检索器调用
外部工具调用

不要一开始追踪所有细节，否则维护成本会反噬。

2. 统一会话与用户标识

session_id：同一会话连续请求
user_id：聚合用户维度行为
request_id：单次请求唯一编号

这让你可以从“异常用户反馈”快速定位到具体 trace。

3. 成本与延迟要分层看

至少拆分：

模型推理耗时
检索耗时
外部 API 耗时
总响应时间

很多团队优化模型参数后发现收益有限，真正瓶颈反而是工具层接口。

评估闭环

推荐两条线并行：

在线轻评估：响应是否命中意图、是否触发重试
离线深评估：抽样回放 + 人工标注

评估指标可从三项开始：

Answer Groundedness（是否有依据）
Task Completion（任务是否完成）
Tool Success Rate（工具调用成功率）

常见反模式

只记录原始文本，不记录结构化上下文
只盯整体延迟，不看步骤级耗时
有追踪无告警，异常只能靠人盯仪表盘

总结

对 Agent 系统来说，观测能力不是可选插件，而是“质量系统”的核心。Langfuse 非常适合作为第一层统一追踪平台，再按需接 Phoenix 或内部评估流水线。

落地建议：先选一个业务场景做 2 周观测基线，再做优化迭代，避免“边改边猜”。

Trace 数据模型：trace / span / generation 的正确用法

Langfuse 的数据模型里有几个常见混淆：

trace：一次完整请求的生命周期，跨多个 span
span：trace 内的一个步骤（如 "检索"、"重排"、"工具调用"）
generation：LLM 调用，是特殊的 span，带 token 计数和 prompt 模板信息
score：附着在 trace 或 span 上的评估分数

实操建议：

每个 trace 必须有 user_id 或 session_id，否则 30 天后无法做用户级分析
generation 的 prompt 必须打版本号，否则 prompt 改动后无法回溯历史质量
score 用枚举类型（"good" / "bad" / "neutral"）而不是数字，便于下游过滤

评估集：从抽样到反馈循环

评估闭环最实用的模式：

抽样规则：每天从线上 trace 抽 5%（含成功和失败案例）
人工标注：3 个标注员按评分标准打分；分歧 case 进讨论池
统计聚合：周维度看趋势，重点关注恶化指标
反馈到 prompt：高频问题 case 写到 prompt 改动的 acceptance criteria

不要试图用 LLM 自动评分替代人工——LLM 评分与人工评分的相关系数通常 0.5-0.7，只能做"筛选"，不能做"判定"。

成本治理的"反直觉"经验

几个被反复验证的成本规律：

重试成本 > 模型升级：把重试率从 15% 降到 5%，省下的钱通常大于换更便宜模型
长 prompt 边际成本递增：每多 1k token，单次成本增加 5-15%，但准确率提升通常 < 2%
工具调用频次的"隐形税"：每个工具调用 200-500ms 延迟 + 上下文膨胀，往往是体验瓶颈
缓存命中率是最便宜的优化：同样的 query 不需要重新计算，缓存层可省 30-50% 成本

建议每月做一次"成本拆解"，把账单按 trace 维度归因，会发现很多"看不见"的浪费。

告警策略：别让告警疲劳毁掉观测

常见错误是"什么异常都告警"，最后没人看。生产告警设计原则：

Severity 分级：P0（线上阻断）→ 即时通知；P1（质量下降）→ 工单+日检；P2（成本异常）→ 周报
基于对比的告警：成功率从 95% 跌到 90% 是 P1，从 90% 跌到 80% 是 P0
抑制静默期：知道是 release 引发的，先静默 2 小时再评估
聚合告警：5 个独立告警不如 1 个"P0 综合指标异常"

与 LangSmith / Phoenix 的取舍

三个主流工具的定位差异：

Langfuse：开源 + 自托管 + 多模型支持，适合作为统一观测层
LangSmith：LangChain 生态深度集成，但绑定较重
Phoenix (Arize)：偏 evaluation 与 drift detection，适合实验阶段

多数团队的合理选择是 Langfuse 作为主观测平台，Phoenix 用于模型评估实验。不建议两个工具并行做同一件事——会重复埋点、增加维护成本。

落地的真实时间表

一个中型团队的 Langfuse 落地时间参考：

第 1 周：接入主链路 3-5 个 span
第 2-3 周：完成 score 标注机制，跑通第一轮评估
第 4-6 周：上线成本仪表盘与告警
第 7-8 周：开始迭代优化 prompt 和工具

不要试图"一次性接入所有功能"，按 4 周一个阶段推进。观测能力的建设是马拉松，不是冲刺。