azd CLI を使用してエージェント評価を実行する (プレビュー)

Important

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

azd ai eval拡張機能を使用して、Microsoft Foundry で構築されたエージェントに測定品質ループを追加します。プロジェクトの横にある評価をスキャフォールディングし、必要に応じてデータセットとルーブリックエバリュエーターを生成し、エージェントに対して評価を実行し、ターミナルを離れることなく結果を読み取ります。

同じ評価をパイプラインから実行でき、 --fail-on 結果をビルドゲートに変換します。

この記事では、 azd ai eval init と azd ai eval run startを使用した最初の評価について説明します。

Prerequisites

Microsoft Foundry にアクセスできる Azure サブスクリプション。
Azure Developer CLI (azd) バージョン 1.27.1 以降。インストール手順については、「 Azure Developer CLI のインストールを参照してください。
azd ai eval拡張機能: azd extension install azure.ai.evaluations。 azd extension list --installedを実行して、インストールされているバージョンを確認します。
認証された azd セッション。認証の状態を確認するには、 azd auth statusを実行します。サインインしていない場合は、 azd auth loginを実行します。
Foundry リソースの Foundry User ロール (以前は Azure AI User) です。詳細については、Microsoft Foundry のロールベースのアクセス制御を参照してください。
Foundry プロジェクトと、評価対象のエージェント。ターゲットinit検出できるようにするには、azd ai agent initと同様に、エージェントをプロジェクトのazure.yamlでサービスとして宣言する必要があります。それ以外の場合は、 --targetで名前を付けます。ホストされるエージェントについては、ホストされているエージェントに関するページを参照してください。
同じプロジェクトでチャットの完了をサポートするモデルデプロイ。採点者は、それを使用して判断します。
任意: generate にそれを合成させたくない場合は、代表的な例の JSONL データセット。

azd 評価のしくみ

評価は、読み取り、編集、コミットできるファイル ( evals/azure.eval.yaml) によって記述されます。コマンドはそのファイルを書き込むか、宣言内容に基づいて動作します。

azd ai eval init          # scaffold the configuration. Makes no service calls
azd ai eval generate      # optional: synthesize a dataset and a rubric evaluator
azd ai eval create        # register the eval in the Foundry project
azd ai eval run start     # run it and summarize the results

Item	Description
`init`	エージェントの `evals/azure.eval.yaml` をスキャフォールディングし、評価サービスを `azure.yaml`に追加します。サービス呼び出しを行いません。
`generate`	データセット、ルーブリックエバリュエーター、またはその両方を合成してダウンロードし、それぞれのカタログエントリを構成に追加します。課金対象の生成ジョブを送信します。
`evals/azure.eval.yaml`	評価の仕組み: 何が評価されるのか、各行がどこから来るのか、そしてどの評価者がそれらを採点するのか。
`create`	宣言されたデータセット、エバリュエーター、および評価自体をプロジェクトに登録します。
`run start`	実行を開始し、既定では実行を待機し、エバリュエーターごとの概要を出力します。
`run output list`	その概要の背後にあるサンプルごとの結果。
`dataset`、`evaluator`	`versions list`を含め、登録済みのデータセットとエバリュエーターを直接管理します。
`job`	`generate` が送信した生成ジョブを確認、キャンセル、削除します。

すべてのコマンドは、スクリプトの -o json と診断の --debug を受け入れます。 initを除くすべてのコマンドは、--project-endpointを受け入れます。

行の取得元を選択する

評価では、行が評価されます。これらは次の 2 つの場所のいずれかから取得され、この決定が最初の決定です。

--source traces は、エージェントがすでに実行した内容を、そのエージェントが出力したトレースを基に評価します。作成するものはありません。
--source dataset は、固定された一連の例を評価します。これは、自分の例または生成された例のいずれかです。反復可能で、エージェントのバージョン間で同等。

トレースソースの評価には、トレースを出力するエージェントが必要です。データセットソースの評価には、 .jsonl ファイルまたは登録済みのデータセットが必要です。

評価のひな形を作成する

プロジェクトルートから init を実行します。

azd ai eval init

フラグがない場合、 init は、 azure.yaml がエージェントを宣言するときにエージェントを検出し、複数を宣言するときにプロンプトを表示し、採点者が判断するモデルのデプロイと使用するエバリュエーターを要求します。 evals/azure.eval.yamlを書き込み、評価サービスをazure.yamlに追加します。サービス呼び出しは行わないので、何かをデプロイする前に安全に実行できます。

エージェントサービスを宣言しないプロジェクトでは、推測ではなく init 停止します。

