Intégrer Model Armor à Gemini Enterprise Agent Platform

Ce document explique comment configurer Model Armor pour protéger les modèles Gemini sur Gemini Enterprise Agent Platform en analysant les requêtes et les réponses. Lorsqu'il est intégré à Gemini Enterprise Agent Platform, Model Armor intercepte les requêtes avant qu'elles n'atteignent les modèles Gemini et intercepte les réponses avant que votre application ne les reçoive. En fonction de votre configuration, Gemini Enterprise Agent Platform appelle le service Model Armor, qui inspecte ou bloque le trafic qui ne respecte pas les règles que vous avez définies. Il applique des mesures de sécurité telles que la détection des injections de requêtes et du jailbreaking, des filtres d'IA responsable et Sensitive Data Protection. Vous pouvez configurer cette intégration en utilisant des paramètres de plancher pour la protection au niveau du projet ou en utilisant des modèles pour la protection par requête.

Model Armor assure la protection des requêtes et des réponses dans l'API Gemini de Vertex AI pour la méthode generateContent. Vous devez activer Cloud Logging pour afficher les résultats de la désinfection des requêtes et des réponses.

En plus de protéger les appels REST directs au service Gemini Enterprise Agent Platform, vous pouvez également utiliser Model Armor pour protéger d'autres interfaces qui donnent accès à l'API Gemini dans Vertex AI, comme les SDK Google IA générative ou les SDK Firebase AI Logic.

Limites

Tenez compte des limites suivantes lorsque vous intégrez Model Armor à Gemini Enterprise Agent Platform :

  • Lorsque Model Armor utilise un modèle Sensitive Data Protection pour analyser des requêtes ou des réponses, il vérifie si le contenu correspond aux critères de filtre définis dans le modèle. S'il trouve une correspondance, Model Armor signale que le contenu a déclenché le filtre Sensitive Data Protection. Bien que Sensitive Data Protection anonymise les données en fonction de la configuration du modèle, Model Armor ne transmet pas les données anonymisées (telles que le contenu masqué, expurgé ou haché) à Gemini Enterprise Agent Platform pour un traitement ultérieur. Au lieu de cela, si le type d'application est INSPECT_AND_BLOCK, Model Armor émet un verdict de blocage pour s'assurer que les données sensibles ne sont pas traitées ultérieurement.
  • La désinfection des requêtes et des réponses contenant des documents ou des fichiers importés (tels que des PDF) n'est pas prise en charge dans cette intégration. Pour analyser des documents, appelez directement l'API REST Model Armor.
  • Si Gemini Enterprise Agent Platform achemine une requête vers une région où le modèle Model Armor spécifié n'existe pas, la requête échoue avec une erreur Template not found.

  • Gemini Enterprise Agent Platform ignore l'étape de désinfection Model Armor et poursuit le traitement de la requête dans les cas suivants :

    • Model Armor n'est pas disponible dans une région où Gemini Enterprise Agent Platform est présent.
    • Model Armor est temporairement inaccessible.
    • Une erreur se produit dans Model Armor.

    Dans tous ces cas, des requêtes ou des réponses non analysées peuvent parfois être exposées, car la requête se poursuit sans désinfection.

    Bien que l'intégration soit conçue pour une haute disponibilité en cas d'échec de connexion, le mode INSPECT_AND_BLOCK signale toujours les erreurs de configuration, telles que les problèmes d'autorisation ou de quota.

Avant de commencer

Configurer l'aide de Model Armor pour protéger Gemini Enterprise Agent Platform

Vous pouvez configurer la protection de Gemini Enterprise Agent Platform par Model Armor de deux manières :

  • Utiliser des modèles pour la protection par requête : cette approche offre un contrôle précis en vous permettant d'appliquer un modèle spécifique à chaque generateContent appel d'API aux modèles Gemini sur Gemini Enterprise Agent Platform.
  • Utiliser des paramètres de plancher pour la protection au niveau du projet : cette approche applique une protection de base en appliquant des paramètres de plancher à tous les generateContent appels d'API aux modèles Gemini sur Gemini Enterprise Agent Platform dans votre projet.

Définissez le type d'application pour déterminer si les violations sont uniquement inspectées ou également bloquées.

Configuration par requête à l'aide de modèles

Les modèles vous permettent de configurer la façon dont Model Armor analyse les requêtes et les réponses, et de définir les configurations des filtres de sécurité. Vous devez d'abord créer des modèles, puis les utiliser avec la méthode generateContent de Gemini. Pour en savoir plus sur les modèles, consultez Créer et gérer des modèles Model Armor.

Après avoir configuré le modèle Model Armor, transmettez l'ID du modèle en tant que paramètre lorsque vous appelez l'API Gemini à l'aide de la méthode generateContent. Gemini Enterprise Agent Platform achemine la requête vers Model Armor pour traitement.

Pour appliquer des modèles spécifiques à un appel generateContent individuel, incluez l'objet modelArmorConfig dans votre requête.

  • promptTemplateName: nom de ressource du modèle Model Armor pour désinfecter la requête.
  • responseTemplateName: nom de ressource du modèle Model Armor pour désinfecter la réponse.

L'exemple de code suivant montre la requête à la méthode 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"
        }
}'

Remplacez les éléments suivants :

  • PROJECT_ID: ID du Google Cloud projet.
  • LOCATION : Google Cloud emplacement du point de terminaison Gemini. Les emplacements acceptés sont europe-west1, europe-west2, europe-west3, asia-southeast1 et asia-south1.
  • TEMPLATE_ID : ID du modèle Model Armor.

L'exemple de code suivant montre la réponse de la méthode 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"
}

Définir le type d'application pour les modèles

