Integra Model Armor con Gemini Enterprise Agent Platform

Questo documento descrive come configurare Model Armor per proteggere i modelli Gemini su Gemini Enterprise Agent Platform controllando prompt e risposte. Quando è integrato con Gemini Enterprise Agent Platform, Model Armor intercetta i prompt prima che raggiungano i modelli Gemini e intercetta le risposte prima che l'applicazione le riceva. In base alla configurazione, Gemini Enterprise Agent Platform chiama il servizio Model Armor, che ispeziona o blocca il traffico che viola le policy definite, applicando misure di sicurezza come il rilevamento di prompt injection e jailbreak, i filtri di AI responsabile e Sensitive Data Protection. Puoi configurare questa integrazione utilizzando le impostazioni di base per la protezione a livello di progetto o utilizzando i modelli per la protezione per richiesta.

Model Armor fornisce protezione per 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 AI generativa o gli SDK Firebase AI Logic.

Limitazioni

Tieni presente le seguenti limitazioni quando integri Model Armor con Gemini Enterprise Agent Platform:

  • Quando Model Armor utilizza un modello Sensitive Data Protection per la scansione di prompt o risposte, verifica se il contenuto corrisponde ai criteri di filtro definiti nel modello. Se trova una corrispondenza, Model Armor segnala che il contenuto ha attivato il filtro Sensitive Data Protection. Sebbene Sensitive Data Protection de-identifichi i dati in base alla configurazione del modello, Model Armor non passa i dati de-identificati, come contenuti mascherati, oscurati o con hash, a Gemini Enterprise Agent Platform per un'ulteriore elaborazione. Se il tipo di applicazione è INSPECT_AND_BLOCK, Model Armor emette un verdetto di blocco per garantire che i dati sensibili non vengano elaborati ulteriormente.
  • La sanificazione di prompt e risposte contenenti documenti non è supportata.
  • Se Gemini Enterprise Agent Platform indirizza una richiesta a una regione in cui non esiste il modello Model Armor specificato, la richiesta non riesce e viene visualizzato l'errore Template not found.

  • 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, i prompt o le risposte non filtrati possono essere esposti occasionalmente perché la richiesta continua senza la sanificazione di prompt e risposte.

    Sebbene l'integrazione sia progettata per garantire un'elevata alta affidabilità durante gli errori di connessione, la modalità INSPECT_AND_BLOCK segnalerà comunque gli errori di configurazione, come problemi di autorizzazione o quota.

Prima di iniziare

  • Concedi il ruolo Utente Model Armor all'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'ID del tuo Google Cloud progetto.
    • PROJECT_NUMBER: il numero del tuo Google Cloud progetto.

  • Abilita l'API Model Armor.

  • Imposta l'override dell'endpoint API utilizzando gcloud CLI.

Configurare la protezione di Gemini Enterprise Agent Platform con Model Armor

Puoi configurare la protezione di Gemini Enterprise Agent Platform con Model Armor in due modi:

  • Utilizza i modelli per la protezione per richiesta: questo approccio fornisce un controllo granulare consentendoti di applicare un modello specifico a ogni generateContent chiamata API ai modelli Gemini su Gemini Enterprise Agent Platform.
  • Utilizza le impostazioni di base per la protezione a livello di progetto: questo approccio applica una protezione di base applicando le impostazioni di base a tutte le chiamate API generateContent ai modelli Gemini su Gemini Enterprise Agent Platform all'interno del tuo progetto.

Definisci il tipo di applicazione per determinare se le violazioni vengono solo ispezionate o anche bloccate.

Configurazione per richiesta utilizzando i modelli

I modelli consentono di configurare la modalità di controllo di prompt e risposte da parte di Model Armor e di definire 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, consulta Creare e gestire 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 indirizza la richiesta a Model Armor per l'elaborazione.

Per applicare modelli specifici a una singola chiamata generateContent, includi l'oggetto modelArmorConfig nella richiesta.

  • promptTemplateName: il nome della risorsa del modello Model Armor per sanificare il prompt.
  • responseTemplateName: il nome della risorsa del modello Model Armor per sanificare la risposta.

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": "[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"
        }
}'

