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 examinando las instrucciones y las 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 detección de inyección de instrucciones y jailbreaking, 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 sanitización de instrucciones y respuestas.

Además de proteger las llamadas directas a la API de REST del servicio de Gemini Enterprise Agent Platform, también puedes usar Model Armor para proteger otras interfaces que brindan acceso a la API de Gemini en Vertex AI, como los SDKs de IA generativa de Google o los SDKs 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, verifica si el contenido coincide con los criterios de filtro definidos en la plantilla. Si encuentra una coincidencia, Model Armor marcará que el contenido activó el filtro de Sensitive Data Protection. Si bien 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 la política es INSPECT_AND_BLOCK, Model Armor emite un veredicto de bloqueo para garantizar que los datos sensibles no se procesen más.
  • No se admite la sanitización de instrucciones y respuestas que contienen documentos.
  • 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 se encuentra Gemini Enterprise Agent Platform.
    • No se puede acceder a Model Armor temporalmente.
    • Se produce un error en Model Armor.

    En ocasiones, todas estas instancias pueden exponer instrucciones o respuestas sin filtrar, ya que la solicitud continúa sin la limpieza de instrucciones y respuestas.

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

Antes de comenzar

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

Puedes configurar la forma en que Model Armor protege Gemini Enterprise Agent Platform de dos 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 llamada a la API de generateContent 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 al aplicar 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 los incumplimientos o si también se bloquean.

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 sanear la instrucción.
  • responseTemplateName: Es el nombre del recurso de la plantilla de Model Armor para sanear 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 ID del proyecto de Google Cloud .
  • 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"
}

Cómo definir el tipo de aplicación para las plantillas

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

En el siguiente ejemplo, se muestra la configuración de la plantilla de Model Armor con el tipo de aplicación 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 del proyecto con la configuración mínima

La configuración mínima define un nivel de protección base mínimo que se aplica a todas las llamadas de 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 Cómo establecer la configuración mínima para obtener información sobre cómo establecer 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 consola de Google Cloud .

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

De forma predeterminada, este comando habilita el modo de aplicación de INSPECT_ONLY. 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 la plataforma de agentes de Gemini Enterprise 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 los parámetros mínimos para habilitar el saneamiento de Gemini Enterprise Agent Platform, Model Armor sanea 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 proyecto de Google Cloud .
  • 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 en INSPECT o INSPECT_AND_BLOCK. En el siguiente ejemplo, se muestra la configuración mínima con el tipo de aplicación 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 políticas 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 establecida.

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 según lo previsto, la API devuelve una respuesta con el campo blockReason establecido en MODEL_ARMOR cuando Model Armor identifica el mensaje como un incumplimiento.

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 parámetros de configuración de seguridad en varios niveles. En estos casos, Model Armor y Gemini Enterprise Agent Platform siguen un orden de prioridad específico:

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

  2. Configuración mínima de Model Armor: Si no se proporciona ninguna 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 prioridad más baja. Solo se aplican si no defines plantillas o parámetros de configuración mínima específicos de Model Armor.

Este enfoque jerárquico proporciona una combinación de estándares mínimos amplios para toda la organización (con la configuración mínima) y control por solicitud (con plantillas), y, al mismo tiempo, utiliza 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? ¿Están configurados 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 solicitudes anulan la configuración mínima.
No Sí Sí Ambos se ejecutan. Model Armor realiza análisis 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.