Pour configurer la façon dont Model Armor gère les détections, définissez le type d'application.

L'exemple suivant montre la configuration du modèle Model Armor avec le type d'application 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"

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet auquel appartient le modèle.
  • TEMPLATE_ID : ID du modèle à créer.
  • LOCATION: the location of the template.

Configuration au niveau du projet à l'aide des paramètres de plancher

Les paramètres de plancher définissent une base de protection minimale qui s'applique à tous les appels generateContent de Gemini Enterprise Agent Platform dans un projet, même si le paramètre modelArmorConfig est omis de la requête API. Pour savoir comment configurer les paramètres de plancher, consultez Configurer les paramètres de plancher.

Pour activer l'intégration de Model Armor et de Gemini Enterprise Agent Platform, définissez les paramètres de plancher uniquement au niveau du projet à l'aide de l'API ou de la Google Cloud console.

Pour configurer les paramètres de plancher avec l'intégration de Gemini Enterprise Agent Platform, exécutez la commande suivante :

gcloud

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

Par défaut, cette commande active le mode d'application INSPECT_ONLY. Pour passer au mode INSPECT_AND_BLOCK, exécutez la commande suivante :

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

Pour supprimer Gemini Enterprise Agent Platform des services intégrés, exécutez la commande suivante :

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

Pour supprimer tous les services intégrés configurés des paramètres de plancher, exécutez la commande suivante :

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

Remplacez PROJECT_ID par l'ID du projet pour les paramètres de plancher.

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"

Remplacez PROJECT_ID par l'ID du projet contenant les paramètres de plancher.

Après avoir configuré les paramètres de plancher pour activer la désinfection de Gemini Enterprise Agent Platform, Model Armor désinfecte tous les appels d'API generateContent aux points de terminaison Gemini du projet à l'aide des paramètres de filtre spécifiés.

L'exemple de code suivant montre comment utiliser la méthode 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
}
}'

Remplacez les éléments suivants :

  • PROJECT_ID: ID de votre Google Cloud projet.
  • LOCATION : Google Cloud emplacement du point de terminaison Gemini. Pour connaître les emplacements acceptés, consultez Emplacements de l'API Model Armor.

L'exemple de code suivant montre la réponse de la méthode 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"
}

Définir le type d'application pour les paramètres de plancher

Pour configurer la façon dont Model Armor gère les détections, définissez le type d'application sur INSPECT ou INSPECT_AND_BLOCK. L'exemple suivant montre la configuration des paramètres de plancher avec le type d'application 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"

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet pour les paramètres de plancher.
  • LOCATION : the location emplacement des paramètres de plancher.

Tester l'application intégrée avec un appel d'API

Testez l'intégration pour appeler la méthode generateContent de l'API Gemini Enterprise Agent Platform. Utilisez une requête conçue pour enfreindre les paramètres de plancher configurés.

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 l'intégration fonctionne comme prévu, l'API renvoie une réponse avec le champ blockReason défini sur MODEL_ARMOR lorsque Model Armor identifie la requête comme une violation.

Voici un exemple de réponse :

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

Règles d'interaction et de priorité

Lorsque vous utilisez Model Armor avec Gemini Enterprise Agent Platform, vous pouvez définir des configurations de sécurité à plusieurs niveaux. Dans ce cas, Model Armor et Gemini Enterprise Agent Platform suivent un ordre de priorité spécifique :

  1. Modèles Model Armor : toute configuration explicitement fournie dans la configuration de la requête API a la priorité la plus élevée. Ces paramètres remplacent toutes les autres configurations conflictuelles pour cette requête spécifique.

  2. Paramètres de plancher Model Armor : si aucune configuration de remplacement n'est fournie dans la requête API, les paramètres de plancher Model Armor s'appliquent.

  3. Filtres de sécurité Gemini Enterprise Agent Platform : les filtres de sécurité par défaut intégrés à Gemini Enterprise Agent Platform ont la priorité la plus basse. Ils ne s'appliquent que si vous ne définissez pas de modèles Model Armor ou de paramètres de plancher spécifiques.

Cette approche hiérarchique combine des normes minimales générales à l'échelle de l'organisation (à l'aide des paramètres de plancher) et un contrôle par requête (à l'aide de modèles), tout en utilisant les fonctionnalités de sécurité inhérentes à Gemini Enterprise Agent Platform comme base de référence.

Le comportement de Model Armor et des fonctionnalités de sécurité de Gemini Enterprise Agent Platform dépend de la façon dont vous fournissez la configuration.

Modèle configuré ? Filtres de sécurité Gemini Enterprise Agent Platform configurés ? Paramètres de plancher configurés ? Comportement
Oui Oui Tous Une erreur s'affiche. Vous ne pouvez pas spécifier à la fois la configuration du modèle et les filtres de sécurité Gemini Enterprise Agent Platform dans la même requête.
Oui Non Tous Model Armor s'exécute à l'aide des modèles spécifiés dans modelArmorConfig. Les filtres de sécurité Gemini Enterprise Agent Platform sont ignorés. Les modèles de requête remplacent les paramètres de plancher.
Non Oui Oui Les deux s'exécutent. Model Armor analyse à l'aide de la règle de paramètre de plancher, et Gemini Enterprise Agent Platform évalue ses filtres de sécurité. Le résultat le plus restrictif est appliqué.
Non Non Oui Model Armor s'exécute à l'aide de la règle de paramètre de plancher active.
Non Oui Non Seuls les filtres de sécurité Gemini Enterprise Agent Platform sont évalués. Model Armor n'est pas appelé.
Non Non Non Ni Model Armor par requête ni les filtres de sécurité Gemini Enterprise Agent Platform ne sont appliqués. Seuls les comportements de modèle de base sont actifs.