Schema del set di dati e progettazione del test

I set di dati di valutazione sono file JSON contenenti richieste e risposte previste. Questo articolo definisce lo schema del set di dati, documenta dove lo strumento cerca i set di dati e mostra come progettare test efficaci, inclusi scenari avanzati come conversazioni a più turni, configurazione dell'analizzatore per elemento e suite di test categorizzati.

Panoramica dello schema

I set di dati di valutazione sono file JSON. Lo strumento supporta due forme equivalenti: un oggetto con versione (consigliato) e una matrice legacy.

Schema delle versioni

Nota

CLI v1 supporta due forme di set di dati: un oggetto con versione (consigliato) e un array legacy. CLI v2 richiede un oggetto con versione contenente schemaVersion e items.

Un set di dati utilizza schemaVersion e una items matrice. L'esempio seguente include expected_response per i valutatori che confrontano una risposta con una risposta di riferimento. Gli analizzatori come Pertinenza, Coerenza e gli analizzatori delle chiamate agli strumenti di anteprima v2 non richiedono expected_response.

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

La versione schema 1.6.0 aggiunge il supporto per la configurazione predefinita e per elemento dell'analizzatore, il controllo della modalità dell'analizzatore, gli elementi denominati e le conversazioni a più turni. Per informazioni dettagliate, vedere Configurare analizzatori e modelli di valutazione a più turni.

Scegliere la versione dello schema del dataset che corrisponde alla versione dell'interfaccia della riga di comando:

  • CLI v1 (latest): usa lo schema v1. Gli esempi di schema v1 riportati in questo articolo rimangono applicabili.
  • CLI v2 (preview): Utilizzo schemaVersion"2.0.0" e la definizione dello schema v2. L'interfaccia della riga di comando v2 non accetta lo schema v1 o set di dati senza versione, indipendentemente dagli analizzatori selezionati.

La valutazione di plug-in autonomi tramite Microsoft 365 Copilot richiede CLI v2. Gli analizzatori delle chiamate agli strumenti richiedono anche l'interfaccia della riga di comando v2, sia che si tratti di valutare un plug-in autonomo o un agente dichiarativo. CLI v1 continua a supportare la valutazione degli agenti dichiarativi, inclusi gli agenti con azioni del plug-in, utilizzando gli analizzatori supportati.

Campi dello schema

Puoi trovare lo schema del set di dati di valutazione in formato schema JSON su GitHub.

