Abilitare Model Armor in Gemini Enterprise

Questo documento descrive come attivare Model Armor per Gemini Enterprise. Model Armor è un servizio Google Cloud che migliora la sicurezza delle tue applicazioni di AI analizzando in modo proattivo i prompt e le risposte forniti dall'assistente Gemini Enterprise. Anche i dati provenienti dai datastore pronti all'uso di Gemini Enterprise (inclusi quelli provenienti da origini dati di Google e origini dati di terze parti) vengono sottoposti a screening utilizzando lo stesso template di Model Armor configurato per i prompt degli utenti. La selezione di questi contenuti aiuta a proteggere da vari rischi e a garantire pratiche di AI responsabile.

Model Armor è supportato su tutte le versioni di Gemini Enterprise senza costi aggiuntivi.

Model Armor non rimuove né altera le informazioni che consentono l'identificazione personale (PII) né maschera i dati sensibili. Tuttavia, Gemini Enterprise blocca qualsiasi risposta dell'assistente Gemini Enterprise che attiva i rilevatori di Sensitive Data Protection.

Nota: l'attivazione di Model Armor in Gemini Enterprise può aumentare la latenza.

La risposta di Model Armor a potenziali problemi nelle query degli utenti o nelle risposte dell'assistente Gemini Enterprise è regolata dal tipo di applicazione del template. Per saperne di più, consulta Definisci il tipo di applicazione.

• Se il tipo di applicazione è Ispeziona e blocca, Gemini Enterprise blocca la richiesta e visualizza un messaggio di errore. Questo è il tipo di applicazione predefinito quando crei un template Model Armor utilizzando la console.

• Se il tipo di applicazione è Solo ispezione, Gemini Enterprise non blocca le richieste o le risposte.

Quando il servizio di screening di Model Armor non è disponibile, puoi configurare Gemini Enterprise in modo che si comporti in uno dei seguenti modi:

Modalità	Descrizione
Consenti interazioni utente	In questa modalità, Gemini Enterprise consente il passaggio di richieste e risposte senza un controllo proattivo quando il servizio di controllo di Model Armor non è disponibile, garantendo una comunicazione continua con l'utente finale. Tuttavia, questo può occasionalmente esporre messaggi non filtrati o fornire risposte a query non filtrate.
Blocca tutte le interazioni utente	In questa modalità, quando il servizio di screening di Model Armor non è disponibile, Gemini Enterprise blocca tutte le richieste e le risposte, incluse quelle legittime.

Prima di iniziare

• Assicurati che i ruoli richiesti siano assegnati a te e al service account:

  • Per attivare Model Armor in Gemini Enterprise, devi disporre del ruolo Gemini Enterprise Admin (roles/discoveryengine.agentspaceAdmin).

  • Per creare i template Model Armor, devi disporre del ruolo Model Armor Admin (roles/modelarmor.admin).

  • Per chiamare le API Model Armor, devi disporre del ruolo Utente Model Armor (roles/modelarmor.user).

  Nota: per concedere più ruoli IAM a un account di servizio, consulta Concedi o revoca più ruoli IAM utilizzando la console Google Cloud .
  • Se il tuo template Model Armor si trova in un progetto diverso da quello della tua app Gemini Enterprise, il progetto del template deve concedere il ruolo Utente Model Armor (roles/modelarmor.user) al service account dell'app Gemini Enterprise. L'ID account di servizio è [e-mail]., dove PROJECT_NUMBER è il numero di progetto della tua app Gemini Enterprise.

• Assicurati di aver creato un'app Gemini Enterprise. Per crearne una, consulta Crea un'app.

Crea un template Model Armor

Ti consigliamo di configurare due template Model Armor separati: uno per i prompt degli utenti e uno per le risposte. I prompt e le risposte degli utenti hanno profili di rischio e obiettivi diversi:

