Exécuter des évaluations dans le cloud à l’aide du Kit de développement logiciel (SDK) Microsoft Foundry

Important

Les éléments marqués (préversion) dans cet article sont actuellement en préversion publique. Cet aperçu est fourni sans contrat de niveau de service, et nous ne recommandons pas cet aperçu pour les charges de travail de production. Certaines fonctionnalités peuvent ne pas être prises en charge ou avoir des fonctionnalités contraintes. Pour plus d’informations, consultez Conditions supplémentaires d'utilisation pour les versions préliminaires de Microsoft Azure.

Dans cet article, vous allez apprendre à exécuter des évaluations dans le cloud (préversion) pour les tests de prédéploiement sur un jeu de données de test.

Utilisez des évaluations cloud pour la plupart des scénarios, en particulier lors de tests à grande échelle, en intégrant des évaluations dans des pipelines d’intégration continue et de livraison continue (CI/CD) ou en effectuant des tests de prédéploiement. L’exécution d’évaluations dans le cloud élimine la nécessité de gérer l’infrastructure de calcul locale et prend en charge les workflows de test automatisés à grande échelle. Vous pouvez également planifier des évaluations à exécuter périodiquement, ou configurer l’évaluation continue pour évaluer automatiquement les réponses de l’agent échantillonné en production.

Les résultats de l’évaluation cloud sont stockés dans votre projet Foundry. Vous pouvez passer en revue les résultats dans le portail, les récupérer via le Kit de développement logiciel (SDK) ou les router vers Application Insights en cas de connexion. L’évaluation cloud prend en charge tous les évaluateurs Microsoft organisés et vos propres évaluateurs personnalisés. Les évaluateurs sont gérés dans le catalogue d’évaluateurs avec le même contrôle d’accès en fonction du rôle.

Conseil

Pour obtenir des exemples exécutables complets, consultez les exemples d’évaluation Python sdk sur GitHub.

Fonctionnement de l’évaluation cloud

Pour exécuter une évaluation cloud, vous créez une définition d’évaluation avec votre schéma de données et vos critères de test (évaluateurs), puis créez une exécution d’évaluation. Le processus d'exécution applique chaque évaluateur à vos données et retourne les résultats notés que vous pouvez consulter pour vérifier l'achèvement.

L’évaluation cloud prend en charge les scénarios suivants :

Scénario Quand utiliser Type de source de données Cible
Évaluation du jeu de données Évaluez les réponses pré-calculées dans un fichier JSONL. jsonl —
Évaluation du jeu de données CSV Évaluez les réponses pré-calculées dans un fichier CSV. csv —
Évaluation cible du modèle Fournissez des requêtes et générez des réponses à partir d’un modèle au moment de l’exécution pour l’évaluation. azure_ai_target_completions azure_ai_model
Évaluation de la cible de l’agent Fournissez des requêtes et générez des réponses à partir d’un agent Foundry (invite ou hébergé) au moment de l’exécution pour l’évaluation. azure_ai_target_completions azure_ai_agent
Évaluation de la réponse de l’agent Récupérez et évaluez les réponses de l’agent Foundry par ID de réponse. azure_ai_responses —
Évaluation du tracé Évaluez les interactions de l’agent déjà capturées dans Application Insights par ID de trace. Utilisez cette approche pour les agents autres que Foundry (LangChain et frameworks personnalisés qui utilisent la journalisation basée sur OpenTelemetry). azure_ai_traces —
Évaluation des données synthétiques (préversion) Générez des requêtes de test synthétiques, envoyez-les à un modèle ou à un agent et évaluez les réponses. azure_ai_synthetic_data_gen_preview azure_ai_model Ou azure_ai_agent
Évaluation de l’équipe rouge Exécutez des tests contradictoires automatisés sur un modèle ou un agent. azure_ai_red_team azure_ai_model Ou azure_ai_agent

La plupart des scénarios nécessitent des données d’entrée. Vous pouvez fournir des données de deux façons :

Type de source Description
file_id Référencez un jeu de données uploadé par ID.
file_content Fournissez les données directement dans la requête.

Chaque évaluation nécessite un data_source_config qui indique au service les champs à attendre dans vos données :

  • custom — Vous définissez un item_schema champ avec vos noms et types de champs. Définissez include_sample_schema à true lorsque vous utilisez une cible afin que les évaluateurs puissent référencer les réponses générées.
  • azure_ai_source — Le schéma est déduit du service. Définissez "scenario" sur "responses" pour l’évaluation de la réponse de l’agent, sur "traces" pour l’évaluation de trace, sur "synthetic_data_gen_preview" pour l’évaluation des données synthétiques (préversion) ou sur "red_team" pour l’équipe rouge.

Chaque scénario nécessite des évaluateurs qui définissent vos critères de test. Pour obtenir des conseils sur la sélection d’évaluateurs, consultez les évaluateurs intégrés.

Conditions préalables

  • Un projet Foundry.
  • Déploiement OpenAI Azure avec un modèle GPT qui prend en charge l’achèvement des conversations (par exemple, gpt-5-mini).
  • Rôle d'utilisateur Azure IA sur le projet Foundry.
  • Si vous le souhaitez, vous pouvez utiliser votre propre compte de stockage pour exécuter des évaluations.

Note

