---
title: エラー分析
sidebarTitle: エラー分析
description: 実トレースを読み、失敗をアクション可能なカテゴリに分類することで、LLM アプリケーションの失敗の仕方を体系的に特定する方法。
translatedAt: 2026-08-19
---

# エラー分析

LLM アプリの失敗は、たいていドメイン固有です。
RAG システムがドキュメントの間違ったセクションを取得した、サポートボットがフォローアップを見逃した、エージェントが間違ったツールを選んだ。
特定のコンテキストで期待されるトーンに合わない。
評価器ライブラリは出発点として良いものの、失敗モードへの深い洞察は、システムの実トレースを読むことから得られます。

## エラー分析とは

エラー分析は、その「読む」作業を体系的に行う方法です。
仕組みは定性的研究から借用しています。
まず読み、何が壊れているかを自分の言葉で命名し、事前定義したリストに照らすのではなく、メモから失敗カテゴリを浮かび上がらせます。
アウトプットは、自分のアプリに合った失敗の分類体系 (Failure taxonomy) と、どのカテゴリが最も重要かを示す失敗率です。

プロセスは 5 ステップです。

1. **トレースを集める。** 本番トラフィック、データセット、または実験出力から代表的なサンプルを抽出します。
2. **オープンコーディング (Open coding)。** 各トレースを読み、最初に何がおかしくなったかを自由記述でメモします。
   事前定義のカテゴリは作らず、失敗そのものからカテゴリを浮かび上がらせます。
3. **クラスタリング。** 似た観察を、名前付きの失敗カテゴリにグルーピングします。
   メモから分類体系の草案を LLM に下書きさせ、名前を磨き込み、2 つの根本原因が混ざっているものは分割します。
4. **ラベル付けと計測。** サンプルの全トレースを分類体系に対してタグ付けし、カテゴリごとの失敗率を計算します。
   定性的な読み取りがチャートになります。
5. **判断と実行。** 各カテゴリについて、プロンプトやコードでの修正、今後のトレースで検出する評価器、当面のモニタリングのいずれかを選択します。

実データに紐づいた、優先順位付き意思決定のリストを手にできます。
今日変えるもの、これから計測するもの、見続けるものが整理されます。

## いつ実施するか [#when-to-run-it]

- **評価器を設計する前に** — トレースから測定すべきものを浮かび上がらせるためです。「役立ち度」のような汎用基準ではありません。
- **プロンプト書き換え、モデル変更、新機能追加の後に** — 失敗の分布が変わり、新しいカテゴリが現れます。
- **[モニタリング](/academy/japan/monitoring) がパターンを浮かび上がらせたとき** — スコアの低下、繰り返される苦情、低確信応答の異常なクラスタなど。
- **ローカルで反復している間** — 代表的な入力の小さなデータセットがあれば十分で、本番トラフィックは始める時点では不要です。
- **継続的な実践として** — 最初の分類体系が最終形になることはありません。
  アプリの進化に合わせて、サイクルごとに再実施してください。

## 得られるもの

**アプリ固有の分類体系。** 汎用メトリクスは実際の失敗とマッチすることがほとんどありません。
自分のトレースを読んで見つけたカテゴリこそが、実態と合います。

**一回限りの修正と再発パターンの仕分け。** 失敗のいくつかは、一度直せば済む明らかなプロンプトの問題です。
他は、次に起きたときに捉えるための評価器が必要です。
エラー分析は、それぞれを正しいバケットに振り分けてくれます。
プロンプト変更で解けるはずの問題に対して評価器を組まずに済みます。

**計測可能なベースライン。** 一度トレースがラベル付けされれば、カテゴリごとの失敗率は、漠然とした直感 (「最近のプロンプト更新からボットの調子が悪い気がする」) を、変更をリリースするたびに変化を観察できる数字に変えます。

## アプリケーションでエラー分析を実施する方法

> **ガイド: [エラー分析](/guides/cookbook/error-analysis-llm-applications)**
>
> サンプルデータを選び、Annotation queue を構築し、失敗カテゴリにクラスタリングし、失敗率を定量化し、対応を決定します。

**エージェントで実行する**

このプロンプトをコーディングエージェントに貼り付けてください。Langfuse skill が各ステップ (トレース取得、クラスタリング、失敗率計算) を一緒に進めます。ドメインの判断はあなたが行います。

```text
LLM アプリケーションの失敗の仕方を理解するため、体系的なエラー分析を行いたいです。
Langfuse skill (https://github.com/langfuse/skills/tree/main/skills/langfuse) と Langfuse CLI (https://github.com/langfuse/langfuse-cli) をインストールし、エラー分析のステップを順に案内してください。
```

## 次のステップ

直接修正できるカテゴリは、プロンプト更新やバグ修正になります。
それ以外については、[何を評価するかを選ぶ](/academy/japan/evaluate/choosing-what-to-evaluate) で、どのカテゴリに継続的なメトリクスを設けるべきか、その集合をどう組み立てるかを解説しています。
[データセット](/academy/japan/datasets) はテスト入力を保持し、[評価](/academy/japan/evaluate) では各カテゴリに対する手法 (コードベース、LLM-as-a-Judge、手動レビュー) を選びます。

<!-- agent-instructions -->

---

## Agent Instructions

This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/academy/japan/monitoring/error-analysis.md`.

### Querying these docs

If the answer is not on this page, query the documentation instead of guessing:

- **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question:

  ```bash
  curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?"
  ```

- **Index of every page**: <https://langfuse.com/llms.txt>, with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt).

### Before writing Langfuse code

- **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results.
- **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application.
- **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples.
- **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx langfuse-cli api <resource> <action>`) to read or write traces, prompts, datasets, and scores from the terminal.

Found an error in these docs? Please open an issue at <https://github.com/langfuse/langfuse-docs/issues>.