Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

将 Model Armor 与 Gemini Enterprise Agent Platform 集成

本文档介绍了如何配置 Model Armor，以通过筛查提示和回答来保护 Gemini Enterprise Agent Platform 上的 Gemini 模型。与 Gemini Enterprise Agent Platform 集成后，Model Armor 会在提示到达 Gemini 模型之前拦截提示，并在应用收到回答之前拦截回答。根据您的配置，Gemini Enterprise Agent Platform 会调用 Model Armor 服务，该服务会检查或屏蔽违反您定义的政策的数据流量，从而强制执行提示注入和越狱检测、Responsible AI 过滤条件和 Sensitive Data Protection 等安全措施。您可以通过使用项目级保护的下限设置或使用每个请求的保护模板来配置此集成。

Model Armor 可为 generateContent 方法提供 Vertex AI 中的 Gemini API 中的提示和回答保护。您需要启用 Cloud Logging，才能查看提示和回答的清理结果。

除了保护对 Gemini Enterprise Agent Platform 服务的直接 REST 调用之外，您还可以使用 Model Armor 来保护其他接口，这些接口提供对 Vertex AI 中的 Gemini API 的访问权限，例如 Google 生成式 AI SDK 或 Firebase AI Logic SDK。

限制

将 Model Armor 与 Gemini Enterprise Agent Platform 集成时，请考虑以下限制：

当 Model Armor 使用 Sensitive Data Protection 模板扫描提示或回答时，Model Armor 会检查内容是否与模板中定义的过滤条件匹配。如果找到匹配项，Model Armor 会标记该内容触发了 Sensitive Data Protection 过滤条件。虽然 Sensitive Data Protection 会根据模板配置对数据进行去标识化，但 Model Armor 不会将去标识化数据（例如经过遮盖、隐去或哈希处理的内容）传递回 Gemini Enterprise Agent Platform 以进行进一步处理。相反，如果强制执行类型为 INSPECT_AND_BLOCK，Model Armor 会发出屏蔽判决，以确保敏感数据不会继续进行进一步处理。
不支持清理包含文档的提示和回答。
如果 Gemini Enterprise Agent Platform 将请求路由到指定 Model Armor 模板不存在的区域，则请求会失败，并显示 Template not found 错误。
在以下情况下，Gemini Enterprise Agent Platform 会跳过 Model Armor 清理步骤，并继续处理请求：
- 在 Gemini Enterprise Agent Platform 所在的区域中，Model Armor 不可用。
- Model Armor 暂时无法访问。
- Model Armor 中发生错误。
所有这些实例有时可能会呈现未经筛查的提示或回答，因为请求会继续进行，而不会进行提示和回答清理。

虽然该集成旨在在连接失败期间实现高可用性，但 INSPECT_AND_BLOCK 模式仍会报告配置错误，例如权限或配额问题。

准备工作

向 Gemini Enterprise Agent Platform 服务帐号授予 Model Armor User 角色。
```
gcloud projects add-iam-policy-binding PROJECT_ID --member='serviceAccount:service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com' --role='roles/modelarmor.user'
```
替换以下内容：
- PROJECT_ID：您的 Google Cloud 项目 ID。
- PROJECT_NUMBER：您的 Google Cloud 项目编号。
启用 Model Armor API。
使用 gcloud CLI 设置 API 端点替换。

配置 Model Armor 如何帮助保护 Gemini Enterprise Agent Platform

您可以通过以下两种方式之一配置 Model Armor 如何保护 Gemini Enterprise Agent Platform：

使用模板进行每个请求的保护：此方法可让您将特定模板应用于 Gemini Enterprise Agent Platform 上 Gemini 模型的每个 generateContent API 调用，从而提供精细的控制。
使用下限设置进行项目级保护：此方法通过将下限设置应用于项目中 Gemini Enterprise Agent Platform 上 Gemini 模型的每个 generateContent API 调用，来强制执行基准保护。

定义强制执行类型以确定是仅检查违规行为还是同时屏蔽违规行为。

使用模板进行每个请求的配置

借助模板，您可以配置 Model Armor 过滤提示和回答的方式，并定义安全过滤器的配置。您必须先创建模板，然后将这些模板与 Gemini 的 generateContent 方法搭配使用。如需详细了解模板，请参阅创建和管理 Model Armor 模板。

