Python を使用してバッチ評価を実装する

  • 10 分

クラウド評価では、Microsoft Foundry のテスト データセット全体で複数のエバリュエーターを実行することで、体系的な品質評価が可能になります。 これらの自動評価により、ローカル コンピューティング インフラストラクチャを管理し、大規模な自動テスト ワークフローをサポートする必要がなくなります。

Adventure Works では、デプロイ前にプロンプトの更新を検証するために、複数の品質基準に対して 500 のテスト例を評価する必要があります。 Foundry SDK を使用したクラウド評価は、この作業を効率的に完了し、エバリュエーターを並列で実行し、分析のために結果を格納します。

注

クラウド評価には、Microsoft Foundry SDK (azure-ai-projects>=2.0.0b1) と DefaultAzureCredential()による認証が必要です。 SDK は、評価操作用の project_client.get_openai_client() を通じて OpenAI と互換性のあるクライアントを提供します。

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

クラウド評価では、エバリュエーターを実行する前に、データ構造を理解する必要があります。 この構造は、JSONL データセット内のフィールドを記述し、実行するエバリュエーターを指定する データ ソース構成 を使用して定義します。

データ スキーマが必要な理由:

データ スキーマは、データセットに存在するフィールドと必要なフィールドを評価サービスに通知します。 データ スキーマは、実行前に検証を有効にし、サービスが適切なリソースを割り当てるのに役立ちます。 これは、データと評価サービスの間のコントラクトと考えてください。

from openai.types.eval_create_params import DataSourceConfigCustom

data_source_config = DataSourceConfigCustom(
    type="custom",
    item_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"},
            "response": {"type": "string"},
            "context": {"type": "string"},
            "ground_truth": {"type": "string"},
        },
        "required": ["query", "response"],  # Only these fields must be present
    },
)

データ マッピングを使用してエバリュエーターを構成する:

データ スキーマを定義したら、実行するエバリュエーターとデータへのアクセス方法を指定します。 testing_criteriaリストにはエバリュエーターの構成が含まれています。各エントリは、データセットに対して実行する 1 つのエバリュエーターを定義します。

testing_criteriaの各エバリュエーターは次を指定します。

  • エバリュエーター名: 使用する組み込みのエバリュエーター (例: builtin.intent_resolution)
  • 初期化パラメーター: AI 支援評価に使用するモデル デプロイのような構成
  • データ マッピング: {{item.field}} 構文を使用してデータセット フィールドをエバリュエーター パラメーターに接続する方法

データ マッピングは重要です。各エバリュエーターに、必要な入力を見つける場所を指示します。 {{item.field}}構文は、JSONL データセットのフィールドを参照します。

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "intent_resolution",  # Your name for this evaluator in results
        "evaluator_name": "builtin.intent_resolution",  # The built-in evaluator to use
        "initialization_parameters": {
            "deployment_name": model_deployment_name  # Which model to use for evaluation
        },
        "data_mapping": {
            "query": "{{item.query}}",  # Map dataset's "query" field to evaluator's "query" parameter
            "response": "{{item.response}}",  # Map dataset's "response" field to evaluator's "response" parameter
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "groundedness",
        "evaluator_name": "builtin.groundedness",
        "initialization_parameters": {
            "deployment_name": model_deployment_name
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
            "context": "{{item.context}}",  # Groundedness needs context to verify claims
        },
    },
]

Important

data_mappingのフィールド名は大文字と小文字が区別され、JSONL データセットと正確に一致する必要があります。 データセットに "質問" (大文字) があり、 "{{item.question}}" (小文字) を指定した場合、評価は失敗します。 データ スキーマとデータ マッピングの間でフィールド名が一致するかどうかを常に確認します。

評価定義を作成して実行する

クラウド評価では、 評価定義 (評価対象と方法) と 評価実行 (特定のデータセットに対して実行) が分離されます。 この分離により、再利用が可能になります。評価基準を 1 回定義してから、異なるデータセットまたはバージョンに対して複数回実行します。

評価定義を作成します。

