Integra Model Armor con Gemini Enterprise Agent Platform

En este documento, se describe cómo configurar Model Armor para proteger los modelos de Gemini en Gemini Enterprise Agent Platform mediante el examen de instrucciones y respuestas. Cuando se integra con Gemini Enterprise Agent Platform, Model Armor intercepta las instrucciones antes de que lleguen a los modelos de Gemini y las respuestas antes de que tu aplicación las reciba. Según tu configuración, Gemini Enterprise Agent Platform llama al servicio de Model Armor, que inspecciona o bloquea el tráfico que incumple las políticas definidas, lo que aplica medidas de seguridad como la inyección de instrucciones y la detección de jailbreak, los filtros de IA responsable y Sensitive Data Protection. Puedes configurar esta integración con la configuración mínima para la protección a nivel del proyecto o con plantillas para la protección por solicitud.

Model Armor proporciona protección de instrucciones y respuestas dentro de la API de Gemini en Vertex AI para el método generateContent. Debes habilitar Cloud Logging para ver los resultados de la limpieza de instrucciones y respuestas.

Además de proteger las llamadas directas a REST al servicio de Gemini Enterprise Agent Platform, también puedes usar Model Armor para proteger otras interfaces que proporcionan acceso a la API de Gemini en Vertex AI, como los SDK de Google IA generativa o los SDK de Firebase AI Logic.

Limitaciones

Ten en cuenta las siguientes limitaciones cuando integres Model Armor con Gemini Enterprise Agent Platform:

  • Cuando Model Armor usa una plantilla de Sensitive Data Protection para analizar instrucciones o respuestas, Model Armor verifica si el contenido coincide con los criterios de filtro definidos en la plantilla. Si encuentra una coincidencia, Model Armor indica que el contenido activó el filtro de Sensitive Data Protection. Aunque Sensitive Data Protection desidentifica los datos según la configuración de la plantilla, Model Armor no pasa los datos desidentificados, como el contenido enmascarado, oculto o con hash, a Gemini Enterprise Agent Platform para su procesamiento posterior. En cambio, si el tipo de aplicación de medidas por incumplimiento es INSPECT_AND_BLOCK, Model Armor emite un veredicto de bloqueo para garantizar que los datos sensibles no continúen para su procesamiento posterior.
  • La limpieza de instrucciones y respuestas que contienen documentos o cargas de archivos (como archivos PDF) no es compatible con esta integración. Para examinar documentos, llama directamente a la API de REST de Model Armor.
  • Si Gemini Enterprise Agent Platform enruta una solicitud a una región en la que no existe la plantilla de Model Armor especificada, la solicitud falla con un error Template not found.

  • Gemini Enterprise Agent Platform omite el paso de limpieza de Model Armor y continúa procesando la solicitud en las siguientes condiciones:

    • Model Armor no está disponible en una región en la que está presente Gemini Enterprise Agent Platform.
    • No se puede acceder a Model Armor temporalmente.
    • Se produce un error en Model Armor.

    Todas estas instancias pueden exponer ocasionalmente instrucciones o respuestas no examinadas porque la solicitud continúa sin la limpieza de instrucciones y respuestas.

    Aunque la integración está diseñada para brindar alta disponibilidad durante las fallas de conexión, el modo INSPECT_AND_BLOCK seguirá informando errores de configuración, como problemas de permisos o cuotas.

Antes de comenzar

Configura cómo Model Armor ayuda a proteger Gemini Enterprise Agent Platform

Puedes configurar cómo Model Armor protege Gemini Enterprise Agent Platform de una de las siguientes maneras:

  • Usa plantillas para la protección por solicitud: Este enfoque proporciona un control detallado , ya que te permite aplicar una plantilla específica a cada generateContent llamada a la API a los modelos de Gemini en Gemini Enterprise Agent Platform.
  • Usa la configuración mínima para la protección a nivel del proyecto: Este enfoque aplica una protección de referencia aplicando la configuración mínima a todas las llamadas a la API de generateContent a los modelos de Gemini en Gemini Enterprise Agent Platform dentro de tu proyecto.

