カスタム エバリュエーター (プレビュー)

組み込みのエバリュエーターは、アプリケーションの世代の品質を簡単に監視する方法を提供します。 評価をカスタマイズするには、独自のコード ベース、プロンプト ベース、またはエンドポイント ベースのエバリュエーターを作成します。

カスタム エバリュエーターを使用すると、 組み込みのエバリュエーター カタログを超えるドメイン固有の品質メトリックを定義できます。 ブランド トーン、ドメイン固有の精度、出力形式のコンプライアンスなど、アプリケーション固有の条件を測定する必要がある場合は、カスタム エバリュエーターを使用します。

次の 3 種類のカスタム エバリュエーターを作成できます。

カスタム エバリュエーターを作成したら、Foundry プロジェクトのエバリュエーター カタログに追加し、 バッチ評価実行で使用できます。

コードベースのエバリュエーター

コード ベースのエバリュエーターは、2 つの dict パラメーター (grade と sample) を受け取り、0.0 から 1.0 までの浮動小数点スコアを返す、item という名前のPython関数です (上位の方が適しています)。 実際には、すべてのデータは itemを介してアクセスされます。

• Dataset の評価: response や ground_truth などの入力フィールドは、item.get("response") や item.get("ground_truth") などのPython コードで取得できます。
• モデルまたはエージェントターゲットの評価: 生成された応答テキストをフェッチするには、 item.get("sample", {}).get("output_text")を使用します。

次の例では、長さに基づいて応答をスコア付けし、50 ~ 500 文字の応答を優先します。

def grade(sample: dict, item: dict) -> float:
    """Score based on response length (prefer 50-500 chars)."""
    # For dataset evaluation, access fields directly from item:
    response = item.get("response", "")

    # For model/agent target evaluation, use item.get("sample") instead:
    # response = item.get("sample", {}).get("output_text", "")

    if not response:
        return 0.0

    length = len(response)
    if length < 50:
        return 0.2
    elif length > 500:
        return 0.5
    return 1.0

サポートされているパッケージと制限

コード ベースのエバリュエーターは、次の制約を持つサンドボックス Python環境で実行されます。

• コード サイズは 256 KB 未満にする必要があります。
• 実行は、評価呼び出しごとに 2 分に制限されます。
• 実行時に使用できるネットワーク アクセスはありません。
• メモリ制限は 2 GB、ディスク制限は 1 GB、CPU は 2 コアに制限されます。

次のサード パーティ製パッケージを使用できます。

NLTK コーパス punkt、 stopwords、 wordnet、 omw-1.4、および names がプリロードされます。

ランタイム パラメーター

pass_threshold および deployment_name は、コード ベースのエバリュエーターを作成するときに初期化パラメーターとして必要です。 コード ベースのエバリュエーターが LLM を呼び出さない場合でも、サービス API スキーマでは評価実行オーケストレーションに deployment_name が必要です。 プロジェクトから任意の有効なモデル 配置名を渡すことができます。

プロンプトベースのエバリュエーター

プロンプト ベースのエバリュエーターは、LLM が各項目について評価するジャッジ プロンプト テンプレートを使用します。 テンプレート変数では、二重中かっこ ( {{query}} など) を使用し、入力データ フィールドにマップします。

プロンプト ベースのエバリュエーターでは、次の 3 つのスコアリング方法がサポートされています。

• 序数: 定義した不連続スケールの整数スコア (例: 1 ~ 5)。 高い方が良いです。
• 連続: 定義した範囲 (0.0 ~ 1.0 など) でのきめ細かい測定の浮動小数点スコア。 高い方が良いです。
• バイナリ (true/false): しきい値ベースのチェックのブール結果。

エバリュエーターは、 result と reasonを持つ JSON オブジェクトを返す必要があります。 resultの型は、スコアリング メソッドと一致します。序数の整数、連続する場合は float、バイナリの場合はブール値です。

次のプロンプト例では、序数スコアリング (1 ~ 5) を使用して応答の使いやすさを評価します。

Friendliness assesses the warmth and approachability of the response.
Rate the friendliness of the response between one and five using the following scale:

1 - Unfriendly or hostile
2 - Mostly unfriendly
3 - Neutral
4 - Mostly friendly
5 - Very friendly

Assign a rating based on the tone and demeanor of the response.

Response:
{{response}}

Output Format (JSON):
{
  "result": <integer from 1 to 5>,
  "reason": "<brief explanation for the score>"
}

ランタイム パラメーター

プロンプト ベースのエバリュエーターを作成するときは、初期化パラメーターとして deployment_name と threshold の両方が必要です。

エンドポイント ベースのエバリュエーター

エンドポイント ベースのエバリュエーターは、自分が所有および運用する外部 HTTP エンドポイントにスコアリングを委任します。 評価サービスは、各項目 (または項目のバッチ) に対してエンドポイントを呼び出し、マップされた入力データを JSON ペイロードとして渡します。 エンドポイントは、選択した任意のロジックを使用してデータを処理し、スコア付きの JSON 応答を返します。

必要な場合は、エンドポイント ベースのエバリュエーターを使用します。

• スコアリング中の外部サービスまたはデータベースへのネットワーク アクセス。
• 独自のインフラストラクチャでホストされている独自のモデルまたは ML パイプライン。
• セキュリティで保護されたコード ベースのエバリュエーターの制限を超える複雑なスコアリング ロジック。
• 既存の評価サービスまたは API との統合。

どのように機能するのか

1. 評価データを使用して POST 要求を受け入れる HTTP エンドポイントをデプロイします。
2. Foundry プロジェクトに、エンドポイント URL と認証資格情報を格納する接続を作成します。
3. 接続を参照するエンドポイント ベースのエバリュエーターを登録します。
4. 評価を実行すると、サービスは接続を解決し、入力データを使用してエンドポイントを呼び出し、評価結果として応答を記録します。

エンドポイント要求スキーマ

評価サービスは、評価メタデータとマップされた入力フィールドを含む JSON 本文を使用して、POST 要求をエンドポイントに送信します。

次の表では、エンドポイントが受信するフィールドについて説明します。

要求の例:

{
  "schema_version": "0.0.1",
  "evaluator_name": "my_endpoint_evaluator",
  "evaluator_version": "1",
  "evaluation_level": "turn",
  "data": {
    "item": {
      "query": "What is the capital of France?"
    },
    "sample": {
      "response": "Paris"
    }
  }
}

エンドポイント応答スキーマ

次の表では、エンドポイントから返されるフィールドについて説明します。

成功応答:

エンドポイントは、標準の評価結果スキーマに準拠する JSON オブジェクトを返す必要があります。

{
  "schema_version": "0.0.1",
  "score": 0.95,
  "reason": "The response accurately answers the question using the provided context.",
  "status": "completed",
  "properties": {
    "confidence": 0.87,
    "source_coverage": "full"
  },
  "threshold": 3,
  "passed": true
}

障害応答:

エラーが発生した場合、エンドポイントは次のスキーマに準拠する JSON オブジェクトを返す必要があります。

 {
   "schema_version": "0.0.1",
   "status": "error",
   "error": {
     "code": "500",
     "message": "Model inference failed"
   }
 }

Authentication

エンドポイント ベースのエバリュエーターは、プロジェクト接続を介して次の 2 つの認証方法をサポートします。

エンドポイント接続を作成する

接続には、エンドポイント URL と認証資格情報が格納されます。 Azure Cognitive Services 管理クライアントを使用して接続を作成します。

API キー接続

from azure.mgmt.cognitiveservices import CognitiveServicesManagementClient
from azure.mgmt.cognitiveservices.models import ConnectionPropertiesV2BasicResource

mgmt_client = CognitiveServicesManagementClient(
    credential=credential,
    subscription_id=subscription_id,
)

connection = ConnectionPropertiesV2BasicResource(
    properties={
        "category": "ApiKey",
        "target": "https://your-endpoint.azurewebsites.net/api/evaluate",
        "authType": "ApiKey",
        "credentials": {
            "key": "<your-api-key>",
        },
    },
)

mgmt_client.account_connections.create(
    resource_group_name=resource_group,
    account_name=account_name,
    connection_name="my-endpoint-connection",
    connection=connection,
)