• Modello per i prompt degli utenti: si concentra sulla prevenzione di input dannosi, prompt injection, tentativi di jailbreak e invio o caricamento di dati sensibili. Questo modello analizza anche i dati provenienti dai connettori pronti all'uso di Gemini Enterprise, come Jira e i connettori federati di Microsoft 365 per SharePoint, OneDrive, Teams e Outlook. Anche se i contenuti dannosi sono un problema anche per gli input degli utenti, puoi disattivare i filtri di AI responsabile sul template di prompt dell'utente perché Gemini include controlli di sicurezza integrati per i prompt degli utenti.
• Modello per gli output delle risposte: si concentra sulla prevenzione della restituzione o della fuga di dati sensibili, della generazione di contenuti dannosi o non in linea con il brand o della restituzione di URL dannosi.

Per saperne di più sulla creazione di template, consulta Crea un template Model Armor.

Considerazioni sulla configurazione

Quando crei un template di Model Armor per le app Gemini Enterprise, tieni presente queste configurazioni:

• Puoi creare i template di Model Armor centralmente in un progetto e riutilizzarli in progetti diversi. Se utilizzi un template tra progetti, assicurati che le autorizzazioni tra progetti siano configurate come descritto in Prima di iniziare.

• Seleziona Multiregione nel campo Regioni. La tabella seguente mostra come mappare le regioni dei template di Model Armor alle regioni dell'app Gemini Enterprise:

  Nota: Dopo la creazione di un modello Armor o di un'app Gemini Enterprise, le regioni non possono essere modificate.

  App Gemini Enterprise multiregionale	Model Armor multiregionale
  Globale	US (più regioni negli Stati Uniti) EU (più regioni nell'Unione Europea)
  US (più regioni negli Stati Uniti)	US (più regioni negli Stati Uniti)
  EU (più regioni nell'Unione Europea)	EU (più regioni nell'Unione Europea)

• Google sconsiglia di configurare Cloud Logging nel template Model Armor per le app Gemini Enterprise. Questa configurazione può esporre dati sensibili agli utenti con il ruolo IAM Visualizzatore log privati (roles/logging.privateLogViewer). In alternativa, valuta le seguenti opzioni:

  • Se devi registrare i dati che passano attraverso il template di Model Armor, puoi reindirizzare i log a uno spazio di archiviazione sicuro come BigQuery, che offre controlli di accesso più rigorosi. Per saperne di più, consulta Instrada i log verso destinazioni supportate.

  • Puoi configurare i log di controllo dell'accesso ai dati per analizzare e generare report sugli esiti del controllo delle richieste e delle risposte generati da Model Armor. Per saperne di più, consulta Configura gli audit log.

• Evita di attivare il filtro di rilevamento di prompt injection e jailbreak per le risposte. Gli attacchi di prompt injection e jailbreaking sono più comunemente utilizzati nei prompt degli utenti. L'attivazione di questo filtro sulle risposte può aumentare i falsi positivi e aggiungere una latenza non necessaria.

Configura l'app Gemini Enterprise con i template di Model Armor

I passaggi seguenti descrivono come aggiungere i template di Model Armor alla tua app Gemini Enterprise.

Console

1. Nella console Google Cloud , vai alla pagina Gemini Enterprise.

   Gemini Enterprise

2. Fai clic sul nome dell'app che vuoi configurare.

3. Fai clic su Configurazioni > Assistente.

4. Per attivare Model Armor, fai clic su Abilita Model Armor.

5. Per Template Model Armor per i prompt dell'utente e Template Model Armor per gli output di risposta, inserisci il Nome risorsa dei template Model Armor che hai creato.

   Nota: per ottenere il Nome risorsa, segui i passaggi descritti nella documentazione Visualizza un template Model Armor e copia il valore Nome risorsa. Puoi utilizzare i template di Model Armor creati nello stesso progetto dell'app Gemini Enterprise o utilizzare i template di Model Armor di un progetto diverso. Se utilizzi un template di un altro progetto, assicurati che le autorizzazioni tra progetti siano configurate come descritto in Prima di iniziare.

6. Se vuoi bloccare le interazioni utente in caso di errori di elaborazione di Model Armor, disattiva l'opzione Consenti le interazioni utente in caso di errore di elaborazione di Model Armor. Per saperne di più, consulta le due modalità supportate da Gemini Enterprise quando Model Armor non è disponibile.

7. Fai clic su Save and publish (Salva e pubblica).

REST

Per aggiungere i template di Model Armor alla tua app Gemini Enterprise, esegui questo comando :

Termine chiave: in Gemini Enterprise, il termine app può essere utilizzato in modo intercambiabile con il termine engine nel contesto delle API. Un motore di Gemini Enterprise è un motore di ricerca generico in cui il campo app_type è impostato su APP_TYPE_INTRANET.

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant?update_mask=customerPolicy" \
-d '{
  "customerPolicy": {
    "modelArmorConfig": {
      "userPromptTemplate": "QUERY_PROMPT_TEMPLATE",
      "responseTemplate": "RESPONSE_PROMPT_TEMPLATE",
      "failureMode": "FAIL_MODE"
    }
  }
}'

