Évaluer vos agents IA

L’évaluation est essentielle pour garantir que votre agent respecte les normes de qualité et de sécurité avant le déploiement. En exécutant des évaluations pendant le développement, vous établissez une base de référence pour les performances de votre agent et pouvez définir des seuils d’acceptation, tels qu’un taux de transmission de la conformité des tâches de 85%, avant de le libérer aux utilisateurs.

Dans cet article, vous allez apprendre à exécuter une évaluation ciblée par agent sur un agent Foundry ou un agent hébergé à l’aide d’évaluateurs intégrés pour la qualité, la sécurité et le comportement de l’agent. Plus précisément, vous :

• Configurez le client du Kit de développement logiciel (SDK) pour l’évaluation.
• Choisissez des évaluateurs pour la qualité, la sécurité et le comportement d’agent.
• Créez un jeu de données de test et exécutez une évaluation.
• Interpréter les résultats et les intégrer à votre flux de travail.

Conditions préalables

• Python 3.8 ou version ultérieure.
• Projet Foundry avec un agent ou un agent hébergé.
• Déploiement OpenAI Azure avec un modèle GPT qui prend en charge l’achèvement des conversations (par exemple, gpt-4o ou gpt-4o-mini).
• rôle d'utilisateur Azure IA sur le projet Foundry.

Configurer le client

Installez le Kit de développement logiciel (SDK) Foundry et configurez l’authentification :

pip install "azure-ai-projects>=2.0.0"

Créez le client de projet. Les exemples de code suivants supposent que vous les exécutez dans ce contexte :

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]
model_deployment = os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]

credential = DefaultAzureCredential()
project_client = AIProjectClient(endpoint=endpoint, credential=credential)
client = project_client.get_openai_client()

Choisir des évaluateurs

Les évaluateurs sont des fonctions qui évaluent les réponses de votre agent. Certains évaluateurs utilisent des modèles IA en tant que juges, tandis que d’autres utilisent des règles ou des algorithmes. Pour l’évaluation de l’agent, tenez compte de cet ensemble :

Pour plus d’évaluateurs intégrés, consultez :

• Évaluateurs d’agent : évaluez la façon dont les agents gèrent efficacement les tâches, les outils et l’intention de l’utilisateur.
• Évaluateurs de qualité : mesure la qualité globale des réponses générées.
• Évaluateurs de similarité de texte : comparez le texte généré par rapport aux réponses de référence à l’aide de métriques NLP.
• Évaluateurs de sécurité : identifiez les risques potentiels liés au contenu et à la sécurité dans la sortie générée.

Pour créer vos propres évaluateurs, consultez évaluateurs personnalisés.

Créer un jeu de données de test

Créez un fichier JSONL avec des requêtes de test pour votre agent. Chaque ligne contient un objet JSON avec un query champ :

{"query": "What's the weather in Seattle?"}
{"query": "Book a flight to Paris"}
{"query": "Tell me a joke"}

Chargez ce fichier en tant que jeu de données dans votre projet :

dataset = project_client.datasets.upload_file(
    name="agent-test-queries",
    version="1",
    file_path="./test-queries.jsonl",
)

Exécuter une évaluation

Lorsque vous exécutez une évaluation, le service envoie chaque requête de test à votre agent, capture la réponse et applique vos évaluateurs sélectionnés pour noter les résultats.

Tout d’abord, configurez vos évaluateurs. Chaque évaluateur a besoin d’un mappage de données qui lui indique où trouver des entrées :

• {{item.X}} référence les champs de vos données de test, comme query.
• {{sample.output_items}} fait référence à la réponse complète de l’agent, y compris les appels d’outils.
• {{sample.output_text}} référence uniquement le texte du message de réponse.

Les évaluateurs assistés par l'IA, comme Task Adherence et Coherence, nécessitent un nom de déploiement de modèle dans initialization_parameters. La valeur doit correspondre à un nom de déploiement GPT dans votre projet — c'est le modèle de référence utilisé pour évaluer les réponses. Certains évaluateurs peuvent nécessiter des champs supplémentaires, tels que ground_truth des définitions d’outils. Pour plus d’informations, consultez la documentation de l’évaluateur.

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "Task Adherence",
        "evaluator_name": "builtin.task_adherence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_items}}",
        },
        "initialization_parameters": {"deployment_name": model_deployment},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "Coherence",
        "evaluator_name": "builtin.coherence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
        "initialization_parameters": {"deployment_name": model_deployment},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "Violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
]

Ensuite, créez l’évaluation. Une évaluation définit le schéma de données de test et les critères de test. Il sert de conteneur pour plusieurs exécutions de programme. Toutes les exécutions sous la même évaluation sont conformes au même schéma et produisent le même ensemble de métriques. Cette cohérence est importante pour comparer les résultats entre les exécutions.