Certaines fonctionnalités d’évaluation ont des restrictions régionales. Pour plus d’informations, consultez les régions prises en charge .

Commencez

Installez le Kit de développement logiciel (SDK) et configurez votre client :

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

import os
from azure.identity import DefaultAzureCredential 
from azure.ai.projects import AIProjectClient 
from openai.types.eval_create_params import DataSourceConfigCustom
from openai.types.evals.create_eval_jsonl_run_data_source_param import (
    CreateEvalJSONLRunDataSourceParam,
    SourceFileContent,
    SourceFileContentContent,
    SourceFileID,
)

# Azure AI Project endpoint
# Example: https://<account_name>.services.ai.azure.com/api/projects/<project_name>
endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]

# Model deployment name (for AI-assisted evaluators)
# Example: gpt-5-mini
model_deployment_name = os.environ.get("AZURE_AI_MODEL_DEPLOYMENT_NAME", "")

# Dataset details (optional, for reusing existing datasets)
dataset_name = os.environ.get("DATASET_NAME", "")
dataset_version = os.environ.get("DATASET_VERSION", "1")

# Create the project client
project_client = AIProjectClient( 
    endpoint=endpoint, 
    credential=DefaultAzureCredential(), 
)

# Get the OpenAI client for evaluation API
client = project_client.get_openai_client()

Préparer les données d’entrée

La plupart des scénarios d’évaluation nécessitent des données d’entrée. Vous pouvez fournir des données de deux façons :

Chargez un fichier JSONL ou CSV pour créer un jeu de données avec version dans votre projet Foundry. Les jeux de données prennent en charge le contrôle de version et la réutilisation entre plusieurs exécutions d’évaluation. Utilisez cette approche pour les tests de production et les flux de travail CI/CD.

Préparez un fichier JSONL avec un objet JSON par ligne contenant les champs dont vos évaluateurs ont besoin :

{"query": "What is machine learning?", "response": "Machine learning is a subset of AI.", "ground_truth": "Machine learning is a type of AI that learns from data."}
{"query": "Explain neural networks.", "response": "Neural networks are computing systems inspired by biological neural networks.", "ground_truth": "Neural networks are a set of algorithms modeled after the human brain."}

Vous pouvez également préparer un fichier CSV avec des en-têtes de colonne correspondant à vos champs évaluateurs :

query,response,ground_truth
What is machine learning?,Machine learning is a subset of AI.,Machine learning is a type of AI that learns from data.
Explain neural networks.,Neural networks are computing systems inspired by biological neural networks.,Neural networks are a set of algorithms modeled after the human brain.

# Upload a local JSONL file. Skip this step if you already have a dataset registered.
data_id = project_client.datasets.upload_file(
    name=dataset_name,
    version=dataset_version,
    file_path="./evaluate_test_data.jsonl",
).id

Fournir des données en ligne

Pour une expérimentation rapide avec de petits jeux de tests, fournissez des données directement dans la demande d’évaluation à l’aide de file_content.

source = SourceFileContent(
    type="file_content",
    content=[
        SourceFileContentContent(
            item={
                "query": "How can I safely de-escalate a tense situation?",
                "ground_truth": "Encourage calm communication, seek help if needed, and avoid harm.",
            }
        ),
        SourceFileContentContent(
            item={
                "query": "What is the largest city in France?",
                "ground_truth": "Paris",
            }
        ),
    ],
)

Transmettez source comme champ "source" dans votre configuration de source de données lors de la création d'une exécution. Les sections de scénario suivantes utilisent file_id par défaut.

Évaluation du jeu de données

Évaluez les réponses pré-calculées dans un fichier JSONL à l’aide du jsonl type de source de données. Ce scénario est utile lorsque vous avez déjà des sorties de modèle et que vous souhaitez évaluer leur qualité.

Conseil

Avant de commencer, effectuez la prise en main et préparez les données d’entrée.

Définir le schéma de données et les évaluateurs

Spécifiez le schéma qui correspond à vos champs JSONL, puis sélectionnez les évaluateurs (critères de test) à exécuter. Utilisez les data_mapping paramètres pour connecter des champs de vos données d’entrée aux paramètres de l'évaluateur avec la syntaxe {{item.field}}. Incluez toujours data_mapping avec les champs d'entrée requis pour chaque évaluateur. Vos noms de champs doivent correspondre à ceux de votre fichier JSONL — par exemple, si vos données utilisent "question" au lieu de "query", utilisez "{{item.question}}" dans le mappage. Pour connaître les paramètres requis par évaluateur, consultez les évaluateurs intégrés.

data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
            "response": {"type": "string"},
            "ground_truth": {"type": "string"},
        },
        "required": ["query", "response", "ground_truth"],
    },
)

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "f1",
        "evaluator_name": "builtin.f1_score",
        "data_mapping": {
            "response": "{{item.response}}",
            "ground_truth": "{{item.ground_truth}}",
        },
    },
]

Créer une évaluation et exécuter

Créez l’évaluation, puis démarrez une exécution sur votre jeu de données chargé. L’exécution exécute chaque évaluateur sur chaque ligne du jeu de données.

# Create the evaluation
eval_object = client.evals.create(
    name="dataset-evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

# Create a run using the uploaded dataset
eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="dataset-run",
    data_source=CreateEvalJSONLRunDataSourceParam(
        type="jsonl",
        source=SourceFileID(
            type="file_id",
            id=data_id,
        ),
    ),
)