Define el tipo de aplicación de medidas por incumplimiento para determinar si solo se inspeccionan o también se bloquean las infracciones.

Configuración por solicitud con plantillas

Las plantillas te permiten configurar cómo Model Armor examina las instrucciones y las respuestas, y definir la configuración de los filtros de seguridad. Primero debes crear plantillas y, luego, usarlas con el método generateContent de Gemini. Para obtener más información sobre las plantillas, consulta Crea y administra plantillas de Model Armor.

Después de configurar la plantilla de Model Armor, pasa el ID de la plantilla como parámetro cuando realices una llamada a la API de Gemini con el método generateContent. Gemini Enterprise Agent Platform enruta la solicitud a Model Armor para su procesamiento.

Para aplicar plantillas específicas a una llamada generateContent individual, incluye el objeto modelArmorConfig en tu solicitud.

  • promptTemplateName: Es el nombre del recurso de la plantilla de Model Armor para limpiar la instrucción.
  • responseTemplateName: Es el nombre del recurso de la plantilla de Model Armor para limpiar la respuesta.

En el siguiente muestra de código, se muestra la solicitud al método 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"
        }
}'

Reemplaza lo siguiente:

  • PROJECT_ID: Es el Google Cloud ID del proyecto.
  • LOCATION: Es la Google Cloud ubicación del extremo de Gemini. Las ubicaciones admitidas son europe-west1, europe-west2, europe-west3, asia-southeast1 y asia-south1.
  • TEMPLATE_ID: Es el ID de la plantilla de Model Armor.

En el siguiente muestra de código, se muestra la respuesta del método 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"
}

Define el tipo de aplicación de medidas por incumplimiento para las plantillas

Para configurar cómo Model Armor controla las detecciones, establece el tipo de aplicación de medidas por incumplimiento.

En el siguiente ejemplo, se muestra la configuración de la plantilla de Model Armor con el tipo de aplicación de medidas por incumplimiento Inspect only.

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"

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto al que pertenece la plantilla.
  • TEMPLATE_ID: Es el ID de la plantilla que se creará.
  • LOCATION: Es la ubicación de la plantilla.

Configuración a nivel de proyecto con la configuración mínima

La configuración mínima define una referencia mínima de protección que se aplica a todas las llamadas a generateContent de Gemini Enterprise Agent Platform dentro de un proyecto, incluso si se omite el parámetro modelArmorConfig de la solicitud a la API. Consulta Establecer límites para obtener información sobre cómo configurar la configuración mínima.

Para habilitar la integración de Model Armor y Gemini Enterprise Agent Platform, establece la configuración mínima solo a nivel del proyecto con la API o la Google Cloud consola.

Para configurar la configuración mínima con la integración de Gemini Enterprise Agent Platform, ejecuta el siguiente comando:

gcloud

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

Este comando habilita el modo de aplicación de medidas por incumplimiento INSPECT_ONLY de forma predeterminada. Para cambiar el modo a INSPECT_AND_BLOCK, ejecuta el siguiente comando:

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

Para quitar Gemini Enterprise Agent Platform de los servicios integrados, ejecuta el siguiente comando:

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

Para quitar todos los servicios integrados configurados de la configuración mínima, ejecuta el siguiente comando:

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

Reemplaza PROJECT_ID por el ID del proyecto para la configuración mínima.

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"

Reemplaza PROJECT_ID por el ID del proyecto que contiene la configuración mínima.

Después de configurar la configuración mínima para habilitar la limpieza de Gemini Enterprise Agent Platform, Model Armor limpia todas las llamadas a la API de generateContent a los extremos de Gemini del proyecto con la configuración de filtro especificada.

