Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Наборы данных для оценки — это файлы JSON, содержащие подсказки и ожидаемые ответы. В этой статье определяется схема набора данных, документы, в которых средство ищет наборы данных, и показано, как разрабатывать эффективные тесты, включая расширенные сценарии, такие как многоэтапные беседы, настройка оценщика для каждого элемента и наборы тестов с категориями.
Обзор схемы
Наборы данных для оценки представляют собой файлы JSON. Средство поддерживает две эквивалентные фигуры: объект с версиями (рекомендуется) и устаревший массив.
Схема с версиями
Примечание
CLI v1 поддерживает две фигуры набора данных: объект с версиями (рекомендуется) и устаревший массив. Для CLI v2 требуется объект с управлением версиями, содержащий schemaVersion и items.
Набор данных использует schemaVersion и массив.items Следующий пример включает expected_response оценщики, которые сравнивают ответ со ссылкой. Оценщики, такие как Relevance, Coherence и оценка вызова средства предварительного просмотра версии 2, не требуют expected_response.
{
"schemaVersion": "1.0.0",
"items": [
{
"prompt": "string",
"expected_response": "string"
}
]
}
В версии 1.6.0 схемы добавлена поддержка конфигурации оценщика по умолчанию и по каждому элементу, управления режимом оценщика, именованных элементов и многоходовых бесед. Дополнительные сведения см. в разделах Настройка вычислителей и шаблонов оценки с несколькими оборотами.
Выберите версию схемы набора данных, соответствующую вашей версии CLI:
-
CLI v1 (
latest): использование схемы v1. Примеры схемы версии 1 в этой статье остаются применимыми. -
CLI v2 (
preview): использованиеschemaVersion"2.0.0"и определение схемы версии 2. CLI версии 2 не принимает схему версии 1 или неверсионные наборы данных независимо от того, какие средства оценивания вы выберете.
Для оценки автономных подключаемых модулей с помощью Microsoft 365 Copilot требуется CLI версии 2. Оценщикам вызова инструментов также требуется интерфейс командной строки версии 2, независимо от того, оцениваете ли вы автономный подключаемый модуль или декларативный агент. CLI v1 продолжает поддерживать оценку декларативных агентов, включая агенты с подключаемыми действиями, с использованием поддерживаемых оценщиков.
Поля схемы
Схему набора данных для оценки можно найти в формате JSON Schema на сайте GitHub.
| Поле | Type (Тип) | Обязательный | Описание |
|---|---|---|---|
schemaVersion |
строка | Требуется в CLI версии 2; рекомендуется в интерфейсе командной строки версии 1 | Версия схемы набора данных. Используется "2.0.0" с интерфейсом командной строки версии 2 (preview) или поддерживаемой версией схемы версии 1 с CLI версии 1 (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 |
Массив строк | Необязательно | Идентификаторы согласия, утвержденные для набора данных. Сведения об использовании с обработчиками вызовов средств в предварительной версии 2 см. в статье Разрешить вызовы средств. |
items[].allowed_tools / items[].turns[].allowed_tools |
Массив строк | Необязательно | Идентификаторы согласия, утвержденные для запроса или поворота. Это не идентификаторы инструментов оценивания. |
items[].allowed_tools_mode / items[].turns[].allowed_tools_mode |
строка | Необязательно |
"extend" (по умолчанию) комбинируется allowed_tools с default_allowed_tools.
"replace" использует только список подсказок или ходов. Используйте "replace" с allowed_tools: [] для утверждения никаких запросов подтверждения средства для этого запроса или поворота. |
Настройка оценщиков
Версия 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" (переопределение для каждого элемента).
Разрешить вызовы инструментов
При оценивании вызовов инструментов, которые запрашивают подтверждение, настройте ожидания как для утверждения, так и для оценщика.
default_allowed_tools на уровне документа и allowed_tools для каждого запроса или очереди позвольте CLI утверждать запросы инструментального подтверждения. Необходимо разрешить каждый идентификатор запрошенного согласия. В противном случае запрос остановится с ошибкой toolCallNotAllowed .
Важно
Разрешение звонка дает согласие. Используйте проверенные сценарии и начните с операций только для чтения. Ожидание оценщика не предоставляет согласия, и утверждение не требует выбора инструмента или подтверждения его выполнения. Средства, не запрашивающие подтверждение, не контролируются этим списком, поэтому он не является границей безопасности.
Идентификаторы согласия отличаются от состоящего из трех частей идентификатора инструмента в домене calls[].tool. Не разделяйте идентификаторы согласия для заполнения полей оценщика. Команды обнаружения, конфигурации и полные наборы данных схемы версии 2 см. в статье Оценщики вызова инструментов.
Пример полной схемы
В следующем примере показаны все объекты схемы в одном наборе данных: значения по умолчанию верхнего уровня, одноходочный элемент с переопределениями оценщика и именованный многоходочный элемент с настройкой оценщика на каждый ход.
{
"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отdefault_evaluatorsи добавляетRelevanceCitationsчерез"extend"режим. - Второй элемент — это именованный многовитковый разговор (
"Expense policy flow") с двумя поворотами. Первый ход наследует вычислители по умолчанию. Второй ход использует"replace"режим, поэтому запускается толькоExactMatch- значения по умолчанию игнорируются для этого хода.
Устаревшая схема массива
Средство также принимает голый массив для обеспечения обратной совместимости:
[
{
"prompt": "Your test prompt here",
"expected_response": "Expected agent response"
}
]
Интерфейс командной строки автоматически обновляет устаревшие документы (отсутствующие 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"
}
Использование инструмента
Проверьте, правильно ли агент использует доступные инструменты и подключаемые модули.
Следующий пример на основе ответов не доказывает, что инструмент был выбран или запущен. Чтобы проверка поведения среды выполнения, используйте ToolCallSelection или ToolCallExecution в ознакомительной версии CLI версии 2.
{
"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"
}
Шаблоны для начинающих
Шаблон тестирования агента basic
{
"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 — это оценщик строкового соответствия, который возвращает непрерывную оценку сходства между 0.0 и 1.0. Используйте threshold эту опцию, чтобы установить минимальный балл, необходимый для сдачи экзамена (по умолчанию: 0.5).
Постоянное совершенствование
Просмотр неудачных тестов
Когда тесты дают плохие результаты:
- Сравнивайте фактический ответ с ожидаемым ответом.
- Определите, нуждается ли ожидаемый ответ в обновлении.
- Проверьте, не требуются ли агенту дополнительные данные или инструкции для обучения.
- Проверка правильности конфигураций инструмента.
Отслеживайте результаты с течением времени
Сохраните результаты теста для сравнения разных версий.
runevals --output ./evals/results/v1.6.0-results.json