Pour obtenir un exemple exécutable complet, consultez sample_evaluations_builtin_with_dataset_id.py sur GitHub. Pour vérifier l'achèvement et interpréter les résultats, consultez Voir les résultats.

Évaluation du jeu de données CSV

Évaluez les réponses pré-calculées dans un fichier CSV à l’aide du type de csv source de données. Ce scénario fonctionne de la même façon que l’évaluation du jeu de données , mais accepte les fichiers CSV au lieu de JSONL. Utilisez CSV lorsque vos données sont déjà au format de feuille de calcul ou de tableau.

Conseil

Avant de commencer, effectuez la prise en main et préparez les données d’entrée.

Préparer un fichier CSV

Créez un fichier CSV avec des en-têtes de colonne correspondant aux champs dont vos évaluateurs ont besoin. Chaque ligne représente un cas de test :

query,response,context,ground_truth
What is cloud computing?,Cloud computing delivers computing services over the internet.,Cloud computing is a technology for on-demand resource delivery.,Cloud computing is the delivery of computing services including servers storage and databases over the internet.
What is machine learning?,Machine learning is a subset of AI that learns from data.,Machine learning is a branch of artificial intelligence.,Machine learning is a type of AI that enables computers to learn from data without being explicitly programmed.
Explain neural networks.,Neural networks are computing systems inspired by biological neural networks.,Neural networks are used in deep learning.,Neural networks are a set of algorithms modeled after the human brain designed to recognize patterns.

Charger et exécuter

Chargez le fichier CSV en tant que jeu de données, puis créez une évaluation à l’aide du csv type de source de données. La définition de schéma et la configuration de l’évaluateur sont les mêmes que pour les évaluations JSONL — la seule différence réside dans le "type": "csv" de la source de données.

# Upload the CSV file
data_id = project_client.datasets.upload_file(
    name="eval-csv-data",
    version="1",
    file_path="./evaluation_data.csv",
).id

# Define the schema matching your CSV columns
data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
            "response": {"type": "string"},
            "context": {"type": "string"},
            "ground_truth": {"type": "string"},
        },
        "required": [],
    },
    include_sample_schema=True,
)

# Define evaluators with data mappings to CSV columns
testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        "initialization_parameters": {"deployment_name": model_deployment_name},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        "initialization_parameters": {"deployment_name": model_deployment_name},
    },
    {
        "type": "azure_ai_evaluator",
        "name": "f1",
        "evaluator_name": "builtin.f1_score",
    },
]

# Create the evaluation
eval_object = client.evals.create(
    name="CSV evaluation with built-in evaluators",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

# Create a run using the CSV data source type
eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="csv-evaluation-run",
    data_source={
        "type": "csv",
        "source": {
            "type": "file_id",
            "id": data_id,
        },
    },
)

Pour vérifier l'achèvement et interpréter les résultats, consultez Voir les résultats.

Évaluation cible du modèle

Envoyez des requêtes à un modèle déployé au moment de l’exécution et évaluez les réponses à l’aide du azure_ai_target_completions type de source de données avec une azure_ai_model cible. Vos données d’entrée contiennent des requêtes ; le modèle génère des réponses qui sont ensuite évaluées.

Conseil

Avant de commencer, effectuez la prise en main et préparez les données d’entrée.

Définir le modèle de message et la cible

Le input_messages modèle contrôle la façon dont les requêtes sont envoyées au modèle. Permet {{item.query}} de référencer des champs à partir de vos données d’entrée. Spécifiez le modèle à évaluer et les paramètres d'échantillonnage facultatifs :

input_messages = {
    "type": "template",
    "template": [
        {
            "type": "message",
            "role": "user",
            "content": {
                "type": "input_text",
                "text": "{{item.query}}"
            }
        }
    ]
}

target = {
    "type": "azure_ai_model",
    "model": "gpt-5-mini",
    "sampling_params": {
        "top_p": 1.0,
        "max_completion_tokens": 2048,
    },
}

Configurer des évaluateurs et des mappages de données

Lorsque le modèle génère des réponses au moment de l’exécution, utilisez-le {{sample.output_text}}data_mapping pour référencer la sortie du modèle. Permet {{item.field}} de référencer des champs à partir de vos données d’entrée.

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

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
]

Créer une évaluation et exécuter

eval_object = client.evals.create(
    name="Model Target Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_id",
        "id": data_id,
    },
    "input_messages": input_messages,
    "target": target,
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="model-target-evaluation",
    data_source=data_source,
)

Pour obtenir un exemple d’exécution complet, consultez sample_model_evaluation.py sur GitHub. Pour vérifier l'achèvement et interpréter les résultats, consultez Voir les résultats.

Conseil

Pour ajouter une autre exécution d’évaluation, vous pouvez utiliser le même code.

Évaluation de l'agent cible

Envoyez des requêtes à un agent Foundry au moment de l’exécution et évaluez les réponses à l’aide du azure_ai_target_completions type de source de données avec une azure_ai_agent cible. Ce scénario fonctionne à la fois pour les agents d’invite et les agents hébergés.

Conseil

Avant de commencer, effectuez la prise en main et préparez les données d’entrée.

Conseil

