Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Los conjuntos de datos de evaluación son archivos JSON que contienen indicaciones y respuestas esperadas. En este artículo se define el esquema del conjunto de datos, se documenta dónde la herramienta busca conjuntos de datos y se muestra cómo diseñar pruebas eficaces, incluidos escenarios avanzados como conversaciones de varios turnos, configuración del evaluador por elemento y conjuntos de pruebas categorizados.
Introducción al esquema
Los conjuntos de datos de evaluación son archivos JSON. La herramienta admite dos formas equivalentes: un objeto versionado (recomendado) y una matriz heredada.
Esquema versionado
Nota
CLI v1 admite dos formas de conjunto de datos: un objeto versionado (recomendado) y una matriz heredada. La CLI v2 requiere un objeto versionado que contenga schemaVersion y .items
Un conjunto de datos utiliza schemaVersion y una items matriz. El siguiente ejemplo incluye expected_response para los evaluadores que comparan una respuesta con una respuesta de referencia. Evaluadores como Relevancia, Coherencia y los evaluadores de llamada de herramienta de vista previa v2 no requieren expected_response.
{
"schemaVersion": "1.0.0",
"items": [
{
"prompt": "string",
"expected_response": "string"
}
]
}
La versión 1.6.0 del esquema agrega compatibilidad con la configuración del evaluador predeterminada y por elemento, el control del modo de evaluador, los elementos con nombre y las conversaciones de varios turnos. Para obtener más información, consulte Configuración de evaluadores y patrones de evaluación de varios turnos.
Elija la versión del esquema del conjunto de datos que coincida con la versión de la CLI:
-
CLI v1 (
latest): Usar esquema v1. Los ejemplos de esquema v1 de este artículo siguen siendo aplicables. -
CLI v2 (
preview): UsoschemaVersion"2.0.0"y la definición del esquema v2. La CLI v2 no acepta el esquema v1 ni conjuntos de datos sin versionar, independientemente de los evaluadores que seleccione.
La evaluación de complementos independientes a través de Microsoft 365 Copilot requiere CLI v2. Los evaluadores de llamadas de herramientas también requieren CLI v2, ya sea para evaluar un complemento independiente o un agente declarativo. CLI v1 continúa admitiendo la evaluación de agentes declarativos, incluidos los agentes con acciones de complemento, utilizando sus evaluadores compatibles.
Campos de esquema
Puede encontrar el esquema del conjunto de datos de evaluación en formato de esquema JSON en GitHub.
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
schemaVersion |
cadena | Requerido en CLI v2; en CLI v1 | Versión del esquema del conjunto de datos. Úselo "2.0.0" con CLI v2 (preview) o una versión de esquema v1 compatible con CLI v1 (latest). La compatibilidad con versiones anteriores está garantizada dentro de una versión principal de esquema. |
items |
matriz | Sí | Array of test items. Cada elemento es un par de solicitud y respuesta de un solo turno o una conversación con nombre de varios turnos. |
description |
cadena | Opcional | Descripción de texto libre del conjunto de datos (por ejemplo, "Regression tests for Q1 2026 release"). |
default_evaluators |
objeto | Opcional | Los evaluadores se aplicaron a todos los elementos del conjunto de datos a menos que se invaliden. Cada clave es un nombre de evaluador (por ejemplo, "Relevance", "Coherence"); el valor es un objeto de opciones (se usa {} para valores predeterminados). Requiere schemaVersion"1.2.0" o más adelante. |
items[].prompt |
cadena | Condicional | La indicación o instrucción enviada al agente. Necesario para elementos de una sola vuelta. Don't use with turns. |
items[].expected_response |
cadena | Condicional | La respuesta de referencia usada para la puntuación. Requerido por evaluadores, como Similarity, ExactMatch y PartialMatch, pero no por evaluadores de llamadas a herramientas. Don't use with turns. |
items[].name |
cadena | Opcional | Nombre para mostrar del elemento de prueba (por ejemplo, "Expense policy flow"). Especialmente útil para identificar elementos de varias vueltas en informes. |
items[].turns |
matriz | Condicional | Matriz ordenada de objetos de turno para una conversación multiturm dentro de un solo elemento. Cada turno contiene prompt, expected_response cuando lo requieran los evaluadores seleccionados, y opcionalmente evaluators y evaluators_mode. No lo use con aplicaciones de nivel prompt/expected_responsesuperior. Requiere schemaVersion"1.2.0" o más adelante. |
items[].evaluators |
objeto | Opcional | Modificaciones por evaluador por elemento. Cada clave es un nombre de evaluador; El valor es un objeto de opciones (por ejemplo, { "citation_format": "mixed" }). El comportamiento depende de evaluators_mode. Requiere schemaVersion"1.2.0" o más adelante. |
items[].evaluators_mode |
cadena | Opcional | Controla cómo items[].evaluators se combina con default_evaluators. Use "extend" (predeterminado) para combinar evaluadores por elemento con valores predeterminados, o "replace" para usar solo los evaluadores por elemento e ignorar los valores predeterminados. Requiere schemaVersion"1.2.0" o más adelante. |
items[].testId |
cadena | Opcional | Identificador estable para la comparación entre versiones (por ejemplo, "REG-001"). |
items[].category |
cadena | Opcional | Etiqueta de categoría (por ejemplo, "knowledge-base", "tool-usage"). |
items[].notes |
cadena | Opcional | Notas de forma libre, como un ID de error vinculado. |
default_allowed_tools |
Array of Strings | Opcional | Identificadores de consentimiento aprobados para el conjunto de datos. Para el uso con evaluadores de llamadas de herramientas en la versión preliminar v2, consulte Permitir llamadas a herramientas. |
items[].allowed_tools / items[].turns[].allowed_tools |
Array of Strings | Opcional | Identificadores de consentimiento aprobados para una indicación o turno. Estas no son identidades de herramientas de evaluación. |
items[].allowed_tools_mode / items[].turns[].allowed_tools_mode |
cadena | Opcional |
"extend" (predeterminado) se combina allowed_tools con default_allowed_tools.
"replace" Usa solo la lista de indicaciones o de turnos. Úsalo "replace" con allowed_tools: [] para aprobar ninguna solicitud de confirmación de herramienta para esa indicación o turno. |
Configuración de evaluadores
La versión 1.6.0 de esquema permite controlar qué evaluadores se ejecutan y cómo se configuran, tanto a nivel de conjunto de datos como a nivel de elemento individual. Para obtener más información sobre el comportamiento de puntuación y las opciones de configuración de cada evaluador, consulte Referencia de evaluadores.
Evaluadores predeterminados
Úselo default_evaluators en el nivel superior para especificar evaluadores que se apliquen a cada elemento del conjunto de datos. Cada clave es un nombre de evaluador y el valor es un objeto de opciones. Use un objeto vacío ({}) para aplicar el evaluador con su configuración predeterminada.
{
"schemaVersion": "1.6.0",
"default_evaluators": {
"Relevance": {},
"Coherence": {}
},
"items": [
{
"prompt": "What is Microsoft Graph?",
"expected_response": "A unified API endpoint for Microsoft services."
}
]
}
En este ejemplo, cada elemento se puntúa por Relevancia y Coherencia mediante la configuración predeterminada.
El evaluador por elemento reemplaza
Use el evaluators campo en un elemento individual (o turno) para agregar o anular evaluadores para esa prueba específica. Se usa evaluators_mode para controlar cómo se combinan los evaluadores por elemento con default_evaluators:
-
"extend"(predeterminado) — Fusiona los evaluadores por elemento con los valores predeterminados. El elemento es calificado tanto por los evaluadores predeterminados como por cualquier evaluador adicional especificado en el elemento. -
"replace"— Ignora los valores predeterminados por completo. Solo se usan los evaluadores especificados en el elemento.
{
"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"
}
]
}
En este ejemplo, el elemento se califica para Relevancia (predeterminado), Coherencia (valor predeterminado) y Citas con citation_format el valor establecido en "mixed" (invalidación por elemento).
Permitir llamadas a herramientas
Al evaluar las llamadas a herramientas que solicitan confirmación, configure las expectativas de aprobación y del evaluador.
default_allowed_tools a nivel de documento y allowed_tools por indicación o turno, permita que la CLI apruebe las solicitudes de confirmación de la herramienta. Se debe permitir cada identificador de consentimiento solicitado; De lo contrario, el aviso se detiene con un toolCallNotAllowed error.
Importante
Permitir una llamada otorga consentimiento. Use escenarios revisados y comience con operaciones de solo lectura. Una expectativa del evaluador no otorga consentimiento y la aprobación no fuerza la selección de herramientas ni prueba la ejecución. Las herramientas que no solicitan confirmación no están controladas por esta lista, por lo que no es un límite de seguridad.
Los identificadores de consentimiento difieren de la identidad de herramienta de tres partes en el calls[].toolarchivo de un evaluador. No dividas los identificadores de consentimiento para rellenar los campos de evaluador. Para conocer los comandos de detección, la configuración y los conjuntos de datos completos del esquema v2, consulte Evaluadores de llamada a herramientas.
Ejemplo de esquema completo
En el ejemplo siguiente se muestran todas las características de esquema de un único conjunto de datos: valores predeterminados de nivel superior, un elemento de un solo turno con anulaciones de evaluador y un elemento de varios turnos con nombre con configuración de evaluador por turno.
{
"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"
}
]
}
]
}
Detalles clave de este ejemplo:
- El primer elemento es una prueba de un solo turno. Hereda
RelevanceCoherencey dedefault_evaluatorsy agregaCitationsa través del"extend"modo. - El segundo elemento es una conversación de varios turnos con nombre (
"Expense policy flow") con dos turnos. El primer turno hereda los evaluadores predeterminados. El segundo turno usa"replace"el modo, por lo que soloExactMatchse ejecuta: los valores predeterminados se ignoran para ese turno.
Esquema de matriz heredada
La herramienta también acepta una matriz simple para la compatibilidad con versiones anteriores:
[
{
"prompt": "Your test prompt here",
"expected_response": "Expected agent response"
}
]
La CLI actualiza automáticamente los documentos heredados (que faltan schemaVersion) al formato versionado y escribe una copia de seguridad con marca de tiempo.
Nomenclatura y ubicación de archivos
La herramienta de evaluación detecta automáticamente los archivos de conjuntos de datos en el proyecto.
Orden de detección automática
Cuando se ejecuta runevals, la herramienta busca conjuntos de datos en este orden:
- Directorio actual:
prompts.json,evals.json,tests.json -
./evals/Subdirectorio:prompts.json,evals.json,tests.json
Estructura recomendada del proyecto
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
Creación del archivo de inicio
Si la herramienta no encuentra un archivo de dataset, le pide que cree un archivo de inicio:
⚠️ No prompts file found in current directory or ./evals/
Create a starter evals file with sample prompts? (Y/n):
Responder Y crea ./evals/evals.json con indicaciones de ejemplo.
Diseñar indicaciones de prueba eficaces
Organice las pruebas en categorías que reflejen el comportamiento del agente que desea verificar.
Comprobación de conocimiento
Pruebe si el agente tiene acceso y utiliza correctamente su knowledge base.
{
"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."
}
Instrucciones siguientes
Compruebe que el agente sigue instrucciones específicas.
{
"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"
}
Uso de herramientas
Compruebe si el agente usa correctamente las herramientas y complementos disponibles.
El siguiente ejemplo basado en respuesta no prueba que se haya seleccionado o ejecutado una herramienta. Para comprobar el comportamiento en tiempo de ejecución, use ToolCallSelection o ToolCallExecution en la versión preliminar de la CLI v2.
{
"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."
}
Casos extremos
Pruebe las condiciones de contorno y las entradas inusuales.
{
"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?"
}
Seguridad y adecuación
Asegúrese de que el agente controle las solicitudes inapropiadas correctamente.
{
"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."
}
Procedimientos recomendados para el diseño de pruebas
Escribir indicaciones claras
A continuación se muestra un ejemplo de una indicación clara.
{
"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."
}
Evita indicaciones ambiguas como las del ejemplo siguiente.
{
"prompt": "Tell me about returns"
}
Incluir escenarios realistas
Base las pruebas en preguntas reales de los usuarios.
{
"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."
}
Cubre la gestión de errores
Pruebe cómo el agente controla los errores correctamente.
{
"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?"
}
Escenarios de evaluación avanzada
Patrones de evaluación de varios turnos
La versión 1.2.0 del esquema y las versiones posteriores admiten conversaciones de varios turnos. Use la turns matriz dentro de un elemento para definir una secuencia ordenada de consultas y respuestas esperadas que forman un único flujo de conversación. Cada turno puede incluir opcionalmente su propia configuración de evaluador.
{
"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"
}
]
}
]
}
Detalles clave:
- Cada elemento con una
turnsmatriz se evalúa como una sola conversación. Los turnos se envían en secuencia, y cada turno se basa en el contexto de conversación de los anteriores. - Use el campo para dar a los artículos de varias vueltas una etiqueta legible en los
nameinformes. - Puede solicitar
evaluatorsyevaluators_modeen turnos individuales. En el ejemplo anterior, el segundo turno usa"replace"moda, por lo que soloExactMatchse ejecuta para ese turno.
Patrón de elementos secuenciales (versión de esquema 1.0.0)
Si usa la versión 1.0.0de esquema, puede aproximar conversaciones de varios turnos diseñando elementos secuenciales donde las consultas posteriores hagan referencia al contexto establecido por las anteriores. Use prefijos y category etiquetas coherentes testId para agrupar y filtrar elementos relacionados en los resultados.
{
"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"
}
]
}
Nota
Con elementos secuenciales, cada elemento se evalúa de forma independiente. El agente no lleva el contexto de conversación entre los elementos. Para una verdadera evaluación de varios turnos con contexto compartido, use la matriz con la turns versión 1.2.0 del esquema o posterior.
Categorización y puntuación por indicación
Utilice el campo opcional category para agrupar elementos para que pueda analizar puntajes por dimensión (conocimiento, herramientas, seguridad, casos extremos, regresión).
{
"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"
}
]
}
Estrategias de organización del conjunto de datos
Para proyectos grandes, organice las pruebas por categoría en varios archivos.
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
Ejecutar archivos de conjuntos de datos específicos.
runevals --prompts-file ./evals/knowledge-base.json
runevals --prompts-file ./evals/tool-usage.json
Pruebas de regresión
Cuando corrija problemas, agregue pruebas para evitar la regresión. Use testId y notes para volver a vincular al seguimiento de errores.
{
"prompt": "Issue that was previously broken",
"expected_response": "Correct behavior after fix",
"testId": "BUG-456",
"notes": "Regression test for bug #456"
}
Plantillas de inicio
Plantilla de prueba de agente básica
{
"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]."
}
]
}
Plantilla de prueba de Knowledge Base
{
"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]"
}
]
}
Plantilla de prueba de uso de herramientas
{
"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]"
}
]
}
Pruebas interactivas y en línea
Use el modo interactivo para realizar pruebas exploratorias sin un archivo de conjunto de datos.
runevals --interactive
Para pruebas rápidas con una sola indicación, pase las indicaciones en línea.
runevals --prompts "What is Microsoft Graph?" \
--expected "Microsoft Graph is the API gateway to Microsoft 365 data and intelligence."
Varias consultas.
runevals --prompts "What is Teams?" "What is SharePoint?" \
--expected "Teams is a collaboration platform" "SharePoint is a content management system"
Comprender las métricas de evaluación
Cada prueba se califica automáticamente en múltiples dimensiones.
Relevancia (1-5)
La relevancia mide qué tan bien la respuesta aborda el mensaje:
- 5: Aborda perfectamente la pregunta
- 3: Aborda parcialmente la pregunta
- 1: No aborda la pregunta
Coherencia (1-5)
La coherencia mide qué tan lógica y bien estructurada es la respuesta:
- 5: Claro, lógico, bien organizado
- 3: Algo organizado, pero podría ser más claro
- 1: Incoherente o confuso
Conexión a tierra (1-5)
La fundamentación mide qué tan bien la respuesta está respaldada por fuentes y citas:
- 5: Totalmente fundamentado con citas apropiadas
- 3: Parcialmente fundamentado con algunas citas
- 1: Sin conexión a tierra ni citas
Similitud (1-5)
La similitud mide el grado de coincidencia de la respuesta con el resultado esperado:
- 5: La respuesta es semánticamente equivalente a la salida esperada
- 3: La respuesta coincide parcialmente con la salida esperada
- 1: La respuesta no coincide con el resultado esperado
Citas (>= 0)
Citas es un evaluador basado en recuentos que cuenta el número de citas válidas en la respuesta. Una puntuación de 0 significa que no hay citas presentes. Configure un umbral mínimo para establecer una barra de superación/suspenso.
Coincidencia exacta
ExactMatch es un evaluador de coincidencias de cadenas con un resultado booleano. La respuesta pasa si contiene exactamente la cadena esperada. Admite una case_sensitive opción (valor predeterminado: false).
PartialMatch (0.0-1.0)
PartialMatch es un evaluador de coincidencias de cadenas que devuelve una puntuación de similitud continua entre 0.0 y .1.0 Use la threshold opción para establecer la puntuación mínima requerida para aprobar (predeterminado: 0.5).
Mejora continua
Revisar pruebas con errores
Cuando las pruebas obtienen una puntuación baja:
- Revise la respuesta real frente a la respuesta esperada.
- Determine si la respuesta esperada necesita actualizarse.
- Comprueba si el agente necesita más datos de entrenamiento o instrucciones.
- Compruebe que las configuraciones de herramientas sean correctas.
Seguimiento de puntuaciones a lo largo del tiempo
Guarde los resultados de las pruebas para comparar entre versiones.
runevals --output ./evals/results/v1.6.0-results.json