--- title: データセットの設計 sidebarTitle: データセットの設計 description: スコープが明確で、入力が現実的で、出力が評価可能で、メタデータが役立ち、実験結果を解釈できる Langfuse データセットを設計するための実践ガイドです。 translatedAt: 2026-08-19 --- # AI アプリケーションのためのデータセット設計 データセットとは、アプリケーションのスコープを代表し、システムの計測と改善に使う、再現可能な例の集まりです。 同じ入力に対してアプリケーションを継続的に実行することで、メトリクスで品質を追跡し、変更を比較し、本番ユーザーに影響が出る前にリグレッションを捕まえられます。 繰り返し評価する価値があるものがまだ定まっていない場合は、次を参照してください。 - [エラー分析](/academy/japan/monitoring/error-analysis)。チェックする価値のある失敗モードをアプリケーションから見つける体系的な方法です - [Langfuse デモプロジェクト](/docs/demo) と [Academy の例](/academy/japan/examples) にあるデータセット。データセットのスコープ感をつかめます Academy の [データセット](/academy/japan/datasets) セクションでは、入力・期待出力・メタデータという基本の構成要素を説明しました。 このガイドでは、データセットとデータセットアイテムを作る前と作っている最中に行う設計作業に焦点を当てます。 データセットの設計は反復的です。 良い出発点は「最小限そろったデータセット」です。アプリケーションを通せて、最も重要な入力のスライスをカバーし、評価器またはレビュー基準を持つ、15〜30 行程度のものです。 そのバージョンを早めに実行し、スキーマと評価器を固め、そのうえで実行結果や本番入力から見えた穴を埋めていきます。 アプリケーションが持つ評価用データセットは、1 つではないことがほとんどです。 データセットは、システムの特定の部分や、エージェントが踏む 1 つのサブステップに合わせてスコープを切ることがよくあります。 ## 1. データセットの目的から始める 行を書き始める前に、そのデータセットが支えるべき「最小の有用な目的」を定義してください。 これがないと、データセットは興味深い例をただ集めた曖昧な入れ物になってしまいます。 たとえば次のようなものです。 - サポートのルーティングを壊さずにプロンプト変更をリリースできるか? - ドキュメント用チャットボットは、よくある導入の質問に十分に答えられているか? - 顧客が返金を求めたとき、エージェントは適切なツールを呼ぶか? データセットの最初の出発点としては、最もよくある例をエンドツーエンドで見ていくのが有効です。 そこから土台と全体像が得られ、広げていくことができます。 時間が経つにつれ、チームは単一ステップ用、敵対的ケース用、レッドチーミング用、アプリケーション内の特定のサブユースケース用のデータセットを追加していきます。 会社名の表記チェック専用のデータセットを見かけたこともあります。 データセットに設定した目的が、その境界と役割を決めます。 エンドツーエンドのデータセットはアプリケーションが受け取るペイロードを使い、ステップ単位のデータセットはそのステップが本番で見る構造化された状態を使います。 2 つの役割で必要な入力・評価器・リリース判断が異なるなら、分けてください。 安定したリグレッション用データセットと敵対的入力のデータセットはどちらも有用ですが、明確に分けずに混ぜると、集計スコアの解釈が難しくなります。 ## 2. 利用できる情報源を調べる 例を選んだりデータセットアイテムを書いたりする前に、使えそうな材料を少量サンプリングして確認してください。 目的は、何が存在していて、それが想定とどう違うのかを理解することです。 まずは 3 種類の情報源から始めます。 - **本番トレース:** 現実の利用、よく通る経路、実際に観測された失敗が分かります。スコア、ユーザーフィードバック、チケット、クレームは有用なトレースを見つけるための手がかりであって、別の情報源の種類ではありません。 - **既存の資産:** 過去のデータセット、FAQ、ポリシー、ドキュメント、サポートの定型文、CSV、JSON ファイル、ベンチマークなどは、既知のカバー範囲をすばやく立ち上げるのに使えます。 - **合成ケース:** 専門家が書いた例や AI が生成した例は、穴を埋め、アプリケーションが直面するであろう状況を把握するのに役立ちます。 情報源ごとに、入力のトピック、入力と出力の形、失敗モードを確認します。 本番トレースには評価器が必要とするリトリーバルのコンテキストが含まれていない、レガシーシステムのチケットのほうがトレースより良い失敗ラベルを持っている、あるいはサポートがいつの間にか「FAQ」を作っていたおかげでエンドツーエンドの良い例がすでにそろっている、といったことが分かるかもしれません。 ここで得たものを、次のステップでの入力分布・評価器・アイテムスキーマの決定に使います。 > **ガイド: [合成データセット](/guides/cookbook/example_synthetic_datasets)** > > 他に使えるデータがないときの出発点として、合成データを使います。 ## 3. 入力の分布を決める 最初のデータセットでは、入力の分布はシンプルに保ちます。 実行後に何をすべきかが分かる、少数のスライスから始めてください。 - **シナリオの種類:** 主要な用件、意図、ルート、タスクの系統。サポートのルーティング用データセットなら、請求、アカウントアクセス、技術的な問題、営業への問い合わせといったものです。 - **難易度やリスク:** 定型、曖昧、難しい、敵対的、業務上クリティカルなケース。ハッピーパス以外も含めますが、最初のデータセットをエッジケースだらけにはしないでください。 - **データセット上の役割:** その行が存在する理由。典型ケース、既知のリグレッション、観測された失敗、合成による穴埋めなど。 サポートのルーティング用データセットなら、最初のバージョンは「シナリオ × 難易度」の単純なマトリクスでよいでしょう。 ![入力分布のマトリクス](/images/academy/datasets/input-distribution-matrix.png) 入力分布とは、データセットに含めるケースの意図的な配合のことです。 どのシナリオが現れ、それがどれくらい難しく、なぜその行が入っているのか。 実験結果をスライスごとに解釈するためのカバー範囲の計画です。 分布が本番の頻度を正確に写している必要はありません。 リグレッション用データセットは、失敗・エッジケース・価値の高い経路を意図的に多めに含めて構いません。 重要なのは、その配合が意図的であり、メタデータから見て取れることです。 軸を増やすのは、それが挙動を変えるか、結果の解釈に役立つ場合だけにしてください。 チャネル、言語、顧客セグメント、地域、コンテキストの有無、プロダクト領域はメタデータとして有用ですが、初日からすべてをバランス調整の制約にする必要はありません。 ## 4. 評価をどう行うかを決める 期待出力を書く前に、評価の方式を選んでください。 これによって、データセットアイテムに何を含める必要があるか、最初の結果がどれだけ役に立つかが決まります。 各アイテムに既知の正解がある場合は [参照あり評価](/academy/japan/evaluate#reference-based-vs-reference-free) を使います。 正しいラベル、期待されるツール呼び出し、必須の事実、構造化出力、参照回答、期待される次のアクションなどです。 失敗を調べやすいため、リグレッションテストや CI ゲートに最も適しています。 トレードオフは、参照を書くのに手間がかかること、そして挙動ではなく文言まで細かく規定してしまうと壊れやすくなることです。 安定した期待出力はないが、すべてのアイテムを同じルールや基準で判定できる場合は [参照なし評価](/academy/japan/evaluate#reference-based-vs-reference-free) を使います。 有効な JSON か、言語が一致しているか、与えられたコンテキストに基づいているか、安全性、トーンといったチェックに向いています。 トレードオフは、評価器や基準の比重が大きくなることです。基準が曖昧なら結果も曖昧になります。 たとえば、ドキュメント用チャットボットのデータセットはどちらの方式でも作れます。 | 方式 | `input` の形 | `expectedOutput` の形 | 評価器の考え方 | | -------- | ---------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | 参照なし | `{ question, retrievedContext[] }` | `expectedOutput` を省略するか `null` にする | LLM-as-a-Judge が、回答が取得したドキュメントに基づいているか、質問に答えているか、裏付けのない事実を避けているかを確認します。 | | 参照あり | `{ question }` | `{ requiredFacts[], requiredSources[], mustNot[] }` | コードまたは LLM の評価器が、回答を必須の事実と出典に照らして比較します。準備は増えますが、失敗を調べやすくなります。 | 要件を捉えられる範囲で最も安い評価器を選んでください。 決定論的なチェックには [コードベース評価器](/docs/evaluation/evaluation-methods/code-evaluators)、言語品質の判断には [LLM-as-a-Judge](/docs/evaluation/evaluation-methods/llm-as-a-judge)、良い出力と悪い出力がどういうものかをまだ学んでいる段階では [手動評価](/academy/japan/evaluate#how-evaluation-typically-evolves) です。 この段階で決める必要があるのは、各データセットアイテムをどうレビューするか (自動評価器か、手動アノテーションか、その両方か) だけです。 評価器そのものを設計する踏み込んだ作業については、[評価の Academy ページ](/academy/japan/evaluate) を参照してください。 各行を採点する評価器やレビュー基準をまだ言語化できないなら、まずレビューのワークフローから始め、[アノテーションキュー](/docs/evaluation/evaluation-methods/annotation-queues) で手動ラベリングしてください。 ## 5. アイテムのスキーマを設計する [データセットアイテムの 3 フィールド](/academy/japan/datasets#the-dataset-item) は柔軟な JSON です。 ここでは、それを実験ランナー・評価器・レビュアーのすべてが扱える具体的な取り決めとして定義します。 次を定義します。 - `input`: システム境界に渡すオブジェクト - `expectedOutput`: 評価器やレビュアーが必要とする参照データだけ。意図的に参照なし評価を行う場合は省略します - `metadata`: 出どころ、シナリオの種類、難易度、データセット上の役割、レビュー状態など、安定したスライスと来歴のフィールド アイテムスキーマを決めたら、それを強制してください。 チームで [正しい構造のまま](/docs/evaluation/experiments/datasets#schema-enforcement) アイテムを追加していけるようになります。 サポートのルーティング用データセットなら、1 行は次のような形になります。 ```json { "input": { "message": "I was charged twice for invoice 4831. Can someone fix this?", "channel": "support_chat", "customer_tier": "business" }, "expectedOutput": { "route": "billing_support", "required_actions": ["acknowledge_duplicate_charge", "ask_for_invoice_id"], "must_not": ["promise_refund_without_review"] }, "metadata": { "source": "expert", "scenario_type": "billing", "difficulty": "medium", "dataset_role": "regression", "failure_mode": "wrong_route" } } ``` `input` にはルーターが必要とするコンテキストだけを残しています。 `expectedOutput` はチェックすべき挙動を示しています。請求サポートにルーティングし、請求書 ID を尋ね、レビュー前に返金を約束しないことです。 `metadata` はその行の出どころ、シナリオ、難易度、役割を記録しています。 行をまとめて集める前に、スキーマを安定させてください。 会話履歴、取得したコンテキスト、ツールの状態、ルーティング用メタデータ、ユーザー属性など、挙動を左右するフィールドは保持しつつ、行ごとに勝手なフィールドを足したり、構造化されたコンテキストを自然文で要約したものを入れたりするのは避けます。 ## 6. 最初のバージョンを作る 目的・分布・評価方法・スキーマが具体化したら、選んだ情報源の例を [データセットアイテム](/docs/evaluation/experiments/datasets) に変えていきます。 先ほど調べた情報源を使い、定義したスキーマに合う形式で追加します。 最小限そろった最初のバージョンとしては、入力分布に沿って取り決め全体をテストできるだけの行を選びます。 - 確実に動くべき、よくあるシナリオ - 曖昧なケースやリスクの高いケースをいくつか - 再発を防ぎたい既知の失敗やリグレッション - 本番トレースや既存資産では分布をカバーできない箇所に限った、合成による穴埋め データセットが完成した感じになるまで待たないでください。 行を増やす前に、筋の通った最初のバージョンを [実験](/docs/evaluation/core-concepts#experiments) で実行します。 ## 7. 最初の実験を回し、意図的に広げる 最初の実行では、入力の形が実際のアプリケーション経路で機能するか、評価器の結果が納得できるものか、期待出力の形が意図した目的に合っているかを確認します。 最初の実行のあとは、変更のリリースに自信を持てるスコープと形にたどり着くまで、拡張と反復を続けます。 - ある失敗から、抜けていたシナリオ・難易度・情報源が見えたら行を追加します。 - 期待出力・基準・入力の形・メタデータが曖昧なら行を修正します。 - 現在のプロンプト・ツール・ポリシー・プロダクトの挙動に合わなくなった行はアーカイブします。 ## データセットは時間とともにどう育つか データセットはアプリケーションとともに育っていく必要があります。 [本番のモニタリング](/academy/japan/monitoring) と、体系的な [エラー分析](/academy/japan/monitoring/error-analysis) による定期的なデータレビューを通じて、データセットはシステムの本番スコープを代表するものへと育っていきます。 有用な拡張パターンが 3 つあります。 - **本番の写し取り**: 良し悪しにかかわらず、注目すべきケースを本番から追加し、データセットのカバー範囲を時間をかけて広げます。 - **失敗トレースからの拡張:** 深刻な本番の失敗を見つけたら、その都度レビュー済みのデータセットアイテムを追加します。システムが本番稼働していて、継続的にトレースを掘れる状態になってから有効です。採点には [LLM-as-a-Judge](/docs/evaluation/evaluation-methods/llm-as-a-judge) や [コードベース評価器](/docs/evaluation/evaluation-methods/code-evaluators) といった自動評価器を使うか、[アノテーションキュー](/docs/evaluation/evaluation-methods/annotation-queues) に送って手動レビューします。 - **目的別のデータセット:** 安定したリグレッション用、敵対的入力用、単一ステップの評価用に、それぞれ別のデータセットを作ります。 > **ガイド: [ドキュメント用チャットボットの評価](/guides/cookbook/example_pydantic_ai_mcp_agent_evaluation)** > > ドキュメント用チャットボットにおけるデータセットと評価の具体例を見られます。 ## 実践に移す - **リリース判断の問いを 1 つ決めて始める。** プロダクト領域を 1 つ選び、特定の変更をリリースできるかを判断できる最小のエンドツーエンドのデータセットを作ります。 - **15〜30 行にする。** 最もよくあるシナリオ、リスクの高いケースをいくつか、既知の失敗を 1〜2 件カバーします。 - **すべての行を実行可能かつ評価可能に保つ。** 各入力はアプリケーションの経路を通せて、評価器またはレビュー基準で採点できる必要があります。 - **最初の実行のあとに広げる。** 再発を防ぎたい本番の失敗トレースを追加し、1 つのデータセットが異なる役割を混ぜ始めたら目的別に分け、合成の行は名前の付いた穴に限って追加します。
データセットを点検するための基本ルール - 補足情報・メモ・コメントの類はメタデータに入れます。期待出力には入れません。 - 評価方式を混ぜないでください。すべてのアイテムを同じ形・同じ評価対象にそろえます。 - すべての入力を、意図したアプリケーション経路に通せる状態に保ちます。 - 各バリエーションが別々の挙動をテストしているのでない限り、行は重複を排除します。 - 結果をフィルタして解釈できる程度には、メタデータの値を一貫させます。 - 結果をスライスしやすいよう、データセット上の役割と出どころをラベル付けします。 - 本番トレースは種であって、正解データではないものとして扱います。 - 合成の行は、名前の付いた穴に限って追加します。 - PII や機微データは、データセットに入る前に処理します。 - プロンプト・ツール・ポリシー・プロダクトの挙動が変わったら、古くなった行をアーカイブまたは更新します。
--- ## 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/datasets/designing-great-datasets.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**: , 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 `) to read or write traces, prompts, datasets, and scores from the terminal. Found an error in these docs? Please open an issue at .