Les agents hébergés qui utilisent le protocole de réponses fonctionnent avec les mêmes exemples de code présentés ici. Pour les agents hébergés qui utilisent le protocole d’appel, le input_messages format est différent. Pour plus d’informations, consultez le protocole d’appel de l’agent hébergé .

Définir le modèle de message et la cible

Le input_messages modèle contrôle la façon dont les requêtes sont envoyées à l’agent. Permet {{item.query}} de référencer des champs à partir de vos données d’entrée. Spécifiez l’agent à évaluer par nom :

input_messages = {
    "type": "template",
    "template": [
        {
            "type": "message",
            "role": "developer",
            "content": {
                "type": "input_text",
                "text": "You are a helpful assistant. Answer clearly and safely."
            }
        },
        {
            "type": "message",
            "role": "user",
            "content": {
                "type": "input_text",
                "text": "{{item.query}}"
            }
        }
    ]
}

target = {
    "type": "azure_ai_agent",
    "name": "my-agent",
    "version": "1"  # Optional. Uses latest version if omitted.
}

Configurer des évaluateurs et des mappages de données

Lorsque l’agent génère des réponses au moment de l’exécution, utilisez des variables {{sample.*}} dans data_mapping pour référencer la sortie de l’agent :

Variable Description Utiliser pour
{{sample.output_text}} Réponse de texte brut de l’agent. Évaluateurs qui attendent une réponse de chaîne (par exemple, coherence, violence).
{{sample.output_items}} Sortie JSON structurée de l’agent, y compris les appels d’outils. Évaluateurs qui ont besoin d’un contexte d’interaction complet (par exemple, task_adherence).
{{item.field}} Champ de vos données d’entrée. Champs d’entrée tels que query ou ground_truth.

Conseil

Le query champ peut contenir un JSON structuré, y compris les messages système et l’historique des conversations. Certains évaluateurs d’agents, tels que task_adherence, utilisent ce contexte pour une évaluation plus précise. Pour plus d’informations sur la mise en forme des requêtes, consultez les évaluateurs d’agent.

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

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

Créer une évaluation et exécuter

eval_object = client.evals.create(
    name="Agent Target Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_id",
        "id": data_id,
    },
    "input_messages": input_messages,
    "target": target,
}

agent_eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-target-evaluation",
    data_source=data_source,
)

Pour obtenir un exemple exécutable complet, consultez sample_agent_evaluation.py sur GitHub. Pour vérifier l'achèvement et interpréter les résultats, consultez Voir les résultats.

Protocole d’appel d’agent hébergé

Les agents hébergés qui utilisent le protocole d’appel prennent en charge le même azure_ai_agent type cible, mais utilisent un format de forme input_messageslibre. Au lieu du format de modèle structuré, fournissez un objet JSON qui est mappé directement au corps de la requête de l’agent /invocations . Utilisez {{item.*}} des espaces réservés pour remplacer les champs de vos données d’entrée.

Si un agent hébergé prend en charge les réponses et les protocoles d’appel, le service utilise par défaut le protocole d’appel.

Définir le format et la cible du message

input_messages = {"message": "{{item.query}}"}

target = {
    "type": "azure_ai_agent",
    "name": "my-hosted-agent",  # Replace with your hosted agent name
    "version": "1",
}

Créer une évaluation et exécuter

eval_object = client.evals.create(
    name="Hosted Agent Invocations Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_id",
        "id": data_id,
    },
    "input_messages": input_messages,
    "target": target,
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="hosted-agent-invocations-evaluation",
    data_source=data_source,
)

La configuration de l’évaluateur et les mappages de données sont les mêmes que pour l’évaluation rapide de l’agent. Utiliser {{sample.output_text}} pour la réponse de texte de l’agent et {{sample.output_items}} pour la sortie structurée complète, y compris les appels d’outils.

Évaluation de la réponse de l’agent

Récupérez et évaluez les réponses de l’agent Foundry par ID de réponse à l’aide du azure_ai_responses type de source de données. Utilisez ce scénario pour évaluer des interactions d’agent spécifiques après qu’ils se produisent.

Conseil

Avant de commencer, complétez la configuration initiale.

Un ID de réponse est un identificateur unique retourné chaque fois qu’un agent Foundry génère une réponse. Vous pouvez collecter des ID de réponse à partir d’interactions de l’agent à l’aide de l’API Réponses ou des journaux de trace de votre application. Fournissez les ID inline en tant que contenu de fichier ou chargez-les en tant que jeu de données (consultez Préparer les données d’entrée).

Collecter les ID de réponse

Chaque appel à l’API Réponses retourne un objet de réponse avec un champ unique id . Collectez ces ID à partir des interactions de votre application ou générez-les directement :

# Generate response IDs by calling a model through the Responses API
response = client.responses.create(
    model=model_deployment_name,
    input="What is machine learning?",
)
print(response.id)  # Example: resp_abc123

Vous pouvez également collecter des identifiants de réponse à partir d’interactions avec l’agent dans les journaux de traçage ou le pipeline de surveillance de votre application. Chaque ID de réponse identifie de manière unique une réponse stockée que le service d’évaluation peut récupérer.

Créer une évaluation et exécuter

data_source_config = {"type": "azure_ai_source", "scenario": "responses"}

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
    },
]

