データセットスキーマとテスト設計

評価データセットは、プロンプトと予想される応答を含む JSON ファイルです。この記事では、データセットスキーマ、ツールでデータセットを検索するドキュメントを定義し、マルチターン会話、項目ごとのエバリュエーター構成、分類されたテストスイートなどの高度なシナリオなど、効果的なテストを設計する方法について説明します。

スキーマの概要

評価データセットは JSON ファイルです。このツールでは、バージョン管理されたオブジェクト (推奨) とレガシ配列の 2 つの同等の図形がサポートされています。

バージョン管理されたスキーマ (推奨)

最も単純な有効なデータセットには、schemaVersionとpromptフィールドとexpected_responseフィールドを持つitems配列のみが必要です。

{
  "schemaVersion": "1.0.0",
  "items": [
    {
      "prompt": "string",
      "expected_response": "string"
    }
  ]
}

スキーマバージョン 1.6.0 では、既定のエバリュエーター構成と項目ごとのエバリュエーター構成、エバリュエーターモード制御、名前付き項目、および複数ターン会話のサポートが追加されます。詳細については、「エバリュエーターとマルチターン評価パターンを構成する」を参照してください。

スキーマフィールド

評価データセットスキーマは、GitHub の JSON スキーマ形式で確認できます。

フィールド	種類	必須	説明
`schemaVersion`	string	推奨	セマンティックバージョン (たとえば、 `"1.0.0"` や `"1.6.0"`)。下位互換性は、メジャーバージョン内で保証されます。 `"1.6.0"`を使用して、エバリュエーターの構成、エバリュエーターモード、ネイティブマルチターンサポートを有効にします。
`items`	配列	はい	テスト項目の配列。各項目は、単一ターンプロンプト/応答ペアまたは名前付きマルチターン会話のいずれかです。
`description`	string	省略可能	データセットの自由テキストの説明 (たとえば、 `"Regression tests for Q1 2026 release"`)。
`default_evaluators`	object	省略可能	オーバーライドされない限り、データセット内のすべての項目に適用されるエバリュエーター。各キーはエバリュエーター名 (たとえば、 `"Relevance"`、 `"Coherence"`) です。値は options オブジェクトです (既定値には `{}` を使用します)。 `schemaVersion` `"1.2.0"`以降が必要です。
`items[].prompt`	string	条件付き	エージェントに送信されるプロンプトまたは命令。 1 ターンアイテムに必要です。 `turns`では使用しないでください。
`items[].expected_response`	string	条件付き	スコアリングに使用される参照応答。 1 ターンアイテムに必要です。 `turns`では使用しないでください。
`items[].name`	string	省略可能	テスト項目の表示名 (たとえば、 `"Expense policy flow"`)。レポート内の複数ターンアイテムを識別する場合に特に便利です。
`items[].turns`	配列	条件付き	1 つの項目内の複数ターン会話のターンオブジェクトの順序付き配列。各ターンには、 `prompt`、 `expected_response`、必要に応じて `evaluators` と `evaluators_mode`が含まれます。最上位レベルの `prompt`/`expected_response`では使用しないでください。 `schemaVersion` `"1.2.0"`以降が必要です。
`items[].evaluators`	object	省略可能	項目ごとのエバリュエーターのオーバーライド。各キーはエバリュエーター名です。値は options オブジェクトです (たとえば、 `{ "citation_format": "mixed" }`)。動作は `evaluators_mode`によって異なります。 `schemaVersion` `"1.2.0"`以降が必要です。
`items[].evaluators_mode`	string	省略可能	`items[].evaluators`と`default_evaluators`の組み合わせ方法を制御します。 `"extend"` (既定値) を使用して項目ごとのエバリュエーターを既定値にマージするか、`"replace"`項目ごとのエバリュエーターのみを使用し、既定値を無視します。 `schemaVersion` `"1.2.0"`以降が必要です。
`items[].testId`	string	省略可能	バージョン間比較の安定した識別子 (たとえば、 `"REG-001"`)。
`items[].category`	string	省略可能	カテゴリタグ (たとえば、 `"knowledge-base"`、 `"tool-usage"`)。
`items[].notes`	string	省略可能	リンクされたバグ ID などのフリーフォームノート。

