Integrare con la piattaforma agentica Gemini Enterprise

Model Armor può essere integrato direttamente in Gemini Enterprise Agent Platform utilizzando le impostazioni di base o utilizzando i modelli. Model Armor si integra con Gemini Enterprise Agent Platform per controllare sia le richieste inviate ai modelli Gemini sia le risposte ricevute da questi modelli. Ispeziona o blocca il traffico che viola le impostazioni di base.

Model Armor fornisce la protezione di prompt e risposte all'interno dell'API Gemini in Vertex AI per il metodo generateContent. Devi abilitare Cloud Logging per visualizzare i risultati della sanificazione di prompt e risposte.

Oltre a proteggere le chiamate REST dirette al servizio Gemini Enterprise Agent Platform, puoi utilizzare Model Armor anche per proteggere altre interfacce che forniscono l'accesso all'API Gemini in Vertex AI, come gli SDK Google Gen AI o gli SDK Firebase AI Logic.

Prima di iniziare

Concedi l'autorizzazione dell'utente Model Armor al account di servizio Gemini Enterprise Agent Platform.

gcloud projects add-iam-policy-binding PROJECT_ID --member='serviceAccount:service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com' --role='roles/modelarmor.user'

Sostituisci quanto segue:

  • PROJECT_ID: l' Google Cloud ID progetto.
  • PROJECT_NUMBER: il tuo Google Cloud numero di progetto.

Configura impostazioni di base

Utilizza le impostazioni di base per configurare le soglie minime di rilevamento per i modelli Model Armor. Queste impostazioni verificano che tutti i modelli nuovi e modificati soddisfino i requisiti delle impostazioni di base.

Per abilitare l'integrazione di Model Armor e Gemini Enterprise Agent Platform, puoi impostare le impostazioni di base solo a livello di progetto utilizzando l'API o la Google Cloud console.

Per configurare le impostazioni di base, vedi Configura impostazioni di base.

Per configurare le impostazioni di base con l'integrazione di Gemini Enterprise Agent Platform, esegui il seguente comando:

gcloud

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

Per impostazione predefinita, questo comando abilita la modalità di applicazione INSPECT_ONLY. Per modificare la modalità in INSPECT_AND_BLOCK, esegui il seguente comando:

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

Per rimuovere Gemini Enterprise Agent Platform dai servizi integrati, esegui il seguente comando:

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

Per rimuovere tutti i servizi integrati configurati dalle impostazioni di base, esegui il seguente comando:

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

Sostituisci PROJECT_ID con l'ID del progetto per le impostazioni di base.

REST

curl -X PATCH \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -d '{"filterConfig" : {}, "integratedServices": "AI_PLATFORM", "aiPlatformFloorSetting":{"inspect_only":true, "enableCloudLogging":true}}' \
    "https://modelarmor.googleapis.com/v1/projects/PROJECT_ID/locations/global/floorSetting"

Sostituisci PROJECT_ID con l'ID del progetto per le impostazioni di base.

Dopo aver configurato le impostazioni di base per abilitare la sanificazione di Gemini Enterprise Agent Platform, Model Armor sanifica tutte le chiamate API generateContent agli endpoint Gemini del progetto utilizzando le impostazioni dei filtri specificate.

Il seguente esempio di codice mostra come utilizzare il metodo 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": ""
          }
      ]
  }
]
, "generationConfig": {
  "responseModalities": ["TEXT"]
  ,"temperature": 0.2
  ,"maxOutputTokens": 1024
  ,"topP": 0.8
}
}'

Sostituisci quanto segue:

  • PROJECT_ID: l' Google Cloud ID progetto.
  • LOCATION: la Google Cloud località dell'endpoint Gemini. Per le località supportate, vedi Località per l'API Model Armor.

Il seguente esempio di codice mostra la risposta del metodo 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"
}

Definisci il tipo di applicazione per le impostazioni di base