配置 Model Armor 模板后，在使用 generateContent 方法调用 Gemini API 时，请将模板 ID 作为参数传递。Gemini Enterprise Agent Platform 会将请求路由到 Model Armor 进行处理。

如需将特定模板应用于单个 generateContent 调用，请在请求中添加 modelArmorConfig 对象。

promptTemplateName：用于清理提示的 Model Armor 模板的资源名称。
responseTemplateName：用于清理回答的 Model Armor 模板的资源名称。

以下代码示例展示了对 generateContent 方法的请求。

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-2.0-flash-001:generateContent" -d '{
"contents": [
    {
        "role": "user",
        "parts": [
            {
                "text": "[YOUR PROMPT HERE]"
            }
        ]
    }
]
, "generationConfig": {
    "responseModalities": ["TEXT"]
    ,"temperature": 0.2
    ,"maxOutputTokens": 1024
    ,"topP": 0.8
},
 "model_armor_config": {
        "prompt_template_name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
        "response_template_name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID"
        }
}'

替换以下内容：

PROJECT_ID： Google Cloud 项目 ID。
LOCATION：Gemini 端点的 Google Cloud 位置。支持的位置包括 europe-west1、europe-west2、europe-west3、asia-southeast1 和 asia-south1。
TEMPLATE_ID：Model Armor 模板 ID。

以下代码示例展示了来自 generateContent 方法的回答。

{
  "promptFeedback": {
    "blockReason": "MODEL_ARMOR",
    "blockReasonMessage": "Blocked by Floor Setting. The prompt violated Responsible AI Safety settings (Harassment, Dangerous), Prompt Injection and Jailbreak filters."
  },
  "usageMetadata": {
    "trafficType": "ON_DEMAND"
  },
  "modelVersion": "gemini-2.0-flash-001",
  "createTime": "2025-03-26T13:14:36.961184Z",
  "responseId": "vP3jZ6DVOqLKnvgPqZL-8Ao"
}

定义模板的强制执行类型

如需配置 Model Armor 处理检测结果的方式，请设置强制执行类型。

以下示例展示了一个采用 Inspect only 执行类型的 Model Armor 模板配置。

export TEMPLATE_CONFIG='{
   "filter_config": {
    "rai_settings": {
     "rai_filters": [{
       "filter_type": "HATE_SPEECH",
       "confidence_level": "MEDIUM_AND_ABOVE"
      }, {
      "filter_type": "HARASSMENT",
      "confidence_level": "MEDIUM_AND_ABOVE"
    }, {
      "filter_type": "DANGEROUS",
      "confidence_level": "MEDIUM_AND_ABOVE"
    },{
      "filter_type": "SEXUALLY_EXPLICIT",
      "confidence_level": "MEDIUM_AND_ABOVE"
    }]
  },
  "pi_and_jailbreak_filter_settings": {
    "filter_enforcement": "ENABLED",
    "confidence_level": "LOW_AND_ABOVE"
  },
  "malicious_uri_filter_settings": {
    "filter_enforcement": "ENABLED"
  }
 },
 "template_metadata": {
    "enforcement_type": "INSPECT_ONLY",
    "multi_language_detection": {
      "enable_multi_language_detection": true
    }
  }
}'

curl -X POST \
    -d "$TEMPLATE_CONFIG"  \
    -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。
TEMPLATE_ID：要创建的模板的 ID。
LOCATION：模板所在的位置。

使用下限设置进行项目级配置

下限设置定义了最低保护基准，即使 API 请求中省略了 modelArmorConfig 参数，该基准也适用于项目中的所有 Gemini Enterprise Agent Platform generateContent 调用。如需了解如何设置下限设置，请参阅配置下限设置。

如需启用 Model Armor 和 Gemini Enterprise Agent Platform 集成，请仅使用 API 或 Google Cloud 控制台在项目级设置下限设置。

如需使用 Gemini Enterprise Agent Platform 集成配置下限设置，请运行以下命令：

gcloud

gcloud model-armor floorsettings update \
  --full-uri=projects/PROJECT_ID/locations/global/floorSetting \
  --add-integrated-services=VERTEX_AI

