Simular conversas com o Microsoft Foundry SDK

Gerar conversas simuladas a partir de descrições de cenários e avaliá-las ao nível da conversa. Use este cenário para testar o comportamento do seu agente em situações controladas antes da implantação. O serviço gera conversas realistas com base nas descrições dos seus cenários e depois avalia-as.

Pré-requisitos

Os exemplos utilizam o cliente SDK configurado em Configurar o cliente SDK.

Compreender a simulação de conversa

Esta abordagem é útil para:

  • Testes pré-implementação: Validar o comportamento dos agentes em vários cenários sem tráfego real de utilizadores.
  • Cobertura de casos extremos: Cenários de teste que raramente ocorrem naturalmente, mas são importantes de gerir bem.
  • Testes de regressão: Garantir que as atualizações dos agentes não degradam o desempenho em cenários conhecidos.
  • Testes à escala: Gere rapidamente muitas conversas para pôr à prova as capacidades do agente.

A simulação de conversa segue estes passos:

  1. Pode fornecer descrições de cenários sob a forma de dados JSONL ou casos de teste em linha com tipagem forte. Cada caso de teste descreve uma situação que o utilizador simulado tenta realizar.
  2. O serviço utiliza um modelo simulador para desempenhar o papel do utilizador, interagindo com o seu agente com base no cenário.
  3. Cada cenário gera uma ou mais conversas completas.
  4. Os avaliadores de nível de conversa avaliam as conversas geradas.
  5. O seu projeto armazena os resultados da avaliação. Pode, opcionalmente, persistir todas as conversas geradas como um conjunto de dados versionado do Foundry.

A execução utiliza a fonte de dados azure_ai_user_conversation_simulation. Coloque as definições que se aplicam a todos os casos de teste em default_simulation_configuration. Um caso de teste pode redefinir definições individuais da conversa nas suas simulation_configuration; as definições que não redefine continuam a usar as predefinições da execução.

Preparar os dados dos cenários

Sugestão

Em vez de criar cenários manualmente, gere-os através do tipo de tarefa Semente de simulação (múltiplos turnos). Antes de usar um conjunto de dados gerado existente com esta API, normalize id para test_case_id e mova-se desired_num_turns para simulation_configuration. Consulte Gerar um conjunto de dados inicial de simulação.

Fornece casos de teste utilizando um destes tipos de fonte:

  • file_id ou file_content para cenários JSONL.
  • inline_user_conversation_simulation para casos de teste fortemente tipados no pedido de execução. Inclua pelo menos um caso de teste.

Para JSONL, use os nomes canónicos das propriedades mostrados no exemplo seguinte. Inclua o objetivo do utilizador, o contexto e as restrições comportamentais em test_case_description. A descrição pode conter de 1 a 2.500 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}}

Quando os dados JSONL usam estes nomes canónicos, omita data_mapping. Se usar nomes diferentes, mapeie esses atributos para test_case_id, test_case_description, e simulation_configuration. Não utilizes data_mapping com uma origem inline_user_conversation_simulation.

Cada caso de teste inline ou JSONL suporta estas propriedades:

Property Descrição
test_case_id Identificador opcional. O serviço gera um identificador quando o omite.
test_case_description Cenário, objetivo do utilizador e restrições comportamentais que orientam a conversa simulada.
simulation_configuration Definições opcionais que substituem as predefinições correspondentes da execução para este caso de teste.

Configurar o utilizador simulado

Use o model_configuration objeto para configurar o modelo que reproduz o utilizador simulado. Este modelo é separado do target modelo ou agente que está a ser avaliado.

Property Obrigatório Descrição
model Sim Implementação do simulador no formato {connectionName}/{modelDeploymentName}. O encaminhador de modelos não é compatível como modelo do simulador; apenas pode ser um alvo de avaliação.
sampling_params No Parâmetros de amostragem aplicados quando o simulador gera turnos de utilizador.
voice_model No Converte texto simulado do utilizador para fala através do endpoint Voice Live. Omita esta propriedade para simulação apenas de texto.

Para simulação de voz, voice_model.type deve ser azure-standard. Defina name como um nome de voz neural padrão do Azure. Também pode definir temperature de 0 a 1; quando omitido, aplica-se o padrão do modelo de voz subjacente.

Configurar conversas

Defina valores para toda a execução em default_simulation_configuration. Os controlos de conversa audio_effects, user_behavior, simulation_configuration, desired_num_turns e conversation_repetitions também podem aparecer em max_num_turns de um caso de teste para substituir as predefinições de execução correspondentes. As propriedades enable_conversation_dataset_generation de geração de conjuntos de dados e output_conversation_dataset_name são válidas apenas em default_simulation_configuration e não podem ser anuladas por caso de teste.

Property Âmbito Predefinição Descrição
max_num_turns Execução ou caso de teste 20 Limite rígido de turnos em cada conversa. Deve ser pelo menos 1.
conversation_repetitions Execução ou caso de teste 1 Número de conversas independentes geradas para cada caso de teste. Deve ser pelo menos 1.
desired_num_turns Execução ou caso de teste None Extensão pretendida da conversa. Não pode exceder o efetivo max_num_turns. Quando omitido, o simulador determina a duração com base no cenário.
audio_effects Execução ou caso de teste None Efeitos aplicados à simulação de voz. Ignorado numa simulação apenas de texto.
user_behavior Execução ou caso de teste None Comportamento simulado do utilizador, como interrupção.
enable_conversation_dataset_generation Executar apenas false Persiste todas as conversas geradas para um conjunto de dados Foundry versionado.
output_conversation_dataset_name Executar apenas Gerado por serviços Nome do conjunto de dados usado quando a geração de conjuntos de dados de conversa está ativada.

Configurar condições de voz e interrupções

Coloque audio_effects e user_behavior dentro de default_simulation_configuration para os aplicar a todos os casos de teste. Para substituir qualquer uma das definições para um caso de teste, coloque-a dentro do simulation_configuration desse caso de teste.

Use audio_effects para testar como o alvo se comporta em condições realistas de escuta. Adicionar um ou mais efeitos: street_traffic, crowd_chatter, background_tv, metro_station, ou telephonic_voice. Define volume_percentage de 1 a 100 para controlar o volume combinado. A predefinição é 15. Os efeitos áudio são ignorados em simulações apenas de texto.

Use user_behavior.interruption para testar como o alvo lida com um utilizador a falar enquanto o alvo responde. Defina o respetivo type como default para ativar interrupções simuladas. Omita interruption quando as interrupções não fizerem parte do teste.

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

Definir avaliadores

Selecione avaliadores concebidos para avaliação ao nível da conversação. As conversas simuladas são automaticamente associadas aos avaliadores.

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

Crie a avaliação e execute

Guarde as linhas canónicas JSONL de Preparar dados do cenário 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"},
)

Use casos de teste em linha

Para definir cenários diretamente no pedido de execução, defina data_source.source para uma inline_user_conversation_simulation fonte. Fontes inline requerem pelo menos um caso de teste e não usam 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}

Obtenha conversas geradas

Verifique periodicamente a execução até esta atingir um estado terminal, conforme descrito em Obter resultados de avaliação na nuvem. Quando enable_conversation_dataset_generation é true, uma execução concluída inclui uma entrada output_datasets como esta:

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

Use o conjunto de dados iddevolvido , name, e version para recuperar ou reutilizar as conversas geradas. Se a geração de conjuntos de dados estiver desativada, output_datasets é omitida.

Passos seguintes

  • Última atualização a