error-analysis

エラー分析

LLM パイプラインのトレースを読み解き、システムがどのように失敗するかをカタログ化できるよう、ユーザーを案内します。

概要

1. 代表的なトレースを約100件収集します
2. 各トレースを読み、合格／不合格を判定して、何が問題だったかを記録します
3. 類似した失敗をカテゴリにまとめます
4. すべてのトレースを各カテゴリに基づいてラベル付けします
5. 失敗率を算出して、修正の優先順位を決めます

基本プロセス

ステップ 1：トレースを収集する

完全なトレースを記録します。入力、すべての中間 LLM 呼び出し、ツールの使用、取得したドキュメント、推論ステップ、最終出力を含めます。

目標：約100件のトレース。 このあたりから、新しいトレースを見ても未知の種類の失敗が見つかりにくくなります。必要な件数はシステムの複雑さによって異なります。

実際のユーザーデータから（推奨）：

• 少量の場合：ランダムにサンプリングします
• 大量の場合：主要な軸（クエリの種類、ユーザーセグメント、機能領域）ごとにサンプリングします
• 埋め込みクラスタリング（K-means）を使用して多様性を確保します

合成データから（実データが少ない場合）：

• generate-synthetic-data スキルを使用します
• 合成クエリを完全なパイプラインで実行し、トレース全体を記録します

ステップ 2：トレースを読み、メモを取る

各トレースをユーザーに提示します。それぞれについて、**システムは良い結果を出しましたか？**と尋ねます。合格か不合格かを判定します。

失敗の場合は、何が問題だったかを記録します。トレース内で最初に問題が起きた箇所に注目します。エラーは連鎖するため、根本原因を修正すれば、その後の症状はなくなります。1つのトレースですべての問題を追いかけないでください。

説明ではなく、観察した内容を書きます。「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. 各カテゴリに、明確な名前と1文の定義を付けます

分ける場合とまとめる場合：

以下は分けます（根本原因が異なります）：

• 「物件の設備（ソーラーパネル）を捏造」対「クライアントの行動（依頼していない内覧を予約）を捏造」— 前者は外部の事実を捏造し、後者はユーザーの意図を捏造しています。

以下はまとめます（根本原因が同じです）：

• 「寝室数のフィルターがない」＋「ペット可のフィルターがない」＋「価格帯のフィルターがない」→ クエリの制約漏れ

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個のカテゴリを目指します。カテゴリは次の条件を満たすようにします。

• 明確に区別できる（各失敗が1つのカテゴリにのみ属する）
• 別の人が一貫して適用できるほど明確である
• 実行に移せる（それぞれが具体的な修正につながる）

ステップ 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 件のトレースはユーザーが確認する必要があります。
• 汎用的なスコアをカテゴリとして使う。 「ハルシネーションスコア」「有用性スコア」「一貫性スコア」は、アプリケーションで実際に起きる失敗に基づいていません。
• 明らかな問題を修正する前に評価器を構築する。 まずプロンプトの不足、ツールの欠落、エンジニアリング上のバグを修正します。
• これを一度限りの作業として扱う。 新機能、プロンプトの書き直し、モデルの切り替え、本番環境でのインシデントなど、大きな変更のたびに再実施します。