eval_object = client.evals.create(
    name="Agent Response Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_responses",
    "item_generation_params": {
        "type": "response_retrieval",
        "data_mapping": {"response_id": "{{item.resp_id}}"},
        "source": {
            "type": "file_content",
            "content": [
                {"item": {"resp_id": "resp_abc123"}},
                {"item": {"resp_id": "resp_def456"}},
            ]
        },
    },
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-response-evaluation",
    data_source=data_source,
)

Pour obtenir un exemple exécutable complet, consultez sample_agent_response_evaluation.py sur GitHub. Pour vérifier l'achèvement et interpréter les résultats, consultez Voir les résultats.

Évaluation de trace

Évaluez les interactions de l’agent qui ont déjà été capturées dans Application Insights. Utilisez le type de azure_ai_traces source de données. Ce scénario est utile pour l’évaluation post-déploiement du trafic de production réel : vous sélectionnez des traces à partir de votre pipeline de supervision et exécutez des évaluateurs sur ces derniers sans relire les demandes.

Important

L’évaluation de trace est l’approche recommandée pour l’évaluation des agents non construits avec le service Microsoft Foundry Agent, y compris LangChain et les cadres personnalisés. Tant que votre agent émet des étendues OpenTelemetry en suivant les conventions sémantiques GenAI vers Application Insights, l’évaluation des traces peut analyser ses interactions à l’aide des mêmes outils d'évaluation disponibles pour les agents Foundry.

L’évaluation de trace prend en charge deux modes :

  • Par ID de trace : évaluez des interactions d’agent spécifiques en fournissant leurs operation_Id valeurs à partir d’Application Insights.
  • Par filtre d’agent : détectez et évaluez automatiquement les traces récentes pour un agent donné, sans collecter manuellement les ID de trace.

Conseil

Avant de commencer, complétez la configuration initiale. Ce scénario nécessite également une ressource Application Insights connectée à votre projet Foundry.

Exigences en matière de données de trace

L’évaluation de trace nécessite que votre agent génère des portées en suivant les conventions sémantiques OpenTelemetry pour l’IA générative. Plus précisément, le service d’évaluation lit des tranchesinvoke_agent à partir d’Application Insights et extrait les données de conversation de leurs attributs.

Les attributs d’étendue suivants sont utilisés :

Attribut Obligatoire Description
gen_ai.operation.name Oui Doit être égal à "invoke_agent". Le service ignore toutes les autres tranches.
gen_ai.agent.id Pour le mode de filtrage de l’agent Identificateur d’agent unique (format : agent-name:version).
gen_ai.agent.name Pour le mode filtre de l’agent Nom d'agent lisible par un humain.
gen_ai.input.messages Pour les évaluateurs, les entrées de requête Tableau JSON de messages d’entrée suivant le format de message de conventions sémantiques GenAI. Messages avec rôle user ou system correspondent à query; messages avec rôle assistant ou tool correspondent à response.
gen_ai.output.messages Entrées de requête pour les évaluateurs Tableau JSON de messages de sortie générés par un modèle. Tous les messages de sortie correspondent à response. Si la sortie contient également le type : tool_call ou le type : tool_result, cela est mappé à tool_calls
gen_ai.tool.definitions Optionnel Tableau JSON de schémas d’outils disponibles pour l’agent. S’il est absent, le service tente de déduire les définitions d’outils à partir des messages d’appel d’outil, mais les schémas déduits peuvent être incomplets.
gen_ai.conversation.id Optionnel Identificateur de conversation, transmis aux résultats d’évaluation pour la corrélation.

Note

Si gen_ai.input.messages et gen_ai.output.messages sont vides ou manquants, les évaluateurs de qualité (cohérence, fluidité, pertinence, résolution d’intention) retourneront score=None. Les évaluateurs de sécurité (violence, auto-préjudice, haine/injustice) peuvent toujours produire des scores avec des données partielles, mais ils peuvent ne pas produire de résultats significatifs.

Pour les agents Python développés avec le SDK Azure AI Agent Server, ajoutez l'extension [tracing] pour activer l’émission automatique des spans :

pip install "azure-ai-agentserver-core[tracing]"

Conditions préalables pour l'analyse de la traçabilité

En plus des conditions préalables générales, l’évaluation de traçage nécessite :

  • Ressource Application Insights connectée à votre projet Foundry. Consultez Configurer le traçage dans Microsoft Foundry.
  • L'identité managée du projet doit avoir le rôle Lecteur Log Analytics sur la ressource Application Insights ainsi que sur son espace de travail Log Analytics associé.
  • Package azure-monitor-query Python (nécessaire uniquement si vous collectez manuellement les ID de trace).
pip install "azure-ai-projects>=2.0.0" azure-monitor-query

Définissez ces variables d’environnement :

  • APPINSIGHTS_RESOURCE_ID — ID de ressource Application Insights (par exemple, /subscriptions/<subscription_id>/resourceGroups/<rg_name>/providers/Microsoft.Insights/components/<resource_name>).
  • AGENT_ID — Identificateur de l’agent émis par l’intégration de suivi (gen_ai.agent.id attribut), utilisé pour filtrer les traces. Format : agent-name:version.
  • TRACE_LOOKBACK_HOURS — (Facultatif) Nombre d’heures à examiner lors de l’interrogation des traces. Par défaut, 1.

Option A : Évaluer par filtre d’agent

L’approche la plus simple : laissez le service détecter et évaluer automatiquement les traces récentes pour un agent spécifique. Aucune collection manuelle d’ID de trace n’est nécessaire.

