Simuler des conversations avec le Kit de développement logiciel (SDK) Microsoft Foundry

Générez des conversations simulées à partir de descriptions de scénarios et évaluez-les au niveau de la conversation. Utilisez ce scénario pour tester le comportement de votre agent dans des situations contrôlées avant le déploiement. Le service génère des conversations réalistes en fonction de vos descriptions de scénarios, puis les évalue.

Prerequisites

Les exemples utilisent le client sdk configuré dans Configurer le client sdk.

Comprendre la simulation de conversation

Cette approche est utile pour :

  • Test de prédéploiement : validez le comportement de l’agent dans différents scénarios sans trafic utilisateur réel.
  • Couverture des cas limites : scénarios de test qui surviennent rarement, mais qu'il est important de bien gérer.
  • Test de régression : assurez-vous que les mises à jour de l’agent ne dégradent pas les performances dans les scénarios connus.
  • Tests de montée en charge : générez rapidement de nombreuses conversations pour mettre à l’épreuve les capacités de l’agent.

La simulation de conversation suit les étapes suivantes :

  1. Vous fournissez des descriptions de scénarios sous forme de données JSONL ou de cas de test intégrés fortement typés. Chaque cas de test décrit une situation que l’utilisateur simulé tente d’accomplir.
  2. Le service utilise un modèle de simulateur pour jouer le rôle de l’utilisateur, en interagissant avec votre agent en fonction du scénario.
  3. Chaque scénario génère une ou plusieurs conversations complètes.
  4. Les évaluateurs au niveau de la conversation évaluent les conversations générées.
  5. Votre projet stocke les résultats de l’évaluation. Vous pouvez éventuellement conserver toutes les conversations générées en tant que jeu de données Foundry versionné.

L’exécution utilise la source de azure_ai_user_conversation_simulation données. Placez les paramètres qui s’appliquent à chaque cas de test dans default_simulation_configuration. Un cas de test peut remplacer des paramètres individuels de la conversation dans simulation_configuration ; les paramètres qu’il ne remplace pas continuent à utiliser les paramètres par défaut de l’exécution.

Préparer des données de scénario

Tip

Au lieu de créer manuellement des scénarios, générez-les à l’aide du type de tâche de départ de simulation (multitour). Avant d’utiliser un jeu de données généré existant avec cette API, normalisez et passez iddesired_num_turns à test_case_idsimulation_configuration. Consultez Générer un jeu de données de départ de simulation.

Fournissez des cas de test à l’aide de l’un des types sources suivants :

  • file_id ou file_content pour les scénarios JSONL.
  • inline_user_conversation_simulation pour les cas de test fortement typés dans la requête d’exécution. Incluez au moins un cas de test.

Pour JSONL, utilisez les noms de propriétés canoniques indiqués dans l’exemple suivant. Incluez l’objectif, le contexte et les contraintes comportementales de l’utilisateur dans test_case_description. La description peut contenir 1 à 2 500 caractères.

{"test_case_id":"contoso_refund_timeline","test_case_description":"Customer returned an item five days ago and wants to know when the refund will arrive.","simulation_configuration":{"desired_num_turns":10}}
{"test_case_id":"contoso_store_hours_lookup","test_case_description":"Customer wants today's closing time and might need to clarify the store location.","simulation_configuration":{"desired_num_turns":3,"conversation_repetitions":2}}

Lorsque les données JSONL utilisent ces noms canoniques, omettez data_mapping. Si elle utilise des noms différents, mappez ces attributs à test_case_id, test_case_descriptionet simulation_configuration. N’utilisez pas data_mapping avec une source inline_user_conversation_simulation.

Chaque cas de test en ligne ou JSONL prend en charge les propriétés suivantes :

Propriété Description
test_case_id Identificateur facultatif. Le service génère un identificateur lorsque vous l’omettez.
test_case_description Scénario, objectif utilisateur et contraintes comportementales qui guident la conversation simulée.
simulation_configuration Paramètres facultatifs qui remplacent les valeurs par défaut d’exécution correspondantes pour ce cas de test.

Configurer l’utilisateur simulé

Utilisez l’objet model_configuration pour configurer le modèle qui joue le rôle de l’utilisateur simulé. Ce modèle est distinct du modèle ou de l’agent target évalué.

