使用線上監控器持續評估

線上監控功能可讓您持續評估正式環境中的代理品質。這種主動做法有助於找出品質漂移，也就是代理效能隨時間明顯下降，這通常是使用者行為或外部資料變更所致。線上監控設定完成後，您就能使用預先定義和自訂指標，以非同步方式為即時追蹤記錄評分，確保代理穩定可靠，符合您的效能標準。

事前準備

如要啟用代理程式線上監控功能，請務必符合下列規定：

  • 按照「部署代理」一文所述部署代理。
  • 確認專案已啟用 Cloud Trace。
  • (選用) 如果您打算透過程式輔助方式建立監控器，請參閱「評估代理」頁面，瞭解 Agent Platform SDK 初始化操作說明。

遙測相關規定

線上監控功能需要代理匯出特定 OpenTelemetry 信號，提供評估所需的背景資訊：

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

    • 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 bucket，而非直接嵌入追蹤記錄 span。如要啟用這項功能，請設定下列環境變數：

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

詳情請參閱「收集多模態提示和回覆」。

線上監控器的運作方式

線上監控會按照排定的評估迴圈執行，通常每 10 分鐘一次。迴圈會按照下列步驟執行：

  1. 查詢：根據篩選條件，從 Cloud Trace 和 Cloud Logging 擷取樣本資料。
  2. 評估：使用 Gemini Enterprise Agent Platform Evaluation Service 執行設定的指標。
  3. 報表：將結果寫回 Cloud Logging，並將數值分數匯出至 Cloud Monitoring。

建立線上監控器

  1. 前往 Google Cloud 控制台，依序點選「Agent Platform」>「代理」>「評估」。

    前往「Evaluation」(評估)

  2. 選取「線上監控」分頁標籤，然後按一下「新增監控」。

  3. 指定篩選追蹤記錄：

    • 代理引擎：從下拉式選單中選取要監控的代理。
    • 篩選條件：選擇要評估代理的所有追蹤記錄，還是套用特定篩選條件。

  4. 定義篩選條件 (如果使用篩選過的追蹤記錄)：

    • 初步檢查：選取時間範圍 (例如「過去 1 天」)，預覽篩選器比對出的實際工作環境追蹤記錄。
    • 篩選器：輸入條件，指定特定流量。您可以依 Duration (例如 Duration > 2) 或 Token usage 等屬性篩選。

  5. 設定指標：新增要持續追蹤的指標，例如「安全性」。

  6. 設定取樣：

    • 取樣百分比：定義要評估的即時流量百分比。
    • 每次執行的樣本數量上限：設定上限，控管評估費用。

  7. 點選「建立」。

管理監控

建立監控器後，可以透過「線上監控器」清單管理：

  • 狀態切換鈕：按一下「更多選項」圖示 ，然後選取「啟用」或「停用」，即可暫停評估，而不刪除設定。
  • 暫停和繼續：使用「更多選項」 暫時停止評估。
  • 複製：建立新的監控工具，並預先填入現有監控工具的設定。
  • 查看追蹤記錄：在「Sampled traces」(取樣追蹤記錄) 欄中，按一下監控器的「View traces」(查看追蹤記錄) 連結，即可直接前往代理程式「Traces」(追蹤記錄) 分頁中篩選出的追蹤記錄。

在觀測能力資訊主頁查看結果

如要查看評估指標和其他成效信號，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「Agent Platform」>「代理」頁面。
  2. 選取左側導覽選單中的「Deployments」(部署作業)。

  3. 選取代理。

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

  4. 在「Dashboard」(資訊主頁) 檢視畫面中，選取「Evaluation」(評估) 子區段，即可查看已設定指標的時間序列圖表，例如回覆品質、安全性和幻覺率。

查看個別追蹤記錄的結果

您也可以直接在追蹤記錄檢視畫面中，檢查特定對話的評估結果：

  1. 在 Google Cloud 控制台，前往代理的「追蹤記錄」分頁。
  2. 從表格中選取工作階段或追蹤記錄，開啟詳細資料面板。
  3. 選取「評估」分頁標籤，即可查看該次互動的分數和理由。

排解線上監控器問題

如果線上監控功能已啟用，但資訊主頁未顯示任何結果，請按照下列步驟操作：

  1. 驗證遙測：確認代理程式正確匯出必要的 OpenTelemetry span 和事件。查看 Cloud Trace，確認即時追蹤記錄是否包含 gen_ai. 屬性。
  2. 檢查篩選器：查看監控項目的篩選條件。使用「Initial Inspection」(初始檢查) 功能，確認篩選器與實際工作環境流量相符。

  3. 查看內部記錄：線上監控器會將診斷資訊寫入 Cloud Logging。如果評估失敗，系統會產生錯誤記錄。您可以在 Logs Explorer 中搜尋監控 ID，或特定追蹤記錄和代理程式，找到這些記錄：

    resource.labels.online_evaluator="projects/YOUR_PROJECT_ID/locations/YOUR_REGION/onlineEvaluators/YOUR_MONITOR_ID"
# Or search by trace or agent
labels.trace="YOUR_TRACE_ID"
labels.reasoning_engine_id="YOUR_AGENT_ID"