主题
指标体系与线上排障
1. 从一个真实的值班场景开始
假设你负责的 Agent 写作系统已经上线三周。某天早上，产品经理丢来一条用户反馈："昨天生成的方案引用的官方链接打不开，而且结构读起来像几篇文章拼在一起。"
你打开监控，发现昨晚的生成任务全部成功，接口成功率 100%，平均延迟也只比上周涨了 8%。但用户就是不满意。问题出在哪？
只看"任务是否完成"或"接口是否返回"，很难回答这类问题。Agent 系统的链路比单次 API 调用长得多：资料召回、结构规划、产物生成、审稿、改写、交付检查，每个节点都可能把隐患传到下一步。要线上排障，你得同时看到"单次任务在哪里出错"和"最近一批任务是否整体变差"。这正是 Trace 和 Metrics 要一起上场的原因。
一句话理解：Trace 复盘单次现场，Metrics 判断整体趋势；两者结合，才能把"产物不对"翻译成"哪一层节点出了问题"。
2. Trace 和 Metrics 的分工
Agent 项目里，一次产物生成通常会经过资料召回、结构规划、产物生成、审稿、改写和交付检查。线上问题也会沿着这些节点扩散：资料召回不稳定，会影响事实密度；审稿规则变松，会影响引用和结构检查；交付检查缺失，会把格式、链接和元数据问题带到交付结果里。
Trace 和 Metrics 解决的是两类问题。
| 观测对象 | 回答的问题 | 适合排查的场景 |
|---|---|---|
| Trace | 这一次任务在哪里出错 | 单个产物引用缺失、审稿误判、工具失败 |
| Metrics | 最近一批任务是否整体变差 | 质量回退、成本上升、延迟变慢 |
例如用户反馈"这个产物引用不可靠"，Trace 可以复盘这一个产物用了哪些来源、结构是否绑定来源 ID、执行节点是否消费了资料、审稿节点有没有拦截无来源判断。Metrics 可以进一步检查最近一周官方来源占比是否下降、引用使用率是否降低、审稿阻塞率是否异常。
单次现场和趋势指标需要放在一起看。只有 Trace，团队容易停留在逐个补救；只有 Metrics，团队能看到异常，却很难判断异常来自 Prompt、模型、工具还是编排节点。
3. 指标要贴住任务链路
Agent 项目的指标不宜只停留在"接口成功率"和"平均耗时"。产物能生成，不代表质量稳定；接口返回 200，也可能出现引用不足、结构松散、审稿漏检或交付后返修。
更稳妥的做法，是先把任务链路拆成几个可观察节点：
- 需求解析：用户输入、目标、场景、风格和约束是否被结构化。
- 资料召回：是否召回可用来源，来源是否可信，资料之间是否冲突。
- 结构规划：部分是否围绕问题展开，是否绑定来源和任务目标。
- 产物生成：内容是否使用资料，是否出现无来源判断。
- 审稿与改写：问题是否被拦截，返工是否集中在少数规则上。
- 交付检查：格式、链接、元数据和可见内容是否一致。
这些节点决定了后面的指标分组。指标越能映射到节点，排障时越容易从"产物质量下降"缩小到"资料召回官方来源占比下降"或"审稿 Agent 人工推翻率升高"。
4. 五类核心指标
把这五类指标放在一起看，才能区分"用户感知变差""事实基础动摇""质量门禁失效""资源消耗异常"和"最终交付不稳"这五种不同的问题。
4.1 延迟指标
| 指标 | 含义 | 关注点 |
|---|---|---|
| TTFB | 提交任务到首个流式事件 | 用户是否感知到响应 |
| 产物完成时间 | 从任务开始到产物完成 | 模型和资料链路是否变慢 |
| 审稿耗时 | 审稿节点执行时间 | 审稿规则是否过重 |
| P95 / P99 | 尾部慢请求 | 是否有少数任务拖慢整体 |
延迟指标要按节点拆开看。只看总耗时，容易把检索变慢、模型排队、同步写入和审稿循环混在一起。把每个节点写入 Trace，再按 span 聚合出 P95，才能判断慢在资料、执行、审稿还是交付检查。
4.2 资料质量指标
| 指标 | 含义 | 关注点 |
|---|---|---|
| 资料召回命中率 | 至少召回一条可用资料的任务占比 | 检索是否失效 |
| 官方来源占比 | 官方、项目、论文来源占比 | 资料可信度是否下降 |
| 来源冲突率 | 资料之间出现冲突的比例 | 是否需要人工确认 |
| 引用使用率 | 产物实际使用召回资料的比例 | 资料是否进入产物 |
资料指标是产物质量的前置指标。官方来源占比下降时，产物不一定马上失败，但后续审稿会更容易出现无来源判断、事实冲突和人工返工。引用使用率偏低时，需要检查结构是否绑定来源，以及执行 Prompt 是否要求按来源组织论证。
4.3 审稿质量指标
| 指标 | 含义 | 关注点 |
|---|---|---|
| 审稿阻塞率 | P0/P1 问题占比 | 产物质量是否下降 |
| 平均返工次数 | 产物到通过审稿的修订次数 | Prompt 或结构是否不稳定 |
| 重复问题 TopN | 最常见审稿问题 | 优先优化哪条规则 |
| 人工推翻率 | 人工否定自动审稿结论比例 | 审稿 Agent 是否过严或过松 |
审稿阻塞率要结合人工推翻率一起看。阻塞率升高，可能是产物质量下降，也可能是审稿规则过严；阻塞率下降，也可能是质量提升，或者审稿漏检变多。人工推翻率和交付后修订率可以帮助区分这些情况。
4.4 成本指标
| 指标 | 含义 | 关注点 |
|---|---|---|
| 每产物 token 成本 | 单个任务总 token 消耗 | 是否有 Prompt 膨胀 |
| 工具调用次数 | 搜索、读取、rerank 等调用量 | 是否过度检索 |
| 缓存命中率 | Prompt、资料、检索缓存命中 | 是否可以降本 |
| 返工成本占比 | 审稿和改写循环产生的成本 | 质量问题是否放大成本 |
成本上升通常不是单个模型调用造成的。更常见的是检索返回条数增加、Prompt 版本变长、审稿规则新增后触发多轮改写，或者缓存键设计变化导致命中率下降。成本指标需要和版本、任务类型、场景一起分组。
4.5 交付结果指标
| 指标 | 含义 | 关注点 |
|---|---|---|
| 交付检查通过率 | 通过格式、链接、元数据等检查的比例 | 交付前质量 |
| 交付后修订率 | 交付后再次修改的比例 | 生成质量是否稳定 |
| 用户采纳率 | 生成产物被使用的比例 | 产品价值 |
| 低价值返工率 | 用户放弃或大幅重写产物的比例 | 输出是否偏离需求 |
交付结果指标更接近最终交付，但反馈会滞后。它适合判断版本变化的长期影响，不适合单独承担实时告警。实时排障时，仍然要回到资料、审稿、延迟和成本这些更靠前的信号。
5. 排障路径
线上问题可以先按症状分类，再沿着任务链路回查。下面四类症状是最常见的入口。
5.1 产物不可信
优先检查：
- 资料召回是否命中官方、项目或论文来源。
- 来源之间是否存在冲突，是否进入人工确认。
- 结构是否绑定来源 ID。
- 执行节点是否使用了来源，而不是只复述用户输入。
- 审稿节点是否检查引用缺失和无来源判断。
如果 Trace 显示资料召回命中率正常，但引用使用率偏低，问题更可能出在结构和执行 Prompt。如果官方来源占比同时下降，要先检查检索策略、索引更新和搜索工具状态。
5.2 产物像拼接稿
优先检查：
- 资料召回是否过宽，是否把弱相关来源放进上下文。
- 结构是否按问题组织，而不是按来源堆叠。
- 执行节点是否只做摘要拼接，缺少部分间承接。
- 改写节点是否只做句子润色，没有重组结构。
- 审稿是否检查部分之间的因果关系和回指关系。
这类问题需要同时看资料和结构。只增加资料召回量，可能会让拼接感更强；只加改写规则，也可能掩盖事实组织问题。更有效的排查入口，是对比结构节点和执行节点的结构差异。
5.3 延迟变慢
优先检查：
- TTFB 是否上升，用户是否更晚看到首个流式事件。
- 哪个 span 的 P95 或 P99 上升。
- 是否新增同步工具调用、同步写入或长轮询。
- 审稿和改写循环次数是否增加。
- 后台写入是否误放到主路径。
延迟排障要区分首响应和任务完成时间。TTFB 变慢会影响用户感知；产物完成时间变慢会影响交付效率；审稿耗时变慢可能是质量规则变化带来的成本。三者对应的优化手段不同。
5.4 成本上升
优先检查：
- Prompt 是否变长，是否重复携带历史上下文。
- 检索返回条数和 rerank 调用是否增加。
- 审稿和改写循环次数是否增加。
- 缓存命中率是否下降。
- 是否有失败任务反复重试。
成本排障要按任务类型分组。长产物、短产物、不同场景和内部产物的成本结构不同，混在一起看平均值，容易掩盖某一类任务的异常。
6. 告警要指向行动
告警不需要覆盖每个指标。适合告警的信号，应当同时满足两点：影响用户体验或质量底线，并且能指向下一步排查。
可以优先设置这些告警：
- TTFB P95 连续升高。
- 审稿阻塞率异常下降或异常升高。
- 官方来源占比明显下降。
- 交付检查失败率升高。
- 每产物平均成本超过预算。
- 失败重试次数持续升高。
告警消息要携带任务类型、版本、节点和指标变化。例如"技术场景任务的资料召回官方来源占比下降"比"系统异常"更有排查价值。前者能把排障入口指向检索、索引、来源过滤和工具调用；后者还需要值班人员重新定位问题边界。
7. 指标落库与看板
Trace 保存单次现场，Metrics 保存聚合趋势。两者可以共享一组基础字段，保证从 Metrics 钻取到 Trace 时不会断链。
| 字段 | 用途 |
|---|---|
| taskId | 关联单个任务 |
| traceId | 关联一次完整执行 |
| nodeName | 标记资料、结构、执行、审稿等节点 |
| promptVersion | 判断 Prompt 版本影响 |
| model | 判断模型切换影响 |
| channel | 区分用户入口或场景 |
| status | 标记成功、失败、降级或人工确认 |
看板可以按三层组织：
- 总览层：任务量、成功率、TTFB、成本、交付检查通过率。
- 质量层：官方来源占比、引用使用率、审稿阻塞率、人工推翻率、交付后修订率。
- 排障层：按节点聚合的 P95、错误码、降级原因、失败重试和版本分布。
这样设计后，团队可以从总览发现异常，再切到质量层判断影响范围，最后进入排障层定位节点和版本。
8. 小结
Agent 项目的指标体系，要围绕产物质量和工程链路一起设计。延迟、资料、审稿、成本、交付结果五类指标，分别对应用户感知、事实基础、质量拦截、资源消耗和最终交付。
排障时先看 Metrics 判断趋势，再用 Trace 复盘单次现场。指标、Trace、版本和任务类型连在一起后，团队才能从"这个产物不对"推进到"是哪一层能力出了问题，以及下一步该查哪个节点"。
一句话总结
指标体系不是把监控面板铺满，而是让"产物质量下降"能一路追到资料、审稿、结构或交付检查中的具体节点。先用 Metrics 判断趋势，再用 Trace 复盘单次现场，配合版本、任务类型和节点信息，团队才能从"这个产物不对"推进到"下一步该查哪里"。