Schéma de jeu de données et conception de test

Les jeux de données d’évaluation sont des fichiers JSON contenant des invites et des réponses attendues. Cet article définit le schéma du jeu de données, documente l’emplacement où l’outil recherche des jeux de données et montre comment concevoir des tests efficaces, y compris des scénarios avancés tels que des conversations multitours, la configuration de l’évaluateur par élément et des suites de tests catégorisées.

Vue d’ensemble du schéma

Les jeux de données d’évaluation sont des fichiers JSON. L’outil prend en charge deux formes équivalentes : un objet avec version (recommandé) et un tableau hérité.

Schéma versionné (recommandé)

Le jeu de données valide le plus simple nécessite uniquement schemaVersion et un items tableau avec prompt les champs et expected_response .

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

La version 1.6.0 du schéma ajoute la prise en charge de la configuration de l’évaluateur par défaut et par élément, du contrôle du mode évaluateur, des éléments nommés et des conversations multitours. Pour plus d’informations, consultez Configurer des évaluateurs et Modèles d’évaluation multitours.

Champs de schéma

Vous trouverez le schéma du jeu de données d’évaluation au format de schéma JSON sur GitHub.

Champ	Type	Requis	Description
schemaVersion	string	Recommandé	Version sémantique (par exemple, "1.0.0" ou "1.6.0"). La compatibilité descendante est garantie dans une version principale. Permet "1.6.0" d’activer la configuration de l’évaluateur, les modes évaluateurs et la prise en charge native de plusieurs tour.
items	tableau	Oui	Tableau d’éléments de test. Chaque élément est une paire invite/réponse à un seul tour ou une conversation multitour nommée.
description	string	Facultatif	Description en texte libre du jeu de données (par exemple, "Regression tests for Q1 2026 release").
default_evaluators	objet	Facultatif	Les évaluateurs ont appliqué à chaque élément du jeu de données, sauf en cas de substitution. Chaque clé est un nom d’évaluateur (par exemple, "Relevance", "Coherence") ; la valeur est un objet options (à utiliser {} pour les valeurs par défaut). Nécessite schemaVersion"1.2.0" ou version ultérieure.
items[].prompt	string	Conditionnelle	Invite ou instruction envoyée à l’agent. Obligatoire pour les éléments à tour unique. N’utilisez pas avec turns.
items[].expected_response	string	Conditionnelle	Réponse de référence utilisée pour le scoring. Obligatoire pour les éléments à tour unique. N’utilisez pas avec turns.
items[].name	string	Facultatif	Nom d’affichage de l’élément de test (par exemple, "Expense policy flow"). Particulièrement utile pour identifier les éléments multitours dans les rapports.
items[].turns	tableau	Conditionnelle	Tableau ordonné d’objets de tour pour une conversation multitour au sein d’un seul élément. Chaque tour contient prompt, expected_responseet éventuellement evaluators et evaluators_mode. N’utilisez pas avec le niveau prompt/expected_responsesupérieur. Nécessite schemaVersion"1.2.0" ou version ultérieure.
items[].evaluators	objet	Facultatif	Remplacements de l’évaluateur par élément. Chaque clé est un nom d’évaluateur ; la valeur est un objet options (par exemple, { "citation_format": "mixed" }). Le comportement dépend evaluators_modede . Nécessite schemaVersion"1.2.0" ou version ultérieure.
items[].evaluators_mode	string	Facultatif	Contrôle la façon dont items[].evaluators combine avec default_evaluators. Utilisez "extend" (par défaut) pour fusionner les évaluateurs par élément avec les valeurs par défaut, ou "replace" pour utiliser uniquement les évaluateurs par élément et ignorer les valeurs par défaut. Nécessite schemaVersion"1.2.0" ou version ultérieure.
items[].testId	string	Facultatif	Identificateur stable pour la comparaison entre versions (par exemple, "REG-001").
items[].category	string	Facultatif	Balise category (par exemple, "knowledge-base", "tool-usage").
items[].notes	string	Facultatif	Notes de forme libre, telles qu’un ID de bogue lié.

Configurer les évaluateurs

La version 1.6.0 du schéma vous permet de contrôler les évaluateurs qui s’exécutent et la façon dont ils sont configurés, au niveau du jeu de données et au niveau de l’élément individuel. Pour plus d’informations sur le comportement de scoring et les options de configuration de chaque évaluateur, consultez Informations de référence sur les évaluateurs.

Évaluateurs par défaut

