Esquema do conjunto de dados e design de teste

Os conjuntos de dados de avaliação são arquivos JSON que contêm prompts e respostas esperadas. Este artigo define o esquema do conjunto de dados, documenta onde a ferramenta procura conjuntos de dados e mostra como projetar testes eficazes, incluindo cenários avançados, como conversas em vários turnos, configuração do avaliador por item e conjuntos de testes categorizados.

Visão geral do esquema

Os conjuntos de dados de avaliação são arquivos JSON. A ferramenta dá suporte a duas formas equivalentes: um objeto versionado (recomendado) e uma matriz herdada.

O conjunto de dados válido mais simples requer apenas schemaVersion e uma items matriz com prompt campos e expected_response .

{
  "schemaVersion": "1.0.0",
  "items": [
    {
      "prompt": "string",
      "expected_response": "string"
    }
  ]
}

A versão 1.6.0 do esquema adiciona suporte para configuração padrão e por item do avaliador, controle do modo avaliador, itens nomeados e conversas de vários turnos. Para obter detalhes, consulte Configurar avaliadores e padrões de avaliação de várias voltas.

Campos do esquema

Você pode encontrar o esquema do conjunto de dados de avaliação no formato JSON Schema no GitHub.

Campo Tipo Obrigatório Descrição
schemaVersion string Recomendado Versão semântica (por exemplo, "1.0.0" ou "1.6.0"). A compatibilidade com versões anteriores é garantida em uma versão principal. Use "1.6.0" para habilitar a configuração do avaliador, os modos do avaliador e o suporte nativo a várias voltas.
items array Sim Matriz de itens de teste. Cada item é um par prompt/resposta de turno único ou uma conversa nomeada de vários turnos.
description string Opcional Descrição de texto livre do conjunto de dados (por exemplo, "Regression tests for Q1 2026 release").
default_evaluators objeto Opcional Avaliadores aplicados a todos os itens no conjunto de dados, a menos que sejam substituídos. Cada chave é um nome de avaliador (por exemplo, "Relevance", "Coherence"); o valor é um objeto de opções (use {} para padrões). Requer schemaVersion"1.2.0" ou posterior.
items[].prompt string Condicional O prompt ou instrução enviada ao agente. Necessário para itens de um turno. Não use com turns.
items[].expected_response string Condicional A resposta de referência usada para pontuação. Necessário para itens de um turno. Não use com turns.
items[].name string Opcional Nome de exibição para o item de teste (por exemplo, "Expense policy flow"). Especialmente útil para identificar itens de várias voltas em relatórios.
items[].turns array Condicional Matriz ordenada de objetos turn para uma conversa de vários turnos dentro de um único item. Cada turno contém prompt, expected_responsee opcionalmente evaluators e evaluators_mode. Não use com arquivos .prompt/expected_response Requer schemaVersion"1.2.0" ou posterior.
items[].evaluators objeto Opcional Substituições de avaliador por item. Cada chave é um nome de avaliador; O valor é um objeto de opções (por exemplo, { "citation_format": "mixed" }). O comportamento depende de evaluators_mode. Requer schemaVersion"1.2.0" ou posterior.
items[].evaluators_mode string Opcional Controla como items[].evaluators combina com default_evaluators. Use "extend" (padrão) para mesclar avaliadores por item com padrões ou "replace" para usar apenas os avaliadores por item e ignorar os padrões. Requer schemaVersion"1.2.0" ou posterior.
items[].testId string Opcional Identificador estável para comparação entre versões (por exemplo, "REG-001").
items[].category string Opcional Marca de categoria (por exemplo, "knowledge-base", "tool-usage").
items[].notes string Opcional Notas de forma livre, como uma ID de bug vinculada.

Configurar avaliadores

A versão 1.6.0 do esquema permite controlar quais avaliadores são executados e como eles são configurados, tanto no nível do conjunto de dados quanto no nível do item individual. Para obter detalhes sobre o comportamento de pontuação e as opções de configuração de cada avaliador, consulte Referência de avaliadores.

Avaliadores padrão

Use default_evaluators no nível superior para especificar avaliadores que se aplicam a cada item no conjunto de dados. Cada chave é um nome de avaliador e o valor é um objeto de opções. Use um objeto vazio ({}) para aplicar o avaliador com suas configurações padrão.

