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 filtrando prompt e risposte. Se integrato con Gemini Enterprise Agent Platform, Model Armor intercetta i prompt prima che raggiungano i modelli Gemini e intercetta le risposte prima che la tua 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, 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 attivare 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 presenti le seguenti limitazioni durante l'integrazione di Model Armor con Gemini Enterprise Agent Platform:

  • Quando Model Armor utilizza un modello Sensitive Data Protection per analizzare prompt o risposte, controlla se i contenuti corrispondono ai criteri di filtro definiti nel modello. Se trova una corrispondenza, Model Armor segnala che i contenuti hanno attivato il filtro Sensitive Data Protection. Sebbene Sensitive Data Protection rimuova l'identificazione dei dati in base alla configurazione del modello, Model Armor non trasmette i dati deidentificati, ad esempio contenuti mascherati, oscurati o sottoposti ad hashing, 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 ulteriormente elaborati.
  • La sanificazione di prompt e risposte che contengono documenti o caricamenti di file (come i PDF) non è supportata in questa integrazione. Per esaminare i documenti, chiama direttamente l'API REST Model Armor.
  • Se Gemini Enterprise Agent Platform indirizza una richiesta a una regione in cui non esiste il modello Model Armor specificato, la richiesta non va a buon fine e viene visualizzato un errore Template not found.

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

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

    Tutte queste istanze possono occasionalmente esporre prompt o risposte non esaminati perché la richiesta continua senza la sanificazione di prompt e risposte.

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

Prima di iniziare

Configurare il modo in cui Model Armor contribuisce a proteggere Gemini Enterprise Agent Platform

Puoi configurare la modalità di protezione di Model Armor di Gemini Enterprise Agent Platform 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 chiamata API generateContent 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 il modo in cui Model Armor controlla prompt e risposte e definire le configurazioni del filtro di sicurezza. Devi prima creare i modelli e poi utilizzarli con il metodo generateContent di Gemini. Per saperne di più sui modelli, consulta 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 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'ID progetto Google Cloud .
  • 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"
}

Definisci 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.

L'esempio seguente 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 la sezione Configura impostazioni di base per scoprire come configurare le impostazioni di base.

Per attivare 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 console Google Cloud .

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

Questo comando attiva la modalità di applicazione forzata INSPECT_ONLY per impostazione predefinita. Per impostare la modalità su INSPECT_AND_BLOCK, esegui questo 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 questo 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 questo 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 attivare la sanificazione di Gemini Enterprise Agent Platform, Model Armor sanifica tutte le chiamate API generateContent agli endpoint Gemini del progetto utilizzando le impostazioni del filtro 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: il tuo ID progetto Google Cloud .
  • 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"
}

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 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 inline 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 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 modelli o impostazioni di base di Model Armor specifici.

Questo approccio gerarchico offre 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 di Model Armor e delle funzionalità di sicurezza di Gemini Enterprise Agent Platform dipende da come fornisci la configurazione.

Modello configurato? Filtri di sicurezza di Gemini Enterprise Agent Platform configurati? Impostazioni di base configurate? Comportamento
Sì Sì Qualsiasi Ricevi 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 Le esecuzioni di Model Armor vengono eseguite utilizzando i modelli specificati in modelArmorConfig. I filtri di sicurezza di Gemini Enterprise Agent Platform vengono ignorati. I modelli di richiesta ignorano le impostazioni di base.
No Sì Sì Entrambi in esecuzione. Model Armor esegue la scansione utilizzando il criterio di impostazione di base e Gemini Enterprise Agent Platform valuta i suoi filtri di sicurezza. Viene applicato il risultato più restrittivo.
No No Sì Model Armor viene eseguito utilizzando il criterio di impostazione del piano attivo.
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 del modello di base.