Sostituisci quanto segue:

  • PROJECT_ID: l' Google Cloud ID progetto.
  • LOCATION: la Google Cloud posizione dell'endpoint Gemini. Le località supportate sono europe-west1, europe-west2, europe-west3, asia-southeast1 e asia-south1.
  • TEMPLATE_ID: l'ID del 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"
}

Definire il tipo di applicazione per i modelli

Per configurare la modalità di gestione dei rilevamenti da parte di Model Armor, imposta il tipo di applicazione.

Il seguente esempio mostra la configurazione del modello Model Armor con il tipo di applicazione 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"

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del progetto a cui appartiene il modello.
  • TEMPLATE_ID: l'ID del modello da creare.
  • LOCATION: la posizione del modello.

Configurazione a livello di progetto utilizzando le impostazioni di base

Le impostazioni di base definiscono una base minima di protezione che si applica a tutte le chiamate generateContent di Gemini Enterprise Agent Platform all'interno di un progetto, anche se il parametro modelArmorConfig viene omesso dalla richiesta API. Consulta Configurare le impostazioni di base per scoprire come configurarle.

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

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" : {"piAndJailbreakFilterSettings": { "filterEnforcement": "ENABLED"}}, "integratedServices": ["AI_PLATFORM"], "aiPlatformFloorSetting":{"inspectOnly":true, "enableCloudLogging":true}, "enableFloorSettingEnforcement":true}' \
  "https://modelarmor.googleapis.com/v1/projects/PROJECT_ID/locations/global/floorSetting"

Sostituisci PROJECT_ID con l'ID del progetto che contiene 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.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
}
}'

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del tuo Google Cloud progetto.
  • LOCATION: la Google Cloud posizione dell'endpoint Gemini. Per le località supportate, consulta 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.5-flash",
"createTime": "2025-03-26T13:14:36.961184Z",
"responseId": "vP3jZ6DVOqLKnvgPqZL-8Ao"
}

Definire 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 su INSPECT o INSPECT_AND_BLOCK. 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='{
  "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"

Sostituisci quanto segue:

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

Testare l'applicazione in linea con una chiamata API

Testa l'integrazione per chiamare il metodo generateContent dell'API Gemini Enterprise Agent Platform. Utilizza un prompt progettato per violare le impostazioni di base configurate.

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

Se l'integrazione funziona come previsto, l'API restituisce una risposta con il campo blockReason impostato su MODEL_ARMOR quando Model Armor identifica il prompt come una violazione.

Di seguito è riportato un esempio di risposta:

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

Regole di interazione e precedenza

Quando utilizzi Model Armor con Gemini Enterprise Agent Platform, puoi definire configurazioni di sicurezza 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 nella configurazione della 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. Si applicano solo se non definisci impostazioni di base o modelli Model Armor 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), pur utilizzando le funzionalità di sicurezza intrinseche di Gemini Enterprise Agent Platform come base.

Il comportamento delle funzionalità di sicurezza di Model Armor e Gemini Enterprise Agent Platform dipende dalla modalità di fornitura della configurazione.

Modello configurato? Filtri di sicurezza di Gemini Enterprise Agent Platform configurati? Impostazioni di base configurate? Comportamento
Sì Sì Qualsiasi Viene visualizzato un errore. Non puoi specificare sia la configurazione del modello sia i filtri di sicurezza di Gemini Enterprise Agent Platform nella stessa richiesta.
Sì No Qualsiasi Model Armor viene eseguito utilizzando i modelli specificati in modelArmorConfig. I filtri di sicurezza di Gemini Enterprise Agent Platform vengono ignorati. I modelli di richiesta sostituiscono le impostazioni di base.
No Sì Sì Entrambi vengono eseguiti. Model Armor esegue la scansione utilizzando la policy delle impostazioni di base e Gemini Enterprise Agent Platform valuta i relativi filtri di sicurezza. Viene applicato il risultato più restrittivo.
No No Sì Model Armor viene eseguito utilizzando la policy delle impostazioni di base attiva.
No Sì No Vengono valutati solo i filtri di sicurezza di Gemini Enterprise Agent Platform. Model Armor non viene chiamato.
No No No Non vengono applicati né Model Armor per richiesta né i filtri di sicurezza di Gemini Enterprise Agent Platform. Sono attivi solo i comportamenti di base del modello.