Gesprekken simuleren met de Microsoft Foundry SDK

Genereer gesimuleerde gesprekken op basis van scenariobeschrijvingen en evalueer deze op gespreksniveau. Gebruik dit scenario om het gedrag van uw agent te testen in gecontroleerde situaties vóór de implementatie. De service genereert realistische gesprekken op basis van uw scenariobeschrijvingen en evalueert deze vervolgens.

Prerequisites

In de voorbeelden wordt de SDK-client gebruikt die is geconfigureerd in de SDK-client instellen.

Informatie over gesprekssimulatie

Deze methode is handig voor:

  • Testen vóór de implementatie: Valideer het gedrag van agents in diverse scenario's zonder echt gebruikersverkeer.
  • Dekking van randgevallen: Testscenario's die zich in de praktijk zelden voordoen, maar die wel goed moeten worden afgehandeld.
  • Regressietests: Zorg ervoor dat agentupdates de prestaties van bekende scenario's niet verminderen.
  • Testen op schaal: Genereer snel veel gesprekken om de mogelijkheden van de agent op de proef te stellen.

Gesprekssimulatie volgt deze stappen:

  1. U geeft scenariobeschrijvingen in de vorm van JSONL-data of sterk getypeerde inline testcases. Elke testcase beschrijft een situatie waarin de gesimuleerde gebruiker probeert te bereiken.
  2. De service maakt gebruik van een simulatormodel om de rol van de gebruiker te spelen, waarbij interactie met uw agent wordt uitgevoerd op basis van het scenario.
  3. Elk scenario genereert een of meer volledige gesprekken.
  4. Evaluators op gespreksniveau beoordelen de gegenereerde gesprekken.
  5. In uw project worden de evaluatieresultaten opgeslagen. U kunt eventueel alle gegenereerde gesprekken opslaan als een Foundry-dataset met versiebeheer.

De uitvoering maakt gebruik van de azure_ai_user_conversation_simulation gegevensbron. Instellingen plaatsen die van toepassing zijn op elke testcase in default_simulation_configuration. Een testcase kan afzonderlijke instellingen voor gesprekken in de eigen simulation_configuration overschrijven; instellingen die niet worden overschreven, blijven de standaardinstellingen van de uitvoering gebruiken.

Scenariogegevens voorbereiden

Tip

In plaats van scenario's handmatig te ontwerpen, genereer ze met het taaktype simulatiezaad (multi-turn). Voordat u een bestaande gegenereerde dataset met deze API gebruikt, normaliseert u id naar test_case_id en verplaatst u desired_num_turns naar simulation_configuration. Zie Een seedgegevensset voor simulatie genereren.

Testcases leveren met behulp van een van deze brontypen:

  • file_id of file_content voor JSONL-scenario's.
  • inline_user_conversation_simulation voor strikt getypeerde testgevallen in het uitvoerverzoek. Neem ten minste één testcase op.

Gebruik voor JSONL de canonieke eigenschapsnamen die worden weergegeven in het volgende voorbeeld. Neem het doel, de context en gedragsbeperkingen van de gebruiker op in test_case_description. De beschrijving mag 1 tot 2500 tekens bevatten.

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

Wanneer de JSONL-gegevens deze canonieke namen gebruiken, laat u data_mapping weg. Als er verschillende namen worden gebruikt, wijst u deze kenmerken toe aan test_case_id, test_case_descriptionen simulation_configuration. Gebruik niet data_mapping met een inline_user_conversation_simulation bron.

Elke inline- of JSONL-testcase ondersteunt deze eigenschappen:

Property Beschrijving
test_case_id Optionele id. De service genereert een id wanneer u deze weglaat.
test_case_description Scenario, gebruikersdoel en gedragsbeperkingen die het gesimuleerde gesprek begeleiden.
simulation_configuration Optionele instellingen die de bijbehorende standaardinstellingen voor de uitvoering van dit testgeval overschrijven.

De gesimuleerde gebruiker configureren

Gebruik het model_configuration object om het model te configureren dat de gesimuleerde gebruiker afspeelt. Dit model staat los van het model of de target agent die wordt geëvalueerd.

Property Required Beschrijving
model Ja Simulatorimplementatie in {connectionName}/{modelDeploymentName} indeling. De modelrouter wordt niet ondersteund als het simulatormodel; het kan alleen een evaluatiedoel zijn.
sampling_params No Samplingparameters die worden toegepast wanneer de simulator gebruikersbeurten genereert.
voice_model No Converteert gesimuleerde gebruikerstekst naar spraak via het Voice Live-eindpunt. Laat deze eigenschap weg voor alleen-tekstsimulatie.

