次の方法で共有

Microsoft Foundry SDK を使用してクラウドで評価を実行する

Important

この記事で "(プレビュー)" と付記されている項目は、現在、パブリック プレビュー段階です。 このプレビューはサービス レベル アグリーメントなしで提供されており、運用環境ではお勧めしません。 特定の機能はサポート対象ではなく、機能が制限されることがあります。 詳細については、「 Microsoft Azure プレビューの追加使用条件」を参照してください。

この記事では、テスト データセットで事前デプロイ テスト用の評価をクラウド (プレビュー) で実行する方法について説明します。

ほとんどのシナリオでクラウド評価を使用します。特に、大規模なテスト、継続的インテグレーションと継続的デリバリー (CI/CD) パイプラインへの評価の統合、またはデプロイ前テストの実行を行う場合に使用します。 クラウドで評価を実行すると、ローカル コンピューティング インフラストラクチャを管理する必要がなくなり、大規模な自動テスト ワークフローがサポートされます。 評価を定期的に実行するように スケジュール したり、運用環境でサンプリングされたエージェントの応答を自動的に評価するように 継続的な評価 を設定したりすることもできます。

クラウド評価結果は Foundry プロジェクトに格納されます。 ポータルで結果を確認したり、SDK を使用して結果を取得したり、接続されている場合は Application Insights にルーティングしたりできます。 クラウド評価では、Microsoft によってキュレーションされたすべての 組み込みエバリュエーター と独自の カスタム エバリュエーターがサポートされます。 エバリュエーターは、同じプロジェクト スコープのロールベースのアクセス制御を使用してエ バリュエーター カタログ で管理されます。

ヒント

実行可能な完全な例については、GitHub の Python SDK 評価サンプル を参照してください。

Foundry SDK を使用すると、評価結果が Foundry プロジェクトに記録され、観測性が向上します。 この機能は、Microsoft によってキュレーションされたすべての 組み込みエバリュエーターをサポートします。 と独自の カスタム エバリュエーター。 エバリュエーターは エバリュエーター ライブラリ に配置でき、同じプロジェクト スコープのロールベースのアクセス制御を持つことができます。

クラウド評価のしくみ

クラウド評価を実行するには、データ スキーマとテスト条件 (エバリュエーター) を使用して評価定義を作成し、評価実行を作成します。 この実行では、データに対して各エバリュエーターが実行され、スコア付けされた結果が返され、完了をポーリングできます。

クラウド評価では、次のシナリオがサポートされています。

Scenario いつ使用するか データ ソースの種類 目標
データセットの評価 JSONL ファイルで事前に計算された応答を評価します。 jsonl —
モデル ターゲットの評価 評価のために、実行時にクエリを提供し、モデルからの応答を生成します。 azure_ai_target_completions azure_ai_model
エージェント ターゲットの評価 実行時に評価のために、クエリを提供し、Foundry エージェントからの応答を生成します。 azure_ai_target_completions azure_ai_agent
エージェントの応答の評価 応答 ID を使用して Foundry エージェントの応答を取得および評価します。 azure_ai_responses —
赤いチームの評価 モデルまたはエージェントに対して自動敵対的テストを実行します。 azure_ai_red_team azure_ai_model または azure_ai_agent

ほとんどのシナリオでは、入力データが必要です。 データは、次の 2 つの方法で提供できます。

ソースの種類 [説明]
file_id アップロードされたデータセットを ID で参照します。
file_content 要求でデータをインラインで指定します。

すべての評価には、データに必要なフィールドをサービスに指示する data_source_config が必要です。

  • custom — フィールド名と型を使用して item_schema を定義します。 エバリュエーターが生成された応答を参照できるように、ターゲットを使用するときに include_sample_schema を true に設定します。
  • azure_ai_source — スキーマはサービスから推論されます。 "scenario"をエージェント応答評価の場合は"responses"、"red_team"の場合はに設定します。

各シナリオには、テスト条件を定義するエバリュエーターが必要です。 エバリュエーターの選択に関するガイダンスについては、 組み込みのエバリュエーターを参照してください。

[前提条件]

注

一部の評価機能には、地域的な制限があります。 詳細については 、サポートされているリージョン を参照してください。

概要

SDK をインストールし、クライアントを設定します。

