查看 Model Armor 追蹤記錄時距

本文說明追蹤記錄中的 Model Armor span，以及如何查看詳細資料。如要進一步瞭解追蹤記錄，請參閱「查看代理追蹤記錄」。

Cloud Trace 和代理觀測簡介

追蹤記錄代表要求在分散式應用程式各部分之間的路徑。也就是說，每項追蹤記錄都代表一項端對端作業。追蹤記錄是由「spans」(時距) 組成，也就是單一函式或作業的記錄，因此您可以追蹤要求流程並檢查延遲時間資料。這項資訊有助於找出問題的根本原因。

Cloud Trace 是 Google Cloud的分散式追蹤系統，提供探索追蹤記錄或使用 SQL 分析追蹤記錄資料的功能。不過，許多Google Cloud 服務 (例如應用程式監控和代理程式註冊資料庫) 都可以顯示 Cloud Trace 管理的資料。這些服務可讓您在所用服務的情境中查看追蹤記錄資料。

事前準備

  1. 啟用 Cloud Trace、Cloud Logging、Telemetry 和 Model Armor API (如有尚未啟用的 API)。

    啟用 API 所需的角色

    您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果您建立了專案，可能已透過擁有者角色 (roles/owner) 取得這項權限。否則，您可以透過 Service Usage 管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

    啟用 API

  2. 為代理設定追蹤。
  3. 在閘道上設定 Model Armor，或在 Google CloudMCP 伺服器上設定。

必要的角色

如要取得查看追蹤記錄資料所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

如要瞭解可能需要的其他角色，請參閱「Cloud Trace 存取控管」和「Cloud Logging 存取控管」。

支援的酬載

如需支援的酬載清單，請參閱「支援和不支援的酬載」。

如果要求包含不支援的酬載，Model Armor 會產生含有錯誤的 Span。

Model Armor span 名稱和屬性

可用的 Model Armor span 如下：

  • 父項 Span：apply_guardrail "Google Cloud Model Armor"
  • 子項 Span：Request Path
  • 子項 Span：Response Path

下列各節列出 Model Armor 跨度的所有可能屬性。並非所有屬性都會出現在每個 Span 中。這些屬性名稱可能隨時變動。

父項 Span 屬性

父項 Span apply_guardrail "Google Cloud Model Armor" 具有下列屬性：

  • cloud.provider：與作業相關聯的雲端服務供應商。
  • cloud.region：作業發生的 Google Cloud 區域。
  • gcp.project_id：作業發生的專案 ID。
  • rpc.system：用於作業的基礎遠端程序呼叫 (RPC) 架構或通訊協定，例如 grpc。
  • service.name：與作業相關聯的 Google Cloud 服務。如果是 Model Armor 跨度，這個欄位的值為 modelarmor。

要求路徑屬性

Request Path 子項 Span 具有下列屬性：

  • gen_ai.security.target.type：護欄適用的內容或動作類型。在 Request Path 跨度中，這項屬性一律為 input。
  • gen_ai.security.decision.type：Model Armor 套用的判定結果或動作。如果值為 modify，表示 Model Armor 根據提供的範本，從內容中遮蓋 (去識別化) 機密資料。
  • gen_ai.security.decision.code：安全性決策的數字代碼。
  • gen_ai.security.decision.reason：使用者可理解的決策原因。
  • gen_ai.security.policy.id：Model Armor 範本的完整資源名稱，格式為 projects/PROJECT_ID/locations/LOCATION/templates/MODEL_ARMOR_TEMPLATE_ID。
  • gen_ai.security.policy.name：用於作業的 Model Armor 範本名稱。
  • gcp.modelarmor.filter.match.state：內容是否違反任何 Model Armor 篩選器 (也稱為偵測工具)。
  • gcp.modelarmor.violations：內容違反的 Model Armor 篩選器。如果值為 deidentified，表示 Model Armor 已根據提供的範本，從內容中遮蓋機密資料。
  • gcp.modelarmor.rai.violations：內容違反的負責任 AI 類別。詳情請參閱「負責任的 AI 安全篩選器」。
  • gcp.modelarmor.sdp.info_types：Sensitive Data Protection 篩選器識別出的機密資料類型 (例如 EMAIL_ADDRESS 或 PHONE_NUMBER)。
  • error.type：發生錯誤的 ID。

回應路徑屬性

Response Path 子項 Span 具有下列屬性：

  • gen_ai.security.target.type：護欄適用的內容或動作類型。在 Response Path span 中，這項屬性一律為 output。
  • gen_ai.security.decision.type：Model Armor 套用的判定結果或動作。如果值為 modify，表示 Model Armor 根據提供的範本，從內容中遮蓋 (去識別化) 機密資料。
  • gen_ai.security.decision.code：安全性決策的數字代碼。
  • gen_ai.security.decision.reason：使用者可理解的決策原因。
  • gen_ai.security.policy.id：Model Armor 範本的完整資源名稱，格式為 projects/PROJECT_ID/locations/LOCATION/templates/MODEL_ARMOR_TEMPLATE_ID。
  • gen_ai.security.policy.name：用於作業的 Model Armor 範本名稱。
  • gcp.modelarmor.filter.match.state：內容是否違反任何 Model Armor 篩選器 (也稱為偵測工具)。
  • gcp.modelarmor.violations：內容違反的 Model Armor 篩選器。如果值為 deidentified，表示 Model Armor 已根據提供的範本，從內容中遮蓋機密資料。
  • gcp.modelarmor.rai.violations：內容違反的負責任 AI 類別。詳情請參閱「負責任的 AI 安全篩選器」。
  • gcp.modelarmor.sdp.info_types：Sensitive Data Protection 篩選器識別出的機密資料類型 (例如 EMAIL_ADDRESS 或 PHONE_NUMBER)。
  • error.type：發生錯誤的 ID。

查看 Model Armor 掃描詳細資料

如要查看 Model Armor 追蹤記錄 span 和詳細資料 (包括屬性和 DAG)，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「Agent Registry」頁面。

    前往 Agent Registry

  2. 選取專案。
  3. 按一下代理程式名稱。
  4. 按一下「Traces」分頁標籤。
  5. 按一下要查看的追蹤記錄 ID。如果追蹤記錄涉及 Model Armor 跨度，則會包含 apply_guardrail "Google Cloud Model Armor" 跨度。

  6. 探索追蹤記錄：

    • 如要以有向無環圖 (DAG) 的形式查看追蹤記錄，請按一下「Graph」(圖表) 檢視畫面。這個檢視畫面會以節點連結圖表呈現代理的執行追蹤記錄。DAG 強調不同追蹤記錄 span 之間的因果關係和依附元件，並顯示一項作業如何觸發下一項作業。圖表中的每個節點都是一個 span。
    • 如要以時間軸形式查看追蹤記錄，請按一下「Timeline」(時間軸) 檢視畫面。時間軸中的每個長條都代表一個 Span。

  7. 按一下 Span 即可查看其屬性。

或者，您也可以點選「在 Cloud Trace 查看」，透過「Trace 探索工具」查看專案中的所有 Span。套用 Span 篩選器，搜尋 apply_guardrail "Google Cloud Model Armor" Span。

後續步驟