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 filtrant 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 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 ainsi des mesures de sécurité telles que la détection de l'injection de prompt et du jailbreaking, les filtres d'IA responsable et la protection des données sensibles. Vous pouvez configurer cette intégration en utilisant les 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 offre une protection des prompts 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 les requêtes ou les réponses, il vérifie si le contenu correspond aux critères de filtrage définis dans le modèle. Si une correspondance est trouvée, Model Armor indique 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 renvoie pas les données anonymisées (comme le contenu masqué, expurgé ou haché) à Gemini Enterprise Agent Platform pour un traitement ultérieur. En revanche, 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 n'est pas prise en charge.
  • 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 et renvoie une erreur Template not found.

  • Gemini Enterprise Agent Platform ignore l'étape de désinfection Model Armor et continue de traiter la requête dans les conditions suivantes :

    • 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 filtrées peuvent parfois être exposées, car la requête se poursuit sans que la requête et la réponse soient nettoyées.

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

Avant de commencer

Configurer la protection de Gemini Enterprise Agent Platform par Model Armor

Vous pouvez configurer la façon dont Model Armor protège Gemini Enterprise Agent Platform 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 appel d'API generateContent aux modèles Gemini sur Gemini Enterprise Agent Platform.
  • Utiliser les paramètres de plancher pour une protection au niveau du projet : cette approche applique une protection de base en appliquant des paramètres de plancher à tous les appels d'API generateContent aux modèles Gemini sur Gemini Enterprise Agent Platform dans votre projet.

Définissez le type d'application pour déterminer si les cas de non-respect sont uniquement inspectés ou également bloqués.

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 demande 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 à utiliser pour assainir la requête.
  • responseTemplateName : nom de ressource du modèle Model Armor permettant de nettoyer la réponse.

L'exemple de code suivant montre la requête envoyée à 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 projet Google Cloud .
  • LOCATION : emplacement Google Cloud 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 : emplacement du modèle.

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

Les paramètres de plancher définissent un niveau de protection de base minimal qui s'applique à tous les appels generateContent de la plate-forme Gemini Enterprise Agent 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 console Google Cloud .

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

Cette commande active le mode d'application INSPECT_ONLY par défaut. 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 la plate-forme d'agents Gemini Enterprise 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 l'étage, 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.

Une fois les paramètres de plancher configurés pour activer la désinfection de Gemini Enterprise Agent Platform, Model Armor désinfecte tous les appels d'API generateContent vers les 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 projet Google Cloud .
  • LOCATION : emplacement Google Cloud du point de terminaison Gemini. Pour connaître les emplacements acceptés, consultez Emplacements pour 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 : emplacement des paramètres de plancher.

Tester l'application inline avec un appel d'API

Testez l'intégration pour appeler la méthode generateContent de l'API Gemini Enterprise Agent Platform. Utilisez un prompt conçu 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 infraction.

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 toute autre configuration incompatible pour cette demande 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. Elles ne s'appliquent que si vous ne définissez pas de modèles ou de paramètres de plancher Model Armor 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.

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

Le modèle est-il configuré ? Les filtres de sécurité Gemini Enterprise Agent Platform sont-ils configurés ? Avez-vous configuré les paramètres de plancher ? Comportement
Oui Oui Tous Un message d'erreur s'affiche. Vous ne pouvez pas spécifier à la fois une configuration de modèle et des 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é de Gemini Enterprise Agent Platform sont ignorés. Les modèles de demande remplacent les paramètres de plancher.
Non Oui Oui Les deux s'exécutent. Model Armor effectue des analyses à l'aide du règlement sur les paramètres de plancher, et Gemini Enterprise Agent Platform évalue ses filtres de sécurité. Le résultat le plus restrictif est appliqué.
Non Non Oui Exécutions Model Armor, à l'aide de la règle de paramètre plancher actif.
Non Oui Non Seuls les filtres de sécurité de Gemini Enterprise Agent Platform sont évalués. Model Armor n'est pas appelé.
Non Non Non Aucun filtre de sécurité Model Armor par requête ni Gemini Enterprise Agent Platform n'est appliqué. Seuls les comportements de référence du modèle sont actifs.