pip install "azure-ai-projects>=2.0.0b1" azure-identity openai

import os
from azure.identity import DefaultAzureCredential 
from azure.ai.projects import AIProjectClient 
from openai.types.eval_create_params import DataSourceConfigCustom
from openai.types.evals.create_eval_jsonl_run_data_source_param import (
    CreateEvalJSONLRunDataSourceParam,
    SourceFileContent,
    SourceFileContentContent,
    SourceFileID,
)

# Azure AI Project endpoint
# Example: https://<account_name>.services.ai.azure.com/api/projects/<project_name>
endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]

# Model deployment name (for AI-assisted evaluators)
# Example: gpt-5-mini
model_deployment_name = os.environ.get("AZURE_AI_MODEL_DEPLOYMENT_NAME", "")

# Dataset details (optional, for reusing existing datasets)
dataset_name = os.environ.get("DATASET_NAME", "")
dataset_version = os.environ.get("DATASET_VERSION", "1")

# Create the project client
project_client = AIProjectClient( 
    endpoint=endpoint, 
    credential=DefaultAzureCredential(), 
)

# Get the OpenAI client for evaluation API
client = project_client.get_openai_client()

入力データを準備する

ほとんどの評価シナリオでは、入力データが必要です。 データは、次の 2 つの方法で提供できます。

JSONL ファイルをアップロードして、Foundry プロジェクトにバージョン管理されたデータセットを作成します。 データセットでは、複数の評価実行でのバージョン管理と再利用がサポートされています。 このアプローチは、運用テストと CI/CD ワークフローに使用します。

エバリュエーターが必要とするフィールドを含む JSON オブジェクトを 1 行に 1 つ含む JSONL ファイルを準備します。

{"query": "What is machine learning?", "response": "Machine learning is a subset of AI.", "ground_truth": "Machine learning is a type of AI that learns from data."}
{"query": "Explain neural networks.", "response": "Neural networks are computing systems inspired by biological neural networks.", "ground_truth": "Neural networks are a set of algorithms modeled after the human brain."}

# Upload a local JSONL file. Skip this step if you already have a dataset registered.
data_id = project_client.datasets.upload_file(
    name=dataset_name,
    version=dataset_version,
    file_path="./evaluate_test_data.jsonl",
).id

データをインラインで提供する

小規模なテスト セットを使用して迅速に実験を行う場合は、 file_contentを使用して評価要求に直接データを提供します。

source = SourceFileContent(
    type="file_content",
    content=[
        SourceFileContentContent(
            item={
                "query": "How can I safely de-escalate a tense situation?",
                "ground_truth": "Encourage calm communication, seek help if needed, and avoid harm.",
            }
        ),
        SourceFileContentContent(
            item={
                "query": "What is the largest city in France?",
                "ground_truth": "Paris",
            }
        ),
    ],
)

実行を作成する際、データ ソース構成のsourceフィールドとして"source"を渡してください。 以下のシナリオ セクションでは、既定で file_id を使用します。

データセットの評価

jsonl データ ソースの種類を使用して、JSONL ファイルで事前に計算された応答を評価します。 このシナリオは、モデルの出力が既にあり、その品質を評価する場合に便利です。

ヒント

開始する前に、「 はじめに」 と 「入力データを準備する」を完了してください。

データ スキーマとエバリュエーターを定義する

JSONL フィールドに一致するスキーマを指定し、実行するエバリュエーター (テスト条件) を選択します。 data_mapping パラメーターを使用して、入力データのフィールドを、{{item.field}}構文を使用してエバリュエーター パラメーターに接続します。 各エバリュエーターに必要な入力フィールドを含む data_mapping を常に含めます。 フィールド名は JSONL ファイル内の名前と一致する必要があります。たとえば、データに"question"ではなく"query"がある場合は、マッピングで"{{item.question}}"を使用します。 エバリュエーターごとに必要なパラメーターについては、 組み込みのエバリュエーターを参照してください。

data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
            "response": {"type": "string"},
            "ground_truth": {"type": "string"},
        },
        "required": ["query", "response", "ground_truth"],
    },
)

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "f1",
        "evaluator_name": "builtin.f1_score",
        "data_mapping": {
            "response": "{{item.response}}",
            "ground_truth": "{{item.ground_truth}}",
        },
    },
]

