配置日志记录

本文档介绍了如何配置 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。

控制台

  1. 启用 Model Armor API(如果尚未启用)。

    启用 API 所需的角色

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

    启用 API

  2. 选择要启用 Model Armor 的项目。

gcloud

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

  1. 安装 Google Cloud CLI,然后使用联合身份登录 gcloud CLI。 登录后,运行以下命令来初始化 Google Cloud CLI:

    gcloud init

  2. 启用 Model Armor API(如果尚未启用):

    启用 API 所需的角色

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

    gcloud services enable modelarmor.googleapis.com

  3. 使用 gcloud CLI 设置 API 端点替换。

使用 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:一个布尔值,用于在清理操作期间记录用户提示和模型回答的完整内容。

控制台

  1. 在 Google Cloud 控制台中,前往 Model Armor 页面。

    前往 Model Armor

  2. 确认您正在查看的是已启用 Model Armor 的项目。

  3. 在 Model Armor 页面上,点击创建模板。 如需详细了解如何创建模板,请参阅创建 Model Armor 模板。

  4. 在配置日志记录部分,选择要配置日志记录的操作。

  5. 点击创建。

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 中的 Gemini 模型以及项目中的 Google 和 Google Cloud MCP 服务器的流量强制执行下限设置时,下限设置会定义用于清理操作的安全和保障过滤器。更新 Model Armor 下限设置时,您可以指定 Model Armor 是否记录清理操作。

您可以分别为 Agent Platform 以及 Google 和 Google Cloud MCP 服务器启用清理操作日志记录。启用后,日志会包含提示和回答(对于 Agent Platform)或工具调用和工具回答(对于 MCP 服务器)、Model Armor 的评估结果以及其他元数据字段。

以下示例展示了如何为智能体平台、Google 和 Google Cloud MCP 服务器启用清理操作日志记录。

控制台

  1. 在 Google Cloud 控制台中,前往 Model Armor 页面。

    前往 Model Armor

  2. 确认您正在查看的是已启用 Model Armor 的项目。

  3. 前往下限设置标签页。

  4. 在日志部分,选中 Vertex AI 和 Google 托管的 MCP 复选框,为每项服务启用日志记录。

  5. 点击保存。

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:

  1. 在 Google Cloud 控制台中,前往 Logs Explorer 页面。

    转到 Logs Explorer

    如需了解详情,请参阅使用 Logs Explorer 查看日志。

  2. 在查询窗格中,输入以下其中一个查询来过滤 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 版本(商务版 [标准版、Plus 版和一线员工版] 除外)集成。
          • SECURE_WEB_PROXY:用于与 Secure Web Proxy 集成。
        • CORRELATION_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 是您生成的唯一标识符(例如 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 设置为 true 来启用。
日志记录条件 自动记录对模板和底价设置执行的创建、读取、更新、删除和列出操作。 记录任何数据平面请求的日志数据(用户提示和模型回答),无论是否启用了 Sensitive Data Protection 或是否匹配了任何过滤条件设置。
日志量和费用 通常较小且更可预测,会产生标准 Cloud Logging 价格。 可能非常庞大且数量众多,由于载荷较大且使用频繁,可能会导致 Cloud Logging 费用高昂。大型载荷可能会拆分为多个日志条目。
安全注意事项 相对安全,因为系统不会记录载荷数据。需要特殊的 IAM 权限才能访问(例如,需要特定的 IAM 角色才能查看审计日志)。 包含可能敏感的用户数据(个人身份信息、机密信息)。任何拥有日志查看权限(例如 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 与其他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 代管式服务账号邮箱。

后续步骤