資料集結構描述和測試設計

評估資料集是包含提示和預期回應的 JSON 檔案。 本文定義資料集結構描述、工具尋找資料集的文件,並示範如何設計有效的測試,包括多輪交談、每個項目評估工具設定和分類測試套件等進階案例。

結構描述概觀

評估資料集為 JSON 檔案。 此工具支援兩種對等圖形:版本化物件 (建議) 和舊版陣列。

版本設定的結構描述

注意

CLI v1 支援兩種資料集圖形:版本化物件 (建議) 和舊陣列。 CLI v2 需要一個版本化物件,其中包含 schemaVersionitems和 。

資料集會使用 schemaVersion 和 items 陣列。 下列範例包含 expected_response 將回應與參考答案進行比較的評估者。 相關性、一致性和 v2 預覽工具 expected_response呼叫等評估工具不需要 。

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

結構描述版本 1.6.0 新增對預設和每個項目評估器設定、評估者模式控制項、具名項目和多輪交談的支援。 如需詳細資訊,請參閱設定評估器和多回合評估模式。

選擇符合您 CLI 版本的資料集結構描述版本:

  • CLI v1 (latest) : 使用結構描述 v1。 本文中的結構描述 v1 範例仍然適用。
  • CLI v2 (preview) : 使用 schemaVersion"2.0.0" 和 結構描述 V2 定義。 無論您選取哪個評估工具,CLI v2 不接受結構描述 v1 或未版本控制的資料集。

透過 Microsoft 365 Copilot 評估獨立外掛程式需要 CLI v2。 工具呼叫評估器也需要 CLI v2,無論是評估獨立外掛程式還是宣告式代理程式。 CLI v1 繼續支援使用其支援的評估器評估宣告式代理程式,包括具有外掛程式動作的代理程式。

結構描述欄位

您可以在 GitHub 上以 JSON 結構描述格式找到評估資料集結構描述。

欄位 Type (類型) 必要 描述
schemaVersion string CLI v2 中為必要項目;CLI v1 中的建議 資料集結構描述版本。 搭配 CLI v2 (preview) ,或與支援的 v1 結構描述版本搭配使用 "2.0.0" CLI v1 (latest) 。 架構主要版本內保證回溯相容性。
items 陣列 是 測試項目陣列。 每個項目都是單輪提示/回應對或指定的多輪交談。
description 字串 選擇性 資料集的自由文字描述 (例如 "Regression tests for Q1 2026 release") 。
default_evaluators 物件 選擇性 評估工具會套用至資料集中的每個項目,除非覆寫。 每個機碼都是一個評估工具名稱 (例如, "Relevance") "Coherence" ;值是用於 {} 預設值) (選項物件。 必要 schemaVersion"1.2.0" 或更新版本。
items[].prompt 字串 條件 傳送給客服專員的提示或指示。 單輪項目所需。 請勿搭配 turns使用 。
items[].expected_response 字串 條件 用於評分的參照回應。 評估工具需要,例如 Similarity、ExactMatch 和 PartialMatch,但工具呼叫評估工具不需要。 請勿搭配 turns使用 。
items[].name 字串 選擇性 測試項目的顯示名稱 (例如, "Expense policy flow") 。 對於識別報表中的多輪項目特別有用。
items[].turns 陣列 條件 用於單一項目內多風對話的有序回合物件陣列。 當選取的評估者需要時,每個回合都包含 prompt, expected_response 並選擇性地包含 evaluators 和 evaluators_mode。 請勿搭配使用頂層 prompt/expected_response. 必要 schemaVersion"1.2.0" 或更新版本。
items[].evaluators 物件 選擇性 每個項目評估工具覆寫。 每個機碼都是評估者名稱;值是 Options 物件 (例如 { "citation_format": "mixed" }) 。 行為取決於 evaluators_mode。 必要 schemaVersion"1.2.0" 或更新版本。
items[].evaluators_mode 字串 選擇性 控制 items[].evaluators 如何與 default_evaluators結合 。 使用 "extend" 預設 () 將每個項目的評估工具與預設值合併,或 "replace" 只使用每個項目的評估工具並忽略預設值。 必要 schemaVersion"1.2.0" 或更新版本。
items[].testId 字串 選擇性 跨版本比較的穩定識別碼 ("REG-001" 例如) 。
items[].category 字串 選擇性 類別標籤 (例如, "knowledge-base") "tool-usage" 。
items[].notes 字串 選擇性 手繪多邊形附註,例如連結的錯誤識別碼。
default_allowed_tools 字串陣列 選擇性 資料集已核准同意識別碼。 如需 v2 預覽中工具呼叫評估工具的使用方式,請參閱 允許工具呼叫。
items[].allowed_tools / items[].turns[].allowed_tools 字串陣列 選擇性 已核准提示或回合的同意識別碼。 這些不是評估工具身分識別。
items[].allowed_tools_mode / items[].turns[].allowed_tools_mode 字串 選擇性 "extend" (預設) allowed_tools 與 default_allowed_tools結合。 "replace" 僅使用提示或回合的清單。 使用 with allowed_tools: [] 可"replace"核准該提示或回合的任何工具確認要求。

設定評估工具

結構描述版本 1.6.0 可讓您在資料集層級和個別項目層級控制執行的評估器及其設定方式。 如需每個評估者的評分行為和設定選項的詳細資訊,請參閱 評估器參考。

預設評估工具

在頂層使用 來 default_evaluators 指定套用至資料集中每個項目的評估工具。 每個索引鍵都是評估工具名稱,而值則是選項物件。 使用空白物件 ({}) 以套用評估工具及其預設設定。

{
  "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" (每個項目覆寫) 進行評分。

允許工具呼叫

評估要求確認的工具呼叫時,請設定核准和評估者期望。 default_allowed_tools 在文件層級並 allowed_tools 按每個提示或回合,讓 CLI 核准工具確認提示。 必須允許每個要求的同意識別碼;否則,提示會停止並出現 toolCallNotAllowed 錯誤。

重要

允許通話會授與同意。 使用已檢閱的案例,並從唯讀作業開始。 評估者期望不會授與同意,核准不會強制選擇工具或證明執行。 未要求確認的工具不受此清單控制,因此它不是安全性界限。

同意識別碼與評估者 calls[].tool中的三部分工具身分識別不同。 請勿分割同意識別碼來填入評估者欄位。 如需探索命令、組態和完整的結構描述 v2 資料集,請參閱 工具呼叫評估工具。

完整結構描述範例

下列範例顯示單一資料集中的每個結構描述功能:頂層預設值、具有評估器覆寫的單輪項目,以及具有每輪評估器組態的具名多輪項目。

{
  "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"
        }
      ]
    }
  ]
}

此範例中的重要詳細資料:

  • 第一項是單輪測試。 它繼RelevanceCoherence承和繼default_evaluators承,並透過模式相"extend"加Citations。
  • 第二個項目是具名多輪交談 ("Expense policy flow") 有兩輪。 第一個回合會繼承預設評估工具。 第二個回合使用 "replace" 模式,因此只會 ExactMatch 執行 - 該回合的預設值會被忽略。

舊版陣列架構

該工具還接受裸陣列以實現回溯兼容性:

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

CLI 會自動將遺漏 schemaVersion) (舊版文件升級為版本化格式,並寫入帶時間戳記的備份。

檔案命名和位置

評估工具會自動探索專案中的資料集檔案。

自動探索順序

當您執行 runevals時,工具會以下列順序搜尋資料集:

  1. 目前目錄: prompts.json, , evals.jsontests.json
  2. ./evals/子目錄: prompts.json, , evals.jsontests.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"
}

工具使用方式

測試代理程式是否正確使用可用的工具和外掛程式。

下列回應型範例無法證明已選取或執行工具。 若要檢查執行階段行為,請使用 CLI v2 預覽中的 ToolCallSelection 或 ToolCallExecution 。

{
  "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 陣列來定義有序的提示順序和預期回應,以形成單一交談流程。 每個回合都可以選擇包含自己的評估器組態。

{
  "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 項目都會評估為單一交談。 回合按順序發送,每個回合都建立在前一個回合的對話上下文之上。
  • 使用欄位在 name 報表中為多輪項目提供可讀標籤。
  • 您可以申請 evaluators 和 evaluators_mode 個別回合。 在上述範例中,第二個回合使用 "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"
    }
  ]
}

注意

使用連續項目時,每個項目都會獨立評估。 代理程式不會在項目之間傳遞交談內容。 若要使用共用內容進行真正的多回合評估,請使用 turns 具有結構描述版本 1.2.0 或更新版本的陣列。

每個提示分類和評分

使用選用 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"
    }
  ]
}

資料集組織策略

對於大型專案,請跨多個檔案依類別組織測試。

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:無基礎或引文

相似性 (1-5)

相似度會測量回應與預期輸出的相符程度:

  • 5:回應在語義上等同於預期的輸出
  • 3:回應部分符合預期的輸出
  • 1:回應與預期輸出不符

引文 (>= 0)

引文是一種基於計數的評估工具,用於計算回應中有效引文數量。 分數表示 0 不存在引用。 設定最小閾值以設定通過/失敗標準。

ExactMatch

ExactMatch 是具有布林值結果的字串比對評估工具。 如果回應確切包含預期的字串,則會傳遞。 支援 case_sensitive 預設 (選項: false) 。

PartialMatch (0.0-1.0)

PartialMatch 是一個字串比對評估工具,它傳回 和 1.0之間的0.0連續相似性分數。 使用選項來 threshold 設定通過 (所需的最低分數預設值: 0.5) 。

持續改進

檢閱未通過的測試

當測試得分低時:

  1. 檢閱實際回應與預期回應。
  2. 判斷預期的回應是否需要更新。
  3. 檢查客服專員是否需要更多訓練資料或指示。
  4. 確認工具組態正確無誤。

追蹤一段時間的分數

儲存測試結果以在不同版本之間進行比較。

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