分析評估結果和失敗叢集

預先發布版 - Gemini Enterprise Agent Platform 的代理程式評估

這項功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》，以及《生成式 AI 服務專屬條款》。這項功能可供顧客評估 AI 代理程式，因此適用「代理式 AI 服務」服務專屬條款。正式發布前的產品和功能是按照「原樣」提供，支援範圍可能有限。詳情請參閱推出階段說明。

事前準備

如要查看及分析評估結果，請確認您具備下列條件：

• 如「評估代理」或「執行離線評估」所述，至少執行一次評估。
• 如果執行離線評估，請設定用於評估輸出的 Cloud Storage bucket。
• (選用) 如果使用 SDK 擷取結果，請確保環境已通過驗證。

執行評估後，Agent Platform 會提供診斷工具，協助您找出失敗的根本原因。您可以從三個層級分析結果：資訊主頁中的匯總趨勢、失敗叢集中的語意群組，以及個別追蹤記錄中的細微邏輯路徑。

線上監控器的評估資訊主頁

如果代理程式有啟用線上監控，您可以在資訊主頁中查看匯總成效趨勢：

1. 在 Google Cloud 控制台，前往「Agent Platform」>「Agents」頁面。
2. 在左側導覽選單中，選取「部署」。

3. 選取代理程式。

   前往「Deployments」(部署作業) 頁面

4. 按一下「資訊主頁」分頁標籤，然後選取「評估」子區段。

• 成效趨勢：以視覺化方式呈現不同代理程式版本或時間範圍內，「工作成功率」或「工具使用品質」等指標的分數變化。
• 零狀態：如果代理程式沒有有效的線上監控器，這個檢視畫面會找出涵蓋範圍缺口，並提供開始評估的號召性動作。

使用 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() 的摘要指標：

您可以展開個別評估案例，查看每個指標的分數、評分量表結果和理由：

解讀評估結果

預先定義的指標會根據指標類型，以兩種格式傳回結果：

• 適應性評量表指標會根據代理的設定和使用者的提示，自動生成評量表。每個評量表都會收到個別的「通過」或「未通過」判決，並附上自然語言的理由，說明評估 LLM 的推理過程。整體分數代表通過率，也就是獲得「通過」評語的評量表比例。
• 靜態評量表指標會使用一組固定的評估標準。舉例來說，幻覺會將回覆內容劃分為原子式陳述，並根據工具使用證據逐一檢查。安全檢查會檢查是否有個人識別資訊、仇恨言論、危險內容和其他違反政策的行為。這些指標會傳回單一數值分數 (0 到 1)。

找出並分類失敗

查看評估結果後，下一步是找出系統性失敗模式並進行分類，以改善服務專員。Agent Platform 提供自動損失分析功能，可分析評量表指標的通過或失敗信號，將失敗分類為預先定義的損失模式，並將這些模式分組為語意叢集。這有助於瞭解代理程式不僅失敗，還能知道原因和方式。

在控制台中存取失敗叢集

1. 前往「Agent Platform」>「Agents」>「Evaluation」頁面。
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() 的損失模式分析：

流失模式分類

自動損失分析會將每個失敗案例分類為一或多個預先定義的損失模式。這些模式具體可行，可直接對應到代理程式中需要改善的特定領域。

系統預先定義了兩種分類，分別對應特定指標：

代理程式任務成功分類

這項分類法會搭配「代理多輪對話工作成效」指標 (multi_turn_task_success_v1) 使用，涵蓋代理行為失敗的高層次原因，包括產生幻覺、遵循指令、呼叫工具、處理工具輸出內容和工具品質：

類別	損失模式	說明
幻覺	動作幻覺	代理聲稱已完成動作，但未執行必要的工具呼叫。
	幻生缺少的資訊	服務專員發明使用者查詢或工具輸出內容中沒有的詳細資料 (例如值、事實或日期)。
	工具或功能產生誤導資訊	代理程式聲稱擁有實際沒有的工具或功能。
指令遵循情形	違反限制條件	服務專員執行工作，但違反明確的使用者限制 (例如格式規則或負面限制)。
	無效動作 (短距離開球)	代理採取無關的動作，而不是說明無法使用現有工具完成工作。
	執行作業未完成	服務專員只完成部分工作就提前停止，或要求不必要的權限來執行明確要求的步驟。
	Over-Punting	代理程式拒絕執行工作，聲稱缺少實際擁有的工具或功能。
工具呼叫	選錯工具	代理從可用選項中選錯工具。
	語意不正確的工具參數	工具呼叫的語法有效，但參數值含有邏輯或語意錯誤。
	語法不正確的工具呼叫	工具呼叫有語法錯誤、缺少必要參數或引數值無效。
處理工具輸出內容	工具輸出內容處理有誤	代理程式收到有效的工具輸出內容，但擷取、處理或解讀資訊時發生錯誤。
工具品質	工具輸出內容不足	工具執行成功，但傳回的資料不足或缺少代理繼續運作所需的資料。
	工具故障	工具因基礎架構問題而失敗，例如驗證失敗、逾時或發生內部錯誤。

工具使用品質分類

這項分類法會與「代理多輪對話工具使用品質」指標 (multi_turn_tool_use_quality_v1) 搭配使用，主要著重於工具呼叫正確性和工具回覆處理：

類別	損失模式	說明
幻覺	參數值產生誤導資訊	如果使用者未提供參數，或無法從內容衍生參數，代理程式會發明特定值。
	工具幻覺	代理嘗試呼叫定義工具集中不存在的函式。
工具呼叫	無法設定參數	代理程式省略了滿足使用者限制條件所需的參數，因此預設為非預期的值。
	參數資料類型不正確	代理程式為參數提供錯誤資料類型的值 (例如需要整數時提供字串)。
	參數對應不正確	代理程式為錯誤的參數指派值 (例如交換開始和結束日期)。
	參數值不正確	代理程式提供的參數值在邏輯上或事實上不正確，或無法套用必要的資料轉換。
	選錯工具	代理從可用工具集選取錯誤的函式。
	工具呼叫語法無效	代理程式產生的函式呼叫含有語法錯誤，導致無法剖析或執行。
	不存在的參數	代理程式包含工具簽章中未定義的參數引數。
	省略必要工具呼叫	代理程式未執行必要功能，例如直接回答問題、略過複合要求的部分內容，或略過必要步驟。
	Under-Punting	代理程式應以自然語言回覆時 (例如要求釐清或拒絕超出範圍的要求)，卻強制進行工具呼叫。
工具回應	工具回應不相關	工具執行成功，但傳回的資料與使用者的特定查詢無關。
	工具錯誤	由於外部問題 (例如 API 服務中斷或權限無效)，工具會傳回明確的錯誤或失敗狀態。

建議的分類流程

請按照下列工作流程，有系統地分類評估失敗情形：

1. 先從摘要指標著手，找出評估資料集中得分最低的指標。
2. 深入瞭解每個案件的結果，找出失敗的特定評估案件。
3. 生成失敗叢集，找出失敗的系統性損失模式。
4. 深入瞭解追蹤記錄，找出發生失敗的確切回合或工具呼叫。在控制台中，依序前往「Agent Platform」>「Agents」>「Deployments」，選取您的代理程式，然後開啟「Traces」分頁。選取追蹤記錄，即可查看完整的對話記錄，以及模型輸入內容、工具呼叫和回應的確切順序。
5. 找出根本原因：使用損失模式類別判斷問題是提示、工具設定還是資料問題。
6. 套用目標修正，修正代理程式的系統指令、工具定義或少量樣本。
7. 重新執行評估並比較分數，確認改善成效。