Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

評価結果と障害クラスタを分析する

始める前に

評価結果を表示して分析するには、次のものがあることを確認してください。

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

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

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

オンラインモニターが有効になっているエージェントについては、ダッシュボードでパフォーマンスの集計トレンドを確認できます。

Google Cloud コンソールで、[エージェントプラットフォーム] > [エージェント] ページに移動します。
左側のナビゲーションメニューで、[デプロイ] を選択します。
エージェントを選択します。
[デプロイメント] に移動
[ダッシュボード] タブをクリックし、[評価] サブセクションを選択します。

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

SDK で評価結果を表示する

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

評価を実行したら、結果オブジェクトで .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 の理由を説明する自然言語の根拠が与えられます。総合スコアは合格率（合格の判定を受けたルーブリックの割合）を表します。
静的ルーブリック指標では、固定の評価基準セットを使用します。たとえば、Hallucination はレスポンスをアトミックな主張に分割し、それぞれをツール使用の証拠と照合します。個人情報、ヘイトスピーチ、危険なコンテンツ、その他のポリシー違反に関する安全性チェック。これらの指標は、単一の数値スコア（0 ～ 1）を返します。

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

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

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

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

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）で使用されます。ハルシネーション、指示の遵守、ツールの呼び出し、ツールの出力処理、ツールの品質など、エージェントの行動に関する大まかな失敗を網羅しています。

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

ツール使用の品質の分類

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

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

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

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

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

評価結果と障害クラスタを分析する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。