Propriété Obligatoire Description
model Oui Déploiement du simulateur au format {connectionName}/{modelDeploymentName}. Le routeur de modèle n’est pas pris en charge en tant que modèle de simulateur ; il ne peut s’agir que d’une cible d’évaluation.
sampling_params Non Paramètres d’échantillonnage appliqués lorsque le simulateur génère des tours utilisateur.
voice_model Non Convertit le texte utilisateur simulé en synthèse vocale via l’endpoint Voice Live. Omettez cette propriété pour la simulation de texte uniquement.

Pour la simulation vocale, voice_model.type doit être azure-standard. Défini name sur un nom de voix neuronale standard Azure. Vous pouvez également définir temperature entre 0 et 1 ; lorsqu’il est omis, la valeur par défaut du modèle vocal sous-jacent s’applique.

Configurer des conversations

Définissez des valeurs globales à l’exécution dans default_simulation_configuration. Les contrôles de conversation max_num_turns, conversation_repetitions, desired_num_turns, audio_effects et user_behavior peuvent également apparaître dans le simulation_configuration d’un cas de test pour remplacer les valeurs par défaut d’exécution correspondantes. Les propriétés enable_conversation_dataset_generation de génération de jeu de données et output_conversation_dataset_name sont valides uniquement dans default_simulation_configuration et ne peuvent pas être substituées par cas de test.

Propriété Scope Default Description
max_num_turns Exécuter ou tester le cas 20 Limite stricte du nombre de tours dans chaque conversation. Doit être au moins égal à 1.
conversation_repetitions Exécuter ou tester le cas 1 Nombre de conversations indépendantes générées pour chaque cas de test. Doit être au moins égal à 1.
desired_num_turns Exécuter ou tester le cas None Longueur de la conversation cible. Il ne peut pas dépasser l’effectif max_num_turns. En cas d’omission, le simulateur détermine la longueur du scénario.
audio_effects Exécuter ou tester le cas None Effets appliqués à la simulation vocale. Ignoré pour la simulation en mode texte uniquement.
user_behavior Exécuter ou tester le cas None Comportement de l’utilisateur simulé, tel qu’une interruption.
enable_conversation_dataset_generation Exécuter uniquement false Conserve toutes les conversations générées dans un jeu de données Foundry versionné.
output_conversation_dataset_name Exécuter uniquement Généré par le service Nom du jeu de données utilisé lorsque la génération du jeu de données de conversation est activée.

Configurer les conditions vocales et les interruptions

Placez-les audio_effects et user_behavior à l’intérieur default_simulation_configuration pour les appliquer à chaque cas de test. Pour remplacer l’un ou l’autre de ces paramètres pour un cas de test, placez-le plutôt dans le simulation_configuration de ce cas de test.

Utilisez audio_effects pour tester les performances de la cible dans des conditions d’écoute réalistes. Ajoutez un ou plusieurs effets : street_traffic, , background_tvcrowd_chatter, metro_stationou telephonic_voice. Définissez volume_percentage de 1 à 100 pour contrôler leur volume combiné. La valeur par défaut est 15. Les effets audio sont ignorés dans les simulations de texte uniquement.

Utilisez user_behavior.interruption pour tester comment la cible gère le cas où un utilisateur parle alors que la cible répond. Définissez sa valeur type sur default pour activer les interruptions simulées. Omettez interruption quand les interruptions ne font pas partie du test.

{
  "default_simulation_configuration": {
    "audio_effects": {
      "effects": ["street_traffic", "telephonic_voice"],
      "volume_percentage": 20
    },
    "user_behavior": {
      "interruption": {
        "type": "default"
      }
    }
  }
}

Définir des évaluateurs

Sélectionnez les évaluateurs conçus pour l’évaluation au niveau de la conversation. Les conversations simulées sont automatiquement associées aux évaluateurs.

import os
from openai.types.eval_create_params import DataSourceConfigCustom
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import TestingCriterionAzureAIEvaluator, PromptAgentDefinition

endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]
model_deployment_name = os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
simulator_model = os.environ["AZURE_AI_SIMULATOR_MODEL"]
agent_name = os.environ.get("FOUNDRY_AGENT_NAME", "")

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    # Simulation uses the same "custom" eval group type as dataset evaluation (S1),
    # since the generated conversations follow the same messages schema.
    data_source_config = DataSourceConfigCustom(
        type="custom",
        item_schema={
            "type": "object",
            "properties": {
                "messages": {"type": "array"},
                "tool_definitions": {"type": "array"},
            },
            "required": ["messages"],
        },
        include_sample_schema=False,
    )

    testing_criteria = [
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="output_quality",
            evaluator_name="builtin.output_quality",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={
                "messages": "{{item.messages}}",
                "tool_definitions": "{{item.tool_definitions}}",
            },
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="tool_use_quality",
            evaluator_name="builtin.tool_use_quality",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={
                "messages": "{{item.messages}}",
                "tool_definitions": "{{item.tool_definitions}}",
            },
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="deflection_rate",
            evaluator_name="builtin.deflection_rate",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={
                "messages": "{{item.messages}}",
                "tool_definitions": "{{item.tool_definitions}}",
            },
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="customer_satisfaction",
            evaluator_name="builtin.customer_satisfaction",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="task_completion",
            evaluator_name="builtin.task_completion",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="coherence",
            evaluator_name="builtin.coherence",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="groundedness",
            evaluator_name="builtin.groundedness",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
    ]

Créer l’évaluation et exécuter

Enregistrez les lignes JSONL canoniques depuis Préparer les données du scénario sous le nom simulation_scenarios.jsonl.

# Create (or update) an agent to simulate against
agent = project_client.agents.create_version(
    agent_name=agent_name,
    definition=PromptAgentDefinition(
        model=model_deployment_name,
        instructions="You are a helpful customer service agent. Be empathetic and solution-oriented.",
    ),
)

# Upload scenario data
scenarios_id = project_client.datasets.upload_file(
    name="simulation-scenarios",
    version="1",
    file_path="./simulation_scenarios.jsonl",
).id

# Create the evaluation
eval_object = openai_client.evals.create(
    name="Multi-turn Conversation Simulation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

# Create a simulation run. AZURE_AI_SIMULATOR_MODEL uses the format
# {connectionName}/{modelDeploymentName}.
eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="conversation-simulation-run",
    data_source={
        "type": "azure_ai_user_conversation_simulation",
        "source": {
            "type": "file_id",
            "id": scenarios_id,
        },
        "target": {
            "type": "azure_ai_agent",
            "name": agent.name,
            "version": agent.version,
        },
        "model_configuration": {
            "model": simulator_model,
            "sampling_params": {
                "temperature": 0.7,
                "top_p": 1.0,
                "max_completion_tokens": 800,
            },
        },
        "default_simulation_configuration": {
            "max_num_turns": 8,
            "conversation_repetitions": 2,
            "desired_num_turns": 5,
            "enable_conversation_dataset_generation": True,
            "output_conversation_dataset_name": "support-simulations",
        },
    },
    extra_body={"evaluation_level": "conversation"},
)

Utiliser des cas de test en ligne

Pour définir des scénarios directement dans la requête d’exécution, définissez data_source.source sur une inline_user_conversation_simulation source. Les sources inline nécessitent au moins un cas de test et n’utilisent data_mappingpas .

inline_source = {
    "type": "inline_user_conversation_simulation",
    "test_cases": [
        {
            "test_case_id": "refund-delay",
            "test_case_description": "A frustrated customer wants an update on a delayed refund.",
            "simulation_configuration": {
                "desired_num_turns": 6,
            },
        }
    ],
}

# In the run request:
# data_source={..., "source": inline_source}

Récupérer les conversations générées

Interrogez l’exécution jusqu’à ce qu’elle atteigne un état terminal, comme décrit dans Obtenir les résultats de l’évaluation cloud. Lorsque enable_conversation_dataset_generation est true, une exécution terminée inclut une entrée output_datasets comme celle-ci :

{
  "type": "simulated_user_conversations",
  "dataset": {
    "id": "dataset_123",
    "name": "support-simulations",
    "version": "1"
  }
}

Utilisez le jeu de données idretourné, nameet version pour récupérer ou réutiliser les conversations générées. Si la génération du jeu de données est désactivée, output_datasets est omis.

Étapes suivantes

  • Dernière mise à jour :