Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

設定記錄功能

本文說明如何設定 Model Armor，記錄下列作業：

建立、更新或刪除範本的作業
清理使用者提示詞或模型回覆的作業

Model Armor 會使用稽核記錄，記錄管理和資源管理活動。詳情請參閱「Model Armor 稽核記錄」。

如要瞭解記錄定價，請參閱「Cloud Logging 定價」。系統也可能依據處理的資料量，收取 Model Armor 使用費，詳情請參閱「Model Armor 定價」。

事前準備

開始之前，請先完成下列工作。

取得必要權限

如要取得設定 Model Armor 記錄所需的權限，請要求管理員授予您 Model Armor 範本的「Model Armor 管理員」(roles/modelarmor.admin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

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

啟用 API

您必須先啟用 Model Armor API，才能使用 Model Armor。

控制台

如果尚未啟用 Model Armor API，請先啟用。
啟用 API 所需的角色
如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「服務使用管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。
啟用 API
選取要啟用 Model Armor 的專案。

gcloud

開始之前，請使用 Google Cloud CLI 搭配 Model Armor API 執行下列步驟：

在 Google Cloud 控制台啟用 Cloud Shell。

啟用 Cloud Shell

Google Cloud 控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已設定適用於您目前專案的值。工作階段可能要幾秒鐘的時間才能初始化。
如果尚未啟用 Model Armor API，請啟用：
啟用 API 所需的角色
如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「服務使用管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。
```
gcloud services enable modelarmor.googleapis.com
```
使用 gcloud CLI 設定 API 端點覆寫。

使用 gcloud CLI 設定 API 端點覆寫

只有在搭配 Model Armor 使用 gcloud CLI，且想使用預設 us 多區域以外的區域或多區域時，才需要執行這個步驟。您必須手動設定 API 端點覆寫，確保 gcloud CLI 正確將要求轉送至 Model Armor 服務。

執行下列指令，為 Model Armor 服務設定 API 端點。

gcloud config set api_endpoint_overrides/modelarmor "https://modelarmor.LOCATION.rep.googleapis.com/"

將 LOCATION 替換為要使用 Model Armor 的區域或多區域。

設定流量清理

如果是 Google 和 Google Cloud MCP 伺服器，請透過底限設定來設定流量清理。詳情請參閱「設定 Google 和 Google Cloud MCP 伺服器的保護措施」。

在範本中設定記錄功能

範本會定義不同安全類別的篩選條件和門檻。建立或更新 Model Armor 範本時，可以指定 Model Armor 是否要記錄特定作業。在範本中繼資料中使用下列標記：

log_template_operations：布林值，可讓您記錄範本的建立、更新、讀取和刪除作業。
log_sanitize_operations：布林值，可讓您在清理作業期間，記錄使用者提示詞和模型回覆的完整內容。

控制台

前往 Google Cloud 控制台的「Model Armor」頁面。

前往 Model Armor
確認您正在查看已啟用 Model Armor 的專案。
在「Model Armor」頁面，點選「建立範本」。如要進一步瞭解如何建立範本，請參閱「建立 Model Armor 範本」。
在「Configure logging」(設定記錄) 部分，選取要設定記錄檔的操作。
點選「建立」。

REST

  curl -X POST \
      -d '{ "filterConfig": {}, "templateMetadata": { "logTemplateOperations": true, "logSanitizeOperations": true } }' \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates?template_id=TEMPLATE_ID"

更改下列內容：

PROJECT_ID：範本所屬專案的 ID。
LOCATION：範本的位置。
TEMPLATE_ID：範本 ID。

Python

如要執行這段程式碼，請先設定 Python 開發環境，然後安裝 Model Armor Python SDK。

   request = modelarmor_v1.CreateTemplateRequest(
     parent="projects/PROJECT_ID/locations/LOCATION",
     template_id="TEMPLATE_ID",
     template={
        "name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
        "filter_config": {},
        "template_metadata": {
           "log_template_operations": True,
           "log_sanitize_operations": True
        }
     }
   )
   response = client.create_template(request=request)

更改下列內容：

PROJECT_ID：範本所屬的專案 ID。
LOCATION：範本的位置。
TEMPLATE_ID：範本 ID。

在底限設定中設定記錄功能

在專案中，對 Gemini Enterprise Agent Platform 和 Google 及 Google Cloud MCP 伺服器內 Gemini 模型產生的流量強制執行底限設定時，底限設定會定義清除作業的安全和安全防護篩選條件。更新 Model Armor 底限設定時，可以指定 Model Armor 是否要記錄清理作業。

您可以分別為 Agent Platform、Google 和 Google Cloud MCP 伺服器啟用清理作業的記錄功能。啟用後，記錄會包含提示詞和回覆 (適用於 Agent Platform) 或工具呼叫和工具回覆 (適用於 MCP 伺服器)、Model Armor 的評估結果，以及其他中繼資料欄位。

下列範例說明如何為 Agent Platform 和 Google 與 Google Cloud MCP 伺服器啟用清理作業記錄。

控制台

前往 Google Cloud 控制台的「Model Armor」頁面。

前往 Model Armor
確認您正在查看已啟用 Model Armor 的專案。
前往「樓層設定」分頁。
在「Logs」(記錄) 部分，勾選「Vertex AI」和「Google managed MCP」(Google 代管 MCP) 核取方塊，啟用各項服務的記錄功能。
按一下 [儲存]。

gcloud

使用 --enable-vertex-ai-cloud-logging 標記啟用 Agent Platform 的記錄功能，並使用 --enable-google-mcp-server-cloud-logging 標記啟用 Google 和 Google Cloud MCP 伺服器的記錄功能。如要停用記錄功能，請使用 --no-enable-vertex-ai-cloud-logging 和 --no-enable-google-mcp-server-cloud-logging 旗標。

下列範例指令會為 Agent Platform、Google 和 MCP 伺服器啟用清除作業記錄功能： Google Cloud

gcloud model-armor floorsettings update \
--full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
--enable-vertex-ai-cloud-logging \
--enable-google-mcp-server-cloud-logging

將 PROJECT_ID 替換為專案 ID。

REST

如要啟用記錄功能，請在 UpdateFloorSetting 方法中，將 Agent Platform 的 aiPlatformFloorSetting.enableCloudLogging 設為 true，並將 Google 和 Google Cloud MCP 伺服器的 googleMcpServerFloorSetting.enableCloudLogging 設為 true。

下列範例指令會為 Agent Platform 和 Google MCP 伺服器啟用清理作業記錄： Google Cloud

curl -X PATCH \
 -d '{ "aiPlatformFloorSetting":{ "enableCloudLogging": true}, "googleMcpServerFloorSetting":{ "enableCloudLogging": true}}' \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://modelarmor.googleapis.com/v1/projects/PROJECT_ID/locations/global/floorSetting?updateMask=aiPlatformFloorSetting.enableCloudLogging,googleMcpServerFloorSetting.enableCloudLogging"

將 PROJECT_ID 替換為專案 ID。

Python

如要執行這段程式碼，請先設定 Python 開發環境，然後安裝 Model Armor Python SDK。

from google.cloud.modelarmor import v1 as modelarmor_v1
from google.protobuf import field_mask_pb2

# TODO: Initialize the ModelArmorClient, "client"
# client = modelarmor_v1.ModelArmorClient()

project_id = "PROJECT_ID"
location = "global"

floor_setting_name = f"projects/{project_id}/locations/{location}/floorSetting"

request = modelarmor_v1.UpdateFloorSettingRequest(
    floor_setting=modelarmor_v1.FloorSetting(
        name=floor_setting_name,
        ai_platform_floor_setting=modelarmor_v1.FloorSetting.AiPlatformFloorSetting(
            enable_cloud_logging=True
        ),
        google_mcp_server_floor_setting=modelarmor_v1.FloorSetting.GoogleMcpServerFloorSetting(
            enable_cloud_logging=True
        ),
    ),
    update_mask=field_mask_pb2.FieldMask(
        paths=["ai_platform_floor_setting.enable_cloud_logging", "google_mcp_server_floor_setting.enable_cloud_logging"]
    )
)

try:
    response = client.update_floor_setting(request=request)
    print("Successfully updated floor settings logging.")
    print(response)
except Exception as e:
    print(f"An error occurred: {e}")

將 PROJECT_ID 替換為專案 ID。

查看及篩選 Model Armor 記錄

如要查看及篩選 Model Armor 記錄，請使用 Logging 中的 Logs Explorer：

前往 Google Cloud 控制台的「Logs Explorer」頁面。

前往「Logs Explorer」頁面

詳情請參閱「使用 Logs Explorer 查看記錄檔」。
在查詢窗格中，輸入下列任一查詢來篩選 Model Armor 記錄：
- 如要查看所有 Model Armor 記錄，包括稽核記錄和清除作業記錄，請按照下列步驟操作：
```
protoPayload.serviceName="modelarmor.googleapis.com" OR jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
```
- 如要只查看 Model Armor 稽核記錄，請按照下列步驟操作：
```
protoPayload.serviceName="modelarmor.googleapis.com"
```
  如需所有服務名稱和受監控資源類型的清單，請參閱「受監控的資源和服務」。
- 如要只查看 Model Armor 清理作業的記錄，請按照下列步驟操作：
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
```
  如要進一步篩選清除作業記錄，可以在查詢中指定用戶端名稱、關聯 ID 或排除規則 (預覽版) 評估標籤：
  - 使用用戶端名稱：Model Armor 與 Gemini Enterprise Agent Platform 或 Gemini Enterprise 等服務整合時，您可以使用用戶端名稱篩選特定整合的記錄。
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
labels."modelarmor.googleapis.com/client_name"="CLIENT_NAME"
```
  - 使用關聯性 ID：
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
labels."modelarmor.googleapis.com/client_correlation_id"="CORRELATION_ID"
```
    更改下列內容：
    - CLIENT_NAME：用戶端名稱。請使用下列其中一個值：
      - CLIENT_NAME_UNSPECIFIED：預設值，用於未指定用戶端名稱的情況。
      - VERTEX_AI：與 Gemini Enterprise Agent Platform 整合。
      - LOAD_BALANCER：使用負載平衡器做為服務擴充功能進行整合。
      - LANGCHAIN：與 LangChain 整合。
      - GEMINI_ENTERPRISE_BUSINESS：與 Gemini Enterprise - Business 版整合。
      - GOOGLE_MCP_SERVER：用於與 Google 和 Google 代管的 MCP 伺服器整合。
      - AGENT_GATEWAY：與 Agent Gateway 整合。
      - GEMINI_ENTERPRISE_NON_BUSINESS：用於整合 Gemini Enterprise 版本 (Business Standard、Plus 和 Frontline 除外)。
      - SECURE_WEB_PROXY：用於與 Secure Web Proxy 整合。
    - CORRELATION_ID：您為特定要求產生的專屬 ID。
  - 使用排除規則 (預覽) 標籤：當排除規則覆寫篩選結果，或 Model Armor 略過排除規則評估時，Model Armor 會在 modelarmor.googleapis.com/SanitizeOperation 記錄項目中填入下列選用的頂層 labels 欄位：
    - modelarmor.googleapis.com/exclusion_rule_overridden_filters：以半形逗號分隔的篩選條件清單，這些篩選條件的 MATCH_FOUND 或 EXECUTION_SKIPPED 結果因符合排除規則而遭到覆寫為 NO_MATCH_FOUND。
    - modelarmor.googleapis.com/exclusion_rule_skipped_filters：以半形逗號分隔的篩選器清單，這些篩選器的排除規則評估作業已略過 (例如，當輸入內容超過 130,000 個權杖 (0.5 MB) 的排除酬載限制時)。
    使用下列查詢範例，依排除規則標籤篩選清理記錄：
    - 如要找出篩選器結果遭排除規則覆寫的要求，請按照下列步驟操作：
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
labels."modelarmor.googleapis.com/exclusion_rule_overridden_filters":"FILTER_NAME"
```
    - 如要找出提示詞注入和越獄偵測遭排除規則覆寫的要求，請按照下列步驟操作：
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
labels."modelarmor.googleapis.com/exclusion_rule_overridden_filters"="PROMPT_INJECTION_AND_JAILBREAK"
```
    - 如要找出略過排除規則評估的請求，請按照下列步驟操作：
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
labels."modelarmor.googleapis.com/exclusion_rule_skipped_filters"="FILTER_NAME"
```
    將 FILTER_NAME 替換為篩選器名稱 (PROMPT_INJECTION_AND_JAILBREAK 或 RESPONSIBLE_AI)。

找出記錄檔和相關事件的關聯性

如要將特定互動的記錄和事件建立關聯，可以使用 Model Armor 用戶端關聯 ID。這個 ID 是您產生的專屬 ID (例如 UUID)，用於追蹤系統中的特定要求。如要在 curl 標頭中設定用戶端關聯 ID，請使用 -H 選項，在要求中加入 MA-Client-Correlation-Id 自訂標頭。

範例格式如下：

uuid=$(uuidgen) \
curl -X POST -d  '{"userPromptData": { "text": "USER_PROMPT" } }' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "MA-Client-Correlation-Id:${uuid}" \
    "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID:sanitizeUserPrompt"

curl -X POST \
    -d  '{"modelResponseData": { "text": "MODEL_RESPONSE" }, "userPrompt": "USER_PROMPT" }' \
    -H "Content-Type: application/json" \
    -H "MA-Client-Correlation-Id:${uuid}" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID:sanitizeModelResponse"

更改下列內容：

PROJECT_ID：範本所屬的專案 ID。
LOCATION：範本的位置。
TEMPLATE_ID：範本 ID。
USER_PROMPT：提供給模型的提示。
MODEL_RESPONSE：從模型收到的回覆。

平台記錄與 Cloud 稽核記錄

請務必區分可在 Model Armor 範本或底限設定中啟用的記錄，以及 Cloud 稽核記錄。

功能	Cloud 稽核記錄	平台記錄檔
主要目的	API 呼叫的安全性稽核 (誰在何時執行了什麼動作) 和法規遵循監控。	作業監控、偵錯，以及清理事件的詳細分析。
擷取的 API 作業	可對範本和底限設定執行建立、讀取、更新、刪除和列出作業。清除作業 (`SanitizeUserPrompt`、`SanitizeModelResponse`) 會以中繼資料的形式記錄。	擷取所有要求，例如 `SanitizeUserPrompt` 和 `SanitizeModelResponse`。
酬載內容	不含用於清理作業的實際使用者提示或模型回覆文字。包含呼叫端、方法、資源、時間戳記和狀態等中繼資料。	包含完整酬載，例如提示或回覆文字、篩選結果，以及其他清理作業詳細資料。
啟用機制	標準 Google Cloud Model Armor API 的 IAM 稽核記錄設定。資料存取記錄通常需要明確啟用。系統會自動產生範本作業的稽核記錄。	在範本中繼資料或底限設定中，將布林旗標 `log_sanitize_operations` 設為 true 即可啟用。
記錄條件	系統會自動記錄範本和樓層設定的建立、讀取、更新、刪除及列出作業。	記錄任何資料平面要求的記錄資料 (使用者提示和模型回覆)，無論是否啟用 Sensitive Data Protection，或是否符合任何篩選器設定。
記錄量和費用	通常較小且較容易預測，因此會產生標準的 Cloud Logging 費用。	可能非常龐大且數量眾多，導致有效負載過大和使用頻率過高，進而產生高額 Cloud Logging 費用。大型酬載可能會分割成多個記錄項目。
安全性考量	相對安全，因為系統不會記錄酬載資料。需要特殊 IAM 權限才能存取 (例如，查看稽核記錄的特定 IAM 角色)。	含有潛在的私密使用者資料 (PII、機密資訊)。任何具備記錄檢視權限的使用者 (例如 `roles/logging.privateLogViewer`) 都能存取。
建議	啟用這項功能，即可監控一般安全性與法規遵循情況。	不建議用於正式環境或機密資料，除非安全地轉送至受存取控管的接收器 (例如具有嚴格 IAM 的 BigQuery)。

在範本中啟用記錄功能，即可將原始提示詞和回覆寫入記錄檔。這類資料可能包括敏感的使用者資料、個人識別資訊 (PII) 或機密資訊。高流量和大酬載可能會導致記錄費用大幅增加，且記錄量可能超出限制，因此需要謹慎管理。

稽核記錄中的呼叫端身分

查看稽核記錄時，Cloud 稽核記錄會在 protoPayload.authenticationInfo.principalEmail 欄位中擷取呼叫端的 ID。記錄的 ID 取決於 Model Armor API 的呼叫方式：

直接叫用 API：如果使用者或服務帳戶直接呼叫 Model Armor API (例如使用 gcloud、用戶端程式庫或 REST API)，則 principalEmail 會包含該使用者或服務帳戶的電子郵件地址。
透過整合式 Google Cloud 服務叫用：如果 Model Armor 與其他Google Cloud 服務 (例如 Gemini Enterprise Agent Platform) 整合，則 principalEmail 會包含該服務的身分，通常是 Google 管理的服務帳戶。服務代理的格式為 service-PROJECT_NUMBER@SERVICE_NAME.iam.gserviceaccount.com。舉例來說，如果呼叫源自 Gemini Enterprise Agent Platform 功能，就會使用 Gemini Enterprise Agent Platform 服務代理。

如要區分呼叫者，請檢查稽核記錄項目中的 principalEmail 欄位。如果是來自使用者或使用者管理的服務帳戶，系統會顯示電子郵件地址；如果是透過其他 Google Cloud 服務發出的呼叫，系統會顯示 Google 管理的服務帳戶電子郵件地址。

後續步驟

將 Model Armor 記錄與 Gemini Enterprise 記錄相互關聯

設定記錄功能 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

取得必要權限

啟用 API

控制台

gcloud

使用 gcloud CLI 設定 API 端點覆寫

設定流量清理

在範本中設定記錄功能

控制台

REST

Python

在底限設定中設定記錄功能

控制台

gcloud

REST

Python

查看及篩選 Model Armor 記錄

找出記錄檔和相關事件的關聯性

平台記錄與 Cloud 稽核記錄

稽核記錄中的呼叫端身分

後續步驟

設定記錄功能