Campo Type Obbligatorio Descrizione
schemaVersion stringa Obbligatorio nell'interfaccia della riga di comando v2. consigliato nell'interfaccia della riga di comando v1 Versione dello schema del set di dati. Utilizzare "2.0.0" con CLI v2 (preview) o una versione dello schema v1 supportata con CLI v1 (latest). La compatibilità con le versioni precedenti è garantita all'interno di una versione principale dello schema.
items matrice Sì Matrice di elementi di test. Ogni elemento è una coppia di prompt/risposta a turno singolo o una conversazione a più turni denominata.
description stringa Facoltativo Descrizione a testo libero del set di dati (ad esempio, "Regression tests for Q1 2026 release").
default_evaluators oggetto Facoltativo Analizzatori applicati a ogni elemento del set di dati, a meno che non venga eseguito l'override. Ogni chiave è il nome di un analizzatore (ad esempio, "Relevance", "Coherence"); il valore è un oggetto options (da usare {} per i valori predefiniti). Richiede schemaVersion"1.2.0" o versione successiva.
items[].prompt stringa Condizionale Richiesta o istruzione inviata all'agente. Obbligatorio per gli oggetti a giro singolo. Non usare con turns.
items[].expected_response stringa Condizionale Risposta di riferimento usata per il punteggio. Richiesto dagli analizzatori come Similarity, ExactMatch e PartialMatch, ma non dagli analizzatori delle chiamate allo strumento. Non usare con turns.
items[].name stringa Facoltativo Nome visualizzato per l'elemento di test (ad esempio, "Expense policy flow"). Particolarmente utile per identificare gli elementi a più turni nei report.
items[].turns matrice Condizionale Matrice ordinata di oggetti di svolta per una conversazione multiturm all'interno di un singolo elemento. Ogni turno contiene prompt, expected_response quando richiesto dagli analizzatori selezionati e, facoltativamente evaluators , e evaluators_mode. Non utilizzare con indirizzi di primo livello prompt/expected_response. Richiede schemaVersion"1.2.0" o versione successiva.
items[].evaluators oggetto Facoltativo Sostituzioni dell'analizzatore per elemento. Ogni chiave è un nome di analizzatore; Il valore è un oggetto OPTIONS (ad esempio, { "citation_format": "mixed" }). Il comportamento dipende da evaluators_mode. Richiede schemaVersion"1.2.0" o versione successiva.
items[].evaluators_mode stringa Facoltativo Controlla il modo items[].evaluators in cui si combina con default_evaluators. Usare "extend" (impostazione predefinita) per unire gli analizzatori per elemento con quelli predefiniti oppure "replace" per usare solo gli analizzatori per elemento e ignorare quelli predefiniti. Richiede schemaVersion"1.2.0" o versione successiva.
items[].testId stringa Facoltativo Identificatore stabile per il confronto tra versioni (ad esempio, "REG-001").
items[].category stringa Facoltativo Tag di categoria (ad esempio, "knowledge-base", ). "tool-usage"
items[].notes stringa Facoltativo Note a mano libera, ad esempio un ID bug collegato.
default_allowed_tools matrice di stringhe Facoltativo Identificatori di consenso approvati per il set di dati. Per l'utilizzo con gli analizzatori delle chiamate agli strumenti nell'anteprima v2, vedere Consentire le chiamate agli strumenti.
items[].allowed_tools / items[].turns[].allowed_tools matrice di stringhe Facoltativo Identificatori di consenso approvati per un prompt o un turno. Queste non sono identità dello strumento di valutazione.
items[].allowed_tools_mode / items[].turns[].allowed_tools_mode stringa Facoltativo "extend" (impostazione predefinita) si combina allowed_tools con default_allowed_tools. "replace" Usa solo l'elenco dei prompt o dei turni. Utilizzare "replace" con allowed_tools: [] per non approvare alcuna richiesta di conferma dell'utensile per tale richiesta o svolta.

Configurare gli analizzatori

La versione 1.6.0 schema consente di controllare quali analizzatori eseguono e come sono configurati, sia a livello di set di dati che a livello di singolo elemento. Per informazioni dettagliate sul comportamento di assegnazione dei punteggi di ogni valutatore e sulle opzioni di configurazione, vedere Guida di riferimento per i valutatori.

Analizzatori predefiniti

Usare default_evaluators al livello superiore per specificare analizzatori che si applicano a ogni elemento del set di dati. Ogni chiave è un nome di analizzatore e il valore è un oggetto opzioni. Usare un oggetto vuoto ({}) per applicare l'analizzatore con le impostazioni predefinite.

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

In questo esempio, a ogni elemento viene assegnato un punteggio per pertinenza e coerenza usando le impostazioni predefinite.

Sostituzioni dell'analizzatore per elemento

Usa il evaluators campo su un singolo elemento (o turno) per aggiungere o sostituire i valutatori per quel test specifico. Da utilizzare evaluators_mode per controllare il modo in cui gli analizzatori per elemento si combinano con default_evaluators:

  • "extend" (predefinito) — Unisce gli analizzatori per elemento con i valori predefiniti. L'elemento viene valutato sia dagli analizzatori predefiniti che da qualsiasi analizzatore aggiuntivo specificato nell'elemento.
  • "replace" — Ignora completamente le impostazioni predefinite. Vengono usati solo gli analizzatori specificati nell'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"
    }
  ]
}

In questo esempio, all'elemento viene assegnato un punteggio per Pertinenza (impostazione predefinita), Coerenza (impostazione predefinita) e Citazioni con citation_format impostato su (override per "mixed" elemento).

Consente le chiamate agli strumenti

Quando si valutano le chiamate dello strumento che richiedono conferma, configurare le aspettative sia di approvazione che dell'analizzatore. default_allowed_tools a livello di documento e per prompt o turno, lasciare che la CLI approvi allowed_tools le richieste di conferma dello strumento. Ogni identificatore di consenso richiesto deve essere consentito; In caso contrario, il prompt si interrompe con un toolCallNotAllowed errore.