ERROR: this project declares no agent service to evaluate. Add one, or name an existing agent with --target

その場合は、--target を使って自分でエージェントに名前を付けます。

スクリプトを使用する場合は、決定事項を直接渡します。

azd ai eval init \
  --source traces \
  --target support-agent \
  --judge-model gpt-4.1-nano \
  --name support-trace-eval \
  --no-prompt

既に存在するデータセットを評価するには:

azd ai eval init \
  --source dataset \
  --target support-agent \
  --dataset ./tests/support-golden.jsonl \
  --evaluator builtin.intent_resolution,builtin.task_adherence \
  --judge-model gpt-4.1-nano

--dataset は、ローカル .jsonl パスまたは登録済みデータセットの名前を受け取ります。 --evaluatorは繰り返し指定でき、コンマ区切りです。builtin.<name>は組み込みのエバリュエーターを参照し、修飾子のない名前はプロジェクトに登録されているカスタムエバリュエーターを参照します。 --evaluatorを渡すと既定値が置き換えられるため、ルーブリック生成も無効になります。

組み込みの名前を検出するには:

azd ai eval evaluator list --builtin

データセットとエバリュエーターを生成する

データセットがない場合、または汎用的なものではなくこのエージェント用のルーブリックを作成したい場合は、それらを生成してください。

azd ai eval generate \
  --target support-agent \
  --generation-model gpt-4.1-nano \
  --agent-instruction "Handles support requests. Test triage, policy adherence, and escalation."

既定では、データセットとルーブリックエバリュエーターの両方が生成され、 evals/でダウンロードされ、各カタログエントリが evals/azure.eval.yamlに追加されます。 --datasetまたは--evaluatorで絞り込んで 1 つだけ生成し、--max-samples (15 から 1000、既定値は 15) で行を上限にします。

generate は、モデル呼び出しのコストがかかるジョブを送信します。この指示は重要です。サービスはこれを使って行とルーブリックが何についてのものかを判断するため、エージェントが何をするのか、そして何をテストすべきかを説明してください。

カタログエントリは成果物を宣言します。どの評価で使用されるかは決められません。 generate後、evals/azure.eval.yamlを開き、実行する予定の評価が生成された内容を参照していることを確認します。トレースソースの評価ではトレースが読み取られます。そのため、生成されたデータセットは、評価によって名前が付けた後でのみ使用されます。

datasets:
    - name: support-agent-dataset
      source: ./datasets/support-agent-dataset.jsonl
evals:
    - name: support-agent-eval
      dataset: support-agent-dataset   # point the eval at the generated dataset

ジョブを送信し、後で戻ってくるには、次の手順を実行します。

azd ai eval generate --target support-agent --generation-model gpt-4.1-nano --no-wait
azd ai eval job list --dataset
azd ai eval job show <job-id> --dataset

job 上の --dataset と --evaluator で、操作するコレクションを選択します。いずれか 1 つが必要です。

azure.eval.yaml を確認する

init は、読み取るファイルを書き込みます。トレースソースの評価は次のようになります。

evals:
    - name: support-trace-eval
      description: Basic quality evaluation for support-agent
      source:
        type: traces
        max_traces: 20
        agent_name: support-agent
      evaluation_level: turn
      evaluators:
        - evaluator: builtin.task_adherence
          initialization_parameters:
            model: gpt-4.1-nano

データセットソースの評価では、トレースソースではなくデータセットに名前を付け、対象のエージェントを記録します。

datasets:
    - name: support-golden
      source: ../tests/support-golden.jsonl
evals:
    - name: support-agent-eval
      description: Basic quality evaluation for support-agent
      dataset: support-golden
      evaluation_level: turn
      evaluators:
        - evaluator: builtin.intent_resolution
          initialization_parameters:
            model: gpt-4.1-nano
        - evaluator: builtin.task_adherence
          initialization_parameters:
            model: gpt-4.1-nano
      target:
        type: agent
        name: support-agent

source:の下のパスは、構成ファイルに対する相対パスです。生成された .jsonl とエバリュエーター JSON は通常のファイルです。これを編集してから、 create 再度実行して新しいバージョンを登録します。

このファイルをコミットします。これは、評価の再現可能な部分です。

eval を作成して実行する

createを使用して、データセット、エバリュエーター、および評価自体など、構成で宣言されるすべてのものを登録します。

azd ai eval create

次に、それを実行します。

azd ai eval run start

