Créer un jeu de données d’évaluation et des évaluateurs

L’optimiseur d’agent évalue votre agent par rapport à un jeu de données , une collection de tâches, évaluée par les évaluateurs. Vous pouvez générer les deux automatiquement à partir de l’interface CLI ou créer manuellement un jeu de données pour un contrôle total.

Les deux parties sont essentielles à une bonne optimisation : le jeu de données définit ce qu’il faut tester et les évaluateurs définissent comment juger chaque réponse. Les évaluateurs faibles produisent des scores bruyants qui mènent à une optimisation médiocre, donc investir dans des évaluateurs forts autant que des tâches représentatives.

La création de ces éléments est la deuxième étape du processus d’optimisation, après avoir préparé votre agent pour l’optimisation. L’optimiseur les utilise pour évaluer votre référence et classer les candidats.

Prerequisites

• Projet Foundry avec un agent hébergé déployé.
• Azure Developer CLI (azd), version 1.37.0 ou ultérieure, requis par l’extension azure.ai.agents.
• L’extension azure.ai.agents CLI, version 1.0.0-beta.22 ou ultérieure, installée (voir Démarrage rapide : Optimiser un agent hébergé).
• Extension azure.ai.evaluations , qui fournit les azd ai eval commandes et nécessite azd la version 1.33.0 ou ultérieure. L’extension microsoft.foundry ne l’inclut pas. Installez-la séparément.
• Une session authentifiée azd . Pour vérifier l’état de votre authentification, exécutez azd auth status. Si vous n’êtes pas connecté, exécutez azd auth login.

Générer un jeu de données et des évaluateurs (recommandé)

L’optimiseur réutilise les ressources d’évaluation que vous créez avec les commandes azd ai eval de l’extension azure.ai.evaluations. Le groupe de commandes azd ai agent eval est déprécié. Il imprime uniquement les instructions de migration dans azd ai eval, et il n’effectue pas de demandes de service ni ne modifie les fichiers projet. L’optimiseur ne prend pas en charge le fichier de l’agent hérité eval.yaml.

Générez un jeu de données et un évaluateur de grille d’évaluation à partir des instructions de votre agent :

azd extension install azure.ai.evaluations
azd ai eval generate \
  --from prompt \
  --target <agent-name> \
  --generation-model <generation-deployment> \
  --agent-instruction "<agent-instructions>" \
  --no-prompt

Par défaut, la commande génère :

• Jeu de lignes pour votre agent.
• Évaluateur de grille d’évaluation personnalisé, qui est un fichier JSON modifiable de dimensions de scoring pondérées.

La commande télécharge les deux artefacts et ajoute une entrée de catalogue pour chacun à la configuration d’évaluation, qui est evals/azure.eval.yaml par défaut. Sauf si vous définissez --dataset-name ou --evaluator-name, le jeu de données est nommé <deployed-agent>-turn-tests et l’évaluateur est nommé <deployed-agent>-evaluator. Pour les options interactives et non interactives et les détails sur les artefacts générés, consultez Générer un jeu de données et un évaluateur.

Ensuite, mettez en place une évaluation qui utilise les ressources générées. L’optimiseur réutilise les évaluations de niveau tour qui ciblent votre agent, donc définissez --evaluation-level turn et --target. Cet exemple ajoute l’évaluateur intégré builtin.task_adherence à l’évaluateur de rubrique généré :

azd ai eval init \
  --source dataset \
  --evaluation-level turn \
  --target <agent-name> \
  --dataset <generated-dataset-name> \
  --evaluator <generated-evaluator-name>,builtin.task_adherence \
  --judge-model <judge-deployment> \
  --name optimizer-eval \
  --no-prompt

Exécutez l’optimiseur et sélectionnez l’évaluation par nom :

azd ai agent optimize --eval optimizer-eval --optimize-model <optimization-deployment>

Pour personnaliser les ressources générées, consultez Personnaliser les évaluateurs et créer un jeu de données personnalisé. Pour choisir l’évaluation qu’une exécution utilise, consultez Sélectionner l’évaluation d’une exécution. Pour les autres options d’exécution, exécutez azd ai agent optimize --help.

Sélectionner l’évaluation pour une exécution

azd ai agent optimize lit le jeu de données et les évaluateurs d’une évaluation que azd ai eval init a déclarée. Sélectionnez l’évaluation avec l’une des options suivantes :

L’optimiseur applique ces règles :

• Elle considère uniquement les évaluations qui ont un objectif agent. Le nom cible doit correspondre au nom de l’agent déployé ou au nom du service de l’agent dans azure.yaml.
• Il réutilise uniquement les évaluations au niveau des tours qui lisent un jeu de données. Les évaluations qui déclarent un source ou un simulation, ou qui utilisent le niveau de conversation, ne sont pas prises en charge, pas plus que les évaluateurs qui définissent dataMapping.
• Si vous ne transmettez aucune option et que le projet a une évaluation correspondante, l’optimiseur l’utilise. Si plusieurs correspondances correspondent, l’optimiseur vous invite à en sélectionner une. Avec --no-prompt ou -o json, la commande échoue et vous demande de passer --eval.
• Si vous passez --eval ou --eval-config et qu’aucune correspondance d’évaluation n’est trouvée, la commande échoue.

