Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
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 des jeux de données, documente où l’outil recherche les jeux de données et montre comment concevoir des tests efficaces, y compris des scénarios avancés tels que les conversations à plusieurs tours, la configuration par évaluateur par élément et les 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 versionné (recommandé) et un tableau hérité.
Schéma versionné
Remarque
CLI v1 prend en charge deux formes de jeux de données : un objet versionné (recommandé) et un tableau hérité. CLI v2 nécessite un objet versionné contenant schemaVersion et items.
Un dataset uses schemaVersion and an array items . L’exemple suivant s’applique expected_response aux évaluateurs qui comparent une réponse à une réponse de référence. Les évaluateurs tels que Pertinence, Cohérence et l’outil d’appel de préversion v2 n’ont pas besoin expected_responsede .
{
"schemaVersion": "1.0.0",
"items": [
{
"prompt": "string",
"expected_response": "string"
}
]
}
La version 1.6.0 de schéma prend désormais en charge la configuration de l’évaluateur par défaut et par élément, le contrôle du mode évaluateur, les éléments nommés et les conversations à plusieurs tours. Pour plus de détails, voir Configurer les évaluateurs et les modèles d’évaluation multitour.
Choisissez la version de schéma du jeu de données qui correspond à votre version CLI :
-
CLI v1 (
latest) : Utiliser le schéma v1. Les exemples de schéma v1 de cet article restent applicables. -
CLI v2 (
preview) : UtiliserschemaVersion"2.0.0"et la définition du schéma v2. CLI v2 n’accepte pas les jeux de données schémas v1 ou sans version, quels que soient les évaluateurs sélectionnés.
Évaluation des plug-ins autonomes via Microsoft 365 Copilot nécessite CLI v2. Les évaluateurs d’appels d’outils nécessitent également CLI v2, qu’il s’agisse d’un plug-in autonome ou d’un agent déclaratif. CLI v1 continue à prendre en charge l’évaluation des agents déclaratifs, y compris les agents avec des actions de plug-in, à l’aide de ses évaluateurs pris en charge.
Champs de schéma
Vous trouverez le schéma du jeu de données d’évaluation au format JSON sur GitHub.
| Champ | Type (Type) | Obligatoire | Description |
|---|---|---|---|
schemaVersion |
chaîne | Requis dans CLI v2 ; recommandé dans CLI v1 | Version de schéma du jeu de données. À utiliser "2.0.0" avec CLI v2 (preview) ou une version de schéma v1 prise en charge avec CLI v1 (latest). La compatibilité descendante est garantie dans une version majeure du schéma. |
items |
tableau | Oui | Tableau d’éléments de test. Chaque élément est soit une paire invite/réponse à un tour, soit une conversation nommée à plusieurs tours. |
description |
chaîne | Facultatif | Description en texte libre du jeu de données (par exemple, "Regression tests for Q1 2026 release"). |
default_evaluators |
objet | Facultatif | Évaluateurs appliqués à chaque élément du jeu de données sauf remplacement. 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 |
chaîne | Conditionnel | Requête ou instruction envoyée à l’agent. Obligatoire pour les articles à tour unique. Ne pas utiliser avec turns. |
items[].expected_response |
chaîne | Conditionnel | Réponse de référence utilisée pour la notation. Requis par les évaluateurs tels que Similarity, ExactMatch et PartialMatch, mais pas par les évaluateurs d’appel d’outil. Ne pas utiliser avec turns. |
items[].name |
chaîne | Facultatif | Nom complet de l’élément de test (par exemple, "Expense policy flow"). Particulièrement utile pour identifier les éléments à plusieurs tours dans les rapports. |
items[].turns |
tableau | Conditionnel | Tableau ordonné d’objets de tour pour une conversation multitour au sein d’un seul élément. Chaque tour contient prompt, expected_response lorsque les évaluateurs sélectionnés l’exigent, et éventuellement evaluators et evaluators_mode. Ne pas utiliser avec des fichiers de niveau prompt/expected_responsesupérieur Nécessite schemaVersion"1.2.0" ou version ultérieure. |
items[].evaluators |
objet | Facultatif | Remplacements par é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 de evaluators_mode. Nécessite schemaVersion"1.2.0" ou version ultérieure. |
items[].evaluators_mode |
chaîne | Facultatif | Contrôle comment 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 défauts. Nécessite schemaVersion"1.2.0" ou version ultérieure. |
items[].testId |
chaîne | Facultatif | Identificateur stable pour la comparaison entre versions (par exemple, "REG-001"). |
items[].category |
chaîne | Facultatif | Balise de catégorie (par exemple, "knowledge-base", "tool-usage"). |
items[].notes |
chaîne | Facultatif | Notes de forme libre, telles qu’un ID de bogue lié. |
default_allowed_tools |
Tableau de chaînes | Facultatif | Identificateurs de consentement approuvés pour le jeu de données. Pour une utilisation avec les évaluateurs d’appel d’outil dans la préversion v2, consultez Autoriser les appels d’outil. |
items[].allowed_tools / items[].turns[].allowed_tools |
Tableau de chaînes | Facultatif | Identificateurs de consentement approuvés pour une invite ou un tour. Ce ne sont pas des identités d’outil d’évaluateur. |
items[].allowed_tools_mode / items[].turns[].allowed_tools_mode |
chaîne | Facultatif |
"extend" (par défaut) combine allowed_tools avec default_allowed_tools.
"replace" Utilise uniquement la liste de l’invite ou du tour. Utilisez "replace" avec allowed_tools: [] pour n’approuver aucune demande de confirmation d’outil pour cette invite ou ce tour. |
Configurer les évaluateurs
La version 1.6.0 de schéma vous permet de contrôler les évaluateurs qui s’exécutent et leur configuration, tant au niveau du jeu de données qu’au niveau de l’élément individuel. Pour plus de détails sur le comportement de notation et les options de configuration de chaque évaluateur, consultez Référence des évaluateurs.
Évaluateurs par défaut
S’utilise default_evaluators au niveau supérieur pour spécifier des é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 d’options. Utilise 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 la pertinence et la cohérence à l’aide des paramètres par défaut.
Remplacements par évaluateur
Utilisez le evaluators champ d’un élément individuel (ou d’un tour) pour ajouter ou remplacer des évaluateurs pour ce test spécifique. Permet evaluators_mode de contrôler la façon dont les évaluateurs par article 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é à la fois par les évaluateurs par défaut et par tous les évaluateurs supplémentaires spécifiés sur l’article. -
"replace"— Ignore entièrement les valeurs par défaut. Seuls les évaluateurs spécifiés sur l’article 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 la pertinence (par défaut), la cohérence (par défaut) et les citations avec citation_format défini sur "mixed" (remplacement par élément).
Autoriser les appels d’outils
Lors de l’évaluation des appels d’outil qui demandent une confirmation, configurez les attentes de l’approbation et de l’évaluateur.
default_allowed_tools au niveau du document et allowed_tools par invite ou tour, laissez l’interface CLI approuver les invites de confirmation de l’outil. Chaque identifiant de consentement demandé doit être autorisé ; Dans le cas contraire, l’invite s’arrête avec une toolCallNotAllowed erreur.
Important
L’autorisation d’un appel accorde le consentement. Utilisez des scénarios examinés et commencez par des opérations en lecture seule. Une attente d’évaluateur n’accorde pas le consentement, et l’approbation ne force pas la sélection de l’outil ou ne prouve pas l’exécution. Les outils qui ne demandent pas de confirmation ne sont pas contrôlés par cette liste, il ne s’agit donc pas d’une limite de sécurité.
Les identificateurs de consentement diffèrent de l’identité de l’outil en trois parties dans le calls[].tool. Ne fractionnez pas les identificateurs de consentement pour remplir les champs de l’évaluateur. Pour les commandes de découverte, la configuration et les jeux de données de schéma complets v2, consultez Évaluateurs d’appel d’outil.
Exemple de schéma complet
L’exemple suivant montre toutes les caractéristiques de schéma dans un seul jeu de données : valeurs par défaut de niveau supérieur, un élément à un tour avec des remplacements d’évaluateur et un élément nommé à plusieurs tours avec une configuration d’é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 de cet exemple :
- Le premier élément est un test à un tour. Il hérite
Relevancede etCoherencededefault_evaluatorset ajouteCitationsvia le"extend"mode. - Le deuxième élément est une conversation nommée à plusieurs tours (
"Expense policy flow") avec deux tours. La première tour hérite des évaluateurs par défaut. Le deuxième tour utilise"replace"le mode, donc ne s’exécute queExactMatch- 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 de ligne de commande met automatiquement à niveau les documents hérités (manquants schemaVersion) au format versionné et écrit une sauvegarde horodatée.
Emplacement et affectation des noms de fichiers
L’outil d’évaluation découvre automatiquement les fichiers de jeux de données dans votre projet.
Ordre de découverte automatique
Lorsque vous exécutez runevals, l’outil recherche les jeux de données dans cet ordre :
- Répertoire actuel :
prompts.json,evals.json,tests.json -
./evals/sous-répertoire :prompts.json, ,evals.jsontests.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 de 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 est 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
Vérifiez si votre agent accède à ses base de connaissances et l’utilise correctement.
{
"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."
}
Instruction suivante
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 les plug-ins disponibles.
L’exemple suivant basé sur les réponses ne prouve pas qu’un outil a été sélectionné ou exécuté. Pour vérifier le comportement de l’exécution, utilisez la case activée ToolCallSelection ou ToolCallExecution dans la préversion de 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."
}
Cas limites
Testez les conditions aux 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
Assurez-vous que l’agent traite 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."
}
Meilleures pratiques pour la conception de tests
Écrire des invites claires
Voici un exemple d’invite en clair.
{
"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
Basez les tests sur les questions réelles des utilisateurs.
{
"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ée
Modèles d’évaluation multitours
La version 1.2.0 de schéma et les versions ultérieures prennent en charge les conversations à plusieurs tours. 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"
}
]
}
]
}
Informations essentielles :
- Chaque élément avec un
turnstableau est évalué comme une seule conversation. Les tours sont envoyés en séquence, chaque tour s’appuyant sur le contexte de conversation des précédents. - Utilisez ce champ pour donner aux éléments à plusieurs tours une étiquette lisible dans les
namerapports. - Vous pouvez postuler
evaluatorsetevaluators_modeà tour de rôle. Dans l’exemple précédent, le deuxième tour utilise"replace"le mode donc ne s’exécute queExactMatchpour 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 approximer les conversations à plusieurs tours en concevant des éléments séquentiels où les invites ultérieures font référence au contexte établi par les précédentes. Utilisez des préfixes et category des balises cohérents testId pour regrouper et filtrer les éléments connexes 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 gère pas le contexte de conversation entre les éléments. Pour une véritable évaluation multitour avec un contexte partagé, utilisez le tableau avec la turns version 1.2.0 de schéma ou ultérieure.
Catégorisation et notation par invite
Utilisez le champ facultatif category pour regrouper des éléments afin de pouvoir analyser les scores par dimension (connaissances, outils, sécurité, cas limites, 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 d’organization des jeux 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 dataset spécifiques.
runevals --prompts-file ./evals/knowledge-base.json
runevals --prompts-file ./evals/tool-usage.json
Tests de régression
Lorsque vous corrigez des problèmes, ajoutez des tests pour empêcher la régression. Utilisez testId et notes pour créer 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 en ligne
Utilisez le mode interactif pour les tests exploratoires sans fichier de jeu de données.
runevals --interactive
Pour des tests rapides à invite unique, transmettez les invites en ligne.
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 la façon dont 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 logique et la structure de la réponse :
- 5 : Clair, logique, bien organisé
- 3 : Assez organisé mais pourrait être plus clair
- 1 : Incohérent ou confus
Ancrage (1-5)
Groundedness mesure dans quelle mesure la réponse est soutenue par les sources et les citations :
- 5 : Entièrement fondé avec des citations appropriées
- 3 : Partiellement fondé avec quelques citations
- 1 : Pas d’ancrage ou de citations
Similitude (1-5)
La similarité 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. Une vingtaine de signifie qu’aucune citation n’est 0 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 réussit 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é continu entre 0.0 et 1.0. Utilisez l’option threshold permettant de définir le score minimum requis pour réussir (par défaut : 0.5).
Amélioration continue
Passer en revue les tests ayant échoué
Lorsque les résultats des tests sont médiocres :
- Passez en revue la réponse réelle par rapport à la réponse attendue.
- Déterminez si la réponse attendue doit être mise à jour.
- Vérifiez si l’agent a besoin de plus de données d’entraînement ou d’instructions.
- 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