Microsoft Entra ID接続

connection = ConnectionPropertiesV2BasicResource(
    properties={
        "category": "CustomKeys",
        "target": "https://your-endpoint.azurewebsites.net/api/evaluate",
        "authType": "AAD",
        "credentials": {
            "Audience": "api://<your-app-registration-client-id>",
        },
    },
)

mgmt_client.account_connections.create(
    resource_group_name=resource_group,
    account_name=account_name,
    connection_name="my-endpoint-entra-connection",
    connection=connection,
)

Entra ID認証では、プロジェクトのマネージド ID によって発行されたトークンを受け入れるようにエンドポイントを構成する必要があります。 通常、これには次の処理が含まれます。

• エンドポイントのMicrosoft Entra IDにアプリケーションを登録する。
• エンドポイントで Easy Auth (または同等のトークン検証) を有効にする。
• プロジェクトのマネージド ID に、ターゲット アプリケーションに対するアプリ ロールの割り当てを付与する。

エバリュエーターを登録する

接続を作成したら、それを参照するエンドポイント ベースのエバリュエーターを登録します。

endpoint_evaluator = project_client.beta.evaluators.create_version(
    name="my-endpoint-evaluator",
    evaluator_version={
        "name": "my-endpoint-evaluator",
        "categories": [EvaluatorCategory.QUALITY],
        "display_name": "My Endpoint Evaluator",
        "description": "Scores responses using a custom evaluation endpoint",
        "definition": {
            "type": "endpoint",
            "connection_name": "my-endpoint-connection",
        },
    },
)

エンドポイント ベースのエバリュエーターを使用して評価を実行する

data_mapping フィールドを使用して、エンドポイントに送信する入力データ フィールドを指定します。

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "endpoint_eval",
        "evaluator_name": "my-endpoint-evaluator",
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
            "context": "{{item.context}}",
        },
    },
]

data_mapping キーは、エンドポイントが受け取る JSON フィールドになります。 {{item.<field_name>}}構文を使用して、それらを評価データセット内の列にマップします。

エンドポイントをデプロイする

評価エンドポイントには、POST 要求を受け入れて JSON を返す任意の HTTP サービスを指定できます。 一般的なホスティング オプションは次のとおりです。

• Azure Functions: 単純なスコアリング ロジックのための軽量のサーバーレス ホスティング。
• Azure App Service: 複雑な評価パイプライン用の完全な Web アプリ ホスティング。
• Azure Container Apps: ML モデル推論のためのコンテナーベースのホスティング。

エンドポイントは、評価サービスのタイムアウト (30 秒) 以内に応答し、要求ごとに有効な JSON 応答を返す必要があります。

SDK を使用してカスタム エバリュエーターを作成する

前提条件とセットアップ

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

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

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

# 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 (required for prompt-based evaluators)
# Example: gpt-5-mini
model_deployment_name = os.environ.get("AZURE_AI_MODEL_DEPLOYMENT_NAME", "")

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

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

コード ベースのエバリュエーターを作成する

grade()関数を文字列として code_text フィールドに渡します。 関数が期待する入力フィールドを宣言する data_schema と、関数が返すスコアを記述する metrics を定義します。 コード ベースのエバリュエーターは、0.0 から 1.0 の範囲の continuous メトリック型を使用します。

まず、エバリュエーターのバージョン スキーマを定義します。

code_evaluator = project_client.beta.evaluators.create_version(
    name="response_length_scorer",
    evaluator_version={
        "name": "response_length_scorer",
        "categories": [EvaluatorCategory.QUALITY],
        "display_name": "Response Length Scorer",
        "description": "Scores responses based on length, preferring 50-500 characters",
        "definition": {
            "type": EvaluatorDefinitionType.CODE,
            "code_text": (
                'def grade(sample: dict, item: dict) -> float:\n'
                '    """Score based on response length (prefer 50-500 chars)."""\n'
                '    response = item.get("response", "")\n'
                '    if not response:\n'
                '        return 0.0\n'
                '    length = len(response)\n'
                '    if length < 50:\n'
                '        return 0.2\n'
                '    elif length > 500:\n'
                '        return 0.5\n'
                '    return 1.0\n'
            ),
            "init_parameters": {
                "type": "object",
                "properties": {
                    "deployment_name": {"type": "string"},
                    "pass_threshold": {"type": "number"},
                },
                "required": ["deployment_name", "pass_threshold"],
            },
            "metrics": {
                "result": {
                    "type": "continuous",
                    "desirable_direction": "increase",
                    "min_value": 0.0,
                    "max_value": 1.0,
                }
            },
            "data_schema": {
                "type": "object",
                "required": ["item"],
                "properties": {
                    "item": {
                        "type": "object",
                        "properties": {
                            "response": {"type": "string"},
                        },
                    },
                },
            },
        },
    },
)

