本文說明如何設定 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。
控制台
gcloud
開始之前,請按照下列步驟,搭配使用 Google Cloud CLI 和 Model Armor API:
安裝 Google Cloud CLI,然後使用聯合身分登入 gcloud CLI。登入後, 執行下列指令來初始化 Google Cloud CLI:
gcloud init啟用 Model Armor API (如果尚未啟用):
啟用 API 所需的角色
如要啟用 API,您必須具備
serviceusage.services.enable權限。如果您建立了專案,可能已透過擁有者角色 (roles/owner) 取得這項權限。否則,您可以透過 Service Usage 管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。gcloud services enable modelarmor.googleapis.com
使用 gcloud CLI 設定 API 端點覆寫
只有在使用 gcloud CLI 時,才需要執行這個步驟。設定 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 範本」。
在「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 的專案。
前往「底價設定」分頁。
在「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 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 和 Google Cloud MCP 伺服器的 googleMcpServerFloorSetting.enableCloudLogging 設為 true。
下列範例指令會為 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 記錄,請使用 Logging 的 Logs Explorer:
前往 Google Cloud 控制台的「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 設為啟用。 |
| 記錄條件 | 自動記錄範本和底價設定的建立、讀取、更新、刪除和列出作業。 | 記錄任何資料層要求的記錄資料 (使用者提示和模型回覆),無論是否啟用 Sensitive Data Protection,或是否符合任何篩選器設定。 |
| 記錄量和費用 | 通常較小且較容易預測,會產生標準 Cloud Logging 定價。 | 可能非常龐大且數量眾多,由於酬載大且使用頻繁,可能會產生高昂的 Cloud Logging 費用。大型酬載可能會分割成多個記錄項目。 |
| 安全性考量 | 由於系統不會記錄酬載資料,因此相對安全。需要特殊 IAM 權限才能存取 (例如查看稽核記錄的特定 IAM 角色)。 | 含有潛在的私密使用者資料 (PII、機密資訊)。任何具備記錄檢視權限的使用者 (例如 roles/logging.privateLogViewer) 都能存取。 |
| 建議 | 啟用這項功能,即可監控一般安全性和法規遵循情形。 | 不建議用於正式環境或機密資料,除非安全地轉送至受存取控管的接收器 (例如具有嚴格 IAM 的 BigQuery)。 |
在範本中啟用記錄功能,會將原始提示和回覆寫入 Logging。這類資料可能包括敏感使用者資料、個人識別資訊 (PII) 或機密資訊。高流量和大型酬載可能會產生大量記錄費用,且記錄量可能超過限制,需要謹慎管理。
稽核記錄中的呼叫端身分
查看稽核記錄時,Cloud 稽核記錄會在 protoPayload.authenticationInfo.principalEmail 欄位中擷取呼叫端的身分。記錄的身分取決於 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.。舉例來說,如果呼叫源自 Gemini Enterprise Agent Platform 功能,就會使用 Gemini Enterprise Agent Platform 服務代理。
如要區分呼叫端,請檢查稽核記錄項目中的 principalEmail 欄位。使用者或使用者自行管理的服務帳戶發出的呼叫,會顯示其電子郵件地址,而透過其他 Google Cloud 服務發出的呼叫,則會顯示 Google 代管服務帳戶的電子郵件地址。