error-analysis

错误分析

引导用户阅读 LLM 流水线跟踪记录，并建立系统故障类型目录。

概述

1. 收集约 100 条有代表性的跟踪记录
2. 阅读每条记录，判断通过/失败，并记录问题所在
3. 将相似故障归为不同类别
4. 按这些类别为每条跟踪记录打标签
5. 计算故障率，以确定修复优先级

核心流程

步骤 1：收集跟踪记录

捕获完整的跟踪记录：输入、所有中间 LLM 调用、工具使用情况、检索到的文档、推理步骤和最终输出。

目标：约 100 条跟踪记录。 通常收集到这个数量后，新记录就不再揭示新的故障类型。具体数量取决于系统复杂度。

来自真实用户数据（首选）：

• 数据量较小：随机抽样
• 数据量较大：按关键维度抽样（查询类型、用户群体、功能领域）
• 使用嵌入聚类（K-means）确保多样性

来自合成数据（真实数据稀缺时）：

• 使用 generate-synthetic-data 技能
• 将合成查询输入完整流水线运行，并捕获完整跟踪记录

步骤 2：阅读跟踪记录并做笔记

向用户逐条展示跟踪记录。针对每条记录，询问：系统是否给出了良好的结果？ 标记为通过或失败。

对于失败的记录，记下问题所在。聚焦于跟踪记录中最先出现的问题——错误会层层传递，因此修复根本原因后，下游症状就会消失。不要试图在单条记录中追查所有问题。

记录观察结果，而不是解释。“SQL 未考虑预算限制”，而不是“模型可能没有理解预算”。

模板：

| Trace ID | Trace | What went wrong | Pass/Fail |
|----------|-------|-----------------|-----------|
| 001      | [full trace] | Missing filter: pet-friendly requirement ignored in SQL | Fail |
| 002      | [full trace] | Proposed unavailable times despite calendar conflicts | Fail |
| 003      | [full trace] | Used casual tone for luxury client; wrong property type | Fail |
| 004      | [full trace] | - | Pass |

启发式：

• 不要预先列出故障类别。让类别从用户实际看到的问题中自然归纳出来。
• 如果用户难以描述问题所在，可提示常见故障类型：编造事实、输出格式错误、忽略用户要求、语气不当、工具使用不当。

步骤 3：将故障归为不同类别

检查 30–50 条跟踪记录后，开始将相似的笔记归为不同类别。不要等到检查完全部 100 条记录才开始——尽早归类有助于明确剩余记录的关注重点。类别会不断演变。目标是为类别取具体且可操作的名称，而不是追求完美。

1. 阅读所有故障笔记
2. 将相似的笔记归为一组
3. 拆分表面相似但根本原因不同的笔记
4. 为每个类别取一个明确名称，并用一句话定义

何时拆分，何时归类：

以下情况应拆分（根本原因不同）：

• “编造房产设施（太阳能板）”与“编造客户活动（声称客户安排了从未要求的看房）”——前者捏造外部事实，后者捏造用户意图。

以下情况应归为一类（根本原因相同）：

• “缺少卧室数量筛选条件” + “缺少允许养宠物的筛选条件” + “缺少价格范围筛选条件” → 缺少查询约束

借助 LLM 聚类（仅在用户检查过 30–50 条跟踪记录后使用）：

Here are failure annotations from reviewing LLM pipeline traces.
Group similar failures into 5-10 distinct categories.
For each category, provide:
- A clear name
- A one-sentence definition
- Which annotations belong to it

Annotations:
[paste annotations]

始终与用户一起检查 LLM 建议的分组。LLM 会根据表面相似性进行聚类（例如，将“应用崩溃”和“登录速度慢”归为一类，因为两者都提到了登录）。

目标是归纳出 5–10 个类别，这些类别应当：

• 互不混淆（每种故障只属于一个类别）
• 足够明确，使其他人也能一致地应用这些类别
• 具有可操作性（每个类别都对应一项具体修复措施）

步骤 4：为每条跟踪记录打标签

重新检查所有跟踪记录，并针对每个故障类别添加二元标签（通过/失败）。每条跟踪记录对应每个类别的一列。使用用户偏好的工具——电子表格、标注应用（参见 build-review-interface）或简单脚本。

步骤 5：计算故障率

failure_rates = labeled_df[failure_columns].sum() / len(labeled_df)
failure_rates.sort_values(ascending=False)

故障率最高的类别就是应当优先处理的方向。

步骤 6：决定如何处理每种失败

按以下顺序与用户逐项梳理每个类别：

能否直接修复？ 许多失败都有明显的解决办法，根本不需要评估器：

• 提示词从未提到该要求。例如：LLM 从未在邮件中附上照片链接，因为提示词没有要求这样做。添加这条指示。
• 缺少工具或工具配置错误。例如：用户想重新安排时间，但没有向 LLM 提供重新安排时间的工具。添加该工具。
• 检索、解析或集成中的工程错误。修复代码。

如果明确的修复方案能解决失败，就先这样做。只有在修复后问题仍然存在时，才考虑使用评估器。

评估器是否值得投入？ 并非所有剩余的失败都需要评估器。构建和维护评估器确实有成本。询问用户：

• 这种失败发生得是否足够频繁，值得关注？
• 发生时会造成多大的业务影响？罕见但会导致收入损失的失败，可能比频繁但只是令人烦恼的失败更值得优先处理。
• 这个评估器会被实际用于迭代系统，还是只是在完成打勾任务？

只为用户会反复迭代的失败构建评估器。从发生频率最高、影响最大的类别开始。

对于值得配备评估器的失败： 对任何客观事项，优先采用基于代码的检查（正则表达式、解析、架构验证）。仅对需要判断的失败使用写入裁判提示词。即使修复提示词后，关键要求（安全、合规）也可能仍需要评估器作为防护措施。

步骤 7：迭代

预计需要 2-3 轮分类审查和完善。每轮之后：

• 合并重叠的类别
• 拆分范围过广的类别
• 明确用户可能犹豫不决之处的定义
• 使用完善后的类别重新标记追踪记录

停止标准

当新的追踪记录不再揭示新的失败类型时，停止审查。大致而言：审查约 100 条追踪记录，且最近 20 条中没有出现新的失败类型。具体数量取决于系统复杂度。

追踪记录抽样策略

生产环境流量较大时，混合使用以下方法：

策略	适用场景	方法
随机	默认起点	从近期追踪记录中均匀抽样
异常值	找出异常行为	按响应长度、延迟、工具调用次数排序；审查极端值
按失败驱动	发生防护措施违规或收到用户投诉后	优先处理已标记的追踪记录
不确定性	已有自动裁判时	重点查看裁判意见不一致或置信度较低的追踪记录
分层	确保覆盖不同用户群体	在各个维度内抽样

反模式

• 阅读追踪记录之前就先构思失败类别。 先阅读，再对发现的问题分类。
• 从预定义类别开始。 固定列表会造成确认偏差。让类别自然涌现。
• 初次审查时跳过用户参与。 用户必须审查最初的 30-50 条追踪记录，才能用领域知识为类别提供依据。
• 使用通用评分作为类别。 “幻觉评分”“有用性评分”“连贯性评分”并未基于应用程序的实际失败模式。
• 修复明显问题之前就构建评估器。 先修复提示词缺漏、缺少工具和工程错误。
• 将其视为一次性工作。 每次重大变更后都要重新执行：新功能、提示词重写、模型切换、生产事故。