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_synthetic_data_gen_preview`	または
赤いチームの評価	モデルまたはエージェントに対して自動敵対的テストを実行します。	`azure_ai_red_team`	または

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

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

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

— フィールド名と型を使用してを定義します。エバリュエーターが生成された応答を参照できるように、ターゲットを使用するときにをに設定します。
— スキーマはサービスから推論されます。エージェントの応答評価、合成データ評価 (プレビュー) の、または赤いチーミングのにをに設定します。

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

[前提条件]

フォンドリープロジェクト。
チャットの完了をサポートする GPT モデルを使用した Azure OpenAI デプロイ (たとえば、gpt-5-mini)。
Foundry プロジェクトの Azure AI User ロール。
必要に応じて、独自のストレージアカウントを使用して評価を実行できます。

注

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

概要

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

pip install "azure-ai-projects>=2.0.0"

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

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

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

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

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

データセットの評価

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

ヒント

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

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

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

Python
cURL

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

curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/v1/evals" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "dataset-evaluation",
    "data_source_config": {
      "type": "custom",
      "item_schema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" },
          "response": { "type": "string" },
          "ground_truth": { "type": "string" }
        },
        "required": ["query", "response", "ground_truth"]
      }
    },
    "testing_criteria": [
  }'

評価を作成して実行する

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

Python
cURL

# 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,
        ),
    ),
)

# Step 1: Create the evaluation
EVAL_ID=$(curl --silent --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/v1/evals" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "dataset-evaluation",
    "data_source_config": {
      "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": "gpt-5-mini" },
        "data_mapping": {
          "query": "{{item.query}}",
          "response": "{{item.response}}"
        }
      },
      {
        "type": "azure_ai_evaluator",
        "name": "violence",
        "evaluator_name": "builtin.violence",
        "initialization_parameters": { "deployment_name": "gpt-5-mini" },
        "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}}"
        }
      }
    ]
  }' | jq -r '.id')

# Step 2: Create a run against your dataset
curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/v1/evals/${EVAL_ID}/runs" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "dataset-run",
    "data_source": {
      "type": "jsonl",
      "source": {
        "type": "file_id",
        "id": "YOUR_DATASET_ID"
      }
    }
  }'

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

モデルターゲットの評価

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

ヒント

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

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

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

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,
    },
}

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

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

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

評価を作成して実行する

Python
cURL

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,
)

curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/v1/evals/${EVAL_ID}/runs" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "model-target-evaluation",
    "data_source": {
      "type": "azure_ai_target_completions",
      "source": {
        "type": "file_id",
        "id": "YOUR_DATASET_ID"
      },
      "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
        }
      }
    }
  }'

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

ヒント

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

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

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

ヒント

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

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

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

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.
}

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

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

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

ヒント

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

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

評価を作成して実行する

Python
cURL

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,
)

curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/v1/evals/${EVAL_ID}/runs" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "agent-target-evaluation",
    "data_source": {
      "type": "azure_ai_target_completions",
      "source": {
        "type": "file_id",
        "id": "YOUR_DATASET_ID"
      },
      "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"
      }
    }
  }'

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

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

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

ヒント

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

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

応答 ID を収集する

Responses API を呼び出すたびに、一意のフィールドを持つ応答オブジェクトが返されます。アプリケーションの対話からこれらの 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 は、評価サービスが取得できる格納された応答を一意に識別します。

評価を作成して実行する

Python
cURL

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,
)

curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/v1/evals/${EVAL_ID}/runs" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "agent-response-evaluation",
    "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"}}
          ]
        }
      }
    }
  }'

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

合成データの評価 (プレビュー)

合成テストクエリを生成し、デプロイされたモデルまたは Foundry エージェントに送信し、データソースの種類を使用して応答を評価します。このシナリオは、テストデータセットがない場合に使用します。サービスは、指定したプロンプトに基づいてクエリを生成し (またはエージェントの指示から)、ターゲットに対してクエリを実行し、応答を評価します。

ヒント

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

合成データの評価のしくみ

サービスは、とオプションのシードデータファイルに基づいて合成クエリを生成します。
各クエリは、応答を生成するために、指定されたターゲット (モデルまたはエージェント) に送信されます。
エバリュエーターは、生成されたクエリと応答を使用して各応答をスコア付けします。
生成されたクエリは、再利用のためにプロジェクトにデータセットとして格納されます。

パラメーター

パラメーター	必須	[説明]
`samples_count`	はい	生成する合成テストクエリの最大数。
`model_deployment_name`	はい	合成クエリの生成に使用するモデルデプロイ。 Responses API 機能を持つモデルのみがサポートされています。可用性については、「応答 API リージョンの可用性」を参照してください。
`prompt`	いいえ	生成するクエリの種類を説明する手順。エージェントターゲットに命令が構成されている場合は省略可能です。
`output_dataset_name`	いいえ	生成されたクエリが格納される出力データセットの名前。指定しない場合、サービスは名前を自動的に生成します。
`sources`	いいえ	生成されたクエリの関連性を向上させるために、(ファイル ID によって) データファイルをシード処理します。現在サポートされているファイルは 1 つだけです。

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

合成データジェネレーターは、フィールドにクエリを生成します。ターゲットは、で使用可能な応答を生成します。これらのフィールドをエバリュエーターにマップします。

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

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

評価を作成して実行する

Python
cURL

モデルターゲット

合成クエリを生成し、モデルを評価する:

eval_object = client.evals.create(
    name="Synthetic Data Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_synthetic_data_gen_preview",
    "item_generation_params": {
        "type": "synthetic_data_gen_preview",
        "samples_count": 5,
        "prompt": "Generate customer service questions about returning defective products",
        "model_deployment_name": model_deployment_name,
        "output_dataset_name": "my-synthetic-dataset",
    },
    "target": {
        "type": "azure_ai_model",
        "model": model_deployment_name,
    },
}

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

必要に応じて、ターゲットモデルの動作を整形するためのシステムプロンプトを追加できます。合成データ生成でを使用する場合は、ロールメッセージのみを含めます。サービスは、生成されたクエリをユーザーメッセージとして自動的に提供します。

data_source = {
    "type": "azure_ai_synthetic_data_gen_preview",
    "item_generation_params": {
        "type": "synthetic_data_gen_preview",
        "samples_count": 5,
        "prompt": "Generate customer service questions about returning defective products",
        "model_deployment_name": model_deployment_name,
    },
    "target": {
        "type": "azure_ai_model",
        "model": model_deployment_name,
    },
    "input_messages": {
        "type": "template",
        "template": [
            {
                "type": "message",
                "role": "system",
                "content": {
                    "type": "input_text",
                    "text": "You are a helpful customer service agent. Be empathetic and solution-oriented."
                }
            }
        ]
    },
}

エージェントターゲット

合成クエリを生成し、Foundry エージェントを評価します。

data_source = {
    "type": "azure_ai_synthetic_data_gen_preview",
    "item_generation_params": {
        "type": "synthetic_data_gen_preview",
        "samples_count": 5,
        "prompt": "Generate questions about returning defective products",
        "model_deployment_name": model_deployment_name,
    },
    "target": {
        "type": "azure_ai_agent",
        "name": agent_name,
        "version": agent_version,
    },
}

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

# Step 1: Create the evaluation
curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/evals?api-version=v1" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Synthetic Data Evaluation",
    "data_source_config": {
      "type": "azure_ai_source",
      "scenario": "synthetic_data_gen_preview"
    },
    "testing_criteria": [
      {
        "type": "azure_ai_evaluator",
        "name": "coherence",
        "evaluator_name": "builtin.coherence",
        "initialization_parameters": {
          "deployment_name": "gpt-5-mini"
        },
        "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}}"
        }
      }
    ]
  }'

# Step 2: Create a run with synthetic data generation
curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/evals/${EVAL_ID}/runs?api-version=v1" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "synthetic-data-evaluation",
    "data_source": {
      "type": "azure_ai_synthetic_data_gen_preview",
      "item_generation_params": {
        "type": "synthetic_data_gen_preview",
        "samples_count": 5,
        "prompt": "Generate customer service questions about returning defective products",
        "model_deployment_name": "gpt-5-mini",
        "output_dataset_name": "my-synthetic-dataset"
      },
      "target": {
        "type": "azure_ai_model",
        "model": "gpt-5-mini"
      }
    }
  }'

完了状態を定期的に確認し、結果を解釈するには、「結果を取得する」を参照してください。応答には、生成されたデータセットの ID を含むプロパティが含まれています。これは、合成データを取得または再利用するために使用できます。

結果を取得する

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

結果をポーリングする

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

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 モデルのデプロイに十分な容量がないため、サービスが要求を再試行する場合に発生します。

解決策:

を使用して、現在の評価ジョブを取り消します。
Azure ポータルでモデル容量を増やします。
評価をもう一度実行します。

認証エラー

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

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

データ形式のエラー

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

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

レート制限エラー

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

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

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

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

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

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

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

完全な動作サンプル
AI エージェントを継続的に評価する
Foundry ポータルで評価結果を表示する
Foundry の概要
REST API リファレンス

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-03-06

次の方法で共有

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

クラウド評価のしくみ

[前提条件]

概要

入力データを準備する

データセットをアップロードする (推奨)

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

データセットの評価

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

評価を作成して実行する

モデル ターゲットの評価

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

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

評価を作成して実行する

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

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

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

評価を作成して実行する

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

応答 ID を収集する

評価を作成して実行する

合成データの評価 (プレビュー)

合成データの評価のしくみ

パラメーター

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

評価を作成して実行する

モデル ターゲット

エージェント ターゲット

結果を取得する

結果をポーリングする

結果を解釈する

出力例 (1 つの項目)

出力例 (集計)

トラブルシューティング

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

認証エラー

データ形式のエラー

レート制限エラー

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

関連するコンテンツ

フィードバック

その他のリソース

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

モデルターゲットの評価

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

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

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

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

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

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

モデルターゲット

エージェントターゲット

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