Utilisez default_evaluators au niveau supérieur pour spécifier les évaluateurs qui s’appliquent à chaque élément du jeu de données. Chaque clé est un nom d’évaluateur et la valeur est un objet options. Utilisez un objet vide ({}) pour appliquer l’évaluateur avec ses paramètres par défaut.

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

Dans cet exemple, chaque élément est noté pour pertinence et cohérence à l’aide des paramètres par défaut.

Remplacements de l’évaluateur par élément

Utilisez le evaluators champ sur un élément individuel (ou un tour) pour ajouter ou remplacer des évaluateurs pour ce test spécifique. Utilisez evaluators_mode pour contrôler la façon dont les évaluateurs par élément se combinent avec default_evaluators:

• "extend" (par défaut) : fusionne les évaluateurs par élément avec les valeurs par défaut. L’élément est noté par les évaluateurs par défaut et par tous les évaluateurs supplémentaires spécifiés sur l’élément.
• "replace" : ignore entièrement les valeurs par défaut. Seuls les évaluateurs spécifiés sur l’élément sont utilisés.

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

Dans cet exemple, l’élément est noté pour Pertinence (par défaut), Cohérence (valeur par défaut) et Citations avec citation_format défini sur "mixed" (remplacement par élément).

Exemple de schéma complet

L’exemple suivant montre chaque fonctionnalité de schéma dans un jeu de données unique : les valeurs par défaut de niveau supérieur, un élément à un seul tour avec remplacements de l’évaluateur et un élément multitour nommé avec la configuration de l’évaluateur par tour.

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

Détails clés dans cet exemple :

• Le premier élément est un test à un seul tour. Il hérite de Relevance et Coherence de default_evaluators et ajoute Citations via le "extend" mode .
• Le deuxième élément est une conversation nommée à plusieurs tours ("Expense policy flow") avec deux tours. Le premier tour hérite des évaluateurs par défaut. Le deuxième tour utilise "replace" le mode , donc seules ExactMatch les exécutions - les valeurs par défaut sont ignorées pour ce tour.

Schéma de tableau hérité

L’outil accepte également un tableau nu pour la compatibilité descendante :

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

L’interface CLI met automatiquement à niveau les documents hérités (manquants schemaVersion) au format versionné et écrit une sauvegarde horodatée.

Nommage et emplacement des fichiers

L’outil d’évaluation découvre automatiquement les fichiers de jeu de données dans votre projet.

Ordre de découverte automatique

Lorsque vous exécutez runevals, l’outil recherche des jeux de données dans cet ordre :

1. Répertoire actif : prompts.json, evals.json, tests.json
2. ./evals/ sous-répertoire : prompts.json, evals.json, tests.json

Structure de projet recommandée

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

Création d’un fichier de démarrage

Si l’outil ne trouve pas de fichier de jeu de données, il vous invite à créer un fichier de démarrage :

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

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

La réponse Y crée ./evals/evals.json avec des exemples d’invites.

Concevoir des invites de test efficaces

Organisez vos tests en catégories qui reflètent le comportement de l’agent que vous souhaitez vérifier.

Vérification des connaissances

Testez si votre agent accède correctement à son base de connaissances et l’utilise.

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

Instructions suivantes

Vérifiez que l’agent suit des instructions spécifiques.

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

Utilisation de l’outil

Testez si l’agent utilise correctement les outils et plug-ins 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."
}

Cas de périphérie

Tester les conditions limites et les entrées inhabituelles.

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

Sécurité et pertinence

Vérifiez que l’agent gère correctement les demandes inappropriées.

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

Bonnes pratiques pour la conception des tests

Écrire des invites en clair

Voici un exemple d’invite claire.

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

Évitez les invites ambiguës comme dans l’exemple suivant.

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

Inclure des scénarios réalistes

Tests de base sur les questions réelles de l’utilisateur.

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

Couvrir la gestion des erreurs

Testez la façon dont l’agent gère les erreurs correctement.

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

Scénarios d’évaluation avancés

Modèles d’évaluation multitours

La version 1.2.0 de schéma et les versions ultérieures prennent en charge les conversations multitours. Utilisez le turns tableau dans un élément pour définir une séquence ordonnée d’invites et de réponses attendues qui forment un flux de conversation unique. Chaque tour peut éventuellement inclure sa propre configuration d’évaluateur.

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

Détails clés :

• Chaque élément avec un turns tableau est évalué comme une seule conversation. Les tours sont envoyés dans l’ordre, chaque tour s’appuyant sur le contexte de conversation des tours précédents.
• Utilisez le name champ pour attribuer aux éléments multitours une étiquette lisible dans les rapports.
• Vous pouvez appliquer evaluators et evaluators_mode sur des tours individuels. Dans l’exemple précédent, le deuxième tour utilise "replace" le mode pour ne ExactMatch s’exécuter que pour ce tour.

