Simulieren von Unterhaltungen mit dem Microsoft Foundry SDK

Generieren Sie simulierte Unterhaltungen aus Szenariobeschreibungen, und bewerten Sie sie auf Unterhaltungsebene. Verwenden Sie dieses Szenario, um das Verhalten Ihres Agents in kontrollierten Situationen vor der Bereitstellung zu testen. Der Dienst generiert realistische Unterhaltungen basierend auf Ihren Szenariobeschreibungen und wertet sie dann aus.

Voraussetzungen

In den Beispielen wird der in SDK-Client einrichten konfigurierte SDK-Client verwendet.

Gesprächssimulation verstehen

Dieser Ansatz ist nützlich für:

  • Tests vor der Bereitstellung: Überprüfen des Agentverhaltens in verschiedenen Szenarien ohne echten Benutzerdatenverkehr.
  • Abdeckung von Grenzfällen: Testszenarien, die in der Praxis nur selten auftreten, jedoch gut gehandhabt werden müssen.
  • Regressionstests: Stellen Sie sicher, dass Agentupdates die Leistung in bekannten Szenarien nicht beeinträchtigen.
  • Tests im großen Maßstab: Generieren Sie schnell viele Konversationen, um die Fähigkeiten des Agenten einem Belastungstest zu unterziehen.

Die Unterhaltungssimulation führt die folgenden Schritte aus:

  1. Sie stellen Szenariobeschreibungen als JSONL-Daten oder stark typierte Inlinetestfälle bereit. Jeder Testfall beschreibt eine Situation, die der simulierte Benutzer zu erreichen versucht.
  2. Der Dienst verwendet ein Simulatormodell, um die Rolle des Benutzers zu spielen und basierend auf dem Szenario mit Ihrem Agent zu interagieren.
  3. Jedes Szenario generiert eine oder mehrere vollständige Unterhaltungen.
  4. Bewerter auf der Ebene ganzer Konversationen bewerten die generierten Konversationen.
  5. Ihr Projekt speichert die Auswertungsergebnisse. Sie können optional alle generierten Unterhaltungen als versionsbasiertes Foundry-Dataset speichern.

Die Ausführung verwendet die azure_ai_user_conversation_simulation Datenquelle. Legen Sie Einstellungen fest, die für jeden Testfall gelten.default_simulation_configuration Ein Testfall kann einzelne Konversationseinstellungen in simulation_configuration überschreiben; Einstellungen, die er nicht überschreibt, verwenden weiterhin die Standardwerte des Durchlaufs.

Vorbereiten von Szenariodaten

Tip

Statt Szenarien manuell zu erstellen, generieren Sie sie mithilfe des Aufgabentyps Simulations-Seed (Multi-Turn). Bevor Sie einen vorhandenen generierten Datensatz mit dieser API verwenden, normalisieren Sie id auf test_case_id und verschieben Sie desired_num_turns nach simulation_configuration. Siehe Ein Seed-Dataset für eine Simulation generieren.

Stellen Sie Testfälle mithilfe eines der folgenden Quelltypen bereit:

  • file_id oder file_content für JSONL-Szenarien.
  • inline_user_conversation_simulation für stark typisierte Testfälle in der Anforderung zum Ausführen. Schließen Sie mindestens einen Testfall ein.

Verwenden Sie für JSONL die kanonischen Eigenschaftennamen, die im folgenden Beispiel gezeigt werden. Schließen Sie das Ziel, den Kontext und die Verhaltenseinschränkungen des Benutzers in test_case_descriptionein. Die Beschreibung kann 1 bis 2.500 Zeichen enthalten.

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

Wenn die JSONL-Daten diese kanonischen Namen verwenden, lassen Sie data_mapping weg. Wenn sie unterschiedliche Namen verwendet, ordnen Sie diese Attribute zu test_case_id, test_case_descriptionund simulation_configuration. Verwenden Sie nicht data_mapping mit einer inline_user_conversation_simulation Quelle.

Jeder Inline- oder JSONL-Testfall unterstützt die folgenden Eigenschaften:

Eigenschaft Beschreibung
test_case_id Optionaler Bezeichner. Der Dienst generiert einen Bezeichner, wenn Sie ihn weglassen.
test_case_description Szenario, Benutzerziel und Verhaltenseinschränkungen, die die simulierte Unterhaltung leiten.
simulation_configuration Optionale Einstellungen, die die entsprechenden Ausführungsstandards für diesen Testfall außer Kraft setzen.

Konfigurieren des simulierten Benutzers

Verwenden Sie das model_configuration Objekt, um das Modell zu konfigurieren, das den simulierten Benutzer wiedergibt. Dieses Modell unterscheidet sich vom target zu bewertenden Modell oder Agent.

Eigenschaft Erforderlich Beschreibung
model Ja Bereitstellung des Simulators im {connectionName}/{modelDeploymentName}-Format. Der Modellrouter wird nicht als Simulatormodell unterstützt. es kann nur ein Auswertungsziel sein.
sampling_params No Sampling-Parameter, die angewendet werden, wenn der Simulator Benutzerdurchgänge generiert.
voice_model No Konvertiert simulierten Benutzertext mithilfe des Voice-Live-Endpunkts in gesprochene Sprache. Lassen Sie diese Eigenschaft für die Nur-Text-Simulation aus.