評価を作成して実行する

評価を作成し、アップロードしたデータセットに対して実行を開始します。 この実行では、データセット内のすべての行に対して各エバリュエーターが実行されます。

# Create the evaluation
eval_object = client.evals.create(
    name="dataset-evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

# Create a run using the uploaded dataset
eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="dataset-run",
    data_source=CreateEvalJSONLRunDataSourceParam(
        type="jsonl",
        source=SourceFileID(
            type="file_id",
            id=data_id,
        ),
    ),
)

実行可能な完全な例については、GitHub のsample_evaluations_builtin_with_dataset_id.py を参照してください。 完了状態を定期的に確認し、結果を解釈するには、「結果を取得する」を参照してください。

モデルターゲット評価

実行時にデプロイされたモデルにクエリを送信し、azure_ai_target_completionsターゲットでazure_ai_modelデータ ソースの種類を使用して応答を評価します。 入力データにはクエリが含まれます。モデルは応答を生成し、その後評価されます。

ヒント

開始する前に、「 はじめに」 と 「入力データを準備する」を完了してください。

メッセージ テンプレートとターゲットを定義する

input_messages テンプレートは、クエリをモデルに送信する方法を制御します。 入力データからフィールドを参照するには、 {{item.query}} を使用します。 評価するモデルと省略可能なサンプリング パラメーターを指定します。

input_messages = {
    "type": "template",
    "template": [
        {
            "type": "message",
            "role": "user",
            "content": {
                "type": "input_text",
                "text": "{{item.query}}"
            }
        }
    ]
}

target = {
    "type": "azure_ai_model",
    "model": "gpt-5-mini",
    "sampling_params": {
        "top_p": 1.0,
        "max_completion_tokens": 2048,
    },
}

エバリュエーターとデータ マッピングを設定する

モデルが実行時に応答を生成する場合は、{{sample.output_text}}のdata_mappingを使用してモデルの出力を参照します。 入力データからフィールドを参照するには、 {{item.field}} を使用します。

data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
        },
        "required": ["query"],
    },
    include_sample_schema=True,
)

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
]

評価を作成して実行する

eval_object = client.evals.create(
    name="Model Target Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_id",
        "id": data_id,
    },
    "input_messages": input_messages,
    "target": target,
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="model-target-evaluation",
    data_source=data_source,
)

実行可能な完全な例については、GitHub のsample_model_evaluation.py を参照してください。 完了状態を定期的に確認し、結果を解釈するには、「結果を取得する」を参照してください。

ヒント

別の評価実行を追加するには、同じコードを使用できます。

エージェントのターゲット評価

実行時に Foundry エージェントにクエリを送信し、azure_ai_target_completionsターゲットを持つazure_ai_agent データ ソースの種類を使用して応答を評価します。

ヒント

開始する前に、「 はじめに」 と 「入力データを準備する」を完了してください。

メッセージ テンプレートとターゲットを定義する

input_messages テンプレートは、エージェントにクエリを送信する方法を制御します。 入力データからフィールドを参照するには、 {{item.query}} を使用します。 名前で評価するエージェントを指定します。

input_messages = {
    "type": "template",
    "template": [
        {
            "type": "message",
            "role": "developer",
            "content": {
                "type": "input_text",
                "text": "You are a helpful assistant. Answer clearly and safely."
            }
        },
        {
            "type": "message",
            "role": "user",
            "content": {
                "type": "input_text",
                "text": "{{item.query}}"
            }
        }
    ]
}

target = {
    "type": "azure_ai_agent",
    "name": "my-agent",
    "version": "1"  # Optional. Uses latest version if omitted.
}

エバリュエーターとデータ マッピングを設定する

エージェントが実行時に応答を生成する場合は、{{sample.*}}data_mapping変数を使用してエージェントの出力を参照します。

Variable [説明] 使用対象
{{sample.output_text}} エージェントのプレーン テキスト応答。 文字列応答を期待するエバリュエーター (たとえば、 coherence、 violence)。
{{sample.output_items}} ツール呼び出しを含む、エージェントの構造化された JSON 出力。 完全な対話コンテキスト (たとえば、 task_adherence) を必要とするエバリュエーター。
{{item.field}} 入力データのフィールド。 queryやground_truthなどの入力フィールド。