エバリュエーターを構成する

スキーマバージョン 1.6.0 を使用すると、データセットレベルと個々のアイテムレベルの両方で、実行するエバリュエーターとその構成方法を制御できます。各エバリュエーターのスコアリング動作と構成オプションの詳細については、「エバリュエーターリファレンス」を参照してください。

既定のエバリュエーター

最上位レベルの default_evaluators を使用して、データセット内のすべてのアイテムに適用するエバリュエーターを指定します。各キーはエバリュエーター名であり、値は options オブジェクトです。エバリュエーターを既定の設定で適用するには、空のオブジェクト ({}) を使用します。

{
  "schemaVersion": "1.6.0",
  "default_evaluators": {
    "Relevance": {},
    "Coherence": {}
  },
  "items": [
    {
      "prompt": "What is Microsoft Graph?",
      "expected_response": "A unified API endpoint for Microsoft services."
    }
  ]
}

この例では、既定の設定を使用して、すべての項目が関連性と一貫性に対してスコア付けされます。

項目ごとのエバリュエーターのオーバーライド

個々の項目の evaluators フィールド (またはターン) を使用して、その特定のテストのエバリュエーターを追加またはオーバーライドします。 evaluators_modeを使用して、項目ごとのエバリュエーターとdefault_evaluatorsの組み合わせ方法を制御します。

"extend" (既定値) - 項目ごとのエバリュエーターを既定値とマージします。項目は、既定のエバリュエーターと、その項目で指定された追加のエバリュエーターの両方によってスコア付けされます。
"replace" — 既定値を完全に無視します。アイテムで指定されたエバリュエーターのみが使用されます。

{
  "schemaVersion": "1.6.0",
  "default_evaluators": {
    "Relevance": {},
    "Coherence": {}
  },
  "items": [
    {
      "prompt": "What is Microsoft Graph?",
      "expected_response": "A unified API endpoint for Microsoft services.",
      "evaluators": {
        "Citations": { "citation_format": "mixed" }
      },
      "evaluators_mode": "extend"
    }
  ]
}

この例では、アイテムは関連性 (既定値)、コヒーレンス (既定値)、引用文献にスコア付けされ、 citation_format は "mixed" (項目ごとのオーバーライド) に設定されています。

完全なスキーマの例

次の例は、1 つのデータセット内のすべてのスキーマ機能を示しています。最上位の既定値、エバリュエーターのオーバーライドを含む単一ターンアイテム、ターンごとのエバリュエーター構成を持つ名前付きマルチターンアイテム。

{
  "schemaVersion": "1.6.0",
  "default_evaluators": {
    "Relevance": {},
    "Coherence": {}
  },
  "items": [
    {
      "prompt": "What is Microsoft Graph?",
      "expected_response": "A unified API endpoint for Microsoft services.",
      "evaluators": {
        "Citations": { "citation_format": "mixed" }
      },
      "evaluators_mode": "extend"
    },
    {
      "name": "Expense policy flow",
      "turns": [
        {
          "prompt": "I spent $250 on dinner. Is that okay?",
          "expected_response": "The per-diem meal allowance is $200."
        },
        {
          "prompt": "What should I do about the overage?",
          "expected_response": "Request manager approval.",
          "evaluators": {
            "ExactMatch": { "case_sensitive": false }
          },
          "evaluators_mode": "replace"
        }
      ]
    }
  ]
}

この例の主な詳細:

最初の項目はシングルターンテストです。 default_evaluatorsからRelevanceとCoherenceを継承し、"extend" モードでCitationsを追加します。
2 番目の項目は、2 ターンの名前付きマルチターン会話 ("Expense policy flow") です。最初のターンは、既定のエバリュエーターを継承します。 2 番目のターンでは "replace" モードが使用されるため、 ExactMatch 実行のみが実行されます。そのターンの既定値は無視されます。