完全な例については、code ベースのエバリュエーター Python SDK サンプルを参照してください。

プロンプト ベースのエバリュエーターを作成する

prompt_textフィールドにジャッジプロンプトを渡します。 プロンプトで必要な入力フィールドを宣言する data_schema と、スコアリング方法と範囲を記述する metrics を定義します。 init_parametersは、実行時にエバリュエーターが必要とするモデルのデプロイとしきい値を宣言します。

prompt_evaluator = project_client.beta.evaluators.create_version(
    name="friendliness_evaluator",
    evaluator_version={
        "name": "friendliness_evaluator",
        "categories": [EvaluatorCategory.QUALITY],
        "display_name": "Friendliness Evaluator",
        "description": "Evaluates the warmth and approachability of a response",
        "definition": {
            "type": EvaluatorDefinitionType.PROMPT,
            "prompt_text": (
                "Friendliness assesses the warmth and approachability of the response.\n"
                "Rate the friendliness of the response between one and five "
                "using the following scale:\n\n"
                "1 - Unfriendly or hostile\n"
                "2 - Mostly unfriendly\n"
                "3 - Neutral\n"
                "4 - Mostly friendly\n"
                "5 - Very friendly\n\n"
                "Assign a rating based on the tone and demeanor of the response.\n\n"
                "Response:\n{{response}}\n\n"
                "Output Format (JSON):\n"
                '{\n  "result": <integer from 1 to 5>,\n'
                '  "reason": "<brief explanation for the score>"\n}\n'
            ),
            "init_parameters": {
                "type": "object",
                "properties": {
                    "deployment_name": {"type": "string"},
                    "threshold": {"type": "number"},
                },
                "required": ["deployment_name", "threshold"],
            },
            "data_schema": {
                "type": "object",
                "properties": {
                    "response": {"type": "string"},
                },
                "required": ["response"],
            },
            "metrics": {
                "custom_prompt": {
                    "type": "ordinal",
                    "desirable_direction": "increase",
                    "min_value": 1,
                    "max_value": 5,
                }
            },
        },
    },
)

完全な例については、prompt ベースのエバリュエーター Python SDK サンプルを参照してください。

カスタム エバリュエーターを使用して評価を実行する

カスタム エバリュエーターを作成した後、組み込みのエバリュエーターを使用するのと同じ方法で評価実行で使用します。 1 回の実行に複数のエバリュエーターを含めることができます。

次の例では、コードベースの response_length_scorer とプロンプトベースの friendliness_evaluator の両方を一緒に実行します。

評価を定義して実行する

# Define the data schema
data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "response": {"type": "string"},
        },
        "required": ["response"],
    },
)

# Reference both custom evaluators in testing criteria
testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "response_length_scorer",
        "evaluator_name": "response_length_scorer",
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
            "pass_threshold": 0.5,
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "friendliness_evaluator",
        "evaluator_name": "friendliness_evaluator",
        "data_mapping": {
            "response": "{{item.response}}",
        },
        "initialization_parameters": {
            "deployment_name": model_deployment_name,
            "threshold": 3,
        },
    },
]

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

# Run the evaluation with inline data
eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="custom-eval-run-01",
    data_source=CreateEvalJSONLRunDataSourceParam(
        type="jsonl",
        source=SourceFileContent(
            type="file_content",
            content=[
                SourceFileContentContent(
                    item={
                        "response": "I'm sorry this watch isn't working for you. I'd be happy to help you with a replacement!",
                    }
                ),
                SourceFileContentContent(
                    item={
                        "response": "I will not apologize for my behavior!",
                    }
                ),
            ],
        ),
    ),
)

