執行離線評估

離線評估功能可讓您分析開發或製作期間擷取的歷來資料，評估代理程式的效能、安全性和品質。您可以根據一組預先定義或自訂的指標，評估個別「追蹤記錄」 (單一執行路徑) 或完整「工作階段」 (多輪對話記錄)。

追蹤記錄與工作階段

  • 追蹤記錄：代理行為的不可變更事實記錄，包括模型輸入內容、回覆和工具呼叫。追蹤記錄代表單一執行路徑。
  • 工作階段：涵蓋使用者與虛擬服務專員之間的所有多輪互動。您可以使用工作階段評估脈絡保留情形和一段時間內的對話流程。

事前準備

為確保您擁有離線評估所需的資料和環境，請完成下列步驟：

  • 確認您已部署有效的 Agent Runtime，並啟用 Cloud Trace。
  • 設定 Cloud Storage bucket，用於儲存評估結果。這個路徑只需要提供一次，日後執行時會預先填入。
  • 如果您打算使用 Agent Platform SDK 進行評估，請按照「評估代理程式」一文的說明初始化用戶端。

遙測相關規定

離線評估需要代理程式匯出特定的 OpenTelemetry 信號，以提供評估所需的脈絡。這些規定與線上監控器的規定相同：

  1. 叫用代理程式範圍：必須包含下列屬性：

    • gen_ai.agent.name：代理程式的 ID。
    • gen_ai.agent.description：代理程式用途的簡短說明。
    • gen_ai.conversation.id：特定對話工作階段的專屬 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 控制台，前往「Agent Platform > Agents > Evaluation」頁面。

    前往「評估」

  2. 按一下「New evaluation」(新增評估)。

  3. 根據評估目標選取「追蹤」或「工作階段」分頁。

  4. 使用篩選器圖示和時間挑選器篩選資料 (例如依「版本」或「過去 2 週」)，然後選取要評估的特定 ID。

  5. 按一下「繼續」。

  6. (選用) 在「評估名稱」欄位中，輸入評估名稱或使用預先填入的預設名稱。

  7. 在「Output private data path」(輸出私人資料路徑) 欄位中，輸入 Cloud Storage bucket URI。首次使用後，這個路徑會預先填入，供日後執行作業時使用。

  8. 系統預設會加入所有四項核心指標。您可以視需要新增或移除指標。

  9. 按一下「評估代理程式」。

評估單一追蹤記錄或工作階段

檢查個別執行路徑時，您可以直接觸發評估：

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

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

  4. 選取「追蹤」分頁標籤。
  5. 按一下「工作階段檢視畫面」或「追蹤記錄檢視畫面」，即可檢查執行路徑。
  6. 從表格中選取特定資料列，開啟詳細資料面板。
  7. 選取「評估」分頁標籤。
  8. 如果系統尚未評估追蹤記錄或工作階段，請按一下「評估」，執行臨時評估。

查看評估結果

評估完成後，您可以分析結果，找出效能落差和系統性問題：

  • 查看執行結果：在 Google Cloud 控制台，依序前往「Agent Platform」>「Agents」>「Evaluation」頁面，然後選取「Evaluations」分頁標籤。按一下評估名稱即可查看詳細報表。

    前往「評估」

  • 下鑽至追蹤記錄：在結果報表中，點擊任一行即可直接前往相關聯的追蹤記錄，並檢查分數背後的推論 (基本原理)。

詳情請參閱「分析評估結果」。