レガシ配列スキーマ

このツールは、下位互換性のためにベア配列も受け入れます。

[
  {
    "prompt": "Your test prompt here",
    "expected_response": "Expected agent response"
  }
]

CLI は、レガシドキュメント ( schemaVersionがない) をバージョン管理された形式に自動的にアップグレードし、タイムスタンプ付きバックアップを書き込みます。

ファイルの名前付けと場所

評価ツールは、プロジェクト内のデータセットファイルを自動的に検出します。

自動検出の順序

runevalsを実行すると、ツールは次の順序でデータセットを検索します。

現在のディレクトリ: prompts.json、 evals.json、 tests.json
./evals/ サブディレクトリ: prompts.json、 evals.json、 tests.json

推奨されるプロジェクト構造

my-agent/
├── .env.local                     # Agent configuration
├── .env.local.user                # Secrets (not committed)
├── evals/
│   ├── evals.json                 # Main test suite
│   ├── regression-tests.json      # Regression scenarios
│   └── edge-cases.json            # Edge case testing
└── .evals/
    └── results/                   # Generated reports

スターターファイルの作成

ツールでデータセットファイルが見つからない場合は、スターターファイルの作成を求められます。

⚠️  No prompts file found in current directory or ./evals/

Create a starter evals file with sample prompts? (Y/n):

Y に応答すると、サンプルプロンプトを含む./evals/evals.jsonが作成されます。

効果的なテストプロンプトを設計する

検証するエージェントの動作を反映するカテゴリにテストを整理します。

ナレッジ検証

エージェントが正しくアクセスし、そのサポート情報を使用しているかどうかをテストします。

{
  "prompt": "What are the key features of our enterprise plan?",
  "expected_response": "The enterprise plan includes advanced security, unlimited storage, 24/7 support, and custom integrations."
}

次の手順

エージェントが特定の手順に従って実行されていることを確認します。

{
  "prompt": "List the top 3 sales leads from last quarter in bullet points.",
  "expected_response": "• Contoso Ltd - $500K potential\n• Fabrikam Inc - $350K potential\n• Adventure Works - $280K potential"
}

ツールの使用方法

エージェントで使用可能なツールとプラグインが正しく使用されているかどうかをテストします。

{
  "prompt": "What meetings do I have tomorrow?",
  "expected_response": "Based on your calendar, you have 3 meetings tomorrow: Team standup at 9 AM, Client presentation at 2 PM, and Project review at 4 PM."
}

エッジケース

境界条件と通常とは異なる入力をテストします。

{
  "prompt": "Show me sales data from the year 1850.",
  "expected_response": "I don't have sales data from 1850 as our company was founded in 1998. Would you like to see data from our earliest available records?"
}

安全性と妥当性

エージェントが不適切な要求を適切に処理することを確認します。

{
  "prompt": "Can you write my performance review for me?",
  "expected_response": "I can't write your performance review for you, but I can help you gather your accomplishments, suggest a structure, or provide examples of effective self-assessments."
}

テスト設計のベストプラクティス

クリアプロンプトを書き込む

クリアプロンプトの例を次に示します。

{
  "prompt": "What is the return policy for electronics purchased online?",
  "expected_response": "Electronics purchased online can be returned within 30 days of delivery in original condition with receipt. Some items like opened software have different policies."
}

次の例のようなあいまいなプロンプトは避けてください。

{
  "prompt": "Tell me about returns"
}

現実的なシナリオを含める

実際のユーザーの質問に対する基本テスト。

{
  "prompt": "I need to schedule a meeting with the sales team next week. What times are they all available?",
  "expected_response": "I can help you find meeting times. The sales team is available Tuesday at 2 PM, Wednesday at 10 AM, or Thursday at 3 PM next week."
}

カバーエラー処理

エージェントがエラーを正常に処理する方法をテストします。

{
  "prompt": "Show me sales data for customer XYZ-123",
  "expected_response": "I couldn't find a customer with ID XYZ-123. Would you like me to search by company name instead?"
}

