重要
この記事でプレビューとしてマークされているアイテムは、現在プレビュー段階です。 このプレビューはサービス レベル アグリーメント(SLA)なしで提供されており、Microsoft はこれを運用ワークロードでの使用に推奨していません。 特定の機能がサポートされていないか、機能が制限されている可能性があります。 詳細については、「Microsoft Azure プレビューの使用条件を参照してください。
この GitHub Action により、CI/CD パイプライン内の Microsoft Foundry Agents のオフライン評価が可能になります。 オフライン評価プロセスが効率化されるため、運用環境に更新プログラムをリリースする前に潜在的な問題を特定し、改善することができます。
このアクションを使用するには、テスト クエリとエバリュエーターの一覧を含むデータ セットを指定します。 このアクションにより、クエリを使用してエージェントが呼び出され、評価が実行され、概要レポートが生成されます。
機能
- Agent Evaluation: CI/CD ワークフロー内のMicrosoft Foundry エージェントの実稼働前評価を自動化します。
- エバリュエーター: Foundry 評価者カタログから任意の評価者を使用します。
- 統計分析: 評価結果には信頼区間が含まれており、統計的有意性をテストして、ランダムな変動による変化ではなく意味があるかどうかを判断します。
エバリュエーターのカテゴリ
- エージェント エバリュエーター: エージェント ワークフローのプロセス とシステム レベルのエバリュエーター。
- RAG エバリュエーター: RAG システムでエンド ツー エンドのプロセスと取得プロセスを評価します。
- リスクと安全の評価者: 対応に関するリスクと安全上の懸念を評価します。
- 汎用エバリュエーター: 一貫性や流暢性などの品質評価。
- OpenAI ベースの採点者: 文字列チェック、テキストの類似性、スコア/ラベル モデルを含む OpenAI 採点者を使用します。
- Custom エバリュエーター: Pythonコードまたは LLM の判断パターンを使用して、独自のカスタム エバリュエーターを定義します。
前提 条件
- プロジェクト。 詳細については、「 プロジェクトの作成」を参照してください。
- Foundry エージェント。
ヒント
認証には、Microsoft Entra IDを使用することをお勧めします。これを使用して、Azure リソースに安全に接続できます。 Azure ログイン GitHub アクションを使用して、認証プロセスを自動化できます。 詳細については、「Azure Login action with OpenID Connectを参照してください。
AI エージェントの評価を設定する方法
AIエージェント評価入力
パラメーター
| 名前 | 必須。 | 説明 |
|---|---|---|
| azure-ai-project-endpoint | はい | Microsoft Foundry Projectのエンドポイント。 この値を見つけるには、 Foundry ポータル でプロジェクトを開き、[ 概要 ] ページからエンドポイントをコピーします。 |
| デプロイメント名 | はい | 評価に使用するAzure AI モデル デプロイの名前。 Foundry ポータルの [モデルとエンドポイント ] で既存のデプロイを検索します。 |
| data-path | はい | 評価用のエバリュエーターと入力クエリを含むデータ ファイルへのパス。 |
| エージェントID | はい | 形式 agent-name:version で評価する 1 つ以上のエージェントの ID ( my-agent:1 や my-agent:1,my-agent:2など)。 複数のエージェントがコンマで区切られ、統計的なテスト結果と比較されます。 |
| baseline-agent-id | いいえ | 複数のエージェントを評価するときに比較するベースライン エージェントの ID。 指定しない場合は、最初のエージェントが使用されます。 |
メモ
エージェント ID とバージョンを見つけるには、 Foundry ポータルでプロジェクトを開き、[ エージェント] に移動し、エージェントを選択して、詳細ウィンドウから エージェント ID を コピーします。 バージョンは、展開バージョン番号 (たとえば、 my-agent:1) です。
データ ファイル
入力データ ファイルは、次の構造の JSON ファイルである必要があります。
| フィールド | タイプ | 必須。 | 説明 |
|---|---|---|---|
| 名前 | 文字列 | はい | 評価データセットの名前。 |
| エバリュエータ | string[] | はい | 使用するエバリュエーター名の一覧。 Foundry ポータルのプロジェクトのエバリュエーター カタログで使用可能なエバリュエーターの一覧を確認します。Build > Evaluations > Evaluator catalog. |
| データ | object[] | はい |
queryとオプションのエバリュエーター フィールド (ground_truth、context など) を含む入力オブジェクトの配列。 エバリュエーターに自動マップされます。 data_mapping を使用してオーバーライドします。 |
| openai_graders | オブジェクト | いいえ | OpenAI ベースのエバリュエーター (label_model、score_model、string_checkなど) の構成。 |
| 評価パラメータ | オブジェクト | いいえ | エバリュエーター固有の初期化パラメーター (しきい値、カスタム設定など)。 |
| データマッピング | オブジェクト | いいえ | ユーザー設定のデータ フィールド マッピング (指定されていない場合はデータから自動生成されます)。 |
基本的なサンプル データ ファイル
{
"name": "test-data",
"evaluators": [
"builtin.fluency",
"builtin.task_adherence",
"builtin.violence"
],
"data": [
{
"query": "Tell me about Tokyo disneyland"
},
{
"query": "How do I install Python?"
}
]
}
その他のサンプル データ ファイル
| ファイル名 | 説明 |
|---|---|
| dataset-tiny.json | テスト クエリとエバリュエーターの数が少ないデータセット。 |
| dataset.json | サポートされているすべてのエバリュエーター型と、信頼区間の計算と統計テストのための十分なクエリを含むデータセット。 |
| dataset-builtin-evaluators.json | 組み込みの Foundry エバリュエーターの例 (一貫性、流暢さ、関連性、接地性、メトリックなど)。 |
| dataset-openai-graders.json | OpenAI ベースの採点者の例 (ラベル モデル、スコア モデル、テキストの類似性、文字列チェック)。 |
| dataset-custom-evaluators.json | 評価関数パラメータを含むカスタム評価関数の例。 |
| dataset-data-mapping.json | 自動フィールド マッピングをカスタム データ列名でオーバーライドする方法を示すデータ マッピングの例。 |
AI エージェントの評価ワークフロー
GitHub アクションを使用するには、GITHUB アクションを CI/CD ワークフローに追加します。 コミット時などのトリガー条件と、自動化されたワークフローをトリガーするファイル パスを指定します。
ヒント
コストを最小限に抑えるために、すべてのコミットで評価を実行しないでください。
この例では、エージェント ID を使用して異なるエージェントを比較するときに AI エージェント評価を実行する方法を示します。
name: "AI Agent Evaluation"
on:
workflow_dispatch:
push:
branches:
- main
permissions:
id-token: write
contents: read
jobs:
run-action:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Azure login using Federated Credentials
uses: azure/login@v2
with:
client-id: ${{ vars.AZURE_CLIENT_ID }}
tenant-id: ${{ vars.AZURE_TENANT_ID }}
subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}
- name: Run Evaluation
uses: microsoft/ai-agent-evals@v3-beta
with:
# Replace placeholders with values for your Foundry Project
azure-ai-project-endpoint: "<your-ai-project-endpoint>"
deployment-name: "<your-deployment-name>"
agent-ids: "<your-ai-agent-ids>"
data-path: ${{ github.workspace }}/path/to/your/data-file
AI エージェントの評価結果の出力
評価結果は、GitHubの Actions で実行される各 AI 評価GitHub アクションの概要セクションに出力されます。 このレポートには、各メトリックの評価スコア、信頼区間、および複数のエージェントを評価する場合は、差分が意味のあるかランダムな変動内かを示すペアワイズ統計比較が表示されます。
次のスクリーンショットは、2 つのエージェントを比較したサンプル レポートを示しています。
azd 評価拡張機能を品質ゲートとして使用する
Azure Developer CLI (azd) 評価拡張機能を使用すると、登録済みの評価を実行し、パス レートがしきい値を下回ったときに pull request をブロックできます。 このワークフローは GitHub OpenID Connect (OIDC) を使用しているため、クライアント シークレットは保存されません。
リポジトリを準備する
ワークフローを構成する前に、以下の条件が満たされていることを確認してください:
- Azure サブスクリプションと、評価ターゲットを含む Foundry プロジェクト。
- GitHub Actions変数、シークレット、環境、保護規則を構成するための管理者アクセス。
- チェックインされた評価定義と決定論的評価データセット。
- 評価の拡張機能には、バージョン 1.33.0 以降の Azure Developer CLI (
azd) が必要です。 インストール手順については、「 Azure Developer CLI のインストールを参照してください。 -
azure.ai.evaluationsの拡張機能は、評価コマンドを提供します。 Foundryazdパッケージ (microsoft.foundry) には含まれません。
azure.ai.evaluations拡張機能をインストールし、評価コマンドが使用可能であることを確認します。 ワークフローでは、azd をインストールした後、そのステップで同じコマンドを実行してください。 Foundry 拡張機能の詳細については、「Azure Developer CLI Foundry 拡張機能のインストール」を参照してください。
azd ext install azure.ai.evaluations
azd ai eval --help
GitHub OIDC の構成と最小権限の適用
Microsoft Entra アプリケーションまたはユーザー割り当てマネージド ID を作成し、ワークフローに対して発行されるトークンのフェデレーション ID 資格情報を追加します。 次の固定値を使用します。
| フェデレーション資格証明のフィールド | Value |
|---|---|
| Issuer | https://token.actions.githubusercontent.com |
| オーディエンス | api://AzureADTokenExchange |
| Subject | GitHub OIDC トークンに含まれる正確な sub クレーム |
不変のカスタム サブジェクトを使用する組織または企業内のリポジトリでは、次のような基盤となる構成を持つサブジェクトを持つことができます:
repository_owner_id:<owner-id>:repository_id:<repo-id>:pull_request
リファレンス: OpenID Connect リファレンス
他のリポジトリから所有者の ID やリポジトリ ID をコピーしないでください。 ワークフロー内でトークンを要求し、トークンを表示せずにそのペイロードをデコードし、iss、aud、sub クレームのみを確認してください。 フェデレーション資格証明を、実際のクレームと完全に一致するように構成します。 環境を使用するジョブのGitHubの標準的なサブジェクトは、異なる形式になる場合があり、組織または企業はサブジェクト クレームをカスタマイズできます。
Microsoft Entra ワークロード ID のセットアップについては、「OpenID Connect を使用して GitHub Actions から Azure に対して認証する」を参照してください。
このロールには、以下のロールのみを割り当てます:
- Foundry プロジェクトの範囲における Foundry ユーザー。
- 専用リソース グループのスコープにおける共同作成者 (
azd upと照合する場合)。
重要
Foundry RBAC ロールの名前が最近変更されました。 Foundry User, Foundry Owner, Foundry Account Owner、および Foundry Project Manager は、以前は、AZURE AI ユーザー、Azure AI 所有者、Azure AI アカウント所有者、および AZURE AI Project Manager という名前でした。 名前の変更がロールアウトされている間、以前の名前が表示される場合があります。ロール ID とコア アクセス許可は、名前の変更によって変更されません。
リソース グループ ロールは、azd upを使用して再調整するときに必要です。azd upはプロビジョニング時にAzure Resource Managerデプロイを記録するためです。 サブスクリプションの範囲で共同作成者を割り当てないでください。
ライブ環境を保護して設定する
live-evaluationという名前の保護されたGitHub環境を作成します。 必要なレビュー担当者を追加し、リポジトリに合わせてデプロイ ブランチを制限します。
詳細については、「デプロイ用の環境の管理」を参照してください。
ワークフローの値を次のように格納します。
AZURE_CLIENT_SECRET を追加しないでください。OIDC がこれを置き換えます。
| 名前 | GitHub ストレージ | Purpose |
|---|---|---|
AZURE_CLIENT_ID |
live-evaluation 環境シークレット |
Microsoft Entra アプリケーションまたはマネージド ID のクライアント ID。 |
AZURE_TENANT_ID |
live-evaluation 環境シークレット |
Microsoft Entra テナント ID。 |
AZURE_SUBSCRIPTION_ID |
live-evaluation 環境シークレット |
専用リソース グループを含むサブスクリプション。 |
AZURE_AI_PROJECT_ENDPOINT |
live-evaluation 環境シークレット |
評価拡張機能によって使用される Foundry プロジェクト エンドポイント。 |
AZURE_LOCATION |
live-evaluation 環境変数 |
azd 環境用の Azure リージョン。 |
AZURE_RESOURCE_GROUP |
live-evaluation 環境変数 |
調整メタデータに使用される専用リソース グループ。 |
AZD_EVAL_LIVE_PR_GATE |
リポジトリ変数 | ライブ ジョブを有効にするには、正確な値 true を設定します。 |
AZD_CONFIG_DIR を RUNNER_TEMP 以下に保ち、非対話モードで認証を行します。
azd auth login `
--client-id $env:AZURE_CLIENT_ID `
--tenant-id $env:AZURE_TENANT_ID `
--federated-credential-provider github `
--no-prompt
リファレンス: Azure Developer CLI リファレンス
ジョブには、 contents: read と id-token: write のアクセス許可が必要です。 同じリポジトリからのプル要求、またはデフォルト ブランチからの手動ディスパッチのみが保護された環境に入ることができるようにゲート設定を行います。 フォーク pull requests はジョブをスキップする必要があり、ワークフローは pull_request_targetを使用してはなりません。
on:
pull_request:
workflow_dispatch:
permissions:
contents: read
id-token: write
jobs:
live-evaluation:
if: >-
vars.AZD_EVAL_LIVE_PR_GATE == 'true' &&
((github.event_name == 'pull_request' &&
github.event.pull_request.head.repo.full_name == github.repository) ||
(github.event_name == 'workflow_dispatch' &&
github.ref_name == github.event.repository.default_branch))
environment:
name: live-evaluation
リファレンス: GitHub Actions コンテキストのリファレンス
各 GitHub Action を、レビュー済みの完全なコミットの SHA に紐づけます。
azd up でインフラストラクチャのテンプレートが必要になった場合は、不活性なテンプレートを提供する
評価専用のプロジェクトを azd ai eval create ではなくazd up と照合した場合、そのプロジェクトではワークロードのリソースがプロビジョニングされません。
azd up --no-prompt から infra/main.bicep が見つからない、またはコンパイルできないという報告があった場合は、この非アクティブなネストされたデプロイを使用してそのファイルを追加します。
targetScope = 'resourceGroup'
resource reconciliationMarker 'Microsoft.Resources/deployments@2022-09-01' = {
name: 'azd-eval-hero-reconciliation'
properties: {
mode: 'Incremental'
template: {
'$schema': 'https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#'
contentVersion: '1.0.0.0'
resources: []
}
}
}
内部テンプレートにはワークロード リソースが含まれていません。 このマーカーは、Azure Resource Manager のデプロイ レコードのみを作成します。
詳細については、Microsoft.Resources のデプロイを参照してください。
正確な評価を実行する
ライフサイクルは次の順序で進めてください:
- チェックインされた評価の定義を照合します。 プロジェクトがインフラストラクチャをプロビジョニングするときに
azd up --no-promptを実行します。 評価のみを目的とするプロジェクトの場合は、代わりにazd ai eval create ci-f1-quality --no-promptを実行します。 このコマンドは、インフラストラクチャをプロビジョニングせずに、宣言されたデータセット、評価器、および評価を登録します。 -
azd ai eval run start --eval ci-f1-quality --no-prompt --no-wait -o jsonを実行します。 - ログに値を書き込まずに、キャプチャされた JSON から
.run_idを読み取る。 -
azd ai eval run show <run-id> --eval ci-f1-quality --wait --fail-on pass-rate=0.8 --no-prompt -o jsonを実行します。 - その特定の実行を
azd ai eval run output export <run-id> --eval ci-f1-quality --format json --output-file <runner-temp-file> --no-promptでエクスポートします。 - アップロード前に、完了状態、集計数、エクスポートされた行数、許可リストに登録された証拠を確認してください。
RUNNER_TEMPで生の標準出力と標準エラーをキャプチャします。 実行 ID をメモリまたはランナー一時ファイルに格納し、 show コマンドと output export コマンドの位置引数としてのみ使用します。
ライフサイクル フェーズごとに個別のGitHub Actions手順を使用します。 成功した場合は、サニタイズされたコマンドラインと概要のみを出力します。これには、「照合完了」、「実行が承認された (ID は伏せ字)」、最終状態とカウント数、ゲートの結果、エクスポートされた行数、許可リストに登録された証拠のプレビューなどが含まれます。
--fail-on pass-rate=0.8の場合、合格率は、合格したテスト ケース数を総テスト ケース数で割った値です。 失敗、エラー、スキップ、その他の理由で通過できなかった行は、実行件数に含まれます。 しきい値を下回る有効で完了した実行は、品質違反です。
azd CLI は拡張機能の終了コードを統合するため、コマンドは品質違反の場合も運用上の失敗の場合もコード 1 で終了します。 品質違反が発生すると、ゲートの理由とメッセージ evaluation quality gate not met が表示されます。 認証、ネットワーク、結果の形式不備や不完全さ、エクスポート時の不整合は、運用上の不備に該当します。
証拠は許可リスト登録済みのもののみアップロードしてください
生の CLI またはサービス出力をアップロードするのではなく、検証された結果から新しい証拠ドキュメントを作成します。 集計の状態、カウント、しきい値、およびレビューされた各サンプルの次のフィールド (query、response、ground_truth、score、passed) のみを保持します。
{
"status": "completed",
"counts": {
"passed": 2,
"failed": 0,
"errored": 0
},
"threshold": 0.8,
"samples": [
{
"query": "<allowlisted query>",
"response": "<allowlisted response>",
"ground_truth": "<allowlisted ground truth>",
"score": 1.0,
"passed": true
}
]
}
アップロードする前に、アーティファクトのディレクトリに想定通りの証拠ファイルのみが含まれていることを確認します。 JWT、エンドポイント、実行 ID、資格情報、ユーザー情報、URL のクエリ文字列、未加工の認証情報、CLI、サービスのペイロードは、印刷したりアップロードしたりしないでください。
未加工のデータをランナーの一時ストレージに保存し、取得したエラー診断情報をマスキングした上で、always() または finally のクリーンアップ手順に従ってファイルを削除します。
ゲートを確認する
pull request gating を有効にする前に、既定のブランチからワークフローを手動で実行してください。 次の点を確認します。
- OIDC 認証は、クライアント シークレットなしで成功します。
- リコンサイル ステップでは、チェックインされた評価が登録されます。
- 非同期開始は、実行 ID を表示せずに受け入れられます。
-
showコマンドは、completedを報告し、0.8のパス レートしきい値を適用します。 - このエクスポートには、その特定の実行からの行のみが含まれています。
- アップロードされたアーティファクトには、許可リスト登録済みのエビデンス スキーマのみが含まれています。
- runner-temporary ファイルは、成功時と失敗時に削除されます。
ゲートのトラブルシューティング
| 症状: | Resolution |
|---|---|
| Microsoft Entra IDはフェデレーション トークンを拒否します。 | トークンの実際の iss、aud、および sub クレームをフェデレーション資格情報と比較します。 環境の subject を想定したり、別のリポジトリの ID をコピーしたりしないでください。 |
azd up は、サブスクリプション、ロケーション、またはリソース グループが不足していることを報告します。 |
保護された環境で AZURE_SUBSCRIPTION_ID、 AZURE_LOCATION、および AZURE_RESOURCE_GROUP を設定し、ジョブに渡します。 |
azd up は infra/main.bicep を見つけられないか、コンパイルできません。 |
この記事で説明されている不活性なインフラストラクチャのテンプレートを追加するか、代わりに評価専用のプロジェクトを azd ai eval create と整合させます。 |
azd ai eval は認識されないコマンドです。 |
azd ext install azure.ai.evaluations を実行し、azd ext list を実行して、拡張機能がインストールされていることを確認します。
microsoft.foundry パッケージにはそれは含まれていません。 |
| 照合の結果、認証エラーが発生しました。 |
Foundry プロジェクトでのみ Foundry ユーザーを割り当て、azd upを使用する場合は、専用リソース グループでのみ共同作成者を割り当てます。 新しいロールの割り当てが反映されるまで、時間がかかる場合があります。 |
このコマンドはコード 1 で終了し、evaluation quality gate not met を出力します。 |
この結果を品質の低下として扱います。 サニタイズされた集計結果と、許可リストに登録された証拠サンプルを確認してください。 |
そのメッセージが表示されないまま、コマンドはコード 1 で終了します。 |
結果を運用上の障害として扱います。 認証、ネットワーク、結果の形式不備、実行の不完全、またはエクスポート エラーについては、情報が伏せられた診断情報のみを確認してください。 |
| フォークのプル要求は、OIDC トークンの取得を試みます。 | 同じリポジトリのヘッドをチェックすることを必須とし、AZD_EVAL_LIVE_PR_GATE はデフォルトでオフのままにし、pull_request_target は使用しないでください。 |
検証が完了したら、不要になった使い捨てのテスト リソースやロール割り当てを削除してください。 一時的なフェデレーション認証情報を削除し、クオリティ ゲートで引き続き使用する場合にのみ、専用のリソース グループを保持します。