Partager via

Exécuter des évaluations à partir du Kit de développement logiciel (SDK)

Important

Les éléments marqués (aperçu) dans cet article sont actuellement en aperçu public. Cette version préliminaire est fournie sans contrat de niveau de service, et nous la déconseillons pour les charges de travail en production. Certaines fonctionnalités peuvent être limitées ou non prises en charge. Pour plus d’informations, consultez Conditions d'utilisation supplémentaires pour les aperçus 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 par lots 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 par lots 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 Batch prend en charge tous les évaluateurs intégrés organisé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 / Astuce

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

Lorsque vous utilisez le Kit de développement logiciel (SDK) Foundry, il journalise les résultats d’évaluation dans votre projet Foundry pour améliorer l’observabilité. Cette fonctionnalité prend en charge tous les évaluateurs intégrés organisés par Microsoft et vos propres évaluateurs personnalisés. Vos évaluateurs peuvent se trouver dans la bibliothèque de l’évaluateur et avoir le même contrôle d’accès en fonction du rôle.

Fonctionnement de l’évaluation par lots

Pour exécuter une évaluation par lots, 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. L'exécution lance chaque évaluateur sur vos données et retourne des résultats notés dont vous pouvez interroger l'état d'avancement jusqu'à la fin du processus.

L’évaluation batch 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 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 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 Descriptif
file_id Référencez un jeu de données chargé par ID.
file_content Fournissez des données en ligne à l'intérieur de 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 pour 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" à "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 à pour le red teaming.

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.

Prerequisites

  • 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 utilisateur Azure AI 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 .

Get started

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 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."}

# 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

Fournissez les données en ligne

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

Utilisez source en tant que champ "source" dans votre configuration de source de données lors de la création d'un run. 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 / Astuce

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 paramètre data_mapping pour connecter les champs de vos données d'entrée aux paramètres évaluateur à l'aide de la syntaxe {{item.field}}. Incluez toujours data_mapping 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 ont "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'état de complétion 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 / Astuce

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'état de complétion et interpréter les résultats, consultez Obtenir les résultats.

Conseil / Astuce

Pour ajouter une autre exécution d’évaluation, réexécutez la même évaluation à l’aide du même groupe d’évaluation. Chaque exécution crée une nouvelle exécution sous le même groupe, ce qui vous permet de comparer >les résultats entre les exécutions après avoir modifié des éléments tels que le modèle, l’invite ou le jeu de données, sans créer d’évaluation ou utiliser une AUTRE API.

Consultez l’exemple qui réutilise le même groupe d’évaluation pour créer plusieurs exécutions à des fins de comparaison.

É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.

Conseil / Astuce

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 à 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 afin de référencer la sortie de l’agent :

Variable Descriptif Utilisée 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 / Astuce

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 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'état de complétion et interpréter les résultats, consultez Obtenir les résultats.

Conseil / Astuce

Pour ajouter une autre exécution d’évaluation, réexécutez la même évaluation à l’aide du même groupe d’évaluation. Chaque exécution crée une nouvelle exécution sous le même groupe, ce qui vous permet de comparer >les résultats entre les exécutions après avoir modifié des éléments tels que le modèle, l’invite ou le jeu de données, sans créer d’évaluation ou utiliser une AUTRE API.

Consultez l’exemple qui réutilise le même groupe d’évaluation pour créer plusieurs exécutions à des fins de comparaison.

É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 / Astuce

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 aussi récupérer les ID de réponse issus des interactions avec l'agent via les journaux d’activité de suivi 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'état de complétion et interpréter les résultats, consultez Obtenir les résultats.

Conseil / Astuce

Pour ajouter une autre exécution d’évaluation, réexécutez la même évaluation à l’aide du même groupe d’évaluation. Chaque exécution crée une nouvelle exécution sous le même groupe, ce qui vous permet de comparer >les résultats entre les exécutions après avoir modifié des éléments tels que le modèle, l’invite ou le jeu de données, sans créer d’évaluation ou utiliser une AUTRE API.

Consultez l’exemple qui réutilise le même groupe d’évaluation pour créer plusieurs exécutions à des fins de comparaison.

É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 / Astuce

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 vos fichiers de données de départ et sur des données facultatives prompt.
  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 Descriptif
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. S’il n’est pas fourni, le service génère automatiquement un nom.
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 optionnellement ajouter une commande système pour orienter le comportement du modèle cible. Lorsque vous utilisez input_messages 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'état de complétion 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.

Interroger pour obtenir les résultats

Les processus d’évaluation sont asynchrones. Interrogez l’état d’avancement de l’exécution jusqu’à la fin du processus, 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...")

if run.status == "failed":
    print(f"Evaluation run failed: {run.error}")
else:
    # 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 sortie (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 avec un « réussi » 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
    }
  ]
}

Résolution des problèmes

Tâche en cours 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 font l'objet d’une limitation du débit 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 recalcul exponentiel lors de la nouvelle tentative de demandes é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 retourne une erreur pour les 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