data_source_config = {
    "type": "custom",
    "item_schema": {
        "type": "object",
        "properties": {
            "query": {"type": "string"},
        },
        "required": ["query"],
    },
    "include_sample_schema": True,
}

evaluation = client.evals.create(
    name="Agent Quality Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

Enfin, créez une exécution qui envoie vos requêtes de test à l’agent et applique les évaluateurs :

eval_run = client.evals.runs.create(
    eval_id=evaluation.id,
    name="Agent Evaluation Run",
    data_source={
        "type": "azure_ai_target_completions",
        "source": {
            "type": "file_id",
            "id": dataset.id,
        },
        "input_messages": {
            "type": "template",
            "template": [{"type": "message", "role": "user", "content": {"type": "input_text", "text": "{{item.query}}"}}],
        },
        "target": {
            "type": "azure_ai_agent",
            "name": "my-agent",  # Replace with your agent name
            "version": "1",  # Optional; omit to use latest version
        },
    },
)

print(f"Evaluation run started: {eval_run.id}")

Interpréter les résultats

Les évaluations se terminent généralement en quelques minutes, en fonction du nombre de requêtes. Sondez l'achèvement et récupérez l'URL du rapport pour afficher les résultats dans le portail Microsoft Foundry sous l'onglet Évaluations :

import time

# Wait for completion
while True:
    run = client.evals.runs.retrieve(run_id=eval_run.id, eval_id=evaluation.id)
    if run.status in ["completed", "failed"]:
        break
    time.sleep(5)

print(f"Status: {run.status}")
print(f"Report URL: {run.report_url}")

Résultats agrégés

Au niveau de l’exécution, vous pouvez voir les données agrégées, notamment les nombres de réussites et d’échecs, l’utilisation des jetons par modèle et les résultats par évaluateur :

{
    "result_counts": {
        "total": 3,
        "passed": 1,
        "failed": 2,
        "errored": 0
    },
    "per_model_usage": [
        {
            "model_name": "gpt-4o-mini-2024-07-18",
            "invocation_count": 6,
            "total_tokens": 9285,
            "prompt_tokens": 8326,
            "completion_tokens": 959
        },
        ...
    ],
    "per_testing_criteria_results": [
        {
            "testing_criteria": "Task Adherence",
            "passed": 1,
            "failed": 2
        },
        ... // remaining testing criteria
    ]
}

Sortie au niveau de la ligne

Chaque exécution d’évaluation retourne des éléments de sortie par ligne dans votre jeu de données de test, fournissant une visibilité détaillée des performances de votre agent. Les éléments de sortie incluent la requête d’origine, la réponse de l’agent, les résultats de l’évaluateur individuel avec les scores et le raisonnement, et l’utilisation des jetons :

{
    "object": "eval.run.output_item",
    "id": "1",
    "run_id": "evalrun_abc123",
    "eval_id": "eval_xyz789",
    "status": "completed",
    "datasource_item": {
        "query": "What's the weather in Seattle?",
        "response_id": "resp_abc123",
        "agent_name": "my-agent",
        "agent_version": "10",
        "sample.output_text": "I'd be happy to help with the weather! However, I need to check the current conditions. Let me look that up for you.",
        "sample.output_items": [
            ... // agent response messages with tool calls
        ]
    },
    "results": [
        {
            "type": "azure_ai_evaluator",
            "name": "Task Adherence",
            "metric": "task_adherence",
            "label": "pass",
            "reason": "Agent followed system instructions correctly",
            "threshold": 3,
            "passed": true,
            "sample":
            {
               ... // evaluator input/output and token usage
            }
        },
        ... // remaining evaluation results
    ]
}

Intégrer à votre flux de travail

• Pipeline CI/CD : utilisez l’évaluation comme porte de qualité dans votre pipeline de déploiement. Pour obtenir une intégration détaillée, consultez Exécutez les évaluations avec GitHub Actions.
• Surveillance de la production : surveillez votre agent en production à l’aide de l’évaluation continue. Pour obtenir des instructions de configuration, consultez Configurer l’évaluation continue.

Optimiser et comparer les versions

Utilisez l’évaluation pour itérer et améliorer votre agent :

1. Exécutez l’évaluation pour identifier les zones faibles. Utilisez l’analyse du cluster pour rechercher des modèles et des erreurs.
2. Ajustez les instructions ou les outils de l’agent en fonction des résultats.
3. Réévaluez et comparez les exécutions pour mesurer l’amélioration.
4. Répétez jusqu’à ce que les seuils de qualité soient atteints.

Contenu connexe

• exemples d’évaluation du SDK Python
• Exécuter le red teaming d’IA
• Tableau de bord de surveillance de l’agent
• Informations de référence sur les évaluateurs d’agents
• Informations de référence sur l’API REST
• Configurer le suivi dans Microsoft Foundry