L’option --config prend un fichier de demande d’optimisation autonome. Vous ne pouvez pas la combiner avec --eval ou --eval-config.

Remplacez ou étendez ce que l’évaluation fournit avec ces indicateurs :

• --dataset remplace le jeu de données de l’évaluation. Transmettez un fichier JSONL local ou un jeu de données enregistré en tant que name:version.
• --evaluator ajoute un évaluateur intégré ou personnalisé par nom. Répétez l’indicateur pour en ajouter plusieurs. Un évaluateur que l’évaluation répertorie déjà n’est pas ajouté deux fois.
• --eval-model définit le modèle qui juge les réponses. Sans cela, l’optimiseur utilise le modèle que les évaluateurs de l’évaluation déclarent dans leurs paramètres d’initialisation. S’ils déclarent différents modèles, ils transmettent --eval-model.

Si le projet n’a aucune évaluation qui cible votre agent, transmettez directement le jeu de données et les évaluateurs :

azd ai agent optimize <agent-name> \
  --dataset eval.jsonl \
  --evaluator builtin.task_adherence \
  --eval-model <judge-deployment> \
  --optimize-model <optimization-deployment>

Personnaliser les évaluateurs (avancés)

Les évaluateurs scorent chaque réponse de l’agent. L’optimiseur prend en charge deux types :

• Évaluateurs intégrés, tels que builtin.task_adherence, qui évaluent chaque critère au niveau de la tâche en tant que réussite ou échec.
• Évaluateurs de rubrique personnalisés, qui scorent les réponses sur plusieurs dimensions de qualité paramétrées à votre agent. azd ai eval generate en crée un et le télécharge sous forme de fichier JSON de barème modifiable.

Pour la plupart des agents, l’évaluateur de rubrique généré donne les scores les plus significatifs, car il est adapté à votre domaine. Modifiez le fichier rubric généré pour affiner les dimensions, puis exécutez azd ai eval evaluator update <name> --from-file <path> pour publier les modifications sous forme de nouvelle version. Pour plus d’informations sur la génération, la modification et la gestion des versions des évaluateurs, consultez Générer un jeu de données et un évaluateur.

Pour utiliser un évaluateur dans une exécution, répertoriez-le dans l’évaluation avec azd ai eval init --evaluator, ou passez-le avec azd ai agent optimize --evaluator <name>. Voir Sélectionner l’évaluation pour une exécution.

Créer un jeu de données personnalisé (avancé)

Créez un jeu de données personnalisé lorsque vous avez besoin d’un contrôle précis sur les scénarios de test ou que les données de production doivent être utilisées directement. L’approche recommandée consiste à itérer sur le jeu de données que azd ai eval generate produit. Affinez-le en jeu de données local ou pointez vers un autre jeu de données déjà inscrit dans votre projet Foundry.

Choisir une source de jeu de données

Un jeu de données peut provenir de l’une des deux sources suivantes :

• Jeu de données Foundry : jeu de données déjà inscrit dans votre projet Foundry. Transmettez-le avec --dataset <name>:<version>, ou déclarez-le dans le datasets catalogue de votre configuration d’évaluation avec un name et un version. L’optimiseur a besoin du nom et de la version.
• Jeu de données local : fichier JSONL que vous créez et conservez dans votre projet. Indiquez son chemin d’accès avec --dataset, ou déclarez-le dans le catalogue datasets avec file. Un chemin relatif --dataset est résolu à partir du répertoire actif. Un chemin relatif file se résout à partir du fichier de configuration d’évaluation.

Les deux sources utilisent le même schéma de tâche décrit dans la section suivante. Pour sélectionner un jeu de données pour une exécution, consultez Sélectionner l’évaluation d’une exécution.

Schéma du jeu de données

Un jeu de données utilise le format JSONL (lignes JSON). Chaque ligne est un objet JSON qui représente une tâche d’évaluation unique , un scénario individuel. Une tâche comporte une invite (query) et, éventuellement, des criteria au niveau de la tâche.

{"name": "task_1", "query": "Your prompt here"}
{"name": "task_2", "query": "Another prompt", "ground_truth": "Expected answer"}

Lorsque vous utilisez un jeu de données local, validez la syntaxe JSONL avant d’exécuter l’optimisation :

python -c "import json; [json.loads(l) for l in open('eval.jsonl')]"

Ajouter des critères au niveau des tâches

Les critères sont facultatifs. Les évaluateurs que vous sélectionnez pour l’exécution sont utilisés pour chaque tâche du jeu de données. Ajoutez criteria pour chaque tâche uniquement lorsqu’une tâche spécifique nécessite des vérifications au-delà de celles effectuées par les évaluateurs partagés. Lorsqu'ils sont présents, les criteria d'une tâche sont évalués et agrégés avec les évaluateurs partagés afin de produire le score global de la tâche.

