在网关上配置 Model Armor

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

Model Armor 模板

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

Model Armor 将筛查功能直接嵌入到由 Agent Gateway 管理的通信路径中。通过将内容传递给 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 模板。您可以对入站流量和出站流量使用相同的模板。

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

   如果您在与包含 AI 智能体或 Agent Gateway 的项目不同的项目中创建 Model Armor 模板，并且您使用 VPC Service Controls，则这两个项目必须位于同一 VPC Service Controls 服务边界内。

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.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.iam.gserviceaccount.com \
         --role=roles/modelarmor.user
     

     替换以下内容：

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

   • 代理到任何位置（出站流量）：向 Service Extensions 服务代理授予以下角色：

     • 在包含网关的项目中拥有 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.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.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.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 模板。

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

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

• 在 Model Armor 模板中设置高级 Sensitive Data Protection 设置，并添加去标识化模板。

• 将 Model Armor 模板上的强制执行类型设置为 INSPECT_AND_BLOCK。

如果您使用 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 协议的以下载荷：

• 发送消息操作
• 智能体卡片
• 获取扩展智能体卡片操作
• JSON-RPC 协议绑定
• HTTP+JSON/REST 协议绑定

Model Armor 允许以下 A2A 载荷，无需进行排查：

• 来自 A2A v1 之前版本的载荷
• SendStreamingMessage
• GetTask
• ListTasks
• CancelTask
• SubscribeToTask
• TaskPushNotificationConfig 上的 CRUD 方法
• 使用 A2A gRPC 协议绑定（通过网络传输的 protobuf）的载荷
• 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）运行的任何其他模型。 此处未列出的载荷无需经过排查即可使用。

• 聊天补全：创建、删除、获取、列出和更新（仅限非流式变体）
• 获取聊天消息
• 回答：创建、获取和删除（仅限非流式变体）
• OpenAI API 错误（包括 vLLM 的变体）
• 旧版补全
• 旧版助理：创建、删除、列出、修改和检索
• 旧版消息：创建、删除、列出、修改和检索
• 旧版会话：创建、删除、修改和检索
• 嵌入：创建

文档筛查

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

配额和系统限制

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

一元清理请求和缓冲流式传输请求受每个过滤器的词元系统限制（提示词注入和越狱检测、Responsible AI 和儿童性虐待内容 [CSAM] 过滤器的限制为 65,536 个词元，Sensitive Data Protection 的限制为 130,000 个词元）以及 4 MB 的输入大小限制。如果提示或回答（例如大型检索增强生成 [RAG] 载荷或多步智能体对话历史记录）超出了过滤器的 token 限制，但未检测到违规行为，则该过滤器会跳过评估，并在 SanitizeOperation 日志条目中返回 EXECUTION_SKIPPED 和 Detection skipped as token limit exceeded.。请求会继续执行，而不会触发该过滤器的屏蔽。如需在不超出词元限制的情况下筛查大型载荷，请使用实时流式清理。

例如，对于使用智能体开发套件构建的智能体，请使用 streamQuery，该套件支持无限数量的 token。或者，对大型 RAG 载荷和代理历史记录进行分块，使每个一元请求都保持在 token 限制范围内。

如需详细了解将 Model Armor 与其他服务集成时适用的配额，请参阅管理配额。如需了解 Model Armor 配额和系统限制（包括输入大小和 token 限制）的一般信息，请参阅 Model Armor 文档中的配额和系统限制。

后续步骤

• 设置 Agent Gateway

• 监控内容安全