为 Model Armor 配置日志记录

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

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

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

准备工作

请先完成以下任务，然后再完成本页面上的其余任务。

获取所需的权限

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

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

启用 API

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

控制台

  1. Enable the Model Armor API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

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

gcloud

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

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. 运行以下命令，为 Model Armor 服务设置 API 端点。

    gcloud config set api_endpoint_overrides/modelarmor "https://modelarmor.LOCATION.rep.googleapis.com/"

    将 LOCATION 替换为您要使用 Model Armor 的区域。

    3. 运行以下命令以启用 Model Armor。

      gcloud services enable modelarmor.googleapis.com --project=PROJECT_ID

    将 PROJECT_ID 替换为相应项目的 ID。

    在模板中配置日志记录

    模板可定义不同安全与防护类别的过滤条件和阈值。创建或更新 Model Armor 模板时，您可以指定 Model Armor 是否记录某些操作。在模板元数据中使用以下标志：

    • log_template_operations：一个布尔值，用于启用创建、更新、读取和删除模板操作的日志记录。

    • log_sanitize_operations：一个布尔值，用于启用清理操作的日志记录。日志包含提示和回答、Model Armor 的评估结果以及其他元数据字段。

    控制台

    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。

    查看日志

    使用 Cloud Logging 中的日志浏览器访问 Model Armor 日志。 如需了解详情，请参阅使用日志浏览器查看日志。 按服务名称 modelarmor.googleapis.com 过滤。查找与您在模板中启用的操作相关的条目。如需查看所有服务名称和受监控的资源类型的列表，请参阅受监控的资源和服务。

    过滤 Model Armor 日志

    使用日志标签过滤 Model Armor 日志，以获取清理操作和模板日志记录。

    在日志浏览器中运行以下查询，以过滤清理操作日志。

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

    如需进一步细化清理操作日志，您可以在查询中指定项目 ID、客户端名称或关联 ID。

    • 使用项目 ID：

      jsonPayload.@type="type.googleapis.com%2Fgoogle.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry";project=PROJECT_ID

    • 使用客户端名称：

      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"

    替换以下内容：

    • PROJECT_ID： Google Cloud 项目 ID。
    • CLIENT_NAME：您的客户的名称。
    • CORRELATION_ID：您为特定请求生成的唯一标识符。

    关联日志和相关事件

    若要关联与该特定互动相关的日志和事件，您需要一个客户端关联 ID。这是您生成的唯一标识符（例如 UUID），用于在整个系统中跟踪特定请求。如需在 curl 标头中设置客户端关联 ID，请使用 -H 选项在请求中添加自定义标头。以下是示例格式：

    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：从模型收到的回答。