Für die Sprachsimulation muss voice_model.typeazure-standard sein. Festlegen name auf einen Azure standardmäßigen neuralen Sprachnamen. Sie können auch temperature auf einen Wert von 0 bis 1 festlegen; wenn kein Wert angegeben wird, wird der Standardwert des zugrunde liegenden Sprachmodells verwendet.

Konfigurieren von Unterhaltungen

Legen Sie Werte für die gesamte Ausführung in default_simulation_configuration fest. Die Konversationssteuerungen max_num_turns, conversation_repetitions, desired_num_turns, audio_effects und user_behavior können auch im simulation_configuration eines Testfalls enthalten sein, um die entsprechenden Standardwerte für die Ausführung zu überschreiben. Die Eigenschaften zur Datensatzgenerierung enable_conversation_dataset_generation und default_simulation_configuration sind nur in output_conversation_dataset_name gültig und können nicht für jeden Testfall überschrieben werden.

Eigenschaft Geltungsbereich Voreinstellung Beschreibung
max_num_turns Ausführungs- oder Testfall 20 Feste Begrenzung der Durchgänge in jeder Unterhaltung. Die Anzahl muss mindestens 1 sein.
conversation_repetitions Ausführungs- oder Testfall 1 Die Anzahl der unabhängigen Unterhaltungen, die für jeden Testfall generiert wurden. Die Anzahl muss mindestens 1 sein.
desired_num_turns Ausführungs- oder Testfall Nichts Gewünschte Gesprächslänge. Es kann die effektive max_num_turns nicht überschreiten. Wenn sie weggelassen wird, bestimmt der Simulator die Länge aus dem Szenario.
audio_effects Ausführungs- oder Testfall Nichts Effekte, die auf die Sprachsimulation angewendet werden. Wird für die Nur-Text-Simulation ignoriert.
user_behavior Ausführungs- oder Testfall Nichts Simuliertes Benutzerverhalten, z. B. Unterbrechungen.
enable_conversation_dataset_generation Run only (Nur ausführen) false Speichert alle generierten Unterhaltungen in einem versionierten Foundry-Dataset.
output_conversation_dataset_name Run only (Nur ausführen) Vom Dienst generiert Name des Datensatzes, der verwendet wird, wenn die Generierung von Konversationsdatensätzen aktiviert ist.

Konfigurieren von Sprachbedingungen und Unterbrechungen

Platzieren audio_effects und user_behavior innen default_simulation_configuration , um sie auf jeden Testfall anzuwenden. Wenn Sie eine der beiden Einstellungen für einen Testfall außer Kraft setzen möchten, platzieren Sie sie stattdessen in diesem Testfall simulation_configuration .

Verwenden Sie audio_effects, um zu testen, wie sich das Prüfobjekt unter realistischen Hörbedingungen verhält. Fügen Sie einen oder mehrere Effekte hinzu: street_traffic, , crowd_chatter, background_tv, , metro_stationoder telephonic_voice. Legen Sie volume_percentage zwischen 1 und 100 fest, um ihr kombiniertes Volumen zu steuern. Der Standardwert lautet 15. Audioeffekte werden in reinen Textsimulationen ignoriert.

Verwenden Sie user_behavior.interruption, um zu testen, wie das Zielsystem damit umgeht, dass ein Benutzer spricht, während das Zielsystem antwortet. Setzen Sie type auf default, um simulierte Unterbrechungen zu aktivieren. Lassen Sie aus interruption , wenn Unterbrechungen nicht Teil des Tests sind.

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

Bewerter definieren

Wählen Sie Evaluatoren aus, die für Bewertungen auf Konversationsebene entwickelt wurden. Die simulierten Unterhaltungen werden automatisch den Bewertern zugeordnet.

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

Erstellen der Auswertung und Ausführung

Speichern Sie die kanonischen JSONL-Zeilen aus "Szenariodaten vorbereiten " 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-Testfälle verwenden

Wenn Sie Szenarien direkt in der Ausführungsanforderung definieren möchten, legen Sie diese auf eine inline_user_conversation_simulation Quelle festdata_source.source. Inline-Quellen erfordern mindestens einen Testfall und verwenden data_mapping nicht.

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}

Generierte Unterhaltungen abrufen

Rufen Sie die Ausführung ab, bis sie einen Terminalstatus erreicht, wie unter "Cloudauswertungsergebnisse abrufen" beschrieben. Wenn enable_conversation_dataset_generation auf true gesetzt ist, enthält ein abgeschlossener Durchlauf einen output_datasets-Eintrag wie diesen hier:

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

Verwenden Sie den zurückgegebenen Datensatz id, name und version, um die generierten Konversationen abzurufen oder wiederzuverwenden. Wenn die Generierung von Datensätzen deaktiviert ist, wird output_datasets ausgelassen.

Nächste Schritte

  • Zuletzt aktualisiert um