引言

智能体返回了 HTTP 200，工具也没有报错，但用户仍然说“答案不对”。另一类情况是回答最终正确，用户却等待了很久。这些问题说明：链路执行成功、任务完成、答案正确和响应及时，是不同的判断维度。

Langfuse 的价值在于把请求过程、评价信号和回归实验关联起来，让排查从猜测变成有证据的分析。本文围绕 badcase 的发现、定位与验证展开，重点区分运行异常、效果问题和性能问题，建立可持续积累的工程闭环。

先定义什么是 Badcase

Badcase 指未达到明确预期的案例。预期可以是业务正确性、任务完成条件，也可以是延迟或资源消耗目标。没有事先定义的标准，仅凭“这个回答看起来一般”，难以形成稳定的改进依据。

问题类型	典型现象	后续工作	验证重点
运行异常	工具报错、模型请求失败、执行异常终止	故障排查与修复	错误率、恢复能力、任务是否完成
效果问题	链路正常，但答案错误、缺乏依据、答非所问	效果评测	正确性、相关性、依据充分性、任务成功率
性能问题	首段有效内容出现晚、总耗时高、循环过多	性能评测	首答延迟、端到端延迟、吞吐与成本

这三类可以同时存在。例如，工具超时触发降级，最终生成了缺乏证据的答案，同时延迟也超出目标。应分别记录问题维度，再识别共同根因。

还需要区分候选问题与确认的 badcase：点踩、低分和超阈值只负责筛选；是否真的违背预期，需要结合上下文与证据确认。用户取消可能是正常行为，触发降级也可能已经成功兜底。

用 Trace 建立完整证据链

在排查视角下，可以用 Session → Trace → Observation 理解数据关系：Session 将多轮请求关联起来，Trace 表示一次请求的执行过程，Observation 记录其中的模型调用、检索、工具和其他步骤。Score 用于保存评价结果，并关联到被评估的对象。

这是一种排查模型，不要求每个请求都具备 Session，也不意味着会话标识会自动保存业务上下文。需要应用正确传递关联标识并记录必要数据。

记录对象	建议采集内容	解决的问题
请求与会话	输入、最终输出、traceId、sessionId、场景、环境、应用版本	还原用户目标与多轮背景
模型调用	实际输入、模型与参数、输出、起止时间、Token 用量	判断证据是否进入模型及生成是否异常
检索过程	查询词、文档标识与版本、召回片段、重排结果	区分没找到、排错了、内容已过期
工具调用	工具名、参数、返回结果、错误、重试次数	判断选错工具、参数错误或下游故障
业务结果	任务状态、终止原因、用户反馈及后续纠正	区分接口成功与业务成功

Langfuse 的追踪能力能够记录嵌套执行步骤，但不会自动知道所有业务事实。具体能采集哪些字段，取决于所用集成和应用埋点。Langfuse 可观测性文档

采集前应处理敏感信息，避免把令牌、完整个人信息和无关业务数据写入观测平台。脱敏后仍需保留影响判断的结构、文档版本和关键状态，否则看似完整的 Trace 仍然无法复现问题。

从三条路径发现候选问题

用户主动反馈

将点踩、投诉、人工接管、用户纠正关联到具体 Trace。多轮问题还应结合 Session，检查用户是否在前文已经给出关键约束。

一条负反馈至少要回答：用户期望什么、系统实际输出什么、发生在哪次请求。只有“用户不满意”而没有请求关联，后续通常无法还原现场。

同时保留一定比例的随机抽检。没有负反馈不代表任务完成，用户也可能直接退出。

运行信号与性能异常

下表是应用侧监控设计示例。success、stopReason、loopCount、fallbackAttemptIndex 和 ttftMs 等名称属于项目自定义埋点约定，并非 Langfuse 全部内置字段；存储位置、过滤方式及聚合方式需要按实际集成实现。

