本文档介绍了如何配置 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 会标记相应内容触发了 Sensitive Data Protection 过滤条件。虽然 Sensitive Data Protection 会根据模板配置对数据进行去标识化处理，但 Model Armor 不会将去标识化数据（例如经过遮盖、涂改或哈希处理的内容）传递回 Gemini Enterprise Agent Platform 以供进一步处理。相反，如果强制执行类型为
INSPECT_AND_BLOCK，Model Armor 会发出屏蔽判决，以确保敏感数据不会继续进行处理。 - 此集成不支持清理包含文档或文件上传内容（例如 PDF 文件）的提示和回答。如需筛查文档，请直接调用 Model Armor REST API。
- 如果 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.' --role='roles/modelarmor.user'
替换以下内容：
PROJECT_ID：您的 Google Cloud 项目 ID。PROJECT_NUMBER：您的 Google Cloud 项目编号。
启用 Model Armor API。
配置 Model Armor 如何帮助保护 Gemini Enterprise Agent Platform
您可以通过以下两种方式之一配置 Model Armor 如何保护 Gemini Enterprise Agent Platform：
- 使用模板进行单次请求保护：此方法可让您将特定模板应用于 Gemini Enterprise Agent Platform 上对 Gemini 模型的每次
generateContentAPI 调用，从而实现精细的控制。 - 使用下限设置实现项目级防护：此方法通过将下限设置应用于项目内对 Gemini Enterprise Agent Platform 上的 Gemini 模型的所有
generateContentAPI 调用，来强制执行基准防护。
定义强制执行类型，以确定是仅检查违规行为还是也屏蔽违规行为。
使用模板进行按请求配置
借助模板，您可以配置 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 安全过滤器。 |
| 是 | 否 | 不限 | 使用 modelArmorConfig 中指定的模板运行 Model Armor。Gemini Enterprise Agent Platform 安全过滤条件会被忽略。请求模板会覆盖下限设置。 |
| 否 | 是 | 是 | 两者都会运行。Model Armor 会使用下限设置政策进行扫描，而 Gemini Enterprise Agent Platform 会评估其安全过滤条件。系统会应用限制性最强的结果。 |
| 否 | 否 | 是 | Model Armor 会根据有效的下限设置政策运行。 |
| 否 | 是 | 否 | 仅评估 Gemini Enterprise Agent Platform 安全过滤条件。 未调用 Model Armor。 |
| 否 | 否 | 否 | 系统不会应用按请求付费的 Model Armor 或 Gemini Enterprise Agent Platform 安全过滤条件。只有基准模型行为处于有效状态。 |