Simulera konversationer med Microsoft Foundry SDK

Generera simulerade konversationer från scenariobeskrivningar och utvärdera dem på konversationsnivå. Använd det här scenariot för att testa agentens beteende i kontrollerade situationer före distributionen. Tjänsten genererar realistiska konversationer baserat på dina scenariobeskrivningar och utvärderar dem sedan.

Förutsättningar

I exemplen används SDK-klienten som konfigurerats i Konfigurera SDK-klienten.

Förstå konversationssimulering

Den här metoden är användbar för:

  • Testning före driftsättning: Verifiera agentbeteendet i olika scenarier utan verklig användartrafik.
  • Gränsfallstäckning: Testscenarier som sällan inträffar naturligt men är viktiga att hantera väl.
  • Regressionstestning: Se till att agentuppdateringar inte försämrar prestanda i kända scenarier.
  • Skaltestning: Generera många konversationer snabbt för att stress-testa agentens funktioner.

Konversationssimulering följer dessa steg:

  1. Du anger scenariobeskrivningar som JSONL-data eller starkt inbyggda testfall. Varje testfall beskriver en situation som den simulerade användaren försöker utföra.
  2. Tjänsten använder en simulatormodell för att spela rollen som användare och interagerar med din agent baserat på scenariot.
  3. Varje scenario genererar en eller flera fullständiga konversationer.
  4. Utvärderare på konversationsnivå utvärderar de genererade konversationerna.
  5. Ditt projekt lagrar utvärderingsresultaten. Du kan också spara alla genererade konversationer som en version av Foundry-datauppsättningen.

Körningen använder datakällan azure_ai_user_conversation_simulation. Ange inställningar som gäller för varje testfall i default_simulation_configuration. Ett testfall kan åsidosätta enskilda konversationsinställningar i sitt simulation_configuration; inställningar som det inte åsidosätter fortsätter att använda standardinställningarna för körningen.

Förbereda scenariodata

Tips/Råd

I stället för att skapa scenarier för hand, generera dem med hjälp av uppgiftstypen Simulation seed (multi-turn). Innan du använder en befintlig genererad datauppsättning med det här API:et normaliserar du id till test_case_id och flyttar desired_num_turns till simulation_configuration. Se Generera en startdatauppsättning för simulering.

Ange testfall med någon av följande källtyper:

  • file_id eller file_content för JSONL-scenarier.
  • inline_user_conversation_simulation för starkt typerade testfall i körningsbegäran. Inkludera minst ett testfall.

För JSONL använder du de kanoniska egenskapsnamn som visas i följande exempel. Inkludera användarens mål, kontext och beteendebegränsningar i test_case_description. Beskrivningen kan innehålla mellan 1 och 2 500 tecken.

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

När JSONL-data använder dessa kanoniska namn utelämnar du data_mapping. Om den använder olika namn mappar du attributen till test_case_id, test_case_descriptionoch simulation_configuration. Använd inte data_mapping med en inline_user_conversation_simulation källa.

Varje inline-testfall eller JSONL-testfall stöder följande egenskaper:

Property Beskrivning
test_case_id Valfri identifierare. Tjänsten genererar en identifierare när du utelämnar den.
test_case_description Scenario, användarmål och beteendebegränsningar som vägleder den simulerade konversationen.
simulation_configuration Valfria inställningar som åsidosätter motsvarande körningsstandarder för det här testfallet.

Konfigurera den simulerade användaren

model_configuration Använd -objektet för att konfigurera den modell som spelar upp den simulerade användaren. Den här modellen är separat från den target modell eller agent som utvärderas.

Property Obligatoriskt Beskrivning
model Yes Distribution av simulator i {connectionName}/{modelDeploymentName}-format. Modellroutern stöds inte som simulatormodell. Det kan bara vara ett utvärderingsmål.
sampling_params No Samplingsparametrar som tillämpas när simulatorn genererar användarsvängningar.
voice_model No Konverterar simulerad användartext till tal via Voice Live-slutpunkten. Utelämna den här egenskapen för textsimulering.