Le jeu de données de support client suivant présente les tâches avec des critères au niveau des tâches :

{"name": "refund_policy", "query": "What is your refund policy?", "criteria": [{"name": "mentions_30_days", "instruction": "Response must mention the 30-day refund window"}, {"name": "polite_tone", "instruction": "Response must be professional and empathetic"}]}
{"name": "order_status", "query": "Where is my order #12345?", "criteria": [{"name": "asks_for_details", "instruction": "Agent should ask for email or order details to look up the order"}, {"name": "no_hallucination", "instruction": "Agent must NOT make up a fake order status"}]}
{"name": "out_of_scope", "query": "Can you help me fix my car?", "criteria": [{"name": "polite_decline", "instruction": "Agent should politely explain this is outside its scope"}, {"name": "redirect", "instruction": "Agent should suggest contacting an appropriate service"}]}

Enregistrer et versionner un jeu de données via la CLI

Pour les jeux de données réutilisables au-delà d’une exécution d’optimiseur, installez l’extension de jeu de données publiée séparément :

azd ext install azure.ai.dataset
azd ai project set <project-endpoint>
azd ai dataset create support-golden --from-file ./support-golden.jsonl

--from-file accepte un fichier JSONL ou un répertoire contenant un fichier JSONL. Utilisez --version pour choisir explicitement une version ; sinon, la commande publie la version suivante. Conservez la version utilisée pour une évaluation inchangée lors de la comparaison des modifications de l’agent.

Publiez des données révisées et examinez les versions :

azd ai dataset update support-golden --from-file ./support-golden-v2.jsonl
azd ai dataset list --all
azd ai dataset show support-golden
azd ai dataset versions list support-golden

list retourne 20 entrées par défaut. Utilisez --limit pour limiter la recherche à une page, --all pour inclure toutes les pages et répétez --tag key=value pour exiger plusieurs correspondances de balises.

Téléchargez une version inscrite pour reproduire une exécution.

azd ai dataset download support-golden --version 1.0 \
  --output-dir ./downloaded-dataset

Utilisez --output-file uniquement pour un jeu de données à fichier unique. Les fichiers existants ne sont pas remplacés, sauf si vous passez --force. Si vous omettez --version, la dernière version est téléchargée et la version sélectionnée est indiquée.

Pour supprimer une version, exécutez azd ai dataset delete support-golden --version <version>. L’indicateur --version est requis ; si on l’omet, une erreur est renvoyée. La suppression sans interaction nécessite de spécifier explicitement --force.

Le azd ai eval dataset groupe expose le même cycle de vie via l’extension d’évaluation. L’enregistrement des données ne rend pas tous les schémas JSONL interchangeables : conservez la structure de ligne requise par votre évaluateur et la cible.

Conseils pour l’écriture de jeux de données appropriés

Inclure les cas limites

Ne vous limitez pas au scénario idéal. Incluez ce qui suit :

• Demandes hors portée : entrées que votre agent doit refuser ou rediriger
• Requêtes ambiguës : tâches où l’agent doit demander des clarifications
• Entrées adversariales — Tentatives de pousser l’agent à adopter un mauvais comportement
• Tâches en plusieurs étapes : requêtes complexes nécessitant un raisonnement structuré

Recommandations en matière de taille

Les jeux de données plus volumineux offrent une couverture plus large, mais prennent plus de temps à évaluer.

Fournir la vérité de base lorsqu’elle est utile

Le ground_truth champ donne aux évaluateurs une réponse de référence à comparer. Ce n’est pas obligatoire : les évaluateurs peuvent également juger les réponses uniquement à partir de leurs instructions et de tout critère propre à la tâche.

{"name": "geography_fact", "query": "What is the largest city in France by population?", "ground_truth": "Paris", "criteria": [{"name": "correct_answer", "instruction": "Response must state that Paris is the largest city in France by population"}]}

Rédigez des requêtes comme de vrais utilisateurs

Utilisez les messages réels de vos utilisateurs si possible. Les prompts réels capturent le vocabulaire et le contexte auxquels votre agent est confronté en production, ce qui vous aide également à rédiger des critères réalistes à l’échelle des tâches.

Être spécifique dans les critères

Les critères vagues entraînent une notation incohérente. Rendre chaque critère spécifique et testable.

Mauvais:

{"name": "good_answer", "instruction": "The response should be good"}

Bon:

{"name": "mentions_30_days", "instruction": "Response must explicitly mention the 30-day refund window"}

Résolution des problèmes

Contenu connexe

• Vue d’ensemble de l’optimiseur d’agent
• Préparer votre agent pour l’optimisation
• Optimiser les instructions de l’agent, les compétences, les outils et les modèles
• Démarrage rapide : Optimiser un agent hébergé
• Exécuter des évaluations d’agent avec l’interface CLI azd