Per configurare la modalità di gestione dei rilevamenti da parte di Model Armor, imposta il tipo di applicazione. Il seguente esempio mostra la configurazione delle impostazioni di base con il tipo di applicazione 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='{
  "filter_config": {
    "rai_settings": {
      "rai_filters": {
        "filter_type": "HATE_SPEECH",
        "confidence_level": "LOW_AND_ABOVE"
      },
      "rai_filters": {
        "filter_type": "DANGEROUS",
        "confidence_level": "LOW_AND_ABOVE"
      },
    "rai_filters": {
        "filter_type": "SEXUALLY_EXPLICIT",
        "confidence_level": "LOW_AND_ABOVE"
      },
      "rai_filters": {
        "filter_type": "HARASSMENT",
        "confidence_level": "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
  },
  "enable_floor_setting_enforcement": "true"
}'

curl -X POST \
    -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/LOCATION/floorSetting"

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del progetto per le impostazioni di base.
  • LOCATION: la località delle impostazioni di base.

Configura i modelli Model Armor

Model Armor può essere integrato anche con Gemini Enterprise Agent Platform utilizzando i modelli Model Armor. I modelli consentono di configurare la modalità di controllo di prompt e risposte da parte di Model Armor e definiscono le configurazioni dei filtri di sicurezza.

Devi prima creare i modelli e poi utilizzarli con il metodo generateContent di Gemini. Per saperne di più sui modelli, vedi Crea e gestisci i modelli Model Armor.

Dopo aver configurato il modello Model Armor, trasmetti l'ID modello come parametro quando effettui una chiamata all'API Gemini utilizzando il metodo generateContent. Gemini Enterprise Agent Platform indirizzerà la richiesta a Model Armor per l'elaborazione.

Il seguente esempio di codice mostra la richiesta al metodo 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": ""
            }
        ]
    }
]
, "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"
    }
}'

Sostituisci quanto segue:

  • PROJECT_ID: l' Google Cloud ID progetto.
  • LOCATION: la Google Cloud località dell'endpoint Gemini. Le località supportate sono us-central1, us-east4, us-west1 e europe-west4.
  • TEMPLATE_ID: l'ID modello Model Armor.

Il seguente esempio di codice mostra la risposta del metodo 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"
}

Precedenza della configurazione

Quando utilizzi Model Armor con Gemini Enterprise Agent Platform, è possibile che le configurazioni di sicurezza siano definite a più livelli. In questi casi, Model Armor e Gemini Enterprise Agent Platform seguono un ordine di precedenza specifico:

  1. Modelli Model Armor: qualsiasi configurazione fornita esplicitamente all'interno della configurazione definita nella richiesta API ha la precedenza più alta. Queste impostazioni sostituiscono qualsiasi altra configurazione in conflitto per quella richiesta specifica.

  2. Impostazioni di base di Model Armor: se nella richiesta API non viene fornita alcuna configurazione di override, vengono applicate le impostazioni di base di Model Armor.

  3. Filtri di sicurezza di Gemini Enterprise Agent Platform: i filtri di sicurezza predefiniti integrati in Gemini Enterprise Agent Platform hanno la precedenza più bassa. Vengono applicati solo se non sono definiti modelli Model Armor o impostazioni di base specifici.

Questo approccio gerarchico fornisce una combinazione di standard minimi ampi a livello di organizzazione (utilizzando le impostazioni di base) e controllo per richiesta (utilizzando i modelli), sfruttando al contempo le funzionalità di sicurezza intrinseche di Gemini Enterprise Agent Platform come base.

Considerazioni

Tieni presente quanto segue quando integri Model Armor con Gemini Enterprise Agent Platform:

  • La redazione di Sensitive Data Protection per il modello di anonimizzazione non è supportata.
  • La sanificazione di prompt e risposte contenenti documenti non è supportata.

  • Gemini Enterprise Agent Platform salta il passaggio di sanificazione di Model Armor e continua a elaborare la richiesta nelle seguenti condizioni:

    • Model Armor non è disponibile in una regione in cui è presente Gemini Enterprise Agent Platform.
    • Model Armor non è raggiungibile temporaneamente.
    • Si verifica un errore in Model Armor.

    In tutti questi casi, occasionalmente è possibile che vengano esposti prompt o risposte non controllati perché la richiesta continua senza la sanificazione di prompt e risposte.

    Sebbene l'integrazione sia progettata per mantenere il servizio in esecuzione anche in caso di errore di connessione, la modalità INSPECT_AND_BLOCK mostra comunque errori di configurazione come problemi di autorizzazione o quota.