結果を取得する

評価実行が完了するまでポーリングし、項目ごとの結果とレポート URL を取得します。

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)

# Get per-item results
output_items = list(
    client.evals.runs.output_items.list(run_id=run.id, eval_id=eval_object.id)
)

print(f"Status: {run.status}")
print(f"Report: {run.report_url}")

リソースのクリーンアップ

カスタム エバリュエーターのバージョンと、必要がなくなった評価を削除します。

# Delete the custom evaluator version
project_client.beta.evaluators.delete_version(
    name="response_length_scorer",
    version=code_evaluator.version,
)

# Delete the evaluation
client.evals.delete(eval_id=eval_object.id)

データ ソース オプション、エバリュエーター マッピング、および高度なシナリオの詳細については、「 SDK から評価を実行する」を参照してください。

エバリュエーターの一覧表示、更新、削除などのその他の例については、SDK サンプル>evaluator カタログ管理Python SDK サンプルを参照してください。

ポータルでカスタム エバリュエーターを作成する

SDK コードを記述しなくても、Azure AI Foundry ポータルでカスタム エバリュエーターを直接作成できます。

1. Foundry プロジェクトで、 Evaluation>Evaluator カタログに移動します。
2. [カスタム エバリュエーター>作成] を選択します。
3. 次のフィールドに入力します。

ポータル評価でカスタム エバリュエーターを使用する

カスタム エバリュエーターを作成したら、ポータルから評価実行で使用します。

1. Foundry プロジェクトで、[ 評価 ] に移動し、[ 作成] を選択します。
2. 評価作成ウィザードに従います。 [ 条件 ] ステップで、[ エバリュエーターの追加] を選択します。
3. エバリュエーター カタログからカスタム エバリュエーターを選択します。
4. 必要な初期化パラメーターを指定します。 プロンプト ベースのエバリュエーターの場合は、 モデルのデプロイ と しきい値を指定します。 コード ベースのエバリュエーターの場合は、 パスのしきい値を指定します。
5. ウィザードを完了し、評価の実行を開始します。

ポータルから評価を実行する詳細な手順については、「ポータル から評価を実行する」を参照してください。

会話レベルのカスタム エバリュエーター

カスタム エバリュエーターは、個々のターンではなく、会話全体にスコアを付けることができます。 会話レベルの評価を有効にするには:

1. 評価実行で evaluation_level="conversation" を設定する
2. grade()が会話配列として期待されるようにitem["messages"]関数を設計する

会話レベルで実行すると、 item dict は、1 つのクエリ/応答ペアではなく、完全な会話メッセージ配列を受け取ります。 これにより、ユーザーの操作全体を評価するカスタム メトリックを構築できます。

例: セッション レベルのコンプライアンス チェック

この例では、エージェントが会話中の任意の時点で必要な免責事項を開示したかどうかを確認します。

def grade(sample: dict, item: dict) -> float:
    """Check if agent disclosed required disclaimer during conversation."""
    messages = item.get("messages", [])
    
    for msg in messages:
        if msg.get("role") == "assistant":
            content = msg.get("content", "")
            if isinstance(content, str) and "not financial advice" in content.lower():
                return 1.0
    
    return 0.0  # Disclaimer never provided

例: 会話の長さのスコアラー

この例では、目標ターン数内で解決されたかどうかに基づいて会話をスコア付けします。

def grade(sample: dict, item: dict) -> float:
    """Score based on conversation length (prefer shorter resolutions)."""
    messages = item.get("messages", [])
    
    # Count user turns (excludes system messages)
    user_turns = sum(1 for msg in messages if msg.get("role") == "user")
    
    if user_turns <= 2:
        return 1.0  # Resolved quickly
    elif user_turns <= 4:
        return 0.7  # Reasonable length
    elif user_turns <= 6:
        return 0.4  # Getting long
    else:
        return 0.2  # Too many turns

関連するコンテンツ

• SDK から評価を実行する
• 組み込みのエバリュエーター