Simular conversaciones con el SDK de Microsoft Foundry

Genere conversaciones simuladas a partir de descripciones de escenarios y evalúelas en el nivel de conversación. Use este escenario para probar el comportamiento del agente en situaciones controladas antes de la implementación. El servicio genera conversaciones realistas en función de las descripciones del escenario y, a continuación, las evalúa.

Prerequisites

En los ejemplos se usa el cliente del SDK configurado en Configuración del cliente del SDK.

Comprender la simulación de conversación

Este enfoque es útil para:

  • Pruebas previas a la implementación: valide el comportamiento del agente en diversos escenarios sin tráfico de usuario real.
  • Cobertura de casos límite: escenarios de prueba que rara vez surgen de forma natural, pero que es importante gestionar correctamente.
  • Pruebas de regresión: asegúrese de que las actualizaciones del agente no degradan el rendimiento en escenarios conocidos.
  • Pruebas de escala: Generar muchas conversaciones rápidamente para poner a prueba al límite las capacidades del agente.

La simulación de conversación sigue estos pasos:

  1. Puede proporcionar descripciones de escenarios en formato JSONL o como casos de prueba en línea con tipado fuerte. Cada caso de prueba describe una situación que el usuario simulado intenta realizar.
  2. El servicio usa un modelo de simulador para desempeñar el rol del usuario, interactuando con el agente en función del escenario.
  3. Cada escenario genera una o varias conversaciones completas.
  4. Los evaluadores de nivel de conversación evalúan las conversaciones generadas.
  5. El proyecto almacena los resultados de la evaluación. Opcionalmente, puede guardar todas las conversaciones generadas como un conjunto de datos de Foundry con versiones.

La ejecución utiliza el origen de datos azure_ai_user_conversation_simulation. Coloque la configuración que se aplica a cada caso de prueba en default_simulation_configuration. Un caso de prueba puede anular ajustes individuales de la conversación en su simulation_configuration; los ajustes que no se anulen seguirán usando los valores predeterminados de la ejecución.

Preparación de los datos del escenario

Tip

En lugar de crear escenarios manualmente, genere estos utilizando el tipo de tarea Semilla de simulación (varias rondas). Antes de usar un conjunto de datos generado existente con esta API, normalice id y pase desired_num_turns a test_case_idsimulation_configuration. Consulte Generación de un conjunto de datos de inicialización de simulación.

Proporcione casos de prueba mediante uno de estos tipos de origen:

  • file_id o file_content para escenarios JSONL.
  • inline_user_conversation_simulation para casos de prueba de tipado fuerte en la solicitud de ejecución. Incluya al menos un caso de prueba.

Para JSONL, use los nombres de propiedad canónicos que se muestran en el ejemplo siguiente. Incluya el objetivo, el contexto y las restricciones de comportamiento del usuario en test_case_description. La descripción puede contener de 1 a 2500 caracteres.

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

Cuando los datos JSONL usan estos nombres canónicos, omita data_mapping. Si usa nombres diferentes, asigne esos atributos a test_case_id, test_case_descriptiony simulation_configuration. No utilice data_mapping con una inline_user_conversation_simulation fuente.

Cada caso de prueba en línea o JSONL admite estas propiedades:

Propiedad Descripción
test_case_id Identificador opcional. El servicio genera un identificador al omitirlo.
test_case_description Escenario, objetivo del usuario y restricciones de comportamiento que guían la conversación simulada.
simulation_configuration Configuración opcional que invalida los valores predeterminados de ejecución correspondientes para este caso de prueba.

Configuración del usuario simulado

Use el model_configuration objeto para configurar el modelo que reproduce el usuario simulado. Este modelo es independiente del target modelo o agente que se está evaluando.

Propiedad Obligatorio Descripción
model Sí Despliegue del simulador en formato {connectionName}/{modelDeploymentName}. El enrutador del modelo no se admite como el modelo del simulador; solo puede ser un destino de evaluación.
sampling_params No Parámetros de muestreo aplicados cuando el simulador genera turnos de usuario.
voice_model No Convierte el texto del usuario simulado en voz a través del punto de conexión de Voice Live. Omita esta propiedad para la simulación de solo texto.

