exploring-ai-failures

AI の失敗を調査する

本番環境の AI トラフィックに対してできる最も価値の高いことは、どこで失敗しているかを確認し、パターンを特定することです。ただし、ほとんどの失敗は表面化しません。 モデルは問題のない応答を返します。HTTP 200 で例外も発生しませんが、その応答は間違っていたり、話題から外れていたり、指示を無視していたり、ツールを誤って使っていたりします。こうした失敗はエラーを発生させず、通常、注目すべきなのはこちらです。

そのため、このスキルでは、顕在的な失敗も潜在的な失敗も見つけて、読み解き、対応可能な優先順位付きの失敗モード群に分類します。プロンプトの修正、バグの報告、作業の優先順位付け、あるいは最上位のモードを自動評価（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 — ユースケースをひとつに絞る

アプリには、トレースタイプの_分類体系_があり、それぞれ異なる失敗の仕方をします。サポートチャットではポリシーを幻覚し、要約ツールでは重要なポイントが抜け落ち、エージェントはループしたりツールを誤用したりします。これらをまとめて評価または分析すると、シグナルが平均化されてしまいます。ひとつに絞り、そのフィルター（$ai_trace_id のプレフィックス、機能プロパティ、モデルなど）を見つけてください。トラフィックがどのように分かれているかユーザーがわからない場合は、まず分類体系を把握します（クエリは references/finding-traces.md を参照してください）。

ステップ 2 — 読むトレースを選ぶ

ここで紹介するのは、どのトレースを開くか選ぶ 方法であり、それ自体が答えではありません。クエリ可能なもの（エラー件数、メトリクスの集計値）は、どこを見るか を教えてくれるものであり、決して最終的な成果物ではありません。状況や手元にあるシグナルをもとに選び、組み合わせてください。

• コードエラー（$ai_is_error） — 最も手軽な一括確認方法ですが、代表性は_最も低い_シグナルです。捕捉するのは例外と API の失敗だけで、最も重要な、表面化しない品質上の失敗は捕捉できません。問題の件数を数えるためではなく、読んで確認するトレースをいくつか取得するために使ってください。構造化出力やツール呼び出しのパイプラインでは、解析やスキーマのエラーとして失敗が表面化することがあるため、多少有用です。
• メトリクスの外れ値 — 出力／入力トークン数、メッセージの長さ、コスト、レイテンシで並べ替え、極端な値を開きます。異常な長さ、切り詰め、コンテキストの肥大化、ループは、分布の両端に集中します。
• 1 種類のトレースに絞った抽出 — リクエストを 1 種類に絞り、読むトレースの分類をそろえます。
• 層化サンプル — 特定のシグナルがない場合（よくあるケース）は、複数の分類と結果から混合サンプルを抽出して読みます。これはデフォルトの方法であり、次善の策ではありません。
• 既存の評価での急増 — すでに評価を実行している場合、評価の失敗数の急増から読むべきトレースを特定できます（llma-evaluation-list と、$ai_evaluation イベントに対する execute-sql を使用します）。
• クラスタリング — 大量のトレースがある場合は、グループ分けを使って代表的なトレースを選びます。exploring-llm-clusters を参照してください。

落とし穴。 エラーメッセージを GROUP BY でまとめ、順位表を作って終わりにしたくなるかもしれません。しかし、その表に並ぶのは、例外を発生させる失敗という、目立つ少数派です。ほとんどの AI プロダクトで重要となる失敗は HTTP 200 で完了し、人間がトレースを読むまで見つかりません。開いて確認していないエラー件数やメトリクス件数から作ったランキングは、成果物ではありません。次に読むべき対象を示す手がかりにすぎません。表面化しない失敗を探すクエリが空の結果を返したり、扱いにくい結果になったりした場合は、あきらめて目立つ失敗を報告するのではなく、_トレースを読む_べきだというシグナルです。

ステップ 3 — トレースをまとめて読む（これが作業の本題です）

選んだトレースを開き、実際に読んでください。1 つのユースケースにつき、およそ 20～30 件を目安にします。各トレースは query-llm-trace で読み取ります。必須の引数は traceId で、渡す値は query-llm-traces-list の結果にあるトレースの id です。このステップは省略できず、代わりになるものもありません。GROUP BY を使ったり、出力を「refusal」や「sorry」といった言葉で検索したりしても、表面化しない失敗は見つけられません。検索すべきパターンがまだ分かっていないからです。読み取ることで、そのパターンを見つけます。何も返さない巧妙な SQL の代替手段は、失敗が存在しない証拠ではありません。読む必要があるということです。

