exploring-ai-failures

探索 AI 失败

对于生产环境中的 AI 流量，最有价值的做法是找出它在哪些地方失败，并总结出模式。问题在于：**大多数失败都是静默的。**模型返回了干净的响应——HTTP 200，没有异常——但内容错误、偏离主题、忽略指令或错误使用工具。这些情况不会引发错误，而它们往往才是最值得关注的失败。

因此，这项技能旨在找出失败（明显的 和 静默的），读懂它们，并将其归纳为一组按优先级排序的失败模式，以便采取行动：修复提示词、提交 Bug、确定工作优先级，或将最突出的问题模式转化为自动化评估（creating-online-evaluations）。

**以下所有内容都服务于一项不可或缺的活动：阅读真实轨迹。**查询只会告诉你该打开_哪些_轨迹——查询本身绝不是答案。如果你没有打开轨迹就报告问题列表，那你描述的只是少数明显的问题（会抛出错误的问题），却漏掉了真正要做的事。

这是自下而上的过程：失败模式从真实轨迹中浮现，而不是预先根据一份通用指标列表来确定。要深入阅读单条轨迹，请参考 exploring-llm-traces；要在大量数据中发现自然形成的分组，请参考 exploring-llm-clusters。

工具

工具	用途
posthog:query-llm-traces-list	列出候选轨迹——按错误筛选、按指标排序、按类型限定范围
posthog:query-llm-trace	完整阅读一条轨迹，了解实际出了什么问题
posthog:execute-sql	查找指标异常值、发现轨迹分类、统计失败模式
posthog:llma-evaluation-list	查找现有评估，看看其中的失败是否揭示了新的问题模式
posthog:generate-app-url	生成包含区域和项目信息、可直达某条轨迹或列表的深层链接

以下各策略的详细查询见 references/finding-traces.md。该文件还说明了 events 与 ai_events 的区别：$ai_input / $ai_output_choices 等大型内容不在 events 中。如需了解完整的 $ai_* 事件架构，请加载 exploring-llm-traces 技能。

与用户协作

与用户协商的是_范围和优先级_，而不是是否要开展工作。开始时就与用户缩小范围：针对哪个功能或用例？他们是否已经发现过问题？是否有可追踪的信号（踩、工单、异常指标）？确定范围后，直接阅读轨迹，并整理出分类后的失败模式——不要停下来征求是否可以开始阅读；阅读是核心工作，不是可有可无的后续选项。如果用户不知道该看什么，就按照下面的流程推进，并随时解释原因；是否需要讲解，由用户决定。

第 1 步——限定一个用例

应用中的轨迹类型有其_分类体系_，不同类型的失败方式也各不相同——客服聊天可能会编造政策内容，摘要器可能遗漏要点，Agent 可能陷入循环或错误使用工具。将它们放在一起评估或分析会稀释信号。选定一种，然后找到对应的筛选条件（$ai_trace_id 前缀、功能属性或模型）。如果用户不确定流量是如何划分的，请先发现其分类体系（查询见 references/finding-traces.md）。

第 2 步 — 选择要阅读的跟踪记录

以下方法用于_选择要打开的跟踪记录_，本身并不能给出答案。可查询的数据（错误计数、指标聚合值）会告诉你_该去哪里查找_，但绝不是最终结果。根据你掌握的上下文和信号进行选择，并结合使用：

• 代码错误（$ai_is_error） — 成本最低的扫描方式，也是_最_不具代表性的信号：它只能捕获异常和 API 失败，无法捕获最重要的无声质量问题。用它来挑几条跟踪记录阅读，而不是统计“问题”数量。对于结构化输出或工具调用流水线，它会稍微有用一些，因为部分失败确实会以解析或架构错误的形式显现。
• 指标异常值 — 按输出／输入 token 数、消息长度、成本或延迟排序，然后打开极端值。长度失控、截断、上下文膨胀和循环通常集中在两端。
• 一种跟踪类型的切片 — 缩小范围，只关注一种请求类型，这样阅读的跟踪记录就采用相同的分类体系。
• 分层抽样 — 没有特定信号时（这是常见情况），从不同切片和结果中抽取一批混合样本并阅读。这是默认做法，而不是备用方案。
• 现有评估中的峰值 — 如果已经在运行评估，某项评估的失败次数突然上升，就能帮助你找到要阅读的跟踪记录（对 $ai_evaluation 事件使用 llma-evaluation-list + execute-sql）。
• 聚类 — 数据量很大时，让分组自然形成，以便挑选有代表性的跟踪记录来阅读；请参阅 exploring-llm-clusters。

陷阱。 很容易就想用 GROUP BY 对错误消息分组，生成一张排名表，然后就此打住。但这张表呈现的只是显眼的少数——会引发异常的失败。对大多数 AI 产品而言，真正重要的失败会以 HTTP 200 完成，只有人阅读跟踪记录时才会显现。如果你根据从未打开过的错误或指标计数生成排名，那就不是交付成果——它只是提示你接下来该阅读什么。如果查询无声失败的结果为空或难以处理，这意味着你应该_阅读跟踪记录_，而不是放弃并报告那些显眼的失败。

第 3 步 — 阅读一批跟踪记录（这才是要做的事）

