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

配置日志记录

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

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

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

如需了解日志价格，请参阅 Cloud Logging 价格。您可能还需要根据处理的数据量支付 Model Armor 使用费；详情请参阅 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 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 获得了此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。
启用 API
选择要启用 Model Armor 的项目。

gcloud

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

安装 Google Cloud CLI，然后使用联合身份登录 gcloud CLI。登录后，运行以下命令来初始化 Google Cloud CLI：
```
gcloud init
```
使用 gcloud CLI 设置 API 端点替换项。

使用 gcloud CLI 设置 API 端点替换项

只有在您将 gcloud CLI 与 Model Armor 搭配使用，并且想要使用默认 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 模板。
在配置日志记录部分，选择要配置日志记录的操作。
点击创建。

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 标志。

以下示例命令可为 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 方法中将 aiPlatformFloorSetting.enableCloudLogging 设置为 true（对于 Agent Platform）和将 googleMcpServerFloorSetting.enableCloudLogging 设置为 true（对于 Google 和 Google Cloud MCP 服务器）。

以下示例命令可为 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：对于使用负载平衡器作为服务扩展程序的集成。
    - 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 角色才能查看审核日志）。	包含可能敏感的用户数据（个人身份信息、机密信息）。可供具有日志查看权限（例如 `roles/logging.privateLogViewer`）的任何人访问。
建议	启用以进行常规安全性和合规性监控。	不建议用于生产数据或敏感数据，除非安全地路由到受访问权限控制的接收器（例如，具有严格 IAM 的 BigQuery）。

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

审核日志中的调用方身份

当您查看审核日志时，Cloud Audit Logs 会在 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 代管式服务账号的电子邮件地址。

后续步骤

将 Model Armor 日志与 Gemini Enterprise 日志相关联

配置日志记录 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

获取所需的权限

启用 API

控制台

gcloud

使用 gcloud CLI 设置 API 端点替换项

设置流量清理

在模板中配置日志记录

控制台

REST

Python

在下限设置中配置日志记录

控制台

gcloud

REST

Python

查看和过滤 Model Armor 日志

关联日志和相关事件

平台日志与 Cloud Audit Logs

审核日志中的调用方身份

后续步骤

配置日志记录