Sostituisci quanto segue:

• PROJECT_ID: l'ID progetto.
• ENDPOINT_LOCATION: la località multiregionale per la richiesta API. Specifica uno dei seguenti valori:
  • us per la multi-regione Stati Uniti
  • eu per la multi-regione UE
  • global per la località globale
  Per saperne di più, consulta Specifica una multi-regione per il datastore.
• LOCATION: la località multiregionale del datastore: global, us o eu
• APP_ID: l'ID dell'app che vuoi configurare.

• QUERY_PROMPT_TEMPLATE: il nome della risorsa del template Model Armor che esamina i prompt e i dati degli utenti provenienti dai connettori pronti all'uso.
  Per ottenere il nome della risorsa, segui i passaggi descritti nella documentazione Visualizza un modello Model Armor e copia il valore Nome risorsa.

  Nota: puoi utilizzare i template di Model Armor creati nello stesso progetto dell'app Gemini Enterprise o utilizzare i template di Model Armor di un progetto diverso. Se utilizzi un template di un altro progetto, assicurati che le autorizzazioni tra progetti siano configurate come descritto in Prima di iniziare.

• RESPONSE_PROMPT_TEMPLATE: il nome della risorsa dei template Model Armor che hai creato. Puoi utilizzare i template di Model Armor creati nello stesso progetto o in un progetto diverso.

• FAIL_MODE: la modalità operativa quando Model Armor non è disponibile: FAIL_CLOSED o FAIL_OPEN.
  Se FAIL_MODE non è definito, FAIL_CLOSED è la modalità predefinita in cui tutte le interazioni con l'assistente Gemini Enterprise vengono bloccate in caso di errori di elaborazione di Model Armor. Per saperne di più, consulta le due modalità supportate da Gemini Enterprise quando Model Armor non è disponibile.

Esempio di comando e risultato

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: my-project-123" \
"https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant?update_mask=customerPolicy" \
-d '{
  "customerPolicy": {
    "modelArmorConfig": {
      "userPromptTemplate": "projects/my-project-123/locations/global/templates/123456789",
      "responseTemplate": "projects/my-project-123/locations/global/templates/123456789",
      "failureMode": "FAIL_OPEN"
    }
  }
}'

{
  "name": "projects/my-project-123/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant",
  "displayName": "Default Assistant",
  "webGroundingType": "WEB_GROUNDING_TYPE_GOOGLE_SEARCH",
  "googleSearchGroundingEnabled": true,
  "customerPolicy": {
    "modelArmorConfig": {
      "userPromptTemplate": "projects/my-project-123/locations/global/templates/123456789",
      "responseTemplate": "projects/my-project-123/locations/global/templates/123456789",
      "failureMode": "FAIL_OPEN"
    }
  }
}

Verifica se il template Model Armor è abilitato

Dopo aver configurato il template di Model Armor, verifica se l'app Gemini Enterprise esamina e blocca in modo proattivo i prompt e le risposte degli utenti dell'assistente Gemini Enterprise, in base ai livelli di confidenza impostati nei filtri di Model Armor.

Quando il template di Model Armor è configurato per ispezionare e bloccare le richieste che violano la policy, viene visualizzato il seguente messaggio di violazione della policy:

Console

Ad esempio, viene visualizzato il messaggio di violazione delle policy:

Messaggio di violazione delle policy di Model Armor

REST

Una risposta JSON che include quanto segue:

answer.state = SKIPPED
answer.assist_skipped_reasons: [CUSTOMER_POLICY_VIOLATION]

Rimuovi i template Model Armor da un'app Gemini Enterprise

Per rimuovere i template di Model Armor da un'app Gemini Enterprise, utilizza la console Google Cloud o l'API REST.

Console

Per rimuovere i template di Model Armor dalla tua app Gemini Enterprise, segui questi passaggi:

1. Nella console Google Cloud , vai alla pagina Gemini Enterprise.

   Gemini Enterprise

2. Fai clic sul nome dell'app che vuoi configurare.

3. Fai clic su Configurazioni > Assistente.

4. Per disattivare Model Armor, fai clic sul pulsante di attivazione/disattivazione Abilita Model Armor in modo che sia impostato su Off.

5. Fai clic su Save and publish (Salva e pubblica).

REST

Per rimuovere i template di Model Armor dalla tua app Gemini Enterprise, esegui questo comando:

Termine chiave: in Gemini Enterprise, il termine app può essere utilizzato in modo intercambiabile con il termine engine nel contesto delle API. Un motore di Gemini Enterprise è un motore di ricerca generico in cui il campo app_type è impostato su APP_TYPE_INTRANET.

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant?update_mask=customerPolicy" \
-d '{
  "customerPolicy": {
    "modelArmorConfig": {
    }
  }
}'

Sostituisci quanto segue:

• PROJECT_ID: l'ID progetto.
• PROJECT_NUMBER: il numero del tuo progetto Google Cloud .
• ENDPOINT_LOCATION: la località multiregionale per la richiesta API. Specifica uno dei seguenti valori:
  • us per la multi-regione Stati Uniti
  • eu per la multi-regione UE
  • global per la località globale
  Per saperne di più, consulta Specifica una multi-regione per il datastore.
• LOCATION: la località multiregionale del datastore: global, us o eu.
• APP_ID: l'ID dell'app che vuoi configurare.

Esempio di comando e risultato

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: my-project-123" \
"https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant?update_mask=customerPolicy" \
-d '{
  "customerPolicy": {
    "modelArmorConfig": {
    }
  }
}'

{
  "name": "projects/my-project-123/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant",
  "displayName": "Default Assistant",
  "webGroundingType": "WEB_GROUNDING_TYPE_GOOGLE_SEARCH",
  "googleSearchGroundingEnabled": true,
  "customerPolicy": {
    "modelArmorConfig": {}
  },
  "generationConfig": {
    "systemInstruction": {}
  }
}

Configura audit log

Model Armor può scrivere log di controllo dell'accesso ai dati, che puoi utilizzare per analizzare e generare report sui verdetti di screening delle richieste e delle risposte generati da Model Armor. Questi log non contengono le query degli utenti o le risposte dell'assistente Gemini Enterprise, quindi sono sicuri per i report e le analisi. Per saperne di più, consulta Audit logging per Model Armor.

Per accedere a questi log, devi disporre del ruolo IAM Visualizzatore log privati (roles/logging.privateLogViewer).

Abilita gli audit log di accesso ai dati

Per abilitare i log di controllo dell'accesso ai dati, segui questi passaggi:

1. Nella console Google Cloud , vai a IAM e amministrazione > Audit log.

2. Seleziona l'API Model Armor.

3. Nella sezione Tipo di autorizzazione, seleziona il tipo di autorizzazione Lettura dati.

4. Fai clic su Salva.

Esamina i log di controllo dell'accesso ai dati

Per esaminare i log di controllo dell'accesso ai dati, segui questi passaggi:

1. Nella console Google Cloud , vai a Esplora log.

2. Cerca nei log i seguenti nomi di metodi:

   • methodName: "google.cloud.modelarmor.v1.ModelArmor.SanitizeUserPrompt" per visualizzare le richieste degli utenti che sono state esaminate.

   • google.cloud.modelarmor.v1.ModelArmor.SanitizeModelResponse per visualizzare le risposte filtrate.

Considerazioni sull'utilizzo di Model Armor

Quando utilizzi Model Armor con Gemini Enterprise, tieni presente quanto segue:

Anonimizzazione e mascheramento	Quando Model Armor utilizza un template di Sensitive Data Protection per la scansione di prompt o risposte, verifica se i contenuti corrispondono ai criteri del rilevatore definiti nel template. Sebbene Sensitive Data Protection supporti l'anonimizzazione in base alla configurazione del template, Model Armor non restituisce dati anonimizzati o mascherati a Gemini Enterprise. Se i contenuti attivano rilevatori di Sensitive Data Protection e il tipo di applicazione è INSPECT_AND_BLOCK, Gemini Enterprise blocca la richiesta o la risposta anziché anonimizzarla.
Limiti e quote di token	Non esistono limiti di token quando utilizzi Model Armor con Gemini Enterprise. Tuttavia, il throughput totale delle valutazioni di Model Armor è comunque regolato indirettamente dalle quote di sistema di Gemini Enterprise e dai limiti di frequenza dell'API Model Armor.
Accordo sul livello del servizio	Gemini Enterprise fornisce un accordo sul livello del servizio. Quando Gemini Enterprise è configurato per utilizzare Model Armor, le query bloccate non vengono conteggiate come violazioni dello SLA, indipendentemente dal fatto che venga utilizzata la modalità fail-open o fail-closed.
Conformità	Sia Gemini Enterprise che Model Armor offrono varie certificazioni di conformità. Se utilizzati insieme, le certificazioni di conformità effettive sono il sottoinsieme comune di entrambi i prodotti. Google consiglia di esaminare le certificazioni di conformità di entrambi i prodotti per assicurarti che soddisfino i tuoi requisiti normativi.
Controllo di documenti e immagini	Oltre ai prompt testuali, l'integrazione di Model Armor supporta documenti (come i PDF) e immagini. L'integrazione di Model Armor esamina i seguenti file solo quando li carichi nell'assistente Gemini Enterprise: Documenti (ad esempio PDF, CSV e file di testo). Immagini caricate direttamente. Immagini contenute in altri file e documenti che carichi direttamente. Se un file o un'immagine all'interno di un documento viola le policy configurate, l'intero file o documento viene ignorato ed escluso dalla richiesta. Per l'elenco dei tipi di documenti supportati, consulta Screening dei documenti.
Connettori pronti all'uso	I dati dei connettori pronti all'uso di Gemini Enterprise vengono sottoposti a screening utilizzando il template Model Armor configurato per i prompt dell'utente. Sono inclusi connettori come Jira e i connettori federati di Microsoft 365 per SharePoint, OneDrive, Teams e Outlook.
Interazioni e agenti sottoposti a screening	Se un template di Model Armor è configurato per esaminare le richieste degli utenti, vengono esaminate solo le interazioni con i seguenti agenti in Gemini Enterprise: L'assistente Gemini Enterprise Agenti creati dai dipendenti, creati nell'app Gemini Enterprise utilizzando Workflow Builder. Agenti creati da Google Le interazioni con gli agenti personalizzati della tua organizzazione, come ADK, A2A e Dialogflow, non vengono esaminate.

Passaggi successivi

• Correlare i log di Model Armor con i log di Gemini Enterprise