此命令默认启用 INSPECT_ONLY 强制执行模式。如需将模式更改为 INSPECT_AND_BLOCK，请运行以下命令：

gcloud model-armor floorsettings update \
  --full-uri=projects/PROJECT_ID/locations/global/floorSetting \
  --vertex-ai-enforcement-type=INSPECT_AND_BLOCK

如需从集成服务中移除 Gemini Enterprise Agent Platform，请运行以下命令：

gcloud model-armor floorsettings update \
  --full-uri=projects/PROJECT_ID/locations/global/floorSetting \
  --remove-integrated-services=VERTEX_AI

如需从下限设置中移除所有已配置的集成服务，请运行以下命令：

gcloud model-armor floorsettings update \
  --full-uri=projects/PROJECT_ID/locations/global/floorSetting \
  --clear-integrated-services

将 PROJECT_ID 替换为下限设置的项目 ID。

REST

curl -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -d '{"filterConfig" : {"piAndJailbreakFilterSettings": { "filterEnforcement": "ENABLED"}}, "integratedServices": ["AI_PLATFORM"], "aiPlatformFloorSetting":{"inspectOnly":true, "enableCloudLogging":true}, "enableFloorSettingEnforcement":true}' \
  "https://modelarmor.googleapis.com/v1/projects/PROJECT_ID/locations/global/floorSetting"

将 PROJECT_ID 替换为包含下限设置的项目的 ID。

配置下限设置以启用 Gemini Enterprise Agent Platform 清理后，Model Armor 会使用指定的过滤设置清理对项目 Gemini 端点的所有 generateContent API 调用。

以下代码示例展示了如何使用 generateContent 方法。

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-2.5-flash:generateContent" -d '{
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/gemini-2.5-flash:generateContent" -d '{
"contents": [
  {
      "role": "user",
      "parts": [
          {
              "text": ""
          }
      ]
  }
]
, "generationConfig": {
  "responseModalities": ["TEXT"]
  ,"temperature": 0.2
  ,"maxOutputTokens": 1024
  ,"topP": 0.8
}
}'

替换以下内容：

PROJECT_ID：您的 Google Cloud 项目 ID。
LOCATION：Gemini 端点的 Google Cloud 位置。如需了解支持的位置，请参阅 Model Armor API 的位置。

以下代码示例展示了来自 generateContent 方法的回答。

{
"promptFeedback": {
  "blockReason": "MODEL_ARMOR",
  "blockReasonMessage": "Blocked by Floor Setting. The prompt violated
  Responsible AI Safety settings (Harassment, Dangerous), Prompt Injection
  and Jailbreak filters."
},
"usageMetadata": {
  "trafficType": "ON_DEMAND"
},
"modelVersion": "gemini-2.5-flash",
"createTime": "2025-03-26T13:14:36.961184Z",
"responseId": "vP3jZ6DVOqLKnvgPqZL-8Ao"
}

定义下限设置的强制执行类型

如需配置 Model Armor 处理检测结果的方式，请将强制执行类型设置为 INSPECT 或 INSPECT_AND_BLOCK。以下示例展示了采用 INSPECT_AND_BLOCK 强制执行类型的下限设置配置。

gcloud

gcloud model-armor floorsettings update \
  --full-uri=projects/modelarmor-api-test/locations/global/floorSetting \
  --vertex-ai-enforcement-type=INSPECT_AND_BLOCK

REST

export FLOOR_SETTING='{
  "filterConfig": {
    "raiSettings": {
      "raiFilters": [
        { "filterType": "HATE_SPEECH", "confidenceLevel": "LOW_AND_ABOVE" },
        { "filterType": "DANGEROUS", "confidenceLevel": "LOW_AND_ABOVE" },
        { "filterType": "SEXUALLY_EXPLICIT", "confidenceLevel": "LOW_AND_ABOVE" },
        { "filterType": "HARASSMENT", "confidenceLevel": "LOW_AND_ABOVE" }
      ]
    },
    "sdpSettings": {
      "basicConfig": { "filterEnforcement": "ENABLED" }
    },
    "piAndJailbreakFilterSettings": {
      "filterEnforcement": "ENABLED",
      "confidenceLevel": "LOW_AND_ABOVE"
    },
    "maliciousUriFilterSettings": { "filterEnforcement": "ENABLED" }
  },
  "integratedServices": ["AI_PLATFORM"],
  "aiPlatformFloorSetting": {
    "inspectAndBlock": true,
    "enableCloudLogging": true
  },
  "enableFloorSettingEnforcement": true
}'