評価定義は再利用可能なテンプレートです。 データ スキーマとテスト条件が組み合わせされていますが、特定のデータセットはまだ参照されていません。

# Create the evaluation definition
eval_object = client.evals.create(
    name="adventure-works-prompt-evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

print(f"Created evaluation: {eval_object.id}")

評価実行の作成:

評価実行では、特定のデータセットに対して評価定義が実行されます。 アップロードされたデータセットは、(前のユニットの) ID で参照します。

from openai.types.evals.create_eval_jsonl_run_data_source_param import (
    CreateEvalJSONLRunDataSourceParam,
    SourceFileID,
)

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

print(f"Started evaluation run: {eval_run.id}")
print(f"Status: {eval_run.status}")

実行中の動作:

実行を作成すると、評価サービスは次のように動作します。

  1. クラウド ストレージからデータセットを読み込む
  2. スキーマに対してデータを検証します
  3. 評価作業をエバリュエーター間で並列に分散する
  4. Foundry プロジェクトに結果を格納する
  5. 視覚化用の Web ベースのレポートを生成します

ヒント

評価実行は非同期であり、大規模なデータセットでは数分かかる場合があります。 このサービスは、再試行、レート制限、並列実行を自動的に処理します。 結果の準備ができたことを確認するには、実行状態をポーリングします。

完了をポーリングして結果を取得する

評価実行は、クラウドで非同期的に実行されます。 結果を取得する前に、完了するまで実行状態をポーリングする必要があります。

ポーリングが必要な理由:

複数のエバリュエーターを持つ大規模なデータセットの完了には数分かかる場合があります。 評価サービスは、並列ワーカー間で作業を分散し、モデルデプロイでレート制限を処理し、失敗した要求を自動的に再試行します。 ポーリングを利用すると、ネットワーク呼び出しでブロックされることなく、スクリプトが効率的に処理を待機できます。

import time

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)  # Check every 5 seconds
    print("Waiting for evaluation run to complete...")

print(f"Evaluation completed with status: {run.status}")

Important

エラーの処理: run.status が "失敗" の場合は、実行オブジェクトのエラーの詳細を確認します。 一般的なエラーには、モデル クォータの不足、無効なデータ マッピング、データセット アクセスの問題などがあります。 評価サービスは、問題の診断に役立つ詳細なエラー メッセージを提供します。

詳細な結果を取得します。

完了したら、データセット内の各項目のスコア付けされた結果を取得します。

# Get detailed results for each item
output_items = list(
    client.evals.runs.output_items.list(
        run_id=run.id,
        eval_id=eval_object.id
    )
)

print(f"Retrieved {len(output_items)} evaluation results")
print(f"View detailed report: {run.report_url}")

エバリュエーターの出力について:

すべてのエバリュエーターは、評価された項目ごとに標準化されたスキーマを返します。

  • ラベル: 単体テストの出力と同様に、バイナリの "pass" または "fail" ラベルを使用して、エバリュエーター間の迅速な比較にラベルを使用します
  • スコア: エバリュエーターの自然スケールからのスコア (品質エバリュエーターの場合は 1 から 5、安全性エバリュエーターの場合は 0 から 7、類似性メトリックの場合は 0 から 1)
  • しきい値: スコアからの合格/失敗を決定する既定のしきい値 (これをオーバーライドできます)
  • 理由: スコアの説明 (LLM ジャッジ エバリュエーターのみ)
  • 詳細: デバッグに関するオプションの追加情報 (tool_call_accuracyなどの一部のエバリュエーターの場合)

データセット全体の集計結果の場合は、全体的な合格/失敗数の run.result_counts にアクセスし、エバリュエーターごとの内訳を run.per_testing_criteria_results します。

ヒント

report_urlを使用して、フィルター処理、並べ替え、視覚化ツールを使用して Foundry ポータルで結果を表示します。 CI/CD ワークフローの場合は、 output_items をプログラムで解析して、品質ゲートを適用します。

次のユニットでは、これらの評価ワークフローを GitHub Actions に統合して、すべてのコード変更に対する品質保証を自動化する方法について説明します。