オフライン評価を実行する

オフライン評価では、開発または本番環境でキャプチャされた過去のデータを分析して、エージェントのパフォーマンス、安全性、品質を測定できます。個々のトレース（単一の実行パス）または完全なセッション（複数ターンの会話履歴）を、事前定義された指標またはカスタム指標のセットに対して評価できます。

トレースとセッション

  • トレース: モデルの入力、レスポンス、ツール呼び出しなど、エージェントの動作に関する事実に基づいた不変の記録。トレースは、単一の実行パスを表します。
  • セッション: ユーザーとエージェント間の複数ターンのやり取り全体を対象とします。セッションを使用して、コンテキストの保持と会話フローを時間の経過とともに評価します。

始める前に

オフライン評価に必要なデータと環境を確保するには、次の操作を行います。

  • Cloud Trace が有効になっている Agent Runtime がデプロイされていることを確認します。
  • 評価結果を保存する Cloud Storage バケットを設定します。このパスは 1 回だけ指定すればよく、以降の実行では事前入力されます。
  • 評価に Agent Platform SDK を使用する場合は、エージェントを評価するの説明に沿ってクライアントを初期化します。

テレメトリーの要件

オフライン評価では、評価に必要なコンテキストを提供するために、エージェントが特定の OpenTelemetry シグナルをエクスポートする必要があります。これらの要件は、オンライン モニターの要件と同じです。

  1. エージェント スパンの呼び出し: 次の属性を含める必要があります。

    • gen_ai.agent.name: エージェントの ID。
    • gen_ai.agent.description: エージェントの目的の簡単な説明。
    • gen_ai.conversation.id: 特定の会話セッションの固有識別子。

  2. 推論イベント: gen_ai.client.inference.operation.details イベントは以下をキャプチャする必要があります。

    • gen_ai.input.messages: エージェントに送信されたプロンプト。
    • gen_ai.output.messages: エージェントが生成したレスポンス。
    • gen_ai.system_instructions: 基盤となるシステムのプロンプト。
    • gen_ai.tool.definitions: エージェントが使用できるツールに関するメタデータ。

Agent Development Kit を使用している場合は、次の環境変数を設定して、これらのテレメトリー機能を有効にする必要があります。

OTEL_SEMCONV_STABILITY_OPT_IN='gen_ai_latest_experimental'
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT='EVENT_ONLY'

Cloud Storage でのメディアの録音

エージェントが画像や大きなドキュメントなどのマルチモーダル データを使用する場合は、トレース スパンに直接埋め込むのではなく、Cloud Storage バケットに入力と出力を記録することをおすすめします。これを有効にするには、次の環境変数を構成します。

OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMAT='jsonl'
OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK='upload'
OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH='gs://STORAGE_BUCKET_NAME/PATH'

詳細については、マルチモーダル プロンプトとレスポンスを収集するをご覧ください。

レジストリから評価を作成する

  1. Google Cloud コンソールで、[エージェント プラットフォーム] > [エージェント] > [評価] ページに移動します。

    [評価] に移動

  2. [新しい評価] をクリックします。

  3. 評価の目標に応じて、[トレース] タブまたは [セッション] タブを選択します。

  4. フィルタ アイコンと期間選択ツールを使用して、データ（[バージョン] や [過去 2 週間] など）をフィルタし、評価する特定の ID を選択します。

  5. [続行] をクリックします。

  6. （省略可）[評価名] フィールドに、評価の名前を入力するか、事前入力されたデフォルトを使用します。

  7. [出力の非公開データパス] フィールドに、Cloud Storage バケットの URI を入力します。初回使用後は、このパスは今後の実行のために事前入力されます。

  8. デフォルトでは、4 つのコア指標がすべて追加されます。必要に応じて指標を追加または削除できます。

  9. [エージェントを評価] をクリックします。

単一のトレースまたはセッションを評価する

個々の実行パスを検査しながら、評価を直接トリガーできます。

  1. Google Cloud コンソールで、[エージェント プラットフォーム] > [エージェント] ページに移動します。
  2. 左側のナビゲーション メニューで、[デプロイ] を選択します。
  3. エージェントを選択します。

    [デプロイメント] に移動

  4. [トレース] タブを選択します。
  5. [セッション ビュー] または [トレース ビュー] をクリックして、実行パスを検査します。
  6. 表から特定の行を選択して、詳細パネルを開きます。
  7. [評価] タブを選択します。
  8. トレースまたはセッションが評価されていない場合は、[評価] をクリックしてアドホック評価を実行します。

評価の結果を表示する

評価が完了したら、結果を分析してパフォーマンスのギャップとシステム上の問題を特定できます。

  • 実行の結果を表示する: Google Cloud コンソールで、[Agent Platform] > [エージェント] > [評価] ページに移動し、[評価] タブを選択します。評価名をクリックして、詳細なレポートを表示します。

    [評価] に移動

  • トレースにドリルダウンする: 結果レポートで任意の行をクリックすると、関連するトレースに直接移動し、スコアの根拠（理由）を確認できます。

詳細については、評価結果を分析するをご覧ください。