各トレースについて、何がうまくいかなかったのかを平易な言葉で記録し、そのメモと一緒に、最も早いイベントのタイムスタンプも書き留めてください（今読んだトレースと query-llm-traces-list の createdAt にあります）。このタイムスタンプとトレース ID があれば、ステップ 4 で解決可能なディープリンクを作成できます。今のうちに記録しておけば、後でもう一度情報を取りに行く手間を省けます。

一連の処理でトレースが失敗している場合は、最初に問題が起きた箇所を記録してください。根本原因が後続の症状を引き起こすことが多く、その原因を修正すれば症状も解消します。メモを「日付フィルターを無視する」「ポリシーを捏造する」「2 つ目の質問を落とす」など、名前を付けたいくつかの失敗パターンにまとめてください。後からクラスタリングでまとめるのを補助できますが、グループ分けは自分で確認してください。新しいトレースを読んでも新しいパターンが出なくなるまで読み続けます（数十件が目安で、数千件ではありません。新しいパターンが出なくなったら止めてください）。

ステップ 4 — ランク付けし、リンクを添えて、ユーザーに引き継ぐ

見つかったモードを、サンプル内にどのくらいの頻度で現れたかを実際に読んで判断し、おおよその順にランク付けします。通常は、いくつかのモードが大半を占めます。名前を付けた失敗モードを、順位を付けて簡潔に提示します。各モードについて、トレースへのディープリンクを自分から1つか2つ添えてください。頼まれるのを待ったり、ユーザーにリンクを求めさせたりしてはいけません。

トレースを読み込んでも、誤読することはあります。幻覚に見えるトレースが、文脈上は正しい場合もありますし、指摘した内容の一部は実際の失敗ではなく、トレースを誤解した結果かもしれません。そのため、リストを確定事項として提示しないでください。各モードについて、リンク付きの例を2つほど提示し、リンクを開いてもらってから、次にどのモードに焦点を当てたいかを尋ねてください。

（読んでいないエラーメッセージやメトリクスの件数からまとめたリストは、目立つものだけを集めたものにすぎません。この手順ではありません。ステップ 3 に戻ってください。）

見る対象が少ない場合

ユースケースが新しい、またはボリュームが少なく、十分な数の失敗を見つけられない場合は、まず対象期間を広げるか、対象の絞り込みを緩めます。それから、気にしている制約を意図的に探る入力（エッジケース、長い入力や曖昧な入力、敵対的な言い回し）でストレステストを行います。または、重要な軸（リクエストの種類 × ユーザーのシナリオ）を網羅する小規模な合成データセットを生成し、システムに通して、そのトレースを読みます。合成結果は、絶対的な正解ではなく、初期調査の足がかりとして扱ってください。重大な影響がある分野やニッチな分野では、信頼性に欠けます。

UI リンクの作成

query-llm-trace は読み込んだトレースの _posthogUrl を返すため、独自にリンクを組み立てず、その URL をそのまま返します。ID が分かっているもののまだ開いていないトレースに限り、自分でリンクを作成できます。その場合も、posthog:generate-app-url だけを使ってください。ホスト名や /project/<id>/ のプレフィックスを手書きしてはいけません。url にはカタログの正規テンプレートを指定し、具体的な ID はパスに直接埋め込まず、params で渡してください。

• トレース一覧： 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 は最も目立つシグナルですが、最も有益とは限りません。時間をかけて調べる価値のある失敗は、エラーなしで完了していることがほとんどです。
• 調査戦略は、読むトレースを選ぶための選択肢であり、パイプラインでも答えでもありません。 文脈に応じて選び、自由に組み合わせ、順序を無理に固定しないでください。
• 一度に扱うユースケースは1つです。 トレースの種類が異なれば失敗の分類も異なります。混ぜると結果が曖昧になります。
• 網羅性より頻度を重視します。 目的は、考えられるあらゆる失敗ではなく、最も頻繁に起きるモードを見つけることです。
• 成果物は、読んだトレースに基づいて名前を付け、ランク付けした失敗モードのリストです。 これがあることで、次の手順（修正、優先順位付け、評価）が明確になります。
• リンク付きの例を返し、次はユーザーに方向を決めてもらいます。 分類表だけで終わらせないでください。各モードにつき、解決可能なトレースリンクを1つか2つ、求められる前に提示し、いくつか確認してもらってください。

関連スキル

• creating-online-evaluations — ランク付けした失敗モードを、継続的に実行される評価に変換します
• exploring-llm-clusters — トレースを1つずつ読む代わりに、クラスター間の振る舞いを比較します
• exploring-llm-traces — このスキルが活用するトレース読解の手法です