run start は、既定で実行を待機し、パスレートと平均スコアとポータルの実行へのリンクを含むエバリュエーターごとのテーブルを出力します。 --no-wait で送信して戻り、--max-samples で送信する行数を制限します。

構成で複数の eval が宣言されている場合は、意図する eval の名前を指定してください:

azd ai eval run start --eval support-trace-eval

結果を検査する

概要を見ると、品質が変化したかどうかがわかります。サンプルごとの行は、次の理由を示します。

azd ai eval run output list --eval support-trace-eval
azd ai eval run output list --eval support-trace-eval --failed-only

一定期間の実行結果と、1 件の eval についてサービスが保持している内容を確認するには、次の手順に従います。

azd ai eval list
azd ai eval run list --eval support-trace-eval
azd ai eval show support-trace-eval

show は、プロジェクト内の評価の ID (ID、名前、および作成時) を返します。 eval がevals/azure.eval.yamlことは、にあります。

run list には、実行ごとに 1 つのパスレートが含まれます。評価者ごとの内訳は、per_testing_criteria_results の -o json にあります。これは、実行ごとに異なる評価者がスコア付けされるようになると、評価者ごとの列では読みにくくなるためです。

他の場所で結果を取得するには:

azd ai eval run output list --eval support-trace-eval --output-file rows.json
azd ai eval run output export --eval support-trace-eval --format csv --output-file summary.csv

2 つは異なり、違いは重要です。 run output list --output-file はサンプルごとの行を書き込み、 run output export は実行ごとに 1 行を書き込みます。要約の背後にある合計です。

ビルドのゲートを設定する

--fail-on を渡すと、実行がチェックになります。実行結果がしきい値に達しない場合、非ゼロで終了します。これにより、品質を悪化させた変更をパイプラインで失敗扱いにできます。

azd ai eval run start --fail-on pass-rate=0.8
azd ai eval run start --fail-on any-failure

--fail-onしないと、失敗したサンプルを含む完了した実行は引き続き 0 を終了します。失敗したサンプルは、ツールエラーではなく、動作中の評価の予想される出力であるため、ゲーティングはオプトインされます。

pass-rate は 0 ~ 1 の数値を受け取ります。 1ではないしきい値は実行が送信される前に拒否されるため、ゲートの入力を誤っても余計なコストはかかりません。

--fail-on には、完了した実行が必要です。 run showで、--waitとペアリングします。

評価をプロジェクトの他の部分と一緒にデプロイする

init は評価サービスを azure.yamlに追加するため、eval はサイドアーティファクトではなくプロジェクトの一部です。

azd up

これはプロジェクトをプロビジョニングし、宣言されたデータセット、エバリュエーター、および評価を登録します。これは、azd ai eval create が単独で行うのと同じ作業です。

エージェントを変更して再評価する

エージェントを変更して再デプロイした後、同じ評価をもう一度実行します。

azd deploy
azd ai eval run start --eval support-trace-eval

同じ評価を再利用すると、データセット、エバリュエーター、しきい値が固定され、比較はエージェントに関する情報になります。

評価で何を測定するかを変更するには、evals/ または evals/azure.eval.yaml 配下の生成された成果物を編集してから、create を再度実行します。 create は、変更されたものすべてについて新しいバージョンを登録し、以前の実行はそれぞれが使用したバージョンにピン留めされたままにします。

ベストプラクティス

エージェントが既に実行され、トレースを出力している場合は、 --source traces から開始します。何が起きたかを測定するものであり、自分で作成する必要はありません。
バージョン間で比較できるケースの固定セットが必要になったら、 --source dataset に移動します。
スコアを信頼する前に、生成されたデータセットとルーブリックを読み取ります。 generate あなたが与える命令からそれらを種付けするので、あいまいな命令は漠然とした行を生成します。
複数のエバリュエーターを使用します。 1 つの条件で、理由を伝えずに数値が移動します。
evals/azure.eval.yamlと生成された成果物をコミットして、評価をレビューできるようにします。
CI で --fail-on を使ってゲートし、実際の回帰で確実に引っかかるしきい値を維持します。

制限事項

拡張機能はプレビュー段階であり、コマンド画面が変更される可能性があります。
generate は課金対象のジョブを送信します。データセットとエバリュエーターは、 azd provisionによって作成されません。
トレースソースの評価では、エージェントが既に出力したトレースのみを読み取ることができます。
azd は拡張機能の終了コードを一つにまとめるため、ゲート違反も実行時の障害も、どちらも非ゼロ終了として扱われます。ゲートメッセージを読んで区別します。

フィードバック

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

Last updated on 2026-08-21