設定記錄功能

本文說明如何設定 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 的殼層環境，並已針對您目前的專案設定好相關值。工作階段可能要幾秒鐘的時間才能初始化。
執行下列指令，為 Model Armor 服務設定 API 端點。
```
gcloud config set api_endpoint_overrides/modelarmor "https://modelarmor.LOCATION.rep.googleapis.com/"
```
將 LOCATION 替換為要使用 Model Armor 的區域。

設定流量清除

如果是 Google 代管的 Model Context Protocol (MCP) 伺服器，請透過底限設定，設定流量清除作業。詳情請參閱「設定 Google 和 Google Cloud 遠端 MCP 伺服器的保護措施」。(預覽)

在範本中設定記錄功能

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

log_template_operations：布林值，可啟用範本建立、更新、讀取和刪除作業的記錄。
log_sanitize_operations：布林值，可啟用清除作業的記錄。記錄內容包括提示詞和回覆、Model Armor 的評估結果，以及其他中繼資料欄位。

控制台

前往 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。

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

底限設定會在專案中，為 Vertex AI 的所有 Gemini 模型和 Google 代管的 Model Context Protocol (MCP) 伺服器 (預先發布版) 建立安全和安全防護篩選器基準。更新 Model Armor 底限設定時，您可以指定是否要記錄 Model Armor 清理作業。

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

控制台

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

前往 Model Armor
確認您正在查看已啟用 Model Armor 的專案。
前往「樓層設定」分頁。
在「記錄」部分中，選取「Google 管理的 MCP」。
按一下 [儲存]。

gcloud

您可以使用下列任一旗標，管理底限設定中的清除作業記錄。

如要啟用記錄功能，請使用下列其中一個標記：

如果是 Vertex AI，請使用 --enable-vertex-ai-cloud-logging 旗標。
如果是 Google 代管的 MCP 伺服器，請使用 --enable-google-mcp-server-cloud-logging 旗標。

如要停用記錄功能，請使用下列其中一個標記：

如果是 Vertex AI，請使用 --no-enable-vertex-ai-cloud-logging 旗標。
如果是 Google 代管的 MCP 伺服器，請使用 --no-enable-google-mcp-server-cloud-logging 旗標。

注意： 您可以使用單一指令，為一或兩項服務啟用或停用記錄功能。

下列範例指令會為 Vertex AI 和 Google 代管 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 方法更新底限設定，啟用消毒作業記錄功能。使用這個方法時，請務必將適當的參數設為 true，以啟用記錄功能：

如果是 Vertex AI，請將 aiPlatformFloorSetting.enableCloudLogging 設為 true。
如果是 Google 代管的 MCP 伺服器，請將 googleMcpServerFloorSetting.enableCloudLogging 設為 true。

下列範例指令會為 Vertex AI 和 Google 代管 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 記錄，可以使用 Logging 中的記錄檔探索工具，請按照下列步驟操作：

前往 Google Cloud 控制台的「Logs Explorer」。詳情請參閱「使用 Logs Explorer 查看記錄檔」。
依服務名稱 modelarmor.googleapis.com 篩選記錄。
找出與範本中啟用作業相關的項目。如需所有服務名稱和受監控資源類型的清單，請參閱「受監控資源和服務」。

篩選 Model Armor 記錄

您可以使用記錄標籤，篩選 Model Armor 記錄中的清除作業和範本記錄。如要這麼做，請按照下列指示操作：

在 Logs Explorer 中執行下列查詢，篩選清除作業記錄。

jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"

如要進一步篩選清除作業記錄，可以在查詢中指定用戶端名稱或關聯 ID。

使用用戶端名稱：將 Model Armor 與 Vertex AI 或 Gemini Enterprise 等服務整合時，您可以使用用戶端名稱，篩選特定整合服務的記錄。
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
labels."modelarmor.googleapis.com/client_name"="CLIENT_NAME"
```

使用關聯性 ID：

labels."modelarmor.googleapis.com/client_correlation_id"="CORRELATION_ID"

更改下列內容：

CLIENT_NAME：用戶端名稱，例如 VERTEX_AI。
CORRELATION_ID：您為特定要求產生的專屬 ID。

關聯記錄和相關事件

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

範例格式如下：

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：模型傳回的回覆。

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

事前準備

取得必要權限

啟用 API

控制台

gcloud

設定流量清除

在範本中設定記錄功能

控制台

REST

Python

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

控制台

gcloud

REST

Python

查看記錄

篩選 Model Armor 記錄

關聯記錄和相關事件

設定記錄功能