import os

agent_id = os.environ["AGENT_ID"]  # e.g., "my-weather-agent:1"
trace_lookback_hours = int(os.environ.get("TRACE_LOOKBACK_HOURS", "1"))

# Create the evaluation
data_source_config = {
    "type": "azure_ai_source",
    "scenario": "traces",
}

eval_object = client.evals.create(
    name="Agent Trace Evaluation (by agent)",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,  # See "Set up evaluators" below
)

# Create a run — the service queries App Insights for matching traces
data_source = {
    "type": "azure_ai_traces",
    "agent_id": agent_id,
    "max_traces": 50,           # Maximum number of traces to evaluate
    "lookback_hours": trace_lookback_hours,
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-trace-eval-run",
    data_source=data_source,
)

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

Le service filtre invoke_agent les étendues selon l'attribut gen_ai.agent.id, échantillonne jusqu'à max_traces ID de traces uniques et évalue toutes les étendues de ces traces.

Option B : Évaluer par ID de trace

Pour plus de contrôle, collectez des ID de trace spécifiques à partir d’Application Insights et évaluez-les. Cela est utile lorsque vous souhaitez évaluer un ensemble organisé d’interactions (par exemple, des traces marquées par des alertes ou échantillonnés pour l’examen de la qualité).

Collecter des ID de trace à partir d’Application Insights

Interrogez Application Insights pour obtenir operation_Id des valeurs à partir des traces de votre agent. Chacune operation_Id représente une interaction complète de l’agent :

import os
from datetime import datetime, timedelta, timezone
from azure.identity import DefaultAzureCredential
from azure.monitor.query import LogsQueryClient, LogsQueryStatus

appinsights_resource_id = os.environ["APPINSIGHTS_RESOURCE_ID"]
agent_id = os.environ["AGENT_ID"]
trace_query_hours = int(os.environ.get("TRACE_LOOKBACK_HOURS", "1"))

end_time = datetime.now(timezone.utc)
start_time = end_time - timedelta(hours=trace_query_hours)

query = f"""dependencies
| where timestamp between (datetime({start_time.isoformat()}) .. datetime({end_time.isoformat()}))
| extend agent_id = tostring(customDimensions["gen_ai.agent.id"])
| where agent_id == "{agent_id}"
| distinct operation_Id"""

credential = DefaultAzureCredential()
logs_client = LogsQueryClient(credential)
response = logs_client.query_resource(
    appinsights_resource_id,
    query=query,
    timespan=None,  # Time range is specified in the query itself
)

trace_ids = []
if response.status == LogsQueryStatus.SUCCESS:
    for table in response.tables:
        for row in table.rows:
            trace_ids.append(row[0])

print(f"Found {len(trace_ids)} trace IDs")

Créer une évaluation et exécuter avec des ID de trace

# Create the evaluation
data_source_config = {
    "type": "azure_ai_source",
    "scenario": "traces",
}

eval_object = client.evals.create(
    name="Agent Trace Evaluation (by trace IDs)",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,  # See "Set up evaluators" below
)

# Create a run using the collected trace IDs
data_source = {
    "type": "azure_ai_traces",
    "trace_ids": trace_ids,
    "lookback_hours": trace_query_hours,
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-trace-eval-run",
    metadata={
        "agent_id": agent_id,
        "start_time": start_time.isoformat(),
        "end_time": end_time.isoformat(),
    },
    data_source=data_source,
)

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

Configurer des évaluateurs et des mappages de données

Lors de l’évaluation des traces, le service extrait automatiquement les données de conversation à partir des attributs de span d’OpenTelemetry. Utilisez ces noms de champs directement dans data_mapping (sans les item.sample. préfixes utilisés dans d’autres scénarios) :

Variable Attribut source Description
{{item.query}} gen_ai.input.messages (rôles utilisateur/système) Requête de l’utilisateur extraite de la trace.
{{item.response}} gen_ai.input.messages (rôles assistant/outil) + gen_ai.output.messages Réponse de l’agent extraite de la trace.
{{item.tool_definitions}} gen_ai.tool.definitions Schémas d’outil disponibles pour l’agent. Obligatoire uniquement pour les évaluateurs liés aux outils
{{item.tool_calls}} Extrait des messages de l’Assistant dans gen_ai.input.messages / gen_ai.output.messages Appels d’outil effectués par l’agent pendant l’interaction. Utilisé par les évaluateurs d’outils. Obligatoire uniquement pour les évaluateurs liés aux outils 
testing_criteria = [
    # Quality evaluators — require query and response from trace data
    {
        "type": "azure_ai_evaluator",
        "name": "intent_resolution",
        "evaluator_name": "builtin.intent_resolution",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
            "tool_definitions": "{{item.tool_definitions}}",
        },
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
    },
    # Tool evaluators — assess tool usage quality
    {
        "type": "azure_ai_evaluator",
        "name": "tool_call_accuracy",
        "evaluator_name": "builtin.tool_call_accuracy",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
            "tool_calls": "{{item.tool_calls}}",
            "tool_definitions": "{{item.tool_definitions}}",
        },
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
    },
    # Safety evaluators — work even with partial trace data
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        "initialization_parameters": {
            "threshold": 4,
        },
    },
]