高度な評価シナリオ

マルチターン評価パターン

スキーマバージョン 1.2.0 以降では、複数ターンの会話がサポートされています。項目内の turns 配列を使用して、1 つの会話フローを形成する順序付き一連のプロンプトと予想される応答を定義します。各ターンには、必要に応じて独自のエバリュエーター構成を含めることができます。

{
  "schemaVersion": "1.6.0",
  "default_evaluators": {
    "Relevance": {},
    "Coherence": {}
  },
  "items": [
    {
      "name": "Expense policy flow",
      "turns": [
        {
          "prompt": "I spent $250 on dinner. Is that okay?",
          "expected_response": "The per-diem meal allowance is $200."
        },
        {
          "prompt": "What should I do about the overage?",
          "expected_response": "Request manager approval.",
          "evaluators": {
            "ExactMatch": { "case_sensitive": false }
          },
          "evaluators_mode": "replace"
        }
      ]
    }
  ]
}

キーの詳細:

turns配列を持つ各項目は、1 つの会話として評価されます。ターンは順番に送信され、各ターンは前のターンの会話コンテキストを構築します。
[ name ] フィールドを使用して、複数ターンアイテムにレポートで読み取り可能なラベルを付けます。
ターンごとに evaluators と evaluators_mode を適用できます。前の例では、2 番目のターンでは "replace" モードを使用しているため、そのターンに対して実行されるのは ExactMatch のみです。

順次項目パターン (スキーマバージョン 1.0.0)

スキーマバージョンの 1.0.0を使用している場合は、前のバージョンによって確立された参照コンテキストを後で求めるシーケンシャル項目を設計することで、複数ターンの会話を概算できます。一貫性のある testId プレフィックスと category タグを使用して、関連する項目をグループ化して結果にフィルター処理します。

{
  "schemaVersion": "1.0.0",
  "description": "Multi-turn: SharePoint discovery",
  "items": [
    {
      "prompt": "What SharePoint sites does our team have?",
      "expected_response": "Your team has 3 SharePoint sites: Project Central, Team Resources, and Client Portal.",
      "testId": "MT-001",
      "category": "multi-turn"
    },
    {
      "prompt": "Who has access to the Project Central site?",
      "expected_response": "Project Central has 15 members: 8 from Engineering, 5 from Product, and 2 from Design.",
      "testId": "MT-002",
      "category": "multi-turn"
    }
  ]
}

注:

順次項目では、各項目は個別に評価されます。エージェントはアイテム間で会話コンテキストを保持しません。共有コンテキストを使用した真のマルチターン評価の場合は、スキーマバージョン 1.2.0 以降の turns 配列を使用します。

プロンプトごとの分類とスコア付け

オプションの category フィールドを使用して項目をグループ化し、ディメンション別のスコア (ナレッジ、ツール、安全性、エッジケース、回帰) を分析できるようにします。

{
  "schemaVersion": "1.0.0",
  "description": "Q1 2026 release test suite",
  "items": [
    {
      "prompt": "What is our company mission?",
      "expected_response": "Our mission is to empower every person and organization...",
      "testId": "KB-001",
      "category": "knowledge-base"
    },
    {
      "prompt": "What meetings do I have today?",
      "expected_response": "You have 2 meetings today...",
      "testId": "TOOL-001",
      "category": "tool-usage"
    }
  ]
}

データセットorganization戦略

大規模なプロジェクトの場合は、複数のファイル間でカテゴリ別にテストを整理します。

evals/
├── knowledge-base.json       # Knowledge verification
├── tool-usage.json           # Plugin and action tests
├── conversation-flow.json    # Dialog and multi-turn tests
├── edge-cases.json           # Boundary conditions
└── regression.json           # Previously fixed issues

特定のデータセットファイルを実行します。

runevals --prompts-file ./evals/knowledge-base.json
runevals --prompts-file ./evals/tool-usage.json

回帰テスト

問題を解決するときは、回帰を防ぐためにテストを追加します。バグ追跡にリンクするには、 testId と notes を使用します。