{
  "schemaVersion": "1.6.0",
  "default_evaluators": {
    "Relevance": {},
    "Coherence": {}
  },
  "items": [
    {
      "prompt": "What is Microsoft Graph?",
      "expected_response": "A unified API endpoint for Microsoft services."
    }
  ]
}

Neste exemplo, cada item é pontuado para Relevância e Coerência usando as configurações padrão.

Substituições do avaliador por item

Use o campo em um item individual (ou turno evaluators ) para adicionar ou substituir avaliadores para esse teste específico. Use evaluators_mode para controlar como os avaliadores por item se combinam com default_evaluators:

  • "extend" (padrão) — Mescla avaliadores por item com os padrões. O item é pontuado pelos avaliadores padrão e por quaisquer avaliadores adicionais especificados no item.
  • "replace" — ignora totalmente os padrões. São utilizados apenas os avaliadores especificados no item.
{
  "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"
    }
  ]
}

Neste exemplo, o item é pontuado para Relevância (padrão), Coerência (padrão) e Citações com citation_format definido como "mixed" (substituição por item).

Exemplo de esquema completo

O exemplo a seguir mostra todos os recursos de esquema em um único conjunto de dados: padrões de nível superior, um item de turno único com substituições de avaliador e um item de vários turnos nomeado com configuração de avaliador 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"
        }
      ]
    }
  ]
}

Principais detalhes neste exemplo:

  • O primeiro item é um teste de volta única. Ele herda Relevance e Coherence de default_evaluators e adiciona Citations por meio do "extend" modo.
  • O segundo item é uma conversa nomeada de vários turnos ("Expense policy flow") com dois turnos. O primeiro turno herda os avaliadores padrão. O segundo turno usa "replace" o modo, então só ExactMatch corre - os padrões são ignorados para esse turno.

Esquema de matriz herdada

A ferramenta também aceita uma matriz simples para compatibilidade com versões anteriores:

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

A CLI atualiza automaticamente documentos legados (ausentes schemaVersion) para o formato versionado e grava um backup com carimbo de data e hora.

Nomenclatura e localização do arquivo

A ferramenta de avaliação descobre automaticamente os arquivos de conjunto de dados em seu projeto.

Ordem de descoberta automática

Quando você executa runevalso , a ferramenta procura conjuntos de dados nesta ordem:

  1. Diretório atual: prompts.json, evals.json, tests.json
  2. ./evals/ Subdiretório: 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

Criação de arquivo inicial

Se a ferramenta não encontrar um arquivo de conjunto de dados, ela solicitará que você crie um arquivo inicial:

⚠️  No prompts file found in current directory or ./evals/

Create a starter evals file with sample prompts? (Y/n):

A resposta Y cria ./evals/evals.json com prompts de exemplo.

Projete prompts de teste eficazes

Organize seus testes em categorias que reflitam o comportamento do agente que você deseja verificar.

Verificação de conhecimento

Teste se o seu agente acessa e usa corretamente sua base de dados de conhecimento.

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

Instrução seguinte

Verifique se o agente segue instruções 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 da ferramenta

Teste se o agente usa corretamente as ferramentas e plug-ins disponíveis.

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

Teste as condições de contorno e as entradas incomuns.

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

Segurança e adequação

Certifique-se de que o agente lide com solicitações inadequadas corretamente.

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

Práticas recomendadas para design de teste

Escreva prompts claros

Veja a seguir um exemplo de um prompt claro.

{
  "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 prompts ambíguos como o exemplo a seguir.

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

Inclua cenários realistas

Baseie os testes em perguntas reais do usuário.

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

Cobrir tratamento de erros

Teste como o agente lida com erros normalmente.

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

Cenários de avaliação avançada

Padrões de avaliação de várias voltas

A versão 1.2.0 de esquema e posterior dá suporte a conversas em vários turnos. Use a turns matriz dentro de um item para definir uma sequência ordenada de prompts e respostas esperadas que formam um único fluxo de conversa. Cada turno pode incluir opcionalmente sua própria configuração de avaliador.

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

Principais detalhes:

  • Cada item com uma turns matriz é avaliado como uma única conversa. Os turnos são enviados em sequência, com cada turno se baseando no contexto de conversa dos anteriores.
  • Use o campo para dar aos itens de várias voltas name um rótulo legível em relatórios.
  • Você pode aplicar evaluators e evaluators_mode em turnos individuais. No exemplo anterior, o segundo turno usa "replace" o modo, portanto, é executado apenas ExactMatch para aquele turno.

Padrão de itens sequenciais (esquema versão 1.0.0)

Se você estiver usando a versão 1.0.0do esquema, poderá aproximar conversas de vários turnos projetando itens sequenciais em que os prompts posteriores fazem referência ao contexto estabelecido pelos anteriores. Use prefixos e category marcas consistentes testId para agrupar e filtrar itens relacionados nos 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"
    }
  ]
}