ヒント

query フィールドには、システム メッセージや会話履歴など、構造化された JSON を含めることができます。 task_adherenceなどの一部のエージェント エバリュエーターは、より正確なスコア付けにこのコンテキストを使用します。 クエリの書式設定の詳細については、 エージェント エバリュエーターを参照してください。

data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
        },
        "required": ["query"],
    },
    include_sample_schema=True,
)

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_text}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "task_adherence",
        "evaluator_name": "builtin.task_adherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{sample.output_items}}",
        },
    },
]

評価を作成して実行する

eval_object = client.evals.create(
    name="Agent Target Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_id",
        "id": data_id,
    },
    "input_messages": input_messages,
    "target": target,
}

agent_eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-target-evaluation",
    data_source=data_source,
)

実行可能な完全な例については、GitHub のsample_agent_evaluation.py を参照してください。 完了状態を定期的に確認し、結果を解釈するには、「結果を取得する」を参照してください。

エージェントの応答の評価

azure_ai_responses データ ソースの種類を使用して、応答 ID によって Foundry エージェントの応答を取得および評価します。 このシナリオを使用して、特定のエージェントの相互作用が発生した後で評価します。

ヒント

開始する前に、「 はじめに」を完了してください。

応答 ID は、Foundry エージェントが応答を生成するたびに返される一意の識別子です。 応答 API を使用して、またはアプリケーションのトレース ログから、エージェントの対話から応答 ID を収集できます。 ID をファイル コンテンツとしてインラインで指定するか、データセットとしてアップロードします ( 「入力データの準備」を参照)。

応答 ID を収集する

Responses API を呼び出すたびに、一意の id フィールドを持つ応答オブジェクトが返されます。 アプリケーションの対話からこれらの ID を収集するか、直接生成します。

# Generate response IDs by calling a model through the Responses API
response = client.responses.create(
    model=model_deployment_name,
    input="What is machine learning?",
)
print(response.id)  # Example: resp_abc123

また、アプリケーションのトレース ログまたは監視パイプラインのエージェント操作から応答 ID を収集することもできます。 各応答 ID は、評価サービスが取得できる格納された応答を一意に識別します。

評価を作成して実行する

data_source_config = {"type": "azure_ai_source", "scenario": "responses"}

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
    },
]

eval_object = client.evals.create(
    name="Agent Response Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_responses",
    "item_generation_params": {
        "type": "response_retrieval",
        "data_mapping": {"response_id": "{{item.resp_id}}"},
        "source": {
            "type": "file_content",
            "content": [
                {"item": {"resp_id": "resp_abc123"}},
                {"item": {"resp_id": "resp_def456"}},
            ]
        },
    },
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-response-evaluation",
    data_source=data_source,
)

実行可能な完全な例については、GitHub のsample_agent_response_evaluation.py を参照してください。 完了状態を定期的に確認し、結果を解釈するには、「結果を取得する」を参照してください。

結果を取得する

評価の実行が完了したら、スコア付けされた結果を取得し、ポータルまたはプログラムで確認します。

結果をポーリングする

評価実行は非同期です。 実行状態が完了するまでポーリングし、結果を取得します。

import time
from pprint import pprint

while True:
    run = client.evals.runs.retrieve(
        run_id=eval_run.id, eval_id=eval_object.id
    )
    if run.status in ("completed", "failed"):
        break
    time.sleep(5)
    print("Waiting for eval run to complete...")

# Retrieve results
output_items = list(
    client.evals.runs.output_items.list(
        run_id=run.id, eval_id=eval_object.id
    )
)
pprint(output_items)
print(f"Report URL: {run.report_url}")

結果を解釈する