Importante

L'autorizzazione di una chiamata concede il consenso. Usa gli scenari esaminati e inizia con le operazioni di sola lettura. Un'aspettativa del valutatore non concede il consenso e l'approvazione non forza la selezione dello strumento o prova l'esecuzione. Gli strumenti che non richiedono conferma non sono controllati da questo elenco, pertanto non si tratta di un limite di sicurezza.

Gli identificatori di consenso differiscono dall'identità dello strumento in tre parti in un analizzatore calls[].tool. Non dividere gli identificatori di consenso per popolare i campi di valutazione. Per i comandi di individuazione, la configurazione e i set di dati completi dello schema v2, vedere Analizzatori delle chiamate di strumenti.

Esempio di schema completo

L'esempio seguente mostra tutte le funzionalità dello schema in un singolo set di dati: valori predefiniti di primo livello, un elemento a turno singolo con sostituzioni dell'analizzatore e un elemento a più turni denominato con configurazione dell'analizzatore per 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"
        }
      ]
    }
  ]
}

Dettagli principali in questo esempio:

  • Il primo elemento è un test a turno singolo. Eredita Relevance e Coherence da default_evaluators e aggiunge Citations attraverso la "extend" modalità.
  • Il secondo elemento è una conversazione"Expense policy flow" a più turni () con due turni. Il primo turno eredita gli analizzatori predefiniti. Il secondo turno usa "replace" la modalità, quindi si limita a ExactMatch correre - le impostazioni predefinite vengono ignorate per quel turno.

Schema di matrice legacy

Lo strumento accetta anche un semplice array per la compatibilità con le versioni precedenti:

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

L'interfaccia della riga di comando aggiorna automaticamente i documenti legacy (mancanti) schemaVersional formato con versione e scrive un backup con data e ora.

Denominazione e percorso dei file

Lo strumento di valutazione individua automaticamente i file di set di dati nel progetto.

Ordine di individuazione automatica

Durante l'esecuzione runevals, lo strumento cerca i set di dati nell'ordine seguente:

  1. Directory corrente: prompts.json, evals.json, tests.json
  2. ./evals/ Sottodirectory: 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

Creazione di file di base

Se lo strumento non trova un file di set di dati, chiede di creare un file di base:

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

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

La risposta a Y crea ./evals/evals.json con richieste di esempio.

Progetta prompt di test efficaci

Organizza i tuoi test in categorie che riflettono il comportamento dell'agente che vuoi verificare.

Verifica delle informazioni

Verifica se il tuo agente accede e utilizza correttamente la sua 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."
}

Istruzioni seguenti

Verificare che l'agente segua istruzioni specifiche.

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

Utilizzo degli strumenti

Verifica se l'agente usa correttamente gli strumenti e i plug-in disponibili.

L'esempio seguente basato sulla risposta non dimostra che uno strumento sia stato selezionato o eseguito. Per controllare il comportamento di runtime, utilizzare ToolCallSelection o ToolCallExecution nell'anteprima 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."
}

Casi limite

Testare condizioni al contorno e input insoliti.

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

Sicurezza e idoneità

Assicurarsi che l'agente gestisca correttamente le richieste inappropriate.

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

Procedure consigliate per la progettazione dei test

Scrivi prompt chiari

Di seguito è riportato un esempio di richiesta chiara.