Pour obtenir un exemple exécutable complet, consultez sample_evaluations_builtin_with_traces.py sur GitHub. Pour vérifier l'achèvement et interpréter les résultats, consultez Voir les résultats.

Évaluation des données synthétiques (aperçu)

Générez des requêtes de test synthétiques, envoyez-les à un modèle déployé ou à un agent Foundry et évaluez les réponses à l’aide du azure_ai_synthetic_data_gen_preview type de source de données. Utilisez ce scénario lorsque vous n’avez pas de jeu de données de test : le service génère des requêtes en fonction d’une invite que vous fournissez (et/ou à partir des instructions de l’agent), les exécute sur votre cible et évalue les réponses.

Conseil

Avant de commencer, complétez la configuration initiale.

Fonctionnement de l’évaluation des données synthétiques

  1. Le service génère des requêtes synthétiques basées sur votre prompt et sur des fichiers de données initiales facultatifs.
  2. Chaque requête est envoyée à la cible spécifiée (modèle ou agent) pour générer une réponse.
  3. Les évaluateurs notent chaque réponse à l’aide de la requête et de la réponse générées.
  4. Les requêtes générées sont stockées en tant que jeu de données dans votre projet pour réutilisation.

Paramètres

Paramètre Obligatoire Description
samples_count Oui Nombre maximal de requêtes de test synthétique à générer.
model_deployment_name Oui Déploiement de modèle à utiliser pour générer des requêtes synthétiques. Seuls les modèles avec la fonctionnalité d’API Réponses sont pris en charge. Pour plus d’informations sur la disponibilité, consultez la disponibilité de la région de l’API Réponses.
prompt Non Instructions décrivant le type de requêtes à générer. Facultatif lorsque la cible de l’agent a des instructions configurées.
output_dataset_name Non Nom du jeu de données de sortie où les requêtes générées sont stockées. Si aucun nom n'est fourni, le service en génère automatiquement un.
sources Non Fichiers de données de départ (par ID de fichier) pour améliorer la pertinence des requêtes générées. Actuellement, un seul fichier est pris en charge.

Configurer des évaluateurs et des mappages de données

Le générateur de données synthétiques génère des requêtes dans le {{item.query}} champ. L'objectif génère des réponses disponibles dans {{sample.output_text}}. Mappez ces champs à vos évaluateurs :

data_source_config = {"type": "azure_ai_source", "scenario": "synthetic_data_gen_preview"}

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
]

Créer une évaluation et exécuter

Cible du modèle

Générez des requêtes synthétiques et évaluez un modèle :

eval_object = client.evals.create(
    name="Synthetic Data Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_synthetic_data_gen_preview",
    "item_generation_params": {
        "type": "synthetic_data_gen_preview",
        "samples_count": 5,
        "prompt": "Generate customer service questions about returning defective products",
        "model_deployment_name": model_deployment_name,
        "output_dataset_name": "my-synthetic-dataset",
    },
    "target": {
        "type": "azure_ai_model",
        "model": model_deployment_name,
    },
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="synthetic-data-evaluation",
    data_source=data_source,
)

Vous pouvez éventuellement ajouter une invite système pour orienter le comportement du modèle visé. Lorsque vous utilisez input_messages avec la génération de données synthétiques, incluez uniquement system les messages de rôle, le service fournit automatiquement les requêtes générées en tant que messages utilisateur.

data_source = {
    "type": "azure_ai_synthetic_data_gen_preview",
    "item_generation_params": {
        "type": "synthetic_data_gen_preview",
        "samples_count": 5,
        "prompt": "Generate customer service questions about returning defective products",
        "model_deployment_name": model_deployment_name,
    },
    "target": {
        "type": "azure_ai_model",
        "model": model_deployment_name,
    },
    "input_messages": {
        "type": "template",
        "template": [
            {
                "type": "message",
                "role": "system",
                "content": {
                    "type": "input_text",
                    "text": "You are a helpful customer service agent. Be empathetic and solution-oriented."
                }
            }
        ]
    },
}

Cible de l’agent

Générez des requêtes synthétiques et évaluez un agent Foundry :

data_source = {
    "type": "azure_ai_synthetic_data_gen_preview",
    "item_generation_params": {
        "type": "synthetic_data_gen_preview",
        "samples_count": 5,
        "prompt": "Generate questions about returning defective products",
        "model_deployment_name": model_deployment_name,
    },
    "target": {
        "type": "azure_ai_agent",
        "name": agent_name,
        "version": agent_version,
    },
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="synthetic-agent-evaluation",
    data_source=data_source,
)

Pour vérifier l'achèvement et interpréter les résultats, consultez Voir les résultats. La réponse inclut une output_dataset_id propriété qui contient l’ID du jeu de données généré, que vous pouvez utiliser pour récupérer ou réutiliser les données synthétiques.

Obtenir les résultats

Une fois l’exécution d’évaluation terminée, récupérez les résultats évalués et passez-les en revue dans le portail ou par programmation.

Interroger pour obtenir les résultats

Les exécutions d’évaluation sont asynchrones. Sondez l’état d’exécution jusqu’à son achèvement, puis récupérez les résultats.

import time
from pprint import pprint

while True:
    run = client.evals.runs.retrieve(
        run_id=eval_run.id, eval_id=eval_object.id
    )
    if run.status in ("completed", "failed"):
        break
    time.sleep(5)
    print("Waiting for eval run to complete...")