Para la simulación de voz, voice_model.type debe ser azure-standard. Establezca name como el nombre de una voz neuronal estándar de Azure. También puede establecer temperature entre 0 y 1; cuando se omite, se aplica el valor predeterminado del modelo de voz subyacente.

Configurar conversaciones

Establezca valores para toda la ejecución en default_simulation_configuration. Los controles de conversación max_num_turns, conversation_repetitions, desired_num_turns, audio_effects y user_behavior también pueden aparecer en el simulation_configuration de un caso de prueba para anular los valores predeterminados de ejecución correspondientes. Las propiedades enable_conversation_dataset_generation de generación de conjuntos de datos y output_conversation_dataset_name solo son válidas en default_simulation_configuration y no se pueden invalidar por caso de prueba.

Propiedad Ámbito Valor predeterminado Descripción
max_num_turns Ejecución o caso de prueba 20 Límite máximo de intercambios en cada conversación. Debe ser 1 como mínimo.
conversation_repetitions Ejecución o caso de prueba 1 Número de conversaciones independientes generadas para cada caso de prueba. Debe ser 1 como mínimo.
desired_num_turns Ejecución o caso de prueba None Longitud objetivo de la conversación. No puede superar el valor efectivo max_num_turns. Cuando se omite, el simulador determina la duración a partir del escenario.
audio_effects Ejecución o caso de prueba None Efectos aplicados a la simulación de voz. Se omite para la simulación de solo texto.
user_behavior Ejecución o caso de prueba None Comportamiento de usuario simulado, como la interrupción.
enable_conversation_dataset_generation Ejecutar solo false Guarda todas las conversaciones generadas en un conjunto de datos versionado de Foundry.
output_conversation_dataset_name Ejecutar solo Generado por el servicio Nombre del conjunto de datos que se usa cuando la generación de conjuntos de datos de conversación está habilitada.

Configurar las condiciones de voz y las interrupciones

Coloque audio_effects y user_behavior dentro default_simulation_configuration para aplicarlos a cada caso de prueba. Para anular cualquiera de estos ajustes en un caso de prueba concreto, colócalo dentro del elemento simulation_configuration de dicho caso de prueba.

Utiliza audio_effects para probar cómo rinde el objetivo en condiciones de escucha realistas. Agregue uno o varios efectos: street_traffic, crowd_chatter, background_tv, metro_stationo telephonic_voice. Establezca volume_percentage de 1 a 100 para controlar su volumen combinado. El valor predeterminado es 15. Los efectos de audio se omiten en simulaciones de solo texto.

Utiliza user_behavior.interruption para probar cómo gestiona el sistema que un usuario hable mientras el sistema está respondiendo. Establezca su valor en typedefault para activar interrupciones simuladas. Omita interruption cuando las interrupciones no formen parte de la prueba.

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

Definir evaluadores

Seleccione evaluadores diseñados para la evaluación de nivel de conversación. Las conversaciones simuladas se asignan automáticamente a los evaluadores.

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}}"},
        ),
    ]

Creación y ejecución de la evaluación

Guarde las filas JSONL canónicas de preparar los datos del escenario como 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"},
)

Usar casos de prueba en línea

Para definir escenarios directamente en la solicitud de ejecución, establezca data_source.source como un origen inline_user_conversation_simulation. Las fuentes en línea requieren al menos un caso de prueba y no utilizan data_mapping.

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}

Obtener conversaciones generadas

Sondee la ejecución hasta que alcance un estado terminal, tal como se describe en Obtención de resultados de evaluación en la nube. Cuando enable_conversation_dataset_generation es true, una ejecución completada incluye una output_datasets entrada como esta:

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

Use el conjunto de datos iddevuelto , namey version para recuperar o reutilizar las conversaciones generadas. Si la generación de conjuntos de datos está deshabilitada, output_datasets se omite.

Pasos siguientes

  • Se actualizó por última vez el