{
  "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 richieste ambigue come nell'esempio seguente.

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

Includi scenari realistici

Basa i test sulle domande effettive dell'utente.

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

Gestione degli errori di copertura

Verificare il modo in cui l'agente gestisce correttamente gli errori.

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

Scenari di valutazione avanzati

Modelli di valutazione a più turni

La versione 1.2.0 dello schema e successive supporta conversazioni a più turni. Usa la turns matrice all'interno di un elemento per definire una sequenza ordinata di richieste e risposte previste che formano un unico flusso di conversazione. Ogni turno può facoltativamente includere la propria configurazione dell'analizzatore.

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

Dettagli principali:

  • Ogni elemento con una turns matrice viene valutato come una singola conversazione. I turni vengono inviati in sequenza, con ogni turno basato sul contesto di conversazione dei precedenti.
  • Usare il campo per assegnare agli elementi a più turni un'etichetta name leggibile nei report.
  • Puoi applicare evaluators e evaluators_mode su singoli turni. Nell'esempio precedente, il secondo turno usa "replace" la modalità, quindi viene eseguito solo ExactMatch per quel turno.

Modello di elementi sequenziali (versione schema 1.0.0)

Se si usa la versione 1.0.0dello schema , è possibile approssimare conversazioni a più turni progettando elementi sequenziali in cui i prompt successivi fanno riferimento al contesto stabilito da quelli precedenti. Usa prefissi e category tag coerenti testId per raggruppare e filtrare gli elementi correlati nei risultati.

{
  "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 gli elementi sequenziali, ogni elemento viene valutato in modo indipendente. L'agente non trasmette il contesto della conversazione tra gli elementi. Per una vera valutazione a più turni con contesto condiviso, usare la matrice con la turns versione 1.2.0 dello schema o successiva.

Categorizzazione e assegnazione dei punteggi per prompt

Usa il campo facoltativo category per raggruppare gli elementi in modo da poter analizzare i punteggi per dimensione (conoscenza, strumenti, sicurezza, casi limite, regressione).

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

Strategie organizzative per set di dati

Per i progetti di grandi dimensioni, organizza i test per categoria in più file.

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

Eseguire file di set di dati specifici.

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

Test di regressione

Quando risolvi i problemi, aggiungi test per prevenire la regressione. Usare testId e notes per collegarsi al monitoraggio dei bug.

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

Modelli di base

Modello di test dell'agente di base

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

Modello di test della 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]"
    }
  ]
}

Modello di test per l'utilizzo dell'utensile

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

Test interattivi e in linea

Usa la modalità interattiva per i test esplorativi senza un file di set di dati.

runevals --interactive

Per test rapidi a prompt singolo, passa le richieste in linea.

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

Più prompt.

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

Informazioni sulle metriche di valutazione

Ogni test viene valutato automaticamente su più dimensioni.

Pertinenza (1-5)

La pertinenza misura il grado di risposta al prompt:

  • 5: Risponde perfettamente alla domanda
  • 3: Risponde parzialmente alla domanda
  • 1: Non risponde alla domanda

Coerenza (1-5)

La coerenza misura quanto sia logica e ben strutturata la risposta:

  • 5: Chiaro, logico, ben organizzato
  • 3: Abbastanza organizzato ma potrebbe essere più chiaro
  • 1: Incoerente o confuso

Radicamento (1-5)

La fondatezza misura quanto bene la risposta è supportata da fonti e citazioni:

  • 5: Completamente fondato con citazioni appropriate
  • 3: Parzialmente fondato con alcune citazioni
  • 1: Nessun fondamento o citazione

Similarità (1-5)

La somiglianza misura quanto la risposta corrisponda all'output atteso:

  • 5: La risposta è semanticamente equivalente all'output atteso
  • 3: La risposta corrisponde parzialmente all'output previsto
  • 1: La risposta non corrisponde all'output previsto

Citazioni (>= 0)

Citazioni è un analizzatore basato sul conteggio che conta il numero di citazioni valide nella risposta. Un punteggio di 0 significa che non sono presenti citazioni. Configurare una soglia minima per impostare una barra di accettazione/errore.

ExactMatch

ExactMatch è un analizzatore di corrispondenze di stringhe con un risultato booleano. La risposta passa se contiene esattamente la stringa prevista. Supporta un'opzione case_sensitive (impostazione predefinita: false).

PartialMatch (0.0-1.0)

PartialMatch è un analizzatore di corrispondenza di stringhe che restituisce un punteggio di somiglianza continuo tra 0.0 e 1.0. Usa l'opzione per impostare il punteggio minimo richiesto per superare l'esame threshold (predefinito: 0.5).

Continui miglioramenti

Rivedere i test non riusciti

Quando i test ottengono un punteggio basso:

  1. Esamina la risposta effettiva rispetto alla risposta prevista.
  2. Determinare se la risposta attesa deve essere aggiornata.
  3. Verificare se l'agente necessita di altri dati di formazione o istruzioni.
  4. Verificare che le configurazioni degli utensili siano corrette.

Tenere traccia dei punteggi nel tempo

Salva i risultati dei test per confrontare le versioni.

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