curl -X PATCH \
    -d "$FLOOR_SETTING" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://modelarmor.googleapis.com/v1/projects/PROJECT_ID/locations/global/floorSetting"

替换以下内容：

PROJECT_ID：下限设置所对应的项目的 ID。
LOCATION：下限设置的位置。

使用 API 调用测试内嵌强制执行

测试集成以调用 Gemini Enterprise Agent Platform API 的 generateContent 方法。使用旨在违反配置的下限设置的提示。

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" "https://${VERTEX_AI_LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${VERTEX_AI_LOCATION}/publishers/google/models/gemini-2.5-flash:generateContent" -d '{
"contents": [
    {
        "role": "user",
        "parts": [
            {
                "text": ""
            }
        ]
    }
]
, "generationConfig": {
    "responseModalities": ["TEXT"]
    ,"temperature": 0.2
    ,"maxOutputTokens": 1024
    ,"topP": 0.8
}
}'

如果集成按预期运行，当 Model Armor 将提示识别为违规时，API 会返回一个回答，并将 blockReason 字段设置为 MODEL_ARMOR。

回答示例：

    {
    "promptFeedback": {
      "blockReason": "MODEL_ARMOR",
      "blockReasonMessage": "Blocked by Floor Setting. The prompt violated Responsible AI Safety settings..."
    },
    "usageMetadata": { "trafficType": "ON_DEMAND" },
    "modelVersion": "gemini-2.5-flash"
    }

交互和优先规则

将 Model Armor 与 Gemini Enterprise Agent Platform 搭配使用时，您可以在多个级别定义安全配置。在这种情况下，Model Armor 和 Gemini Enterprise Agent Platform 遵循特定的优先顺序：

Model Armor 模板：API 请求配置中明确提供的任何配置都具有最高优先级。这些设置会替换该特定请求的任何其他冲突配置。
Model Armor 下限设置：如果在 API 请求中未提供任何替换配置，则应用 Model Armor 下限设置。
Gemini Enterprise Agent Platform 安全过滤器：Gemini Enterprise Agent Platform 内置的默认安全过滤器具有最低优先级。只有在您未定义特定的 Model Armor 模板或下限设置时，它们才会应用。

这种分层方法结合了广泛的组织级最低标准（使用下限设置）和每个请求的控制（使用模板），同时仍将 Gemini Enterprise Agent Platform 的固有安全功能用作基准。

Model Armor 和 Gemini Enterprise Agent Platform 安全功能的行为取决于您提供配置的方式。

是否配置了模板？	是否配置了 Gemini Enterprise Agent Platform 安全过滤器？	是否配置了下限设置？	行为
是	是	不限	您会收到错误。您无法在同一请求中同时指定模板配置和 Gemini Enterprise Agent Platform 安全过滤器。
是	否	不限	Model Armor 运行，使用 `modelArmorConfig` 中指定的模板。Gemini Enterprise Agent Platform 安全过滤器将被忽略。请求模板会替换下限设置。
否	是	是	两者都运行。Model Armor 使用下限设置政策进行扫描，Gemini Enterprise Agent Platform 会评估其安全过滤器。应用限制性最强的结果。
否	否	是	Model Armor 运行，使用有效的下限设置政策。
否	是	否	仅评估 Gemini Enterprise Agent Platform 安全过滤器。不会调用 Model Armor。
否	否	否	既不应用每个请求的 Model Armor，也不应用 Gemini Enterprise Agent Platform 安全过滤器。仅基准模型行为处于有效状态。

将 Model Armor 与 Gemini Enterprise Agent Platform 集成 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

限制

准备工作

配置 Model Armor 如何帮助保护 Gemini Enterprise Agent Platform

使用模板进行每个请求的配置

定义模板的强制执行类型

使用下限设置进行项目级配置

gcloud

REST

定义下限设置的强制执行类型

gcloud

REST

使用 API 调用测试内嵌强制执行

交互和优先规则

将 Model Armor 与 Gemini Enterprise Agent Platform 集成