在新建 LLM 评估项目、流水线重大变更…

适用于需要从 LLM pipeline 的真实或合成 trace 中系统发现、归类、量化失败模式，以指导修复和 evaluator 建设的场景。

适用场景

解决思路

1. 先跑通整体流程：收集约 100 条代表性 trace；逐条阅读并判定 pass/fail、记录问题；把相似失败归为类别；给每条 trace 打上各类别标签；计算失败率以排序修复优先级。
2. Step 1 收集 trace：捕获完整 trace，包括输入、所有中间 LLM 调用、工具使用、检索文档、推理步骤和最终输出。
3. Step 1 收集 trace：目标约 100 条 trace；这通常是新 trace 不再暴露新失败类型的量级；具体数量取决于系统复杂度。
4. Step 1 收集 trace：优先从真实用户数据采样；小数据量随机采样。
5. Step 1 收集 trace：大数据量按关键维度采样，包括 query type、user segment、feature area。
6. Step 1 收集 trace：使用 embedding clustering（K-means）确保多样性。
7. Step 1 收集 trace：真实数据稀疏时从合成数据采样；使用 generate-synthetic-data skill。
8. Step 1 收集 trace：将合成查询跑完整 pipeline，并捕获完整 trace。
9. Step 2 阅读 trace 并做笔记：把每条 trace 展示给用户。
10. Step 2 阅读 trace 并做笔记：对每条 trace 询问：系统是否产出好结果？判定 Pass/Fail。
11. Step 2 阅读 trace 并做笔记：对失败记录哪里出错；聚焦 trace 中第一个出错点，因为错误会级联，根因修复后下游症状会消失；不要追一条 trace 里的所有问题。
12. Step 2 阅读 trace 并做笔记：写观察，不写解释；例如写“SQL missed the budget constraint”，不要写“The model probably didn't understand the budget.”。
13. Step 2 阅读 trace 并做笔记：使用模板记录：| Trace ID | Trace | What went wrong | Pass/Fail |，并逐条填写。
14. Step 2 启发式：不要从预定义失败列表开始；让类别从用户实际看到的内容中涌现。
15. Step 2 启发式：如果用户难以表述哪里不对，用常见失败类型提示：made-up facts、malformed output、ignored user requirements、wrong tone、tool misuse。
16. Step 3 把失败归为类别：阅读 30-50 条 trace 后开始把相似笔记归入类别；不要等 100 条都完成，提前归组能帮助后续阅读更敏锐；类别会演进；目标是具体、可执行的名称，而非完美。
17. Step 3 把失败归为类别：通读所有失败笔记。
18. Step 3 把失败归为类别：将相似笔记归在一起。
19. Step 3 把失败归为类别：把看似相似但根因不同的笔记拆开。
20. Step 3 把失败归为类别：给每个类别清晰名称和一句话定义。
21. Step 3 拆分与归组：根因不同则拆分；例如“Made up property features (solar panels)”与“Made up client activity (scheduled a tour never requested)”，一个编造外部事实，一个编造用户意图。
22. Step 3 拆分与归组：根因相同则归组；例如“Missing bedroom count filter”+“Missing pet-friendly filter”+“Missing price range filter”→ Missing Query Constraints。
23. Step 3 拆分与归组：仅在用户已审查 30-50 条 trace 后使用 LLM-assisted clustering；使用 prompt：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]。
24. Step 3 拆分与归组：始终与用户一起审查 LLM 建议的分组；LLM 按表面相似性聚类，例如因为都提到 login 而把“app crashes”和“login is slow”归在一起。
25. Step 3 拆分与归组：目标得到 5-10 个类别，满足：Distinct（每个失败只属于一个类别）、Clear enough that someone else could apply them consistently、Actionable（每个都指向具体修复）。
26. Step 4 给每条 trace 打标签：回到所有 trace，为每个失败类别应用二元标签（pass/fail）；每条 trace 对每个类别有一列。
27. Step 4 给每条 trace 打标签：使用用户偏好的工具，包括 spreadsheet、annotation app（见 build-review-interface）或简单脚本。
28. Step 5 计算失败率：failure_rates = labeled_df[failure_columns].sum() / len(labeled_df)；failure_rates.sort_values(ascending=False)。
29. Step 5 计算失败率：最频繁的失败类别是最先聚焦的地方。
30. Step 6 决定每个失败怎么处理：按顺序与用户处理每个类别：先问能不能直接修？很多失败有明显修复，根本不需要 evaluator。
31. Step 6 决定每个失败怎么处理：prompt 从未提到该要求；例如 LLM 从不在邮件中包含 photo links 是因为 prompt 没要求；添加指令。
32. Step 6 决定每个失败怎么处理：工具缺失或配置错误；例如用户想 reschedule 但没有暴露 rescheduling tool 给 LLM；添加工具。
33. Step 6 决定每个失败怎么处理：retrieval、parsing 或 integration 的工程 bug；修代码。
34. Step 6 决定每个失败怎么处理：如果明确修复能解决失败，先做修复；只对修复后仍存在的失败考虑 evaluator。
35. Step 6 决定每个失败怎么处理：评估 evaluator 是否值得投入；不是每个剩余失败都需要 evaluator；构建和维护 evaluator 有真实成本；问用户。
36. Step 6 决定每个失败怎么处理：这个失败发生频率是否足够高？
37. Step 6 决定每个失败怎么处理：发生时业务影响是什么？罕见但导致收入损失的失败可能优先于频繁但只是烦人的失败。
38. Step 6 决定每个失败怎么处理：这个 evaluator 是否真的会用于迭代系统，还是只是 checkbox work？
39. Step 6 决定每个失败怎么处理：把 evaluator 保留给用户会反复迭代的失败；从最高频、最高影响的类别开始。
40. Step 6 决定每个失败怎么处理：对值得做 evaluator 的失败，对任何客观检查优先用 code-based checks（regex、parsing、schema validation）；仅对需要判断的失败使用 write-judge-prompt。
41. Step 6 决定每个失败怎么处理：关键要求（safety、compliance）即使在修 prompt 后也可能需要 evaluator 作为 guardrail。
42. Step 7 迭代：预期 2-3 轮审查和细化类别；每轮后执行后续操作。
43. Step 7 迭代：合并重叠类别。
44. Step 7 迭代：拆分过宽类别。
45. Step 7 迭代：在用户会犹豫的地方澄清定义。
46. Step 7 迭代：用细化后的类别重新标注 trace。
47. 停止标准：当新 trace 不再揭示新失败类型时停止审查；大致是审查约 100 条，最后 20 条没有新失败类型出现；具体取决于系统复杂度。
48. Trace 采样策略：Random，默认起点；从近期 trace 均匀采样。
49. Trace 采样策略：Outlier，用于显现异常行为；按 response length、latency、tool call count 排序；审查极端值。
50. Trace 采样策略：Failure-driven，用于 guardrail violations 或用户投诉后；优先处理被标记的 trace。
51. Trace 采样策略：Uncertainty，用于已有 automated judges 时；聚焦 judges 意见不一致或置信度低的 trace。
52. Trace 采样策略：Stratified，用于确保跨用户群体覆盖；在每个维度内采样。
53. 反模式：不要在阅读 trace 前头脑风暴失败类别；先读，再归类发现的问题。
54. 反模式：不要从预定义类别开始；固定列表会造成 confirmation bias；让类别涌现。
55. 反模式：不要跳过用户做初始审查；用户必须审查前 30-50 条 trace，用领域知识为类别打基础。
56. 反模式：不要用通用分数作为类别；“Hallucination score”、“helpfulness score”、“coherence score”没有扎根于应用实际失败模式。
57. 反模式：不要在修明显问题前构建 evaluator；先修 prompt gaps、missing tools、engineering bugs。
58. 反模式：不要把它当作一次性活动；每次重大变更后重新运行，包括 new features、prompt rewrites、model switches、production incidents。

适用边界 · 注意事项

• 无法捕获完整 trace（输入、所有中间 LLM 调用、工具调用、检索文档、推理步骤、最终输出）时，先补齐可观测性，不适合直接运行该流程。
• 没有用户参与、无法让用户审查前 30-50 条 trace 时，不适合，因为失败类别需要领域知识来落地。
• 只想快速修复一个已知 bug 或不需要系统性失败模式目录时，不需要完整 error-analysis 流程。