För röstsimulering voice_model.type måste vara azure-standard. Ange name som namnet på en Azure-standardröst med neuralt tal. Du kan också ange temperature från 0 till 1. När det utelämnas gäller standardvärdet för den underliggande röstmodellen.

Konfigurera konversationer

Ange värden för hela körningen i default_simulation_configuration. Konversationskontrollerna max_num_turns, conversation_repetitions, desired_num_turns, audio_effects och user_behavior kan också förekomma i ett testfalls simulation_configuration för att åsidosätta motsvarande standardvärden för körningen. Egenskaper för datauppsättningsgenerering enable_conversation_dataset_generation och output_conversation_dataset_name är endast giltiga i default_simulation_configuration och kan inte åsidosättas per testfall.

Property Scope Standardinställning Beskrivning
max_num_turns Körnings- eller testfall 20 Fast gräns för antalet inlägg i varje konversation. Måste vara minst 1.
conversation_repetitions Körnings- eller testfall 1 Antal oberoende konversationer som genereras för varje testfall. Måste vara minst 1.
desired_num_turns Körnings- eller testfall None Mållängd för konversation. Det får inte överskrida det effektiva max_num_turns. När den utelämnas avgör simulatorn längden från scenariot.
audio_effects Körnings- eller testfall None Effekter som tillämpas på röstsimulering. Ignoreras för simulering med endast text.
user_behavior Körnings- eller testfall None Simulerat användarbeteende, till exempel avbrott.
enable_conversation_dataset_generation Kör endast false Bevarar alla genererade konversationer till en version av Foundry-datauppsättningen.
output_conversation_dataset_name Kör endast Genererad av tjänsten Datauppsättningsnamn som används när generering av konversationsdatauppsättning är aktiverat.

Konfigurera röstvillkor och avbrott

Placera audio_effects och user_behavior inuti default_simulation_configuration för att tillämpa dem på varje testfall. Om du vill åsidosätta endera inställningen för ett testfall placerar du den i testfallets simulation_configuration i stället.

Använd audio_effects för att testa hur målet presterar under realistiska lyssningsförhållanden. Lägg till en eller flera effekter: street_traffic, crowd_chatter, background_tv, metro_stationeller telephonic_voice. Ange volume_percentage från 1 till 100 för att styra den kombinerade volymen. Standardvärdet är 15. Ljudeffekter ignoreras i simuleringar med endast text.

Använd user_behavior.interruption för att testa hur målet hanterar en användare som talar medan målet svarar. Ange dess type till default för att aktivera simulerade avbrott. interruption Utelämna när avbrott inte ingår i testet.

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

Definiera utvärderare

Välj utvärderare som är utformade för utvärdering på konversationsnivå. De simulerade konversationerna mappas automatiskt till utvärderarna.

Om du vill utvärdera genererade röstinspelningar använder du en befintlig Foundry-röstagent som mål och anger voice_model i model_configuration. Ange enable_conversation_dataset_generation till true i default_simulation_configuration. Inkludera conversation_artifacts i utvärderingens objektschema. Konfigurera en ljudutvärderare utan data_mapping, enligt beskrivningen i Utvärdera inspelade röstkonversationer.

Simulatormodellen genererar användarvändor, rösten återger dem som tal, målagenten svarar och ljudutvärderaren poängsätter inspelningen. Ljudutvärderare använder en gpt-realtime family judge-distribution, så ge dem en annan distribution än alla textutvärderare i samma körning.

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

Skapa utvärderingen och kör

Spara de kanoniska JSONL-raderna från Förbered scenariodata som 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"},
)

Använd infogade testfall

Om du vill definiera scenarier direkt i körningsbegäran anger du data_source.source till en inline_user_conversation_simulation källa. Inlinekällor kräver minst ett testfall och använder inte 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}

Hämta genererade konversationer

Avfråga körningen tills den når ett sluttillstånd enligt beskrivningen i Hämta resultat för molnutvärdering. När enable_conversation_dataset_generation är true innehåller en slutförd körning en output_datasets-post som denna:

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

Använd den returnerade datamängden id, nameoch version för att hämta eller återanvända de genererade konversationerna. Om datamängdsgenereringen är inaktiverad output_datasets utelämnas.


Nästa steg