数据集架构和测试设计

评估数据集是包含提示和预期响应的 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 架构格式的评估数据集架构。

域 类型 必需 说明
schemaVersion 字符串 在 CLI v2 中是必需的;CLI v1 中建议的内容 数据集架构版本。 "2.0.0"与 CLI v2 (preview) 一起使用,或通过 CLI v1 (latest) 支持的 v1 架构版本使用。 架构主要版本中的向后兼容性有保证。
items array 是 测试项数组。 每个项目要么是单轮提示/响应对,要么是命名的多轮对话。
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 array 条件 用于单个项目中 multiturm 对话的轮次对象的有序数组。 每个轮次包含 prompt, expected_response 当所选赋值器需要时,以及可选的 evaluatorsevaluators_mode和 。 不要与顶级 prompt/expected_response. 需要 schemaVersion"1.2.0" 或更高版本。
items[].evaluators 对象 可选 按项评估程序替代。 每个键都是一个评估程序名称;该值是一个选项对象 (例如 { "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 字符串 可选 任意多边形笔记,例如链接的 Bug ID。
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" (default) - 将每个项的计算器与默认值合并。 该项目由默认评估器和在项目上指定的任何其他评估程序进行评分。
  • "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"
        }
      ]
    }
  ]
}

此示例中的关键详细信息:

  • 第一项是单轮测试。 它继承和Coherence继Relevance承,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 字段在报表中为多轮次项目提供可读标签。
  • 您可以单独申请evaluatorsevaluators_mode。 在前面的示例中,第二个转弯使用 "replace" 模式,因此仅 ExactMatch 运行该转弯。

架构版本 1.0.0) (顺序项模式

如果您使用的是 schema version 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 and notes 链接回 bug 跟踪。

{
  "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)

Groundedness 衡量响应得到来源和引文支持的程度:

  • 5:完全有根据,并附有适当的引文
  • 3:部分有依据,有一些引文
  • 1:无基础或引文

相似度 (1-5)

相似性衡量响应与预期输出匹配的程度:

  • 5:响应在语义上等同于预期输出
  • 3:响应与预期输出部分匹配
  • 1:响应与预期输出不匹配

引文 (>= 0)

Citations 是一个基于计数的计算器,用于计算响应中有效引文的数量。 分数 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