En la siguiente muestra de código, se muestra cómo usar el método 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
}
}'

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del Google Cloud proyecto de.
  • LOCATION: Es la Google Cloud ubicación del extremo de Gemini. Para conocer las ubicaciones admitidas, consulta Ubicaciones de la API de Model Armor.

En el siguiente muestra de código, se muestra la respuesta del método 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"
}

Define el tipo de aplicación de medidas por incumplimiento para la configuración mínima

Para configurar cómo Model Armor controla las detecciones, establece el tipo de aplicación de medidas por incumplimiento en INSPECT o INSPECT_AND_BLOCK. En el siguiente ejemplo, se muestra la configuración mínima con el tipo de aplicación de medidas por incumplimiento 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"

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto para la configuración mínima.
  • LOCATION: Es la ubicación de la configuración mínima.

Prueba la aplicación de medidas por incumplimiento intercalada con una llamada a la API

Prueba la integración para llamar al método generateContent de la API de Gemini Enterprise Agent Platform. Usa una instrucción diseñada para incumplir la configuración mínima configurada.

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
}
}'

Si la integración funciona como se espera, la API muestra una respuesta con el campo blockReason establecido en MODEL_ARMOR cuando Model Armor identifica la instrucción como una infracción.

A continuación, se muestra una respuesta de ejemplo:

    {
    "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"
    }

Reglas de interacción y precedencia

Cuando usas Model Armor con Gemini Enterprise Agent Platform, puedes definir configuraciones de seguridad en varios niveles. En esos casos, Model Armor y Gemini Enterprise Agent Platform siguen un orden de precedencia específico:

  1. Plantillas de Model Armor: Cualquier configuración que se proporcione de forma explícita en la configuración de la solicitud a la API tiene la mayor precedencia. Estos parámetros de configuración anulan cualquier otra configuración en conflicto para esa solicitud específica.

  2. Configuración mínima de Model Armor: Si no se proporciona una configuración de anulación en la solicitud a la API, se aplica la configuración mínima de Model Armor.

  3. Filtros de seguridad de Gemini Enterprise Agent Platform: Los filtros de seguridad predeterminados integrados en Gemini Enterprise Agent Platform tienen la precedencia más baja. Se aplican solo si no defines plantillas de Model Armor o configuración mínima específicas.

Este enfoque jerárquico proporciona una combinación de estándares mínimos amplios en toda la organización (con la configuración mínima) y control por solicitud (con plantillas), mientras que sigue usando las funciones de seguridad inherentes de Gemini Enterprise Agent Platform como referencia.

El comportamiento de Model Armor y las funciones de seguridad de Gemini Enterprise Agent Platform dependen de cómo proporciones la configuración.

¿Se configuró la plantilla? ¿Se configuraron los filtros de seguridad de Gemini Enterprise Agent Platform? ¿Se configuró la configuración mínima? Comportamiento
Sí Sí Cualquiera Recibes un error. No puedes especificar la configuración de la plantilla y los filtros de seguridad de Gemini Enterprise Agent Platform en la misma solicitud.
Sí No Cualquiera Se ejecuta Model Armor con las plantillas especificadas en modelArmorConfig. Se ignoran los filtros de seguridad de Gemini Enterprise Agent Platform. Las plantillas de solicitud anulan la configuración mínima.
No Sí Sí Ambos se ejecutan. Model Armor analiza con la política de configuración mínima, y Gemini Enterprise Agent Platform evalúa sus filtros de seguridad. Se aplica el resultado más restrictivo.
No No Sí Se ejecuta Model Armor con la política de configuración mínima activa.
No Sí No Solo se evalúan los filtros de seguridad de Gemini Enterprise Agent Platform. No se llama a Model Armor.
No No No No se aplican los filtros de seguridad de Model Armor por solicitud ni de Gemini Enterprise Agent Platform. Solo están activos los comportamientos del modelo de referencia.