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

Important

Les éléments indiqués comme (aperçu) dans cet article sont en aperçu public. Cette préversion est fournie sans contrat de niveau de service et nous ne la recommandons pas pour les environnements de production. Certaines fonctionnalités peuvent ne pas être prises en charge ou avoir des fonctionnalités contraintes. Pour plus d’informations, consultez Conditions d'utilisation supplémentaires 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 intégrés préparés par Microsoft 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 exécute chaque évaluateur sur vos données et retourne les résultats notés que vous pouvez consulter pour vérifier leur 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 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 chargé par ID.
file_content Fournissez des données inline 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 des 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, "synthetic_data_gen_preview" pour l’évaluation des données synthétiques (préversion), ou "red_team" pour l'exercice des équipes rouges.

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 intégrées

Pour une expérimentation rapide avec de petits ensembles 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",
            }
        ),
    ],
)

Passez source comme le champ "source" dans la configuration de votre source de données lors de la création d'une exécution. Les sections de scénario qui suivent 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 le data_mapping paramètre pour connecter les 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 contiennent "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 sonder l'achèvement et interpréter les résultats, consultez Obtenir 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 du schéma et la configuration de l’évaluateur sont les mêmes que pour les évaluations JSONL — la seule différence se trouve 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 sonder l'achèvement et interpréter les résultats, consultez Obtenir 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 sonder l'achèvement et interpréter les résultats, consultez Obtenir les résultats.

Conseil

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

Évaluation de la cible de l'agent

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 les variables {{sample.*}} dans data_mapping pour faire référence à 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’agent tels que task_adherence utilisent ce contexte pour un scoring plus précis. 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 sonder l'achèvement et interpréter les résultats, consultez Obtenir 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 les espaces réservés {{item.*}} 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, effectuez l'étape d'initiation.

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 ID de réponse à partir des interactions de l'agent dans les journaux de traces ou dans la chaîne 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 sonder l'achèvement et interpréter les résultats, consultez Obtenir 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, effectuez l'étape d'initiation.

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

  1. Le service génère des requêtes synthétiques basées sur vos prompt fichiers de données initiales et 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 le nom n’est pas fourni, le service génère un nom automatiquement.
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. La cible 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 facultativement ajouter une invite système pour orienter le comportement du modèle cible. Lorsque vous utilisez la génération de données synthétiques avec input_messages, incluez uniquement system les messages de rôle — le service fournit automatiquement les requêtes générées en tant que des 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 sonder l'achèvement et interpréter les résultats, consultez Obtenir 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.

Sondage pour les résultats

Les exécutions d’évaluation sont asynchrones. Interrogez l’état de l’exécution jusqu’à ce qu’il se termine, 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 ayant une réussite constitue 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 Utilisateur Azure AI 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 (respectant 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 d’exécutions d’évaluation sont limitées en fréquence 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 un recul exponentiel pour les nouvelles tentatives des 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 jetons par minute (TPM) de votre déploiement de modèle dans le portail Azure.

Erreurs de l’outil évaluateur d’agent

Si un évaluateur d’agent renvoie une erreur concernant des outils non pris en charge :

  • 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