評価結果と失敗クラスタを分析する

始める前に

評価結果を表示して分析するには、次のものが必要です。

• エージェントを評価するまたはオフライン評価を実行するの説明に従って、少なくとも 1 回の評価を実行している。
• オフライン評価を実行する場合は、評価出力用に Cloud Storage バケットを構成している。
• （省略可）SDK を使用して結果を取得する場合は、環境が認証されている。

評価を実行すると、Agent Platform には、障害の根本原因を特定するのに役立つ診断ツールが用意されています。結果は、ダッシュボードの集計トレンド、障害クラスタのセマンティック グループ、個々のトレースの粒度の細かいロジックパスの 3 つのレベルで分析できます。

オンライン モニターの評価ダッシュボード

アクティブな オンライン モニター を使用するエージェントの場合、ダッシュボードで集計されたパフォーマンス のトレンドを確認できます。

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

3. エージェントを選択します。

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

4. [ダッシュボード] タブをクリックし、[評価] サブセクションを選択します。

• パフォーマンスのトレンド: タスクの成功 やツールの使用品質 などの指標のスコアが、エージェントのバージョンや期間によってどのように変化するかを可視化します。
• ゼロ状態: アクティブな オンライン モニター を使用していないエージェントの場合、このビューで カバレッジのギャップを特定し、評価を開始するための行動を促すフレーズを表示します。

SDK で評価結果を表示する

評価結果には、Agent Platform SDK を使用してプログラムでアクセスできます。 SDK には、Colab 環境と Jupyter Notebook 環境用の組み込みのインタラクティブな可視化機能が用意されており、集計された概要指標とケースごとの詳細な結果の両方が表示されます。

評価を実行したら、結果オブジェクトで .show() を呼び出して、ノートブックにインタラクティブなレポートを直接レンダリングします。

from vertexai import evals, types

# Run an evaluation
result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[
        types.RubricMetric.FINAL_RESPONSE_QUALITY,
        types.RubricMetric.TOOL_USE_QUALITY,
        types.RubricMetric.HALLUCINATION,
        types.RubricMetric.SAFETY,
    ],
)

# Visualize aggregate and per-case results in your notebook
result.show()

可視化には次のものが含まれます。

• 概要指標: 各指標の平均スコアや合格率など、すべての評価ケースの集計スコア。
• ケースごとの結果: 個々の評価ケースのスコア。展開して詳細な結果を確認できます。

次の例は、result.show() の概要指標を示しています。

個々の評価ケースを展開して、指標ごとのスコア、ルーブリックの判定、理由を確認できます。

評価結果を解釈する

事前定義された指標は、指標のタイプに応じて 2 つの形式で結果を返します。

• 適応型ルーブリック指標 は、エージェントの構成とユーザーのプロンプトに基づいてルーブリックを自動的に生成します。各ルーブリックには、判定 LLM の推論を説明する自然言語の理由とともに、個別の合格 または不合格 の判定が与えられます。総合スコアは合格率を表します。つまり、合格 の判定を受けたルーブリックの割合です。
• 静的ルーブリック指標 は、固定の評価基準セットを使用します。たとえば、ハルシネーションはレスポンスをアトミックなクレームに分割し、それぞれをツールの使用状況の証拠と照らし合わせて確認します。 PII、ヘイトスピーチ、危険なコンテンツ、その他のポリシー違反がないか安全性をチェックします。これらの指標は、単一の数値スコア（0 ～ 1）を返します。

障害を特定してトリアージする

評価結果を確認したら、次のステップとして、システム障害のパターンを特定し、トリアージしてエージェントを改善します。Agent Platform には、自動損失分析が用意されています。これは、ルーブリック ベースの指標からの合格または不合格のシグナル を分析し、障害を事前定義された損失パターンに分類して、 セマンティック クラスタにグループ化します。これにより、エージェントが失敗したという事実だけでなく、失敗した理由と方法を把握できます。

コンソールで障害クラスタにアクセスする

1. [Agent Platform] > [エージェント] > [評価] ページに移動します。
2. [評価] タブを選択します。
3. 完了した評価実行の名前をクリックしてレポートを開きます。
4. 評価でクラスタが検出された場合は、レポートの [障害クラスタ] セクションに表示されます。

SDK で障害クラスタを生成する

generate_loss_clusters メソッドを使用して、障害クラスタをプログラムで生成することもできます。

# Generate failure clusters from evaluation results
loss_clusters = client.evals.generate_loss_clusters(
    eval_result=result,
)

# Visualize the loss pattern analysis in your notebook
loss_clusters.show()

次の例は、loss_clusters.show() の損失パターン分析を示しています。

損失パターンの分類

自動損失分析では、各障害が 1 つ以上の事前定義された損失パターンに分類されます。これらのパターンは具体的で実用的なものになるように設計されており、改善できるエージェントの特定の領域に直接マッピングされます。

事前定義された分類が 2 つあり、それぞれ特定の指標に沿っています。

エージェントのタスク成功率の分類

この分類は、エージェントのマルチターンのタスク成功率 指標（multi_turn_task_success_v1）で使用されます。ハルシネーション、指示実行、ツール呼び出し、ツール出力処理、ツールの品質など、エージェントの動作に関する高レベルの障害をカバーしています。

