Microsoft Foundry SDK を使用してデプロイされたモデルとエージェントの会話を評価する (プレビュー)

Application Insights でキャプチャされた完全な運用会話を評価して、特定の対話やデプロイされたエージェント トラフィックのサンプルを調査します。

前提条件

  • クラウド評価の前提条件とクライアントのセットアップを完了します。
  • Application Insights でのトレースされた運用会話。
  • 選択した評価レベルをサポートする会話レベルのエバリュエーター。

この例では、「SDK クライアントのセットアップ」で構成された SDK クライアントを使用します。

トレースからの ID による会話の評価

Application Insights からの特定の会話を評価するために、会話 ID を指定します。 このオプションを使用して、問題の根本原因を特定したり、特定の対話に関する修正を確認したりします。 たとえば、アラートによってフラグ付けされた会話を調査したり、既知の問題の修正プログラムを確認したりできます。

会話 ID を検索する場所

会話 ID は次の中から検索できます。

  • Application Insights トレース ログ UI - 興味深いトレースを参照し、トレースの詳細で conversation_id フィールドを見つけます。
  • アプリケーションのログ出力 — エージェントの応答を作成するときに conversation_id を明示的に設定した場合は、ログから取得します。
  • OpenTelemetry トレース コンテキスト — エージェントが標準のトレース コンテキスト伝達を使用している場合、 conversation_id は traceparent ヘッダー から派生することもあります。

Note

ツール定義は、トレースから自動的に取得されるか、エージェント レジストリから照会されます。 要求で指定する必要はありません。

会話ID検索のパラメーター

パラメーター 必須 説明
conversation_ids はい 評価対象の会話IDの配列。
lookback_hours いいえ end_timeから遡って検索する時間数。 既定値は 7 日 (168 時間) です。
end_time いいえ 検索ウィンドウの末尾 (ISO 8601 形式)。 既定値は現在の時刻です。 
import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]
model_deployment_name = os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]

# Provide conversation IDs or trace IDs from App Insights
conversation_ids = ["conversation_1234", "conversation_5678"]

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    # Eval group for trace-based evaluations
    data_source_config = {
        "type": "azure_ai_source",
        "scenario": "traces",
    }

    testing_criteria = [
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="conversation_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}}"},
        ),
    ]

    # Create evaluation with traces scenario
    eval_object = openai_client.evals.create(
        name="Multi-turn Trace Evaluation (by ID)",
        data_source_config=data_source_config,
        testing_criteria=testing_criteria,
    )

    # Run evaluation on specific conversation IDs
    eval_run = openai_client.evals.runs.create(
        eval_id=eval_object.id,
        name="multiturn-trace-by-id-run",
        data_source={
            "type": "azure_ai_trace_data_source_preview",
            "trace_source": {
                "type": "conversation_id_source",
                "conversation_ids": conversation_ids,
            },
        },
        extra_body={"evaluation_level": "conversation"},
    )

Note

  • Application Insights のデータ インジェストにより、トレースが生成されてから評価に使用できるようになるまでの間に遅延が発生する可能性があります。 クエリでトレースが見つからない場合は、数分待ってから再試行してください。
  • 最大ルックバックは 7 日 (168 時間) です。 古いトレースにアクセスするには、App Insights の保持制限内で start_time と end_time を使用します。

実行可能な完全な例については、GitHubのsample_multiturn_trace_evaluation_by_id.pyを参照してください。

エージェント フィルターによるサンプリングされた会話の評価

エージェント名をフィルター処理して、Application Insights からサンプリングされた会話のセットを評価します。 このオプションを使用して、運用トラフィック全体のエージェントの全体的な品質を評価します。 たとえば、定期的な品質評価を実行したり、運用環境での品質低下を監視したりします。

フィルター処理に指定するエージェントは、マルチエージェント会話の一部にすることができます。 このフィルターは、そのエージェントが参加したすべての会話と一致します。

Note

ツール定義は、トレースから自動的に取得されるか、エージェント レジストリから照会されます。 要求で指定する必要はありません。

エージェント ID フィールド

次のいずれかの形式を使用して、フィルター処理するエージェントを指定します。

Format Example 説明
agent_name + agent_version "agent_name": "my-agent", "agent_version": "1" 2 つの異なるフィールド。 agent_versionを省略した場合は、最新バージョンを使用します。
agent_id "agent_id": "my-agent:1" "name:version"形式の 1 つの文字列。

フィルター戦略

戦略 説明
random_sampling (既定値) 最大 max_traces 件の会話を一様ランダムにサンプリングします。
smart_filtering 潜在的な問題、エッジケース、または異常を含む会話などの「興味深い」トレースを優先する傾向のある、サービス管理型ヒューリスティック。

Parameters

パラメーター 必須 説明
agent_name はい トレースをフィルター処理するエージェント名。
agent_version いいえ エージェントのバージョン。 省略した場合は、最新バージョンを使用します。
agent_id いいえ agent_name + agent_versionに代わるもの。 "name:version"形式の 1 つの文字列。
start_time はい 時間ウィンドウの開始（Unixエポック秒数、UTC）。
end_time はい 時間ウィンドウの終了（Unixエポック秒数、UTC）。 取り込みの遅延を避けるため、+600秒の余裕を持たせます。
max_traces いいえ サンプリングする最大会話数。 既定値は 1,000 です。
filter_strategy いいえ "random_sampling" (既定) または "smart_filtering" (関心のあるトレースに偏るサービス管理ヒューリスティック)。

Important

時間枠 (end_time - start_time) は 、少なくとも 15 分 (900 秒) である必要があります。 この要件が存在するのは、会話レベルのクエリでは、部分的な会話を回避するために、各エッジに 5 分間の非アクティブ バッファーが適用されるためです。

import os
import time
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]
model_deployment_name = os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
agent_name = os.environ["FOUNDRY_AGENT_NAME"]
agent_version = os.environ.get("FOUNDRY_AGENT_VERSION", "")

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    # Eval group for trace-based evaluations
    data_source_config = {
        "type": "azure_ai_source",
        "scenario": "traces",
    }

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

    eval_object = openai_client.evals.create(
        name="Multi-turn Trace Evaluation (Agent Filter)",
        data_source_config=data_source_config,
        testing_criteria=testing_criteria,
    )

    # Compute time window in unix seconds
    # Pad end_time by +600s (10 min) to avoid ingestion-delay edge exclusion
    now_unix = int(time.time())
    end_time = now_unix + 600
    start_time = now_unix - (24 * 3600)  # 24 hours lookback

    # Build trace_source with agent filter
    trace_source = {
        "type": "agent_filter",
        "agent_name": agent_name,
        "start_time": start_time,
        "end_time": end_time,
        "max_traces": 5,
    }
    if agent_version:
        trace_source["agent_version"] = agent_version

    # Run evaluation on sampled agent conversations
    eval_run = openai_client.evals.runs.create(
        eval_id=eval_object.id,
        name="multiturn-agent-filter-run",
        data_source={
            "type": "azure_ai_trace_data_source_preview",
            "trace_source": trace_source,
        },
        extra_body={"evaluation_level": "conversation"},
    )

Note

App Insights クエリの期間は現在、最大 7 日間 (168 時間) に制限されています。 App Insights の保持制限内で start_time と end_time を明示的に指定しないと、7 日より前のトレースにアクセスすることはできません。

次のステップ

  • Last updated on