Observação

Com itens sequenciais, cada item é avaliado independentemente. O agente não carrega contexto de conversa entre itens. Para uma verdadeira avaliação de várias voltas com contexto compartilhado, use a matriz com a turns versão 1.2.0 do esquema ou posterior.

Categorização e pontuação por prompt

Use o campo opcional category para agrupar itens para que você possa analisar as pontuações por dimensão (conhecimento, ferramentas, segurança, casos extremos, regressão).

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

Estratégias de organização do conjunto de dados

Para projetos grandes, organize os testes por categoria em vários arquivos.

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

Executar arquivos de conjunto de dados específicos.

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

Testes de regressão

Ao corrigir problemas, adicione testes para evitar a regressão. Use testId e notes para vincular de volta ao rastreamento de bugs.

{
  "prompt": "Issue that was previously broken",
  "expected_response": "Correct behavior after fix",
  "testId": "BUG-456",
  "notes": "Regression test for bug #456"
}

Modelos iniciais

Modelo de teste de agente básico

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

Modelo de teste da Base de Dados de Conhecimento

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

Modelo de teste de uso de ferramenta

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

Testes interativos e em linha

Use o modo interativo para testes exploratórios sem um arquivo de conjunto de dados.

runevals --interactive

Para testes rápidos de prompt único, aprovado em prompts embutidos.

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

Vários prompts.

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

Entender as métricas de avaliação

Cada teste é pontuado automaticamente em várias dimensões.

Relevância (1-5)

A relevância mede o quão bem a resposta aborda o prompt:

  • 5: Aborda perfeitamente a questão
  • 3: Aborda parcialmente a questão
  • 1: Não aborda a questão

Coerência (1-5)

A coerência mede o quão lógica e bem estruturada é a resposta:

  • 5: Claro, lógico, bem organizado
  • 3: Um pouco organizado, mas poderia ser mais claro
  • 1: Incoerente ou confuso

Aterramento (1-5)

A fundamentação mede o quão bem a resposta é apoiada por fontes e citações:

  • 5: Totalmente fundamentado com citações apropriadas
  • 3: Parcialmente fundamentado com algumas citações
  • 1: Sem fundamentação ou citações

Similaridade (1-5)

A similaridade mede o quanto a resposta corresponde à saída esperada:

  • 5: A resposta é semanticamente equivalente à saída esperada
  • 3: A resposta corresponde parcialmente à saída esperada
  • 1: a resposta não corresponde à saída esperada

Citações (>= 0)

Citações é um avaliador baseado em contagem que conta o número de citações válidas na resposta. Uma pontuação de 0 significa que nenhuma citação está presente. Configure um limite mínimo para definir uma barra de aprovação/reprovação.

ExactMatch

ExactMatch é um avaliador de correspondência de cadeia de caracteres com um resultado booliano. A resposta será passada se contiver exatamente a cadeia de caracteres esperada. Dá suporte a uma case_sensitive opção (padrão: false).

PartialMatch (0.0-1.0)

PartialMatch é um avaliador de correspondência de cadeia de caracteres que retorna uma pontuação de similaridade contínua entre 0.0 e 1.0. Use a threshold opção para definir a pontuação mínima necessária para obter aprovação (padrão: 0.5).

Melhoria contínua

Revisar testes com falha

Quando os testes têm uma pontuação ruim:

  1. Analise a resposta real versus a resposta esperada.
  2. Determine se a resposta esperada precisa ser atualizada.
  3. Verifique se o agente precisa de mais dados de treinamento ou instruções.
  4. Verifique se as configurações da ferramenta estão corretas.

Acompanhar pontuações ao longo do tempo

Salve os resultados do teste para comparar entre as versões.

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

Conteúdo relacionado

  • Last updated on