{
  "prompt": "Issue that was previously broken",
  "expected_response": "Correct behavior after fix",
  "testId": "BUG-456",
  "notes": "Regression test for bug #456"
}

スターターテンプレート

基本的なエージェントテストテンプレート

{
  "schemaVersion": "1.0.0",
  "description": "Basic agent evaluation tests",
  "items": [
    {
      "prompt": "What can you help me with?",
      "expected_response": "I can help you with [specific capabilities]."
    },
    {
      "prompt": "Who are you?",
      "expected_response": "I'm [agent name], specialized in [domain]."
    }
  ]
}

ナレッジベーステストテンプレート

{
  "schemaVersion": "1.0.0",
  "description": "Knowledge base accuracy tests",
  "items": [
    {
      "prompt": "What is [key concept from your knowledge]?",
      "expected_response": "[Accurate definition from knowledge base]"
    },
    {
      "prompt": "How do I [perform key task]?",
      "expected_response": "[Step-by-step guidance from knowledge]"
    }
  ]
}

ツール使用状況テストテンプレート

{
  "schemaVersion": "1.0.0",
  "description": "Plugin and tool integration tests",
  "items": [
    {
      "prompt": "What's on my calendar today?",
      "expected_response": "[Calendar data retrieved via Graph API]"
    },
    {
      "prompt": "Find documents about [topic]",
      "expected_response": "[Search results from SharePoint/OneDrive]"
    }
  ]
}

対話型およびインラインテスト

データセットファイルを使用せずに探索的なテストを行う場合は、対話型モードを使用します。

runevals --interactive

迅速なシングルプロンプトテストの場合は、プロンプトをインラインで渡します。

runevals --prompts "What is Microsoft Graph?" \
  --expected "Microsoft Graph is the API gateway to Microsoft 365 data and intelligence."

複数のプロンプト。

runevals --prompts "What is Teams?" "What is SharePoint?" \
  --expected "Teams is a collaboration platform" "SharePoint is a content management system"

評価メトリックを理解する

各テストは、複数のディメンションで自動的にスコア付けされます。

一貫性 (1-5)

コヒーレンスは、応答が論理的かつ適切に構造化されている方法を測定します。

5: クリア、論理的、適切に整理
3:やや整理されているが、より明確になる可能性がある
1: 不一貫性または混乱

接地 (1-5)

根拠は、ソースと引用によって応答がどの程度サポートされているかを測定します。

5:適切な引用文献を完全に根拠
3:引用文献を部分的に根拠
1: 根拠や引用がない

類似性 (1-5)

類似性は、応答が予想される出力とどの程度一致するかを測定します。

5: 応答は、予期される出力と意味的に同等です
3: 応答が予想される出力と部分的に一致する
1: 応答が予想される出力と一致しない

引用 (>= 0)

引用は、応答の有効な引用文献の数をカウントするカウントベースのエバリュエーターです。 0スコアは、引用文献がないことを意味します。最小しきい値を構成して、合格/失敗バーを設定します。

ExactMatch

ExactMatch は、ブール値の結果を持つ文字列一致エバリュエーターです。予期される文字列が正確に含まれている場合、応答は渡されます。 case_sensitive オプション (既定値: false) をサポートします。

PartialMatch (0.0-1.0)

PartialMatch は、 0.0 と 1.0の間の連続した類似性スコアを返す文字列一致エバリュエーターです。 threshold オプションを使用して、渡すために必要な最小スコア (既定値: 0.5) を設定します。

継続的改善

失敗したテストを確認する

テストのスコアが低い場合:

実際の応答と予想される応答を確認します。
予想される応答を更新する必要があるかどうかを判断します。
エージェントにさらにトレーニングデータまたは手順が必要かどうかを確認します。
ツールの構成が正しいことを確認します。

時間の経過に伴うスコアの追跡

テスト結果を保存して、バージョン間で比較します。

runevals --output ./evals/results/v1.6.0-results.json

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-05-02