异常信号	示例条件	优先检查方向
任务失败	`success = false`	区分技术错误与业务未完成
工具错误	工具 Observation 标记为 ERROR	参数、鉴权、限流与下游服务
非正常终止	`stopReason` 表示迭代上限或错误	终止条件、异常处理与循环状态
循环过多	`loopCount > 5`	重复调用、规划无进展
触发降级	`fallbackAttemptIndex > 0`	主路径失败原因及兜底结果
首答过慢	`ttftMs > 3000`	先确认计时口径，再定位慢节点
总耗时异常	超出场景目标，或 P95/P99 恶化	慢工具、串行调用、排队与重试
Token 异常	同类任务输入量明显增长	历史消息、工具结果与提示词膨胀
输出异常	应有回答却为空或明显不完整	流中断、提前结束、解析与后处理

5 次循环、3000 ms 都是示例阈值，应按任务类型和服务目标配置。复杂任务循环较多不一定异常，短答案也可能符合用户要求。

监控应按环境、应用版本、模型和业务场景拆分。P95/P99 用于观察总体分布，排查时还需要定位对应时间窗口内的具体慢 Trace，不能只对着聚合曲线修改代码。

链路正常，但答案有问题

这类问题需要效果评估，错误日志无法替代。

方式	适用问题	主要边界
代码规则	JSON 不合法、字段缺失、明确业务约束被违反	只能覆盖已表达为规则的标准
LLM-as-a-Judge	答非所问、依据不足、任务完成度低	判断有波动，需与人工标注校准
人工抽检	复杂业务判断、多轮交互、自动评估盲区	需要统一标准并管理评审成本

建议分别记录 task_success、groundedness、relevance 等维度，并写清评分含义和解释。它们是业务设计的指标名称，不是接入后自动得到的质量结论。Langfuse 可以用 Score 承载规则、模型、用户或人工的评价结果。评估概念

Judge 低分表示需要检查，不能直接等同于事实错误。尤其是在裁判没有获得必要证据、评分标准含糊或输出格式解析失败时，先检查评价本身是否可靠。

打开 Trace，找最早偏离预期的步骤

排查应从最终现象回溯，找出最早偏离预期的节点，而不是一看到错答就改 Prompt。

顺序	检查内容	核心问题
1	用户输入与必要会话历史	用户真正要完成什么？约束是否遗漏？
2	整体执行树与时间线	哪一步失败、变慢、循环或降级？
3	路由与检索	是否走对路径、找到正确版本的证据？
4	工具选择、参数与返回值	是否调用正确、结果是否被误读？
5	模型实际输入与输出	正确证据是否真正传入？指令是否冲突？
6	解析、流式交付与前端状态	输出是否被截断、覆盖或显示成旧结果？

例如，用户询问退款条件，系统给出了错误期限：

未召回退款政策：优先修检索或知识数据。
召回的是旧版本：检查文档更新、索引和版本过滤。
正确片段已召回，但未进入模型输入：检查上下文拼装与裁剪。
输入证据正确，模型仍答错：检查指令、模型选择与生成行为。
模型答案正确，页面展示错误：检查后处理和前端状态。

同一个表面现象，修复位置完全不同。对照相似成功案例，比较输入、工具参数、证据版本、Prompt 及模型配置，通常比孤立分析一条失败记录更有效。

人工确认与 Dataset 回归

将现场转化为可复现案例

候选问题经过人工复核后，记录问题类型、最早出错节点、关键证据、预期行为和修复方向。可以利用人工标注队列组织审查；具体功能与入口以所部署版本为准。

确认的 badcase 再沉淀为 Dataset 用例。建议保存：

原始输入及必要的会话上下文。
预期结果或明确的判断标准。
原始 Trace 的关联标识与根因分类。
文档版本、工具响应快照或可控的测试数据。
应用、Prompt、模型及评价器的版本信息。

外部工具返回和业务状态会变化。需要区分两种验证：快照回放用于稳定复现逻辑问题，真实环境测试用于验证集成与当前服务行为。回放通过不意味着生产依赖已经恢复。

效果评测与性能评测分别执行、交叉验收

效果评测关注“任务是否正确完成”；性能评测关注“在什么负载下，以多少时间和资源完成”。修复后用同一数据集版本和评价标准对比 baseline 与候选版本，涉及检索、工具或编排的修改，要运行完整 Agent 流程。

验收维度	要回答的问题
原问题	已确认的 badcase 是否修复？
回归	原先正确的关键用例是否退化？
效果	任务成功率、依据充分性是否改善？
性能	首答、总耗时和尾延迟是否满足目标？
资源	Token 与成本是否出现不可接受的增长？