模擬使用 Microsoft Foundry SDK 進行對話

從情境描述中產生模擬對話,並在對話層級進行評估。 利用此情境測試代理在受控情境下的行為,然後再部署。 該服務會根據你的情境描述產生真實的對話,然後進行評估。

先決條件

範例中使用了在 「設定 SDK 客戶端」中設定的 SDK 客戶端。

瞭解對話模擬

此方法適用於:

  • 部署前測試:驗證代理在不同情境下的行為,無需真實用戶流量。
  • 邊緣案例涵蓋範圍:測試自然很少發生但需要妥善處理的重要案例。
  • 迴歸測試:確保代理更新不會在已知情境下降低效能。
  • 規模化測試:快速產生大量對話,對代理的能力進行壓力測試。

對話模擬遵循以下步驟:

  1. 你可以將情境描述以 JSONL 資料或強型別內嵌測試案例的形式提供。 每個測試案例描述模擬使用者嘗試達成的情境。
  2. 該服務使用模擬器模型扮演使用者的角色,根據情境與你的代理互動。
  3. 每個情境都會產生一個或多個完整的對話。
  4. 對話層級評估器會評估生成的對話。
  5. 你的專案會儲存評估結果。 你可以選擇性地將所有產生的對話持續保存為版本化的 Foundry 資料集。

這次執行使用的是 azure_ai_user_conversation_simulation 資料來源。 將適用於每個測試案例的設定放在 default_simulation_configuration 中。 測試案例可以在其 simulation_configuration 中覆寫各個對話設定;未被覆寫的設定則會繼續使用執行的預設值。

準備情境資料

小提示

與其手動撰寫情境,不如使用 模擬種子(多回合) 任務類型來生成。 在使用此 API 使用現有產生的資料集前,先將正規化 id 為 test_case_id 並移 desired_num_turns 入 simulation_configuration。 參見 「產生模擬種子資料集」。

透過以下來源類型之一提供測試案例:

  • file_id 或 file_content 用於 JSONL 情境。
  • inline_user_conversation_simulation 用於執行要求中的強型別測試案例。 至少包含一個測試案例。

對於 JSONL,請使用以下範例所示的典型屬性名稱。 將使用者的目標、上下文及行為限制納入 test_case_description。 描述可包含1至2,500字元。

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

當 JSONL 資料使用這些典型名稱時,省略 data_mapping。 如果使用不同名稱,則將這些屬性映射為 test_case_id、 test_case_description和 simulation_configuration。 不要將 data_mapping 與 inline_user_conversation_simulation 來源搭配使用。

每個內嵌或 JSONL 測試案例都支援以下特性:

屬性 說明
test_case_id 可選識別碼。 當你省略時,服務會產生一個識別碼。
test_case_description 情境、使用者目標,以及引導模擬對話的行為限制。
simulation_configuration 可選設定可覆蓋此測試案例對應的執行預設值。

設定模擬使用者

用這個 model_configuration 物件來設定扮演模擬使用者的模型。 此模型與 target 被評估的模型或代理人是分開的。

屬性 Required 說明
model Yes 以 {connectionName}/{modelDeploymentName} 格式部署模擬器。 模型 路由器 不支援作為模擬器模型;它只能成為評估目標。
sampling_params No 模擬器產生使用者輪次時所套用的取樣參數。
voice_model No 透過 Voice Live 端點將模擬使用者文字轉換為語音。 僅用文字模擬時省略此特性。

若要進行語音模擬,voice_model.type 必須為 azure-standard。 設定name為 Azure 標準神經語音名稱。 你也可以設定 temperature 0 到 1;若省略,則會依底層語音模型的預設值設定。

設定對話

在 default_simulation_configuration 中設定整個執行範圍的值。 對話控制項 max_num_turns、conversation_repetitions、desired_num_turns、audio_effects 和 user_behavior 也可以出現在測試案例的 simulation_configuration 中,以覆寫對應的執行預設值。 資料集生成屬性 enable_conversation_dataset_generation 和 output_conversation_dataset_name 僅在 default_simulation_configuration 中有效,且無法針對個別測試案例覆寫。

屬性 Scope 預設 說明
max_num_turns 執行或測試案例 20 每場對話的回合都嚴格限制。 必須至少為 1。
conversation_repetitions 執行或測試案例 1 每個測試案例產生的獨立對話數量。 必須至少為 1。
desired_num_turns 執行或測試案例 None 目標對話長度。 不得超過實際生效的 max_num_turns 值。 若省略,模擬器會根據情境決定其長度。
audio_effects 執行或測試案例 None 套用於語音模擬的效果 純文字模擬時會忽略。
user_behavior 執行或測試案例 None 模擬使用者行為,例如中斷。
enable_conversation_dataset_generation 僅限執行 false 將所有產生的對話持續保存到版本化的 Foundry 資料集。
output_conversation_dataset_name 僅限執行 由服務產生 啟用對話資料集產生時所使用的資料集名稱。

設定語音狀態與中斷

將 audio_effects 和 user_behavior 放在 default_simulation_configuration 內,以將它們套用至每個測試案例。 若要針對單一測試案例覆寫其中任一設定,請改為將其放在該測試案例的 simulation_configuration 內。

用 audio_effects 來測試目標在真實聽覺條件下的表現。 加入一個或多個效果:street_traffic、metro_stationcrowd_chatterbackground_tv或。telephonic_voice 設定 volume_percentage 從 1 到 100 來控制它們的總音量。 預設值為 15。 純文字模擬中忽略了音效效果。

用 user_behavior.interruption 來測試目標在回應時如何處理使用者的語音。 將其 type 設為 default,以啟用模擬中斷。 如果打斷不是考試的一部分,就省略 interruption 。

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

定義評估者

選擇專為對話層級評估設計的評估器。 模擬對話會自動映射至評估者。

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

建立評估並執行

將 Prepare scenario data 的標準 JSONL 列儲存為 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"},
)

使用線上測試案例

若要在執行請求中直接定義情境,請設 data_source.source 為 inline_user_conversation_simulation 來源。 內嵌來源至少需要一個測試案例,且不使用 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}

取得生成的對話

輪詢該執行,直到其達到如 取得雲端評估結果 中所述的終止狀態。 當 enable_conversation_dataset_generation 設為 true 時,已完成的執行會包含如下的 output_datasets 項目:

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

使用回傳的資料集 id、name 和 version,來擷取或重複使用生成的對話。 若資料集產生被停用,則 output_datasets 省略。


下一步