使用線上監控器持續評估

線上監控功能可持續評估正式環境中代理程式的品質。這種主動式做法有助於找出品質偏移 (代理程式效能隨時間明顯下降)，這是由使用者行為或外部資料變化所致。設定線上監控器後，您可以使用預先定義和自訂指標，非同步評估即時追蹤記錄，確保代理程式維持可靠性，並符合效能標準。

事前準備

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

  • 按照「部署代理程式」一文的說明部署代理程式。
  • 確認專案已啟用 Cloud Trace。
  • (選用) 如果您打算以程式輔助方式建立監控器，請參閱「評估代理程式」頁面，瞭解 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'

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

線上監控器的運作方式

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

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

建立線上監控器

  1. 在 Google Cloud 控制台，前往「Agent Platform > Agents > Evaluation」頁面。

    前往「評估」

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

  3. 指定篩選追蹤記錄：

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

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

    • 初步檢查：選取時間範圍 (例如「過去 1 天」)，預覽篩選器相符的生產追蹤記錄。
    • 篩選器：輸入條件，指定特定流量。您可以依 Duration (例如 Duration > 2) 或 Token usage 等屬性進行篩選。

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

  6. 設定取樣：

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

  7. 點選「建立」。

管理螢幕

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

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

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

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

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

  3. 選取代理程式。

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

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

查看個別追蹤記錄的結果

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

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

排解線上監控器問題

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

  1. 驗證遙測資料：請確認代理程式是否正確匯出必要的 OpenTelemetry 範圍和事件。檢查 Cloud Trace，看看即時追蹤記錄是否包含 gen_ai. 屬性。
  2. 檢查篩選器：檢查監視器的篩選條件。使用「初步檢查」功能，確認篩選器與實際流量相符。

  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"