Modèle d’éléments séquentiels (version de schéma 1.0.0)

Si vous utilisez la version 1.0.0de schéma , vous pouvez estimer les conversations multitours en concevant des éléments séquentiels où les invitent ultérieurement le contexte de référence établi par les précédents. Utilisez des préfixes et category des balises cohérents testId pour regrouper et filtrer les éléments associés dans les résultats.

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

Remarque

Avec les éléments séquentiels, chaque élément est évalué indépendamment. L’agent ne transporte pas le contexte de conversation entre les éléments. Pour une véritable évaluation multitour avec contexte partagé, utilisez le tableau avec la version du turns schéma ou une version 1.2.0 ultérieure.

Catégorisation et scoring par invite

Utilisez le champ facultatif category pour regrouper les éléments afin de pouvoir analyser les scores par dimension (connaissances, outils, sécurité, cas de périphérie, régression).

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

Stratégies de organization de jeu de données

Pour les grands projets, organisez les tests par catégorie sur plusieurs fichiers.

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

Exécutez des fichiers de jeu de données spécifiques.

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

Tests de régression

Lorsque vous résolvez des problèmes, ajoutez des tests pour empêcher la régression. Utilisez testId et notes pour établir un lien vers le suivi des bogues.

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

Modèles de démarrage

Modèle de test d’agent de 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]."
    }
  ]
}

Modèle de test de la base de connaissances

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

Modèle de test d’utilisation de l’outil

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

Tests interactifs et inline

Utilisez le mode interactif pour les tests exploratoires sans fichier de jeu de données.

runevals --interactive

Pour les tests rapides à invite unique, passez les invites inline.

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

Plusieurs invites.

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

Comprendre les métriques d’évaluation

Chaque test est automatiquement noté sur plusieurs dimensions.

Pertinence (1-5)

La pertinence mesure dans quelle mesure la réponse répond à l’invite :

• 5 : Répond parfaitement à la question
• 3 : Répond partiellement à la question
• 1 : ne répond pas à la question

Cohérence (1-5)

La cohérence mesure la façon dont la réponse est logique et bien structurée :

• 5 : Clair, logique, bien organisé
• 3 : Quelque peu organisé, mais pourrait être plus clair
• 1 : Incohérent ou confus

Groundedness (1-5)

Groundedness mesure la mesure dans laquelle la réponse est prise en charge par les sources et les citations :

• 5 : Entièrement fondée avec des citations appropriées
• 3 : Partiellement fondée avec quelques citations
• 1 : Aucune mise à la terre ou citations

Similarité (1-5)

Similarity mesure à quel point la réponse correspond à la sortie attendue :

• 5 : La réponse est sémantiquement équivalente à la sortie attendue
• 3 : La réponse correspond partiellement à la sortie attendue
• 1 : La réponse ne correspond pas à la sortie attendue

Citations (>= 0)

Citations est un évaluateur basé sur le nombre qui compte le nombre de citations valides dans la réponse. Un score de 0 signifie qu’aucune citation n’est présente. Configurez un seuil minimal pour définir une barre de réussite/échec.

ExactMatch

ExactMatch est un évaluateur de correspondance de chaîne avec un résultat booléen. La réponse passe si elle contient exactement la chaîne attendue. Prend en charge une case_sensitive option (par défaut : false).

PartialMatch (0.0-1.0)

PartialMatch est un évaluateur de correspondance de chaîne qui retourne un score de similarité continue entre 0.0 et 1.0. Utilisez l’option threshold pour définir le score minimal requis pour réussir (valeur par défaut : 0.5).

Amélioration continue

Passer en revue les tests ayant échoué

Lorsque les tests obtiennent un score médiocre :

1. Passez en revue la réponse réelle par rapport à la réponse attendue.
2. Déterminez si la réponse attendue doit être mise à jour.
3. Vérifiez si l’agent a besoin de plus de données d’entraînement ou d’instructions.
4. Vérifiez que les configurations des outils sont correctes.

Suivre les scores au fil du temps

Enregistrez les résultats des tests pour les comparer entre les versions.

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

Contenu connexe

• Informations de référence sur l’interface CLI
• Résolution des problèmes
• Vue d’ensemble de l’interface CLI Des évaluations d’agent
• Démarrage rapide : Utiliser l’interface CLI Des évaluations de l’agent