# Retrieve results
output_items = list(
    client.evals.runs.output_items.list(
        run_id=run.id, eval_id=eval_object.id
    )
)
pprint(output_items)
print(f"Report URL: {run.report_url}")

Interpréter les résultats

Pour un exemple de données unique, tous les évaluateurs génèrent le schéma suivant :

  • Étiquette : étiquette binaire « pass » ou « fail », similaire à la sortie d’un test unitaire. Utilisez ce résultat pour faciliter les comparaisons entre les évaluateurs.
  • Score : score de l’échelle naturelle de chaque évaluateur. Certains évaluateurs utilisent une grille affinée, un scoring sur une échelle de 5 points (évaluateurs de qualité) ou une échelle de 7 points (évaluateurs de sécurité du contenu). D’autres, comme les évaluateurs de similarité textuelle, utilisent des scores F1, qui sont flottants entre 0 et 1. Tout « score » non binaire est binarisé pour « passer » ou « échouer » dans le champ « étiquette » en fonction du « seuil ».
  • Seuil : tous les scores non binaires sont binarisés pour « passer » ou « échouer » en fonction d’un seuil par défaut, que l’utilisateur peut remplacer dans l’expérience du Kit de développement logiciel (SDK).
  • Motif : Pour améliorer l’intelligibilité, tous les évaluateurs LLM-juge génèrent également un champ de raisonnement pour expliquer pourquoi un certain score est donné.
  • Détails : (facultatif) Pour certains évaluateurs, tels que tool_call_accuracy, il peut y avoir un champ ou des indicateurs « détails » qui contiennent des informations supplémentaires pour aider les utilisateurs à déboguer leurs applications.

Exemple de sortie (élément unique)

{
  "type": "azure_ai_evaluator",
  "name": "Coherence",
  "metric": "coherence",
  "score": 4.0,
  "label": "pass",
  "reason": "The response is well-structured and logically organized, presenting information in a clear and coherent manner.",
  "threshold": 3,
  "passed": true
}

Exemple de résultat (agrégat)

Pour obtenir des résultats agrégés sur plusieurs exemples de données (un jeu de données), le taux moyen des exemples réussis forme le taux de réussite pour ce jeu de données.

{
  "eval_id": "eval_abc123",
  "run_id": "run_xyz789",
  "status": "completed",
  "result_counts": {
    "passed": 85,
    "failed": 15,
    "total": 100
  },
  "per_testing_criteria_results": [
    {
      "name": "coherence",
      "passed": 92,
      "failed": 8,
      "pass_rate": 0.92
    },
    {
      "name": "relevance", 
      "passed": 78,
      "failed": 22,
      "pass_rate": 0.78
    }
  ]
}

Dépannage

Tâche en cours d'exécution depuis longtemps

Votre travail d’évaluation peut rester dans l’état En cours d’exécution pendant une période prolongée. Cela se produit généralement lorsque le déploiement de modèle OpenAI Azure n'a pas suffisamment de capacité, ce qui entraîne la nouvelle tentative de demandes du service.

Résolution:

  1. Annulez le travail d’évaluation actuel à l’aide de client.evals.runs.cancel(run_id, eval_id=eval_id).
  2. Augmentez la capacité du modèle dans le portail Azure.
  3. Réexécutez l’évaluation.

Erreurs d’authentification

Si vous recevez une erreur 401 Unauthorized ou 403 Forbidden, vérifiez que :

  • Votre DefaultAzureCredential est configuré correctement (exécutez az login si vous utilisez Azure CLI).
  • Votre compte a le rôle Azure AI User sur le projet Foundry.
  • L’URL du point de terminaison de projet est correcte et inclut les noms de compte et de projet.

Erreurs de format de données

Si l’évaluation échoue avec une erreur de schéma ou de mappage de données :

  • Vérifiez que votre fichier JSONL a un objet JSON valide par ligne.
  • Vérifiez que les noms de champs dans data_mapping correspondent exactement aux noms de champs de votre fichier JSONL (sensible à la casse).
  • Vérifiez que item_schema les propriétés correspondent aux champs de votre jeu de données.

Erreurs de limite de débit

Les créations de processus d'évaluation sont limitées au niveau du locataire, de l’abonnement et du projet. Si vous recevez une 429 Too Many Requests réponse :

  • Vérifiez l’en-tête retry-after dans la réponse pour connaître le temps d’attente recommandé.
  • Passez en revue le corps de la réponse pour connaître les détails de la limite de débit.
  • Utilisez le backoff exponentiel pour réessayer les requêtes échouées.

Si un travail d’évaluation échoue avec une 429 erreur pendant l’exécution :

  • Réduisez la taille de votre jeu de données d’évaluation ou fractionnez-le en lots plus petits.
  • Augmentez le quota de tokens par minute (TPM) pour le déploiement de votre modèle dans le portail Azure.

Erreurs de l’outil évaluateur d’agent

Si un évaluateur d’agent retourne une erreur pour des outils non supportés :

  • Vérifiez les outils pris en charge pour les évaluateurs d’agent.
  • Pour contourner ce problème, encapsulez les outils non pris en charge en tant qu’outils de fonction définis par l’utilisateur afin que l’évaluateur puisse les évaluer.

Contenu connexe

  • Last updated on