Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

配置日志记录

本文档介绍了如何配置 Model Armor 以记录以下操作：

创建、更新或删除模板的操作
用于清理用户提示或模型回答的操作

Model Armor 使用审核日志来记录管理和资源管理活动。如需了解详情，请参阅 Model Armor 审核日志记录。

如需了解日志价格，请参阅 Cloud Logging 价格。 Model Armor 的使用费也可能根据处理的数据量收取；如需了解详情，请参阅 Model Armor 价格。

准备工作

在开始之前，请完成以下任务。

获取所需的权限

如需获得为 Model Armor 配置日志记录所需的权限，请让您的管理员为您授予Model Armor Admin (roles/modelarmor.admin) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

启用 API

您必须先启用 Model Armor API，然后才能使用 Model Armor。

控制台

启用 Model Armor API。
启用 API 所需的角色
如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已通过所有者角色 (roles/owner) 拥有此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。
启用 API
选择要启用 Model Armor 的项目。

gcloud

在开始之前，请使用 Google Cloud CLI 和 Model Armor API 按照以下步骤操作：

在 Google Cloud 控制台中，激活 Cloud Shell。

激活 Cloud Shell

Cloud Shell 会话随即会在控制台的底部启动，并显示命令行提示符。 Google Cloud Cloud Shell 是一个已安装 Google Cloud CLI 且已为当前项目设置值的 Shell 环境。该会话可能需要几秒钟来完成初始化。
使用 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 和 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 模板。
在配置日志记录 部分，选择要配置日志记录的操作。
点击创建。

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 管理的 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

如需了解详情，请参阅使用 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：用于使用 Load Balancer 作为 Service Extension 进行集成。
    - 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：您为特定请求生成的唯一标识符。

关联日志和相关事件

如需关联特定互动的日志和事件，您可以使用 Model Armor 客户端关联 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 Audit Logs

务必区分您可以在 Model Armor 模板或下限设置中启用的日志与 Cloud Audit Logs。

功能	Cloud Audit Logs	平台日志
主要目的	API 调用的安全审核（谁在何时执行了哪些操作）和合规性监控。	运营监控、调试和清理事件的详细分析。
捕获的 API 操作	对模板和下限设置执行创建、读取、更新、删除和列出操作。清理操作（`SanitizeUserPrompt`、`SanitizeModelResponse`）将记录为元数据。	捕获所有请求，例如 `SanitizeUserPrompt` 和 `SanitizeModelResponse`。
载荷内容	不包含清理操作的实际用户提示或模型回答文本。包含调用方、方法、资源、时间戳和状态等元数据。	包含完整载荷，例如提示或回答文本、过滤结果以及清理的其他详细信息。
启用机制	Model Armor API 的标准 Google Cloud IAM 审核日志设置。数据访问日志通常需要明确启用。系统会自动生成模板操作的审核日志。	通过在模板元数据或下限设置中设置布尔值标志 `log_sanitize_operations` 来启用。
日志记录条件	自动记录对模板和下限设置执行的创建、读取、更新、删除和列出操作。	记录任何数据平面请求的数据（用户提示和模型回答），无论是否启用了 Sensitive Data Protection 或是否匹配了任何过滤条件设置。
日志量和费用	通常较小且更可预测，产生标准 Cloud Logging 费用。	可能非常大且数量庞大，可能会因载荷较大和频繁使用而导致 Cloud Logging 费用显著增加。大型载荷可能会拆分为多个日志条目。
安全注意事项	相对安全，因为系统不会记录载荷数据。需要特殊的 IAM 权限才能访问（例如，查看审核日志需要特定的 IAM 角色）。	包含可能敏感的用户数据（PII、机密信息）。任何拥有日志查看权限（例如 `roles/logging.privateLogViewer`）的人员都可以访问。
建议	启用以进行常规安全和合规性监控。	不建议用于生产或敏感数据，除非安全地路由到访问受控的接收器（例如，具有严格 IAM 的 BigQuery）。

在模板中启用日志记录会将原始提示和回答写入 Logging。此数据可能包含敏感用户数据、个人身份信息 (PII) 或机密信息。高流量和大型载荷可能会导致大量日志记录费用，并且可能会导致日志量超出限制，需要仔细管理。

审核日志中的调用方身份

查看审核日志时，Cloud Audit Logs 会在 protoPayload.authenticationInfo.principalEmail 字段中捕获调用方的身份。记录的身份取决于 Model Armor API 的调用方式：

直接 API 调用：如果用户或服务帐号直接调用 Model Armor API（例如，使用 gcloud、客户端库或 REST API），则 principalEmail 包含该用户或服务帐号的电子邮件地址。
通过集成 Google Cloud 服务调用：如果 Model Armor 与 Gemini Enterprise Agent Platform 等其他 Google Cloud 服务集成，则 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 Audit Logs

审核日志中的调用方身份

配置日志记录