1 つのデータ例の場合、すべてのエバリュエーターは次のスキーマを出力します。

  • ラベル: 単体テストの出力に似たバイナリ "pass" または "fail" ラベル。 この結果を使用して、エバリュエーター間の比較を容易にします。
  • スコア: 各エバリュエーターの自然なスケールからのスコア。 一部のエバリュエーターは、きめ細かいルーブリックを使用し、5 ポイント スケール (品質エバリュエーター) または 7 ポイント スケール (コンテンツ 安全エバリュエーター) でスコア付けします。 テキスト類似性エバリュエーターなどの他のユーザーは、F1 スコアを使用します。これは 0 から 1 の間の浮動小数点数です。 バイナリ以外の "score" は、"しきい値" に基づいて "label" フィールドで "pass" または "fail" にバイナリ化されます。
  • しきい値: バイナリ以外のスコアは、既定のしきい値に基づいて "成功" または "失敗" にバイナリ化され、ユーザーは SDK エクスペリエンスでオーバーライドできます。
  • 理由: すべての LLM ジャッジ エバリュエーターは、明瞭性を向上させるために、特定のスコアが与えられる理由を説明する推論フィールドも出力します。
  • 詳細: (省略可能) tool_call_accuracyなどの一部のエバリュエーターには、ユーザーがアプリケーションをデバッグするのに役立つ追加情報を含む "詳細" フィールドまたはフラグが存在する場合があります。

出力例 (1 つの項目)

{
  "type": "azure_ai_evaluator",
  "name": "Coherence",
  "metric": "coherence",
  "score": 4.0,
  "label": "pass",
  "reason": "The response is well-structured and logically organized, presenting information in a clear and coherent manner.",
  "threshold": 3,
  "passed": true
}

出力例 (集計)

複数のデータ例 (データセット) に対する集計結果の場合、"pass" を持つ例の平均レートは、そのデータセットの合格率を形成します。

{
  "eval_id": "eval_abc123",
  "run_id": "run_xyz789",
  "status": "completed",
  "result_counts": {
    "passed": 85,
    "failed": 15,
    "total": 100
  },
  "per_testing_criteria_results": [
    {
      "name": "coherence",
      "passed": 92,
      "failed": 8,
      "pass_rate": 0.92
    },
    {
      "name": "relevance", 
      "passed": 78,
      "failed": 22,
      "pass_rate": 0.78
    }
  ]
}

トラブルシューティング

長時間実行されているジョブ

評価ジョブは、長時間 実行 状態のままになる可能性があります。 これは通常、Azure OpenAI モデルのデプロイに十分な容量がないため、サービスが要求を再試行する場合に発生します。

解決策:

  1. client.evals.runs.cancel(run_id, eval_id=eval_id)を使用して、現在の評価ジョブを取り消します。
  2. Azure portal でモデル容量を増やします。
  3. 評価をもう一度実行します。

認証エラー

401 Unauthorizedまたは403 Forbiddenエラーが発生した場合は、次のことを確認します。

  • DefaultAzureCredentialが正しく構成されている (Azure CLI を使用している場合はaz login実行)。
  • アカウントには、Foundry プロジェクトに対する Azure AI ユーザー ロールがあります。
  • プロジェクト エンドポイントの URL は正しく、アカウント名とプロジェクト名の両方が含まれています。

データ形式のエラー

スキーマまたはデータ マッピング エラーで評価が失敗した場合:

  • JSONL ファイルに 1 行に 1 つの有効な JSON オブジェクトがあることを確認します。
  • data_mappingのフィールド名が JSONL ファイル内のフィールド名と正確に一致することを確認します (大文字と小文字が区別されます)。
  • item_schemaプロパティがデータセット内のフィールドと一致することを確認します。

レート制限エラー

評価実行の作成は、テナント、サブスクリプション、およびプロジェクト レベルでレート制限されます。 429 Too Many Requests応答を受け取った場合:

  • 応答の retry-after ヘッダーで、推奨される待機時間を確認します。
  • レート制限の詳細については、応答本文を確認します。
  • 失敗した要求を再試行するときは、指数バックオフを使用します。

実行中に評価ジョブが 429 エラーで失敗した場合:

  • 評価データセットのサイズを小さくするか、小さなバッチに分割します。
  • Azure portal で、モデル デプロイの 1 分あたりのトークン (TPM) クォータを増やします。

エージェント エバリュエーター ツールのエラー

サポートされていないツールのエラーがエージェント エバリュエーターから返された場合:

  • エージェント エバリュエーターで サポートされているツール を確認します。
  • 回避策として、エバリュエーターが評価できるように、サポートされていないツールをユーザー定義関数ツールとしてラップします。

関連するコンテンツ

  • Last updated on