Integrare con la piattaforma agentica Gemini Enterprise

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

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 ottenere visibilità sui 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 all'utente Model Armor l'autorizzazione dell'utente per il account di servizio della piattaforma di agenti Gemini Enterprise.

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: il tuo ID progetto Google Cloud .
  • PROJECT_NUMBER: il tuo Google Cloud numero di progetto.

Configura impostazioni di base

Utilizzi 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 Configurare 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

Questo comando attiva la modalità di applicazione INSPECT_ONLY per impostazione predefinita. Per impostare la modalità su INSPECT_AND_BLOCK, esegui il comando seguente:

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

Per rimuovere la piattaforma di agenti Gemini Enterprise 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 '{
"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. 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 PROJECT_ID con l'ID del progetto che contiene le impostazioni di base.

Configurare i modelli Model Armor

Model Armor può essere integrato anche con Gemini Enterprise Agent Platform utilizzando i modelli Model Armor. I modelli ti consentono di configurare il modo in cui Model Armor filtra prompt e risposte 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.5-flash:generateContent" -d '{
"contents": [
    {
        "role": "user",
        "parts": [
            {
                "text": "PROMPT"
            }
        ]
    }
]
, "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 us-central1, us-east4, us-west1 e europe-west4.
  • PROMPT: il prompt di testo.
  • 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.5-flash",
  "createTime": "2025-03-26T13:14:36.961184Z",
  "responseId": "vP3jZ6DVOqLKnvgPqZL-8Ao"
}

Precedenza della configurazione

Quando utilizzi Model Armor con Gemini Enterprise Agent Platform, è possibile 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 all'interno della configurazione definita nella richiesta API ha la massima priorità. 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 applicate solo se non sono definiti un modello Model Armor specifico o impostazioni di base.

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 di riferimento.

Considerazioni

Tieni in considerazione 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 che contengono documenti non è supportata.

  • La piattaforma agentica Gemini Enterprise 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.

    In tutti questi casi, occasionalmente possono essere esposti prompt o risposte non filtrati perché la richiesta continua senza la sanificazione di prompt e risposte.

    Sebbene l'integrazione sia progettata per mantenere il servizio in esecuzione anche se la connessione non va a buon fine, la modalità INSPECT_AND_BLOCK mostra comunque errori di configurazione come problemi di autorizzazione o quota.