カテゴリ	損失パターン	説明
ハルシネーション	アクションのハルシネーション	エージェントは、必要なツール呼び出しを実行せずにアクションを完了したと主張します。
	情報不足のハルシネーション	エージェントは、ユーザーのクエリやツールの出力に存在しない詳細（値、事実、日付など）を でっち上げます。
	ツールまたは機能のハルシネーション	エージェントは、持っていないツールや機能を持っていると主張します。
指示実行	制約違反	エージェントはタスクを実行しますが、明示的なユーザー制約 （書式設定ルールや否定制約など）に違反します。
	無駄なアクション（過小なプンティング）	エージェントは、利用可能なツールではタスク を実行できないことを伝える代わりに、無関係なアクションを実行します。
	実行が不完全	エージェントはタスクを部分的に完了しますが、途中で停止するか、明示的にリクエストされたステップに対して不要な権限を要求します。
	過剰なプンティング	エージェントは、実際には持っているツールや機能がないと主張して、タスクを拒否します。
ツールの呼び出し	誤ったツールの選択	エージェントは、利用可能なオプションから間違ったツールを選択します。
	意味的に正しくないツールパラメータ	ツール呼び出しは構文的には有効ですが、パラメータ値に論理的または 意味的なエラーが含まれています。
	構文的に正しくないツール呼び出し	ツール呼び出しに構文エラーがあるか、必須パラメータが指定されていないか、 引数値が無効です。
ツール出力の処理	誤ったツール出力の処理	エージェントは有効なツール出力を受け取りますが、情報を正確に抽出、 処理、解釈しません。
ツールの品質	ツール出力が不十分	ツールは正常に実行されますが、エージェントが処理を進めるために必要なデータが不足しているか、欠落しています。
	ツールの障害	認証の失敗、タイムアウト、内部エラーなどのインフラストラクチャの問題により、ツールが失敗します。

ツールの使用品質の分類

この分類は、エージェントのマルチターンのツール使用の品質 指標（multi_turn_tool_use_quality_v1）で使用されます。ツールの呼び出しの正確さとツール応答の処理に特に重点を置いています。

カテゴリ	損失パターン	説明
ハルシネーション	パラメータ値のハルシネーション	エージェントは、ユーザーが指定していないか、コンテキストから導き出すことができないパラメータの特定の値をでっち上げます。
	ツールのハルシネーション	エージェントは、定義されたツールセットに存在しない関数を呼び出そうとします。
ツールの呼び出し	パラメータの設定に失敗した	エージェントは、ユーザーの制約を満たすために必要なパラメータを省略し、 意図しない値にデフォルト設定します。
	パラメータのデータ型が正しくない	エージェントは、パラメータに間違ったデータ型の値を提供します （整数が必要な場合に文字列など）。
	パラメータのマッピングが正しくない	エージェントは、間違ったパラメータに値を割り当てます（開始日と終了日を入れ替えるなど）。
	パラメータ値が正しくない	エージェントは、論理的または事実的に 正しくないパラメータ値を指定するか、必要なデータ変換を適用しません。
	誤ったツールの選択	エージェントは、利用可能なツールセットから間違った関数を選択します。
	ツールの呼び出し構文が無効	エージェントは、解析や実行を妨げる構文エラーを含む関数呼び出しを生成します。
	存在しないパラメータ	エージェントには、ツールのシグネチャで定義されていないパラメータ引数が含まれています。
	必要なツール呼び出しの省略	エージェントは、直接回答する、複合リクエストの一部をスキップする、前提条件となるステップをスキップするなどして、必要な関数を実行できません。
	過小なプンティング	エージェントは、自然言語で応答する必要がある場合（説明を求める、範囲外のリクエストを拒否するなど）に、ツール呼び出しを強制します。
ツール応答	関連性の低いツール応答	ツールは正常に実行されますが、ユーザーの特定のクエリに関連しないデータを返します。
	ツールのエラー	外部の問題（API の停止や無効な権限など）により、ツールが明示的なエラーまたは失敗ステータスを返します。

推奨されるトリアージ ワークフロー

次のワークフローを使用して、評価の失敗を体系的にトリアージします。

1. 概要指標から開始 して、評価データセット全体でスコアが最も低い指標を特定します。
2. ケースごとの結果をドリルダウン して、失敗した特定の評価ケースを見つけます。
3. 障害クラスタを生成 して、障害全体のシステム損失パターンを特定します。
4. トレースをドリルダウン して、障害が発生した正確なターンまたはツール呼び出しを見つけます。コンソールで、[Agent Platform] > [エージェント] > [デプロイメント] に移動し、エージェントを選択して [トレース] タブを開きます。トレースを選択すると、会話履歴全体と、モデル入力、ツール呼び出し、レスポンスの正確なシーケンスが表示されます。
5. 根本原因を特定する : 損失パターンのカテゴリを使用して、 問題がプロンプトの問題、ツールの構成の問題、または データの問題のいずれであるかを判断します。
6. エージェントのシステム指示、ツール定義、または少数ショットの例に的を絞った修正を適用 します。
7. 評価を再実行 し、スコアを比較して改善を確認します。