Voor spraaksimulatie moet voice_model.typeazure-standard zijn. Stel name in op de naam van een standaard neurale Azure-stem. U kunt ook 0 tot en met 1 instellen temperature . Als u dit weglaat, is de standaardinstelling van het onderliggende spraakmodel van toepassing.

Gesprekken configureren

Waarden voor de hele uitvoering instellen in default_simulation_configuration. De gespreksbesturingselementen max_num_turns, conversation_repetitions, desired_num_turns, audio_effects en user_behavior kunnen ook voorkomen in de simulation_configuration van een testcase om de bijbehorende standaardinstellingen voor de uitvoering te overschrijven. De eigenschappen enable_conversation_dataset_generation van het genereren van gegevenssets en output_conversation_dataset_name zijn alleen geldig in default_simulation_configuration en kunnen niet per testcase worden overschreven.

Property Bereik Default Beschrijving
max_num_turns Testgeval uitvoeren of testen 20 Harde limiet op het aantal beurten in elk gesprek. Moet ten minste 1 zijn.
conversation_repetitions Testgeval uitvoeren of testen 1 Het aantal onafhankelijke gesprekken dat voor elke testcase is gegenereerd. Moet ten minste 1 zijn.
desired_num_turns Testgeval uitvoeren of testen Geen Doelgespreklengte. Het kan de effectieve max_num_turnswaarde niet overschrijden. Wanneer u dit weglaat, bepaalt de simulator de lengte van het scenario.
audio_effects Testgeval uitvoeren of testen Geen Effecten die zijn toegepast op spraaksimulatie. Genegeerd voor alleen-tekstsimulatie.
user_behavior Testgeval uitvoeren of testen Geen Gesimuleerd gebruikersgedrag, zoals onderbreking.
enable_conversation_dataset_generation Alleen uitvoeren false Slaat alle gegenereerde gesprekken op in een Foundry-gegevensset met versiebeheer.
output_conversation_dataset_name Alleen uitvoeren Gegenereerd door de service Naam van de dataset die wordt gebruikt wanneer het genereren van conversatiedatasets is ingeschakeld.

Spraakvoorwaarden en onderbrekingen configureren

Plaats audio_effects en user_behavior binnen default_simulation_configuration om ze toe te passen op elke testcase. Als u een van beide instellingen voor één testcase wilt overschrijven, plaatst u die instelling in plaats daarvan binnen de simulation_configuration van die testcase.

Gebruik audio_effects om te testen hoe het doelobject presteert onder realistische luisteromstandigheden. Voeg een of meer effecten toe: street_traffic, crowd_chatter, background_tv, metro_stationof telephonic_voice. Stel volume_percentage in op een waarde van 1 tot en met 100 om hun gezamenlijke volume te regelen. De standaardwaarde is 15. Audio-effecten worden genegeerd in alleen-tekstsimulaties.

Gebruik user_behavior.interruption om te testen hoe het doelsysteem omgaat met een gebruiker die spreekt terwijl het doelsysteem antwoord geeft. Stel de waarde ervan type op default in om gesimuleerde onderbrekingen in te schakelen. Weglaten interruption wanneer onderbrekingen geen deel uitmaken van de test.

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

Evaluatoren definiëren

Selecteer evaluators die zijn ontworpen voor evaluatie op gespreksniveau. De gesimuleerde gesprekken worden automatisch gekoppeld aan de beoordelaars.

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

De evaluatie maken en uitvoeren

Sla de canonieke JSONL-rijen op uit scenariogegevens voorbereiden als 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"},
)

Inline testgevallen gebruiken

Als u scenario's rechtstreeks in de uitvoeringsaanvraag wilt definiëren, stelt u data_source.source in op een inline_user_conversation_simulation-bron. Inline-bronnen vereisen ten minste één testgeval en gebruik geen 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}

Gegenereerde gesprekken opvragen

Peil de uitvoering totdat deze de terminalstatus bereikt, zoals beschreven in resultaten van cloudevaluatie ophalen. Wanneer enable_conversation_dataset_generation is true, bevat een voltooide uitvoering een output_datasets vermelding zoals deze:

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

Gebruik de geretourneerde gegevensset idnameen version om de gegenereerde gesprekken op te halen of opnieuw te gebruiken. Als het genereren van datasets is uitgeschakeld, wordt output_datasets weggelaten.

Volgende stappen 

  • Laatst bijgewerkt om