打开并实际阅读你选出的跟踪记录——针对一个用例，计划阅读大约 20–30 条。使用 query-llm-trace 逐条阅读，它唯一必需的参数是 traceId；传入的值是 query-llm-traces-list 结果中的跟踪记录 id。这一步不能省略，也没有任何东西可以替代它。你无法通过 GROUP BY 或在输出中搜索“refusal”／“sorry”之类的措辞来找出无声失败，因为你还不知道该搜索哪些模式——阅读才能让你发现这些模式。某个巧妙的 SQL 代理查询什么都没返回，并不能证明这些失败不存在；这说明你必须阅读。

对于每条跟踪记录，用通俗语言记录出了什么问题，并在旁边记下该跟踪记录最早事件的时间戳（就在你刚读过的跟踪记录中，以及 query-llm-traces-list 的 createdAt 字段中）。有了这个时间戳和跟踪记录 ID，就足以在第 4 步构建可解析的深层链接，因此现在记录下来可以省去之后再查一次。

如果某条跟踪记录在调用链中失败，请记录_最先出问题的环节_——根本原因通常会导致下游症状，修复它也能一并消除这些症状。将记录归纳为几个命名的失败模式（“忽略日期筛选条件”“捏造政策”“漏掉第二个问题”）；之后可以再整理这些分组，但要自行检查。持续阅读，直到新跟踪记录不再带来新的失败模式（几十条，而不是几千条——没有新发现时就停止）。

第 4 步 — 排名、添加链接并交还给用户

根据你阅读的内容，按大致出现频率为找到的模式排名——通常少数几种模式占主导。给出一份简短的失败模式排名列表。每种模式都要主动附上 一两个示例跟踪记录深层链接——不要等用户开口，也不要让用户提出请求。

你读过这些跟踪记录，但仍可能误读——看起来像幻觉的跟踪记录在上下文中可能是正确的，而你标记的一些内容可能是你误解了跟踪记录，并非真正的失败。因此，不要把列表说成定论。每种模式给用户几个带链接的示例，让他们打开链接，然后询问他们接下来想重点关注哪种模式。

（根据你从未阅读过的错误消息或指标计数整理出来的列表，只是最显眼的一部分，并非这里要做的事——请回到第 3 步。）

可供查看的内容较少时

如果用例较新或流量较低，找不到足够的失败案例：先扩大时间范围或放宽筛选条件；然后用刻意探测你关心的限制条件的输入进行压力测试（边缘情况、较长或含糊的输入、对抗性措辞）；或者针对重要维度（请求类型 × 用户场景）生成一小批合成数据，通过系统运行并阅读这些跟踪记录。将合成结果视为初步参考，而非真实情况——对于高风险或小众领域，这些结果并不可靠。

构造 UI 链接

query-llm-trace 会返回其读取的跟踪记录对应的 _posthogUrl，因此请直接将该链接交给用户，而不是自行拼接。只有当你知道跟踪记录的 id、但尚未打开它时，才自行构造链接，并且只能使用 posthog:generate-app-url——绝不要手动填写主机名或 /project/<id>/ 前缀。url 必须是规范的目录模板；请通过 params 传入具体 id，绝不要将其直接写入路径。

• 跟踪记录列表： generate-app-url {url: "/ai-observability/traces"}（然后筛选到你的用例）
• 单条跟踪记录： generate-app-url {url: "/ai-observability/traces/{id}", params: {id: "<trace_id>"}}

跟踪记录链接不包含时间戳，因此请在要交给用户的 URL 后附加 ?timestamp=<url_encoded_timestamp>——跟踪记录页面会读取它以定位较早的记录，而两个工具都无法表达这一信息。

生成的链接会解析到正确的区域主机和项目路径前缀（例如 https://us.posthog.com/project/<id>/ai-observability/traces/<trace_id>），因此，即使用户当前不在目标项目中，也会进入正确的位置。

提示

• 阅读就是工作本身，不是最后一步。 聚合数据、错误计数和评分只能帮助判断_应打开哪些跟踪记录_，绝不能替代阅读。汇报任何内容前，先阅读第一批跟踪记录，不要征求用户许可。
• 不要过度关注错误。 $ai_is_error 是最显眼、但最没意思的信号；值得花时间查看的失败通常不会触发它。
• 这些发现策略是用于挑选跟踪记录阅读的菜单，不是流水线，也不是答案。根据上下文选择，可自由组合，不必强行遵循固定顺序。
• 一次只处理一个用例。 不同类型的跟踪记录有不同的失败分类，混在一起会模糊结果。
• 频率优先于完整性。 目标是找出最常发生的模式，而不是列出所有可以想象到的失败。
• 输出应是根据你读过的跟踪记录整理出的、按名称列出的失败模式排名——这份成果能让下一步（修复、确定优先级或评估）一目了然。
• 提供带链接的示例，然后让用户决定方向。 不要止步于分类表格。主动为每种模式提供一两个可打开的跟踪记录链接，并请用户查看几个示例。

相关技能

• creating-online-evaluations — 将排名靠前的失败模式转化为持续运行的评估
• exploring-llm-clusters — 对比不同集群的行为，而非逐条阅读跟踪记录
• exploring-llm-traces — 本技能所依赖的跟踪记录阅读方法