在网关上配置 Model Armor

借助 Model Armor，您可以确保 AI 代理遵循您的安全和治理标准，而无需直接在代理中实现过滤逻辑。如果您将 Model Armor 与 Agent Gateway 搭配使用，Model Armor 会检查通过网关的所有提示和回答，从而应用组织的内容安全防护措施。借助此功能，您可以针对网关管理的所有代理强制执行一致的内容安全防护措施。 Model Armor 可帮助您缓解提示注入、越狱尝试、敏感信息泄露和有害内容生成等风险。如需了解详情，请参阅 Model Armor 过滤器。

Model Armor 模板

如需在网关上配置 Model Armor，请创建模板来指定如何过滤 AI 代理收到的提示和返回的回答。模板可为多个安全类别提供自定义的过滤条件及阈值。如需了解详情，请参阅 Model Armor 模板。

Model Armor 可将筛查功能直接嵌入到受代理网关管控的通信路径中。通过 Model Armor 传递内容时，网关会强制执行内容安全模板。在模板中，您可以配置 Model Armor，以对违反模板的内容进行遮盖或屏蔽。

入站流量和出站流量

借助 Agent Gateway，Model Armor 可帮助保护以下流量。

客户端到代理（代理入站流量）

您可以定义模板，供 Model Armor 用于评估客户端到代理流量中的请求和响应。您可以将单个模板同时应用于两个方向，也可以为每个方向配置不同的模板。

Model Armor 在筛选以下内容时会遵循模板：

  • 从客户端（最终用户或调用应用）发送到 AI 智能体的传入请求
  • 从 AI 智能体发送给客户端的出站响应

当客户端向代理发送提示时，Agent Gateway 会拦截流量并将载荷发送到 Model Armor 进行清理。如果 Model Armor 发出 ALLOW 判定，Agent Gateway 会将提示发送给 AI 代理。如果 Model Armor 判定为 BLOCK，客户端会收到错误，并且流程会在到达 AI 智能体 之前结束。

AI 智能体处理请求并生成响应后，Agent Gateway 会在传出流到达客户端之前拦截该流。Model Armor 会评估回答并给出判定结果。 根据判决结果，Agent Gateway 会允许或完全阻止回答。

代理到任意目的地（代理出站流量）

您可以定义模板，供 Model Armor 用于评估“代理到任意位置”流量中的请求和响应。您可以将单个模板同时应用于两个方向，也可以为每个方向配置不同的模板。

Model Armor 在过滤 AI 智能体与外部系统之间的通信时会遵循模板，包括：

  • 外部大语言模型 (LLM)
  • 第三方 AI 智能体
  • Model Context Protocol (MCP) 服务器

当 AI 智能体与外部系统通信时，Agent Gateway 会拦截出站流量并调用 Model Armor。Model Armor 会根据您设置的出站模板评估载荷。

如果出站数据违反了安全政策，Model Armor 会发出 BLOCK 判决。然后，Agent Gateway 会终止连接，以防止有害或敏感数据到达 LLM、工具或外部 AI 智能体。

准备工作

启用 Model Armor API（如果尚未启用）。

启用 API 所需的角色

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

启用 API

所需的角色

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

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

如需了解使用 Agent Gateway 所需的角色，请参阅 Agent Gateway 文档中的必需的角色。

如需了解通过网关的受支持和不受支持的载荷，请参阅本文档中的受支持和不受支持的载荷。

在网关上配置 Model Armor

如需在网关上配置 Model Armor，请按以下步骤操作：

  1. 在要创建 Model Armor 模板的项目中启用 Model Armor API。

  2. 在您计划添加网关的同一区域中创建一个或多个 Model Armor 模板。您可以对入站流量和出站流量使用同一模板。

    记下模板名称。如需在Cloud de Confiance 控制台中复制模板的名称，请查看模板的详细信息，然后点击模板名称旁边的 复制到剪贴板。

  3. 在存储 Model Armor 模板的同一区域中设置 Agent Gateway。对于客户端到代理（入站）网关，请指定您为入站流量创建的 Model Armor 模板。对于代理到任意位置（出站）网关，请指定您为出站流量创建的 Model Armor 模板。您可以为这两个流量流使用同一模板。

  4. 向相应的服务代理授予所需的 IAM 角色：

    • 客户端到代理（入站）：向 AI Platform Reasoning Engine Service Agent 服务代理授予以下角色：

      • 包含 AI 智能体的项目中的 Model Armor Callout User (roles/modelarmor.calloutUser) 角色。

      • 包含 Model Armor 模板的项目中的 Model Armor User (roles/modelarmor.user) 角色。

      gcloud projects add-iam-policy-binding AGENT_RUNTIME_PROJECT_ID \
    --member=serviceAccount:service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform-re.s3ns-system.iam.gserviceaccount.com \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
    --member=serviceAccount:service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform-re.s3ns-system.iam.gserviceaccount.com \
    --role=roles/modelarmor.user

      替换以下内容：

      • AGENT_RUNTIME_PROJECT_ID：您在其中创建代理的项目的 ID。
      • AGENT_RUNTIME_PROJECT_NUMBER：您在其中创建代理的项目的项目编号。
      • MODEL_ARMOR_PROJECT_ID：包含 Model Armor 模板的项目的项目 ID。

    • 从代理到任意位置（出站）：向服务扩展服务代理授予以下角色：

      • 在包含网关的项目中拥有 Model Armor Callout User (roles/modelarmor.calloutUser) 和 Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) 角色。
      • 包含 Model Armor 模板的项目中的 Model Armor User (roles/modelarmor.user) 角色。
      gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.s3ns-system.iam.gserviceaccount.com \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.s3ns-system.iam.gserviceaccount.com \
    --role=roles/serviceusage.serviceUsageConsumer
gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
    --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.s3ns-system.iam.gserviceaccount.com \
    --role=roles/modelarmor.user

      替换以下内容：

      • GATEWAY_PROJECT_ID：您在其中创建了网关的项目的项目 ID。
      • GATEWAY_PROJECT_NUMBER：您在其中创建了网关的项目的项目编号。
      • MODEL_ARMOR_PROJECT_ID：包含 Model Armor 模板的项目的项目 ID。

      如需查看相关说明，请参阅将授权委托给 Model Armor。

    如需了解如何授予角色的一般信息，请参阅授予单个 IAM 角色。

可选：部署前模板验证检查

在将模板部署到网关之前，您可以运行部署前检查，以验证模板配置是否正确强制执行安全政策。

您可以使用一组测试提示直接查询 sanitizeUserPrompt 方法来验证模板。如需详细了解如何运行此部署前检查以及经过验证的测试提示列表，请参阅验证模板配置。

隐去请求和响应中的敏感数据

您可以指示 Model Armor 从载荷中隐去敏感数据，例如国民身份证号和手机号码。如需使用此功能，请按以下步骤操作：

如果您使用 INSPECT_AND_BLOCK 强制执行类型，则会发生以下情况之一：

  • 如果载荷仅违反 Sensitive Data Protection 检测器，Model Armor 会根据您的高级 Sensitive Data Protection 设置和去标识化模板对载荷进行编辑。

  • 如果载荷违反了多个检测器，Model Armor 不会执行编辑，而是会屏蔽整个载荷。

如果您使用 INSPECT_ONLY 强制执行类型而不是 INSPECT_AND_BLOCK，Model Armor 不会对载荷进行编辑。

无论您选择哪种强制执行类型（INSPECT_ONLY 或 INSPECT_AND_BLOCK），Model Armor 日志都会根据您的高级 Sensitive Data Protection 设置和去标识化模板进行编辑。

如需查看 Model Armor 检测器（也称为过滤条件）的完整列表，请参阅 Model Armor 过滤条件。

支持的载荷和不支持的载荷

本部分列出了 Model Armor 会清理的载荷类型。

客户端到代理（入站）流量

对于使用 ADK 协议的客户端到智能体（入站）流量，Model Armor 仅清理使用智能体开发套件 (ADK) 构建且在 Vertex AI Agent Engine 上运行的智能体的 reasoningEngines.streamQuery 请求和响应。

所有其他 ReasoningEngine 载荷和 ReasoningEngine 错误响应都不会发送到 Model Armor。非 ADK 载荷（例如 Langchain 载荷）也不会发送到 Model Armor。

代理到任意目的地（出站流量）的流量

对于从代理到任意位置（出站）的流量，支持以下载荷。

A2A 载荷

Model Armor 仅清理 A2A v1 协议的以下载荷：

Model Armor 允许以下 A2A 载荷在不进行清理的情况下通过：

MCP 载荷

Model Armor 仅清理以下 MCP 载荷：

  • tools/call 请求和响应
  • prompts/get 请求和响应
  • MCP 工具执行错误（恶意 MCP 工具作者进行提示注入的目标）

Model Armor 允许以下载荷，而无需进行清理：

  • tools/list
  • resources/*
  • notifications/*
  • 适用于 MCP 的可流式传输的 HTTP/SSE
  • MCP 协议错误（例如，除了工具执行错误之外的所有错误）

外部 LLM 载荷

Model Armor 仅清理 OpenAI API 协议（出站）的以下载荷，包括 openai.com 上的 GPT 模型以及通过 OpenAI API 兼容的 LLM 服务器（例如 vLLM）的任何其他模型。未在此处列出的载荷无需清理即可使用。

文档筛查

此集成不支持清理包含文档或文件上传内容（例如 PDF）的提示和回答。如需筛查文档，请直接调用 Model Armor REST API。如需了解详情，请参阅 Model Armor 文档中的文档筛查。

配额和系统限制

配额在 Model Armor 模板所在的项目中消耗。如果网关位于其他项目中，则网关项目也会消耗 ExternalProcessor 配额。

如需详细了解将 Model Armor 与其他服务搭配使用时适用的配额，请参阅管理配额。

如需了解 Model Armor 配额和系统限制（包括输入大小和 token 限制）的常规信息，请参阅 Model Armor 文档中的配额和系统限制。

后续步骤