Esquema de conjunto de datos y diseño de prueba

Los conjuntos de datos de evaluación son archivos JSON que contienen mensajes y respuestas esperadas. En este artículo se define el esquema del conjunto de datos, documentos en los que 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 de 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 con versiones (recomendado) y una matriz heredada.

El conjunto de datos válido más sencillo solo schemaVersion requiere y una items matriz con prompt campos y 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 predeterminada y por elemento del evaluador, el control del modo 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 multiturno.

Campos de esquema

Puede encontrar el esquema del conjunto de datos de evaluación en formato de esquema JSON en GitHub.

Campo Tipo Obligatorio Descripción
schemaVersion string Recomendado Versión semántica (por ejemplo, "1.0.0" o "1.6.0"). La compatibilidad con versiones anteriores está garantizada dentro de una versión principal. Use "1.6.0" para habilitar la configuración del evaluador, los modos de evaluador y la compatibilidad nativa con varios turnos.
items matriz Sí Matriz de elementos de prueba. Cada elemento es un par de solicitud/respuesta de un solo turno o una conversación de varios turnos con nombre.
description string Opcional Descripción de texto libre del conjunto de datos (por ejemplo, "Regression tests for Q1 2026 release").
default_evaluators objeto Opcional Evaluadores aplicados 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 options (se usa {} para valores predeterminados). Requiere schemaVersion"1.2.0" o posterior.
items[].prompt string Condicional Símbolo del sistema o instrucción enviado al agente. Necesario para los elementos de un solo turno. No use con turns.
items[].expected_response string Condicional Respuesta de referencia usada para la puntuación. Necesario para los elementos de un solo turno. No use con turns.
items[].name string Opcional Nombre para mostrar del elemento de prueba (por ejemplo, "Expense policy flow"). Especialmente útil para identificar elementos de varios turnos en informes.
items[].turns matriz Condicional Matriz ordenada de objetos de turno para una conversación de varios turnos dentro de un solo elemento. Cada turno contiene prompt, expected_responsey, opcionalmente evaluators , y evaluators_mode. No use con el nivel prompt/expected_responsesuperior . Requiere schemaVersion"1.2.0" o posterior.
items[].evaluators objeto Opcional Invalidaciones del evaluador por elemento. Cada clave es un nombre de evaluador; el valor es un objeto options (por ejemplo, { "citation_format": "mixed" }). El comportamiento depende de evaluators_mode. Requiere schemaVersion"1.2.0" o posterior.
items[].evaluators_mode string Opcional Controla cómo items[].evaluators se combina con default_evaluators. Use "extend" (valor 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 posterior.
items[].testId string Opcional Identificador estable para la comparación entre versiones (por ejemplo, "REG-001").
items[].category string Opcional Etiqueta de categoría (por ejemplo, "knowledge-base", "tool-usage").
items[].notes string Opcional Notas de forma libre, como un identificador de error vinculado.

Configuración de evaluadores

La versión 1.6.0 del esquema permite controlar qué evaluadores se ejecutan y cómo se configuran, tanto en el nivel de conjunto de datos como en el 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

Use default_evaluators en el nivel superior para especificar evaluadores que se aplican a cada elemento del conjunto de datos. Cada clave es un nombre de evaluador y el valor es un objeto options. 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 como Relevancia y Coherencia mediante la configuración predeterminada.

Invalidaciones del evaluador por elemento

Use el evaluators campo en un elemento individual (o turno) para agregar o invalidar evaluadores para esa prueba específica. Use evaluators_mode para controlar cómo se combinan los evaluadores por elemento con default_evaluators:

  • "extend" (valor predeterminado): combina los evaluadores por elemento con los valores predeterminados. Los evaluadores predeterminados y los evaluadores adicionales especificados en el elemento puntúan el elemento.
  • "replace" : omite completamente los valores predeterminados. 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 puntua como Relevancia (valor predeterminado), Coherencia (valor predeterminado) y Citas con citation_format establecido en "mixed" (invalidación por elemento).

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 invalidaciones del 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 Relevance y Coherence de default_evaluators y agrega Citations a 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 solo ExactMatch se ejecuta : los valores predeterminados se omiten para ese turno.

Esquema de matriz heredada

La herramienta también acepta una matriz sin sistema operativo para la compatibilidad con versiones anteriores:

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

La CLI actualiza automáticamente los documentos heredados (falta schemaVersion) al formato con versiones y escribe una copia de seguridad con marca de tiempo.

Ubicación y nomenclatura de archivos

La herramienta de evaluación detecta automáticamente los archivos de conjunto de datos en el proyecto.

Orden de detección automática

Al ejecutar runevals, la herramienta busca conjuntos de datos en este orden:

  1. Directorio actual: prompts.json, , evals.jsontests.json
  2. ./evals/subdirectorio: 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

Creación de archivos de inicio

Si la herramienta no encuentra un archivo de conjunto de datos, se le pedirá 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 a Y crea ./evals/evals.json con mensajes de ejemplo.

Diseño de solicitudes de prueba eficaces

Organice las pruebas en categorías que reflejen el comportamiento del agente que desea comprobar.

Comprobación de conocimientos

Pruebe si el agente accede correctamente y usa 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 la herramienta

Pruebe si el agente usa correctamente herramientas y complementos disponibles.

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

Pruebe las condiciones de límite 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 idoneidad

Asegúrese de que el agente controla correctamente las solicitudes inapropiadas.

{
  "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 mensajes claros

A continuación se muestra un ejemplo de una solicitud 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."
}

Evite mensajes ambiguos como el ejemplo siguiente.

{
  "prompt": "Tell me about returns"
}

Incluir escenarios realistas

Pruebas base sobre las preguntas reales del usuario.

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

Control de errores de cobertura

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 versiones posteriores admiten conversaciones de varios turnos. Use la turns matriz dentro de un elemento para definir una secuencia ordenada de mensajes 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 turns matriz se evalúa como una sola conversación. Los turnos se envían en secuencia, con cada turno que se compila en el contexto de conversación de los anteriores.
  • Use el name campo para proporcionar a los elementos de varios turnos una etiqueta legible en los informes.
  • Puede aplicar evaluators y evaluators_mode en turnos individuales. En el ejemplo anterior, el segundo turno usa "replace" el modo , por lo que solo ExactMatch se 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 aproximarse a las conversaciones de varios turnos mediante el diseño de elementos secuenciales en los que más adelante se solicita el contexto de referencia establecido por los anteriores. Use prefijos y category etiquetas coherentes testId para agrupar y filtrar elementos relacionados con 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 los elementos secuenciales, cada elemento se evalúa de forma independiente. El agente no lleva contexto de conversación entre elementos. Para una verdadera evaluación multiturno con contexto compartido, use la matriz con la turns versión 1.2.0 de esquema o posterior.

Categorización y puntuación por solicitud

Use el campo opcional category para agrupar elementos de modo que pueda analizar las puntuaciones por dimensión (conocimiento, herramientas, seguridad, casos perimetrales, 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

Ejecute archivos de conjunto de datos específicos.

runevals --prompts-file ./evals/knowledge-base.json
runevals --prompts-file ./evals/tool-usage.json

Pruebas de regresión

Al corregir 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 e insertadas

Use el modo interactivo para las pruebas exploratorias sin un archivo de conjunto de datos.

runevals --interactive

Para las pruebas rápidas de solicitud única, pase las solicitudes insertadas.

runevals --prompts "What is Microsoft Graph?" \
  --expected "Microsoft Graph is the API gateway to Microsoft 365 data and intelligence."

Varias solicitudes.

runevals --prompts "What is Teams?" "What is SharePoint?" \
  --expected "Teams is a collaboration platform" "SharePoint is a content management system"

Descripción de las métricas de evaluación

Cada prueba se puntúa automáticamente en varias dimensiones.

Relevancia (1-5)

La relevancia mide la forma en que la respuesta aborda el aviso:

  • 5: Aborda perfectamente la pregunta
  • 3: Aborda parcialmente la pregunta
  • 1: No aborda la pregunta

Coherencia (1-5)

La coherencia mide cómo es lógica y bien estructurada la respuesta:

  • 5: Claro, lógico, bien organizado
  • 3: Algo organizado, pero podría ser más claro
  • 1: Incoherente o confuso

Puesta a tierra (1-5)

La base mide el grado de soporte de la respuesta mediante fuentes y citas:

  • 5: Totalmente fundamentado con citas apropiadas
  • 3: Parcialmente fundamentado con algunas citas
  • 1: Sin fundamento ni citas

Similitud (1-5)

Similitud mide la proximidad de la respuesta con la salida esperada:

  • 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 la salida esperada

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. Configure un umbral mínimo para establecer una barra de paso o error.

ExactMatch

ExactMatch es un evaluador de coincidencia de cadena 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 coincidencia de cadena 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 necesaria para pasar (valor predeterminado: 0.5).

Mejora continua

Revisión de pruebas erróneas

Cuando las pruebas puntúan mal:

  1. Revise la respuesta real frente a la respuesta esperada.
  2. Determine si la respuesta esperada necesita actualizarse.
  3. Compruebe si el agente necesita más datos de entrenamiento o instrucciones.
  4. Compruebe que las configuraciones de la herramienta son correctas.

Seguimiento de las puntuaciones a lo largo del tiempo

Guarde los resultados de las pruebas para compararlos entre versiones.

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

Contenido relacionado

  • Se actualizó por última vez el