Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

設定記錄功能

本文說明如何設定 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，您需要服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。
啟用 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 的殼層環境，並已針對您目前的專案設定好相關值。工作階段可能要幾秒鐘的時間才能初始化。
使用 gcloud CLI 設定 API 端點覆寫。

使用 gcloud CLI 設定 API 端點覆寫

如果您使用 gcloud CLI 啟用 Model Armor API，才需要執行這個步驟。您必須手動設定 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 和 MCP 伺服器的保護措施」。Google Cloud

在範本中設定記錄功能

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

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

控制台

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

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

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 的評估結果，以及其他中繼資料欄位。

下列範例說明如何為代理程式平台、Google 和 Google Cloud MCP 伺服器啟用清除作業記錄。

控制台

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

前往 Model Armor
確認您正在查看已啟用 Model Armor 的專案。
前往「樓層設定」分頁。
在「記錄」部分，選取「Vertex AI」和「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 旗標。

下列範例指令會為代理程式平台、Google 和 Google Cloud MCP 伺服器啟用清除作業記錄：

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 和 MCP 伺服器的 googleMcpServerFloorSetting.enableCloudLogging 設為 true。 Google Cloud

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

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 記錄，請使用 Cloud 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 如要與 Business 以外的 Gemini Enterprise 版本 (Standard、Plus、Frontline) 整合。
    - SECURE_WEB_PROXY 與 Secure Web Proxy 整合。
  - CORRELATION_ID：您為特定要求產生的專屬 ID。

關聯記錄和相關事件

如要將特定互動的記錄和事件相互關聯，可以使用 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`。
酬載內容	不包含實際使用者提示或模型回覆文字，適用於清除作業。包含呼叫者、方法、資源、時間戳記和狀態等中繼資料。	包括完整酬載，例如提示或回覆文字、篩選結果，以及其他清除詳細資料。
啟用機制	Model Armor API 的標準 Google Cloud 身分與存取權管理稽核記錄設定。資料存取記錄通常需要明確啟用。系統會自動產生範本作業的稽核記錄。	在範本中繼資料或底限設定中，將布林值標記 `log_sanitize_operations` 設為 true 即可啟用。
記錄條件	系統會自動記錄範本和底限設定的建立、讀取、更新、刪除及列出作業。	記錄任何資料平面要求的記錄資料 (使用者提示和模型回覆)，無論是否啟用 Sensitive Data Protection，或是否符合任何篩選器設定。
記錄檔資料量和費用	通常較小且更容易預測，因此會產生標準 Cloud Logging 費用。	可能非常龐大且數量眾多，導致酬載過大和使用頻率過高，進而產生大量 Cloud Logging 費用。大型酬載可能會拆分為多個記錄項目。
安全性考量	由於系統不會記錄酬載資料，因此相對安全。需要特殊的 IAM 權限才能存取 (例如，查看稽核記錄的特定 IAM 角色)。	含有可能涉及私密的使用者資料 (個人識別資訊、機密資訊)。任何具備記錄檢視權限的使用者都能存取 (例如 `roles/logging.privateLogViewer`)。
建議	啟用這項功能，即可監控一般安全性與法規遵循情形。	除非安全地將資料傳送至存取權受控的接收器 (例如具有嚴格 IAM 的 BigQuery)，否則不建議用於生產環境或處理敏感資料。

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

稽核記錄中的呼叫者身分

查看稽核記錄時，Cloud 稽核記錄會在 protoPayload.authenticationInfo.principalEmail 欄位中擷取呼叫端的 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 管理的服務帳戶電子郵件地址。

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

事前準備

取得必要權限

啟用 API

控制台

gcloud

使用 gcloud CLI 設定 API 端點覆寫

設定流量清除

在範本中設定記錄功能

控制台

REST

Python

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

控制台

gcloud

REST

Python

查看及篩選 Model Armor 記錄

關聯記錄和相關事件

平台記錄與 Cloud 稽核記錄

稽核記錄中的呼叫者身分

設定記錄功能