평가 데이터 세트는 프롬프트 및 예상 응답을 포함하는 JSON 파일입니다. 이 문서에서는 데이터 세트 스키마를 정의하고 도구가 데이터 세트를 찾는 위치를 문서화하며 다중 전환 대화, 항목별 평가자 구성 및 분류된 테스트 도구 모음과 같은 고급 시나리오를 포함하여 효과적인 테스트를 설계하는 방법을 보여줍니다.
스키마 개요
평가 데이터 세트는 JSON 파일입니다. 이 도구는 두 가지 동등한 셰이프인 버전이 있는 개체(권장)와 레거시 배열을 지원합니다.
버전이 지정된 스키마
참고
CLI v1은 버전이 있는 개체(권장) 및 레거시 배열의 두 가지 데이터 세트 셰이프를 지원합니다. CLI v2에는 다음을 포함하는 schemaVersion 버전이 있는 개체가 items필요합니다.
데이터 세트는 배열을 items 사용합니다schemaVersion. 다음 예제에서는 응답을 참조 답변과 비교하는 평가자에 대한 예제를 포함 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) 또는 CLI v1(latest)과 함께 지원되는 v1 스키마 버전과 함께 사용합니다"2.0.0". 스키마 주 버전 내에서 이전 버전과의 호환성이 보장됩니다. |
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 | 조건부 | 단일 항목 내의 다중 turm 대화에 대한 순서가 지정된 턴 개체 배열입니다. 각 턴에는 선택된 평가자가 요구하는 경우 , expected_response 그리고 선택적으로 evaluators and 가 evaluators_mode포함됩니다prompt. 최상위 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 항목별 계산기를 기본값과 병합하거나 "replace" 항목별 계산기만 사용하고 기본값을 무시하려면 (기본값)을 사용합니다 "extend" . 필요 schemaVersion"1.2.0" 이상. |
items[].testId |
문자열 | 선택 사항 | 버전 간 비교를 위한 안정적인 식별자입니다(예: "REG-001"). |
items[].category |
문자열 | 선택 사항 | 범주 태그(예: "knowledge-base", "tool-usage"). |
items[].notes |
문자열 | 선택 사항 | 연결된 버그 ID와 같은 자유형 메모입니다. |
default_allowed_tools |
문자열 배열 | 선택 사항 | 데이터 세트에 대해 승인된 동의 식별자입니다. v2 미리 보기에서 도구 호출 계산기와 함께 사용하는 내용은 도구 호출 허용을 참조하세요. |
items[].allowed_tools / items[].turns[].allowed_tools |
문자열 배열 | 선택 사항 | 프롬프트 또는 턴에 대해 승인된 동의 식별자입니다. 이들은 평가자 도구 ID가 아닙니다. |
items[].allowed_tools_mode / items[].turns[].allowed_tools_mode |
문자열 | 선택 사항 |
"extend"(기본값)는 와 결합됩니다allowed_tools.default_allowed_tools
"replace" 프롬프트 또는 차례 목록만 사용합니다. 함께 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 문서 수준에서 프롬프트 또는 턴당 CLI allowed_tools 가 도구 확인 프롬프트를 승인하도록 합니다. 요청된 모든 동의 식별자가 허용되어야 합니다. 그렇지 않으면 프롬프트가 오류와 함께 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"
}
]
}
]
}
이 예제의 주요 세부 정보:
- 첫 번째 항목은 단일 턴 테스트입니다. 모드를 통해 상
Coherencedefault_evaluators속Relevance하고 추가합니다Citations."extend" - 두 번째 항목은 2턴이 있는 명명된 다중 턴 대화(
"Expense policy flow")입니다. 첫 번째 턴은 기본 계산기를 상속합니다. 두 번째 턴은 모드를 사용"replace"하므로 실행만ExactMatch합니다. 해당 턴의 기본값은 무시됩니다.
레거시 배열 스키마
또한 이 도구는 이전 버전과의 호환성을 위해 완전 배열을 허용합니다.
[
{
"prompt": "Your test prompt here",
"expected_response": "Expected agent response"
}
]
CLI는 레거시 문서(누락 schemaVersion됨)를 버전이 있는 형식으로 자동으로 업그레이드하고 타임스탬프 백업을 씁니다.
파일 명명 및 위치
평가 도구는 프로젝트에서 데이터 세트 파일을 자동으로 검색합니다.
자동 검색 순서
를 실행 runevals하면 도구는 다음 순서로 데이터 세트를 검색합니다.
- 현재 디렉터리:
prompts.json, ,evals.jsontests.json -
./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_mode개별 턴에 적용evaluators할 수 있습니다. 앞의 예에서 두 번째 턴은 모드를 사용"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"
}
]
}
Dataset organization strategies
대규모 프로젝트의 경우 여러 파일의 범주별로 테스트를 구성합니다.
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
회귀 테스트
문제를 해결할 때 회귀를 방지하기 위한 테스트를 추가합니다. AND notes 를 사용하여 testId 버그 추적에 다시 연결합니다.
{
"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는 부울 결과를 사용하는 문자열 일치 계산기입니다. 응답은 예상되는 문자열을 정확히 포함하면 통과합니다. 옵션(기본값: false)을 지원합니다case_sensitive.
PartialMatch (0.0-1.0)
PartialMatch는 와 1.0간의 0.0 연속적인 유사성 점수를 반환하는 문자열 일치 계산기입니다. 옵션을 사용하여 threshold 통과하는 데 필요한 최소 점수를 설정합니다(기본값: 0.5).
지속적 개선
실패한 테스트 검토
테스트 점수가 낮은 경우:
- 실제 응답과 예상 응답을 검토합니다.
- 예상된 응답을 업데이트해야 하는지 확인합니다.
- 에이전트에 추가 학습 데이터 또는 지침이 필요한지 확인합니다.
- 도구 구성이 올바른지 확인합니다.
시간 경과에 따른 점수 추적
버전 간에 비교할 수 있도록 테스트 결과를 저장합니다.
runevals --output ./evals/results/v1.6.0-results.json