Simulare conversazioni con Microsoft Foundry SDK

Generare conversazioni simulate dalle descrizioni degli scenari e valutarle a livello di conversazione. Usare questo scenario per testare il comportamento dell'agente in situazioni controllate prima della distribuzione. Il servizio genera conversazioni realistiche in base alle descrizioni degli scenari e quindi le valuta.

Prerequisiti

Gli esempi usano il client SDK configurato in Configurare il client SDK.

Informazioni sulla simulazione della conversazione

Questo approccio è utile per:

  • Test di pre-distribuzione: convalidare il comportamento dell'agente in diversi scenari senza traffico utente reale.
  • Copertura dei casi limite: scenari di test che si verificano raramente, ma che è importante gestire correttamente.
  • Test di regressione: assicurarsi che gli aggiornamenti dell'agente non degradino le prestazioni in scenari noti.
  • Test di scala: Genera rapidamente numerose conversazioni per mettere alla prova le capacità degli operatori.

La simulazione di conversazioni segue questa procedura:

  1. Fornisci le descrizioni degli scenari sotto forma di dati JSONL o di casi di test inline fortemente tipizzati. Ogni test case descrive una situazione che l'utente simulato tenta di eseguire.
  2. Il servizio usa un modello di simulatore per svolgere il ruolo dell'utente, interagendo con l'agente in base allo scenario.
  3. Ogni scenario genera una o più conversazioni complete.
  4. I valutatori a livello di conversazione valutano le conversazioni generate.
  5. Il progetto archivia i risultati della valutazione. Facoltativamente, è possibile rendere persistenti tutte le conversazioni generate come set di dati Foundry con controllo delle versioni.

L'esecuzione usa l'origine dati azure_ai_user_conversation_simulation. Inserire le impostazioni che si applicano a ogni test case in default_simulation_configuration. Un test case può eseguire l'override delle singole impostazioni di conversazione nel relativo simulation_configuration; le impostazioni che non eseguono l'override continuano a usare le impostazioni predefinite di esecuzione.

Preparare i dati dello scenario

Suggerimento

Anziché creare gli scenari manualmente, generarli utilizzando il tipo di attività Seed di simulazione (multi-turno) Prima di usare un set di dati già generato con questa API, normalizzare id in test_case_id e spostare desired_num_turns in simulation_configuration. Vedere Generare un set di dati di inizializzazione della simulazione.

Fornire test case usando uno di questi tipi di origine:

  • file_id o file_content per gli scenari JSONL.
  • inline_user_conversation_simulation per test case fortemente tipizzati nella richiesta di esecuzione. Includi almeno un caso di test.

Per JSONL, usare i nomi di proprietà canonici illustrati nell'esempio seguente. Includere l'obiettivo, il contesto e i vincoli comportamentali dell'utente in test_case_description. La descrizione può contenere da 1 a 2.500 caratteri.

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

Quando i dati JSONL usano questi nomi canonici, omettere data_mapping. Se usa nomi diversi, eseguire il mapping di tali attributi a test_case_id, test_case_descriptione simulation_configuration. Non usare data_mapping con un'origine inline_user_conversation_simulation .

Ogni test case inline o JSONL supporta queste proprietà:

Proprietà Descrizione
test_case_id Identificatore facoltativo. Il servizio genera un identificatore se non viene specificato.
test_case_description Scenario, obiettivo utente e vincoli comportamentali che guidano la conversazione simulata.
simulation_configuration Impostazioni facoltative che eseguono l'override delle impostazioni predefinite di esecuzione corrispondenti per questo test case.

Configurare l'utente simulato

Usare l'oggetto model_configuration per configurare il modello che riproduce l'utente simulato. Questo modello è separato dal modello o dall'agente target da valutare.

Proprietà Obbligatorio Descrizione
model Yes Distribuzione del simulatore in formato {connectionName}/{modelDeploymentName}. Il router del modello non è supportato come modello del simulatore; può essere usato solo come obiettivo di valutazione.
sampling_params No Parametri di campionamento applicati quando il simulatore genera turni utente.
voice_model No Converte il testo dell'utente simulato in voce tramite l'endpoint Voice Live. Ometti questa proprietà per la simulazione di solo testo.

Per la simulazione vocale, voice_model.type deve essere azure-standard. Impostare name su un nome di voce neurale standard Azure. È anche possibile impostare temperature da 0 a 1. Se omesso, viene applicato il valore predefinito del modello vocale sottostante.

Configurare le conversazioni

Impostare valori a livello di esecuzione in default_simulation_configuration. I controlli di conversazione max_num_turns, desired_num_turns, conversation_repetitions, audio_effects e user_behavior possono anche comparire nel simulation_configuration di un test case per sovrascrivere i valori predefiniti di esecuzione corrispondenti. Le proprietà enable_conversation_dataset_generation di generazione del set di dati e output_conversation_dataset_name sono valide solo in default_simulation_configuration e non possono essere sottoposte a override per ogni test case.

Proprietà Scope Predefinito Descrizione
max_num_turns Esecuzione o test case 20 Limite rigido per gli turni in ogni conversazione. Deve essere almeno 1.
conversation_repetitions Esecuzione o test case 1 Numero di conversazioni indipendenti generate per ogni test case. Deve essere almeno 1.
desired_num_turns Esecuzione o test case None Lunghezza obiettivo della conversazione Non può superare l'effettivo max_num_turns. Se omesso, il simulatore determina la lunghezza dello scenario.
audio_effects Esecuzione o test case None Effetti applicati alla simulazione vocale. Ignorato per la simulazione di solo testo.
user_behavior Esecuzione o test case None Comportamento dell'utente simulato, ad esempio un'interruzione.
enable_conversation_dataset_generation Esegui solo false Salva tutte le conversazioni generate in un dataset Foundry versionato.
output_conversation_dataset_name Esegui solo Generato dal servizio Nome del set di dati usato quando la generazione del set di dati di conversazione è abilitata.

Configurare le condizioni vocali e le interruzioni

Inserire audio_effects e user_behavior all'interno di default_simulation_configuration per applicarli a ogni caso di test. Per sovrascrivere una delle due impostazioni per un singolo test case, inserirla invece all'interno del simulation_configuration di quel test case.

Utilizzare audio_effects per verificare le prestazioni del target in condizioni di ascolto realistiche. Aggiungere uno o più effetti: street_traffic, crowd_chatter, background_tv, metro_stationo telephonic_voice. Impostare volume_percentage da 1 a 100 per controllare il volume combinato. Il valore predefinito è 15. Gli effetti audio vengono ignorati nelle simulazioni di solo testo.

Usare user_behavior.interruption per verificare come il sistema di destinazione gestisce il caso in cui un utente parli mentre il sistema di destinazione sta rispondendo. Imposta type su default per abilitare le interruzioni simulate. Omettere interruption quando le interruzioni non fanno parte del test.

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

Definire gli analizzatori

Seleziona i valutatori progettati per valutare conversazioni. Le conversazioni simulate vengono automaticamente associate ai valutatori.

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

Creare la valutazione ed eseguire

Salvare le righe JSONL canoniche da Preparare i dati dello scenario come 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"},
)

Usare casi di test in linea

Per definire gli scenari direttamente nella richiesta di esecuzione, impostare data_source.source su un'origine inline_user_conversation_simulation. Le sorgenti inline richiedono almeno un caso di test e non usano 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}

Ottenere conversazioni generate

Interrogare periodicamente l'esecuzione finché non raggiunge uno stato finale, come descritto in Ottenere i risultati della valutazione nel cloud. Quando enable_conversation_dataset_generation è true, un'esecuzione completata include una voce output_datasets come la seguente:

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

Usare il set di dati idrestituito , namee version per recuperare o riutilizzare le conversazioni generate. Se la generazione del set di dati è disabilitata, output_datasets viene omessa.

Passaggi successivi

  • Ultimo aggiornamento: