Abilitare Model Armor in Gemini Enterprise

Questo documento descrive come abilitare Model Armor per Gemini Enterprise. Model Armor è un Google Cloud servizio che migliora la sicurezza delle tue applicazioni AI schermando in modo proattivo i prompt e le risposte forniti dall'assistente Gemini Enterprise. In questo modo, puoi proteggerti da vari rischi e garantire pratiche di AI responsabile. Model Armor è supportato in tutte le edizioni di Gemini Enterprise senza costi aggiuntivi.

Model Armor non rimuove né modifica 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 filtri di Sensitive Data Protection (SDP).

Nota: l'abilitazione 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 modello. Per saperne di più, consulta Definire 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 ispeziona, Gemini Enterprise non blocca le richieste o le risposte.

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

Modalità	Descrizione
Consenti interazioni utente	In questa modalità, Gemini Enterprise consente il passaggio di richieste e risposte senza screening proattivo quando il servizio di screening di Model Armor non è disponibile, garantendo una comunicazione continua con l'utente finale. Tuttavia, questa operazione può occasionalmente esporre messaggi non schermati o fornire risposte a query non schermate.
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 di avere i ruoli richiesti assegnati a te e al account di servizio Gemini Enterprise:

  • Per abilitare Model Armor in Gemini Enterprise, devi disporre del ruolo Amministratore di Discovery Engine (roles/discoveryengine.admin).

  • Per creare i template Model Armor, devi disporre del ruolo Amministratore di Model Armor (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 Concedere o revocare più ruoli IAM utilizzando la Google Cloud console.

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

Creare un template Model Armor

Puoi creare e utilizzare lo stesso template Model Armor per i prompt e le risposte dell'assistente oppure puoi creare due template Model Armor separati. Per saperne di più, consulta Creare un template Model Armor.

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

• Seleziona Multi-regione nel campo Regioni. La tabella seguente mostra come mappare le regioni dei template Model Armor alle regioni delle app Gemini Enterprise:

  Nota: dopo aver creato un template Model Armor e un'app Gemini Enterprise, le regioni non possono essere modificate.

  Multi-regione dell'app Gemini Enterprise	Multi-regione di Model Armor
  Globale	Stati Uniti (più regioni negli Stati Uniti) UE (più regioni nell'Unione Europea)
  Stati Uniti (più regioni negli Stati Uniti)	Stati Uniti (più regioni negli Stati Uniti)
  UE (più regioni nell'Unione Europea)	UE (più regioni nell'Unione Europea)

• Google non consiglia 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 log che passano attraverso il template 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 Instradare i log verso destinazioni supportate.

  • Puoi configurare gli audit log dell'accesso ai dati per analizzare e generare report sui verdetti di screening di richieste e risposte generati da Model Armor. Per saperne di più, consulta Configurare gli audit log.

Configurare l'app Gemini Enterprise con i template Model Armor

I passaggi seguenti descrivono come aggiungere i template Model Armor all'app Gemini Enterprise.

Console

1. Nella Google Cloud console, 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 Visualizzare un template Model Armor e copia il valore Nome risorsa.

6. Se vuoi bloccare le interazioni utente in caso di errori di elaborazione di Model Armor, fai clic sul pulsante di attivazione/disattivazione Consenti le interazioni utente in caso di errore di elaborazione di Model Armor per disattivarlo. Per saperne di più, consulta le due modalità supportate da Gemini Enterprise quando Model Armor non è disponibile.

7. Fai clic su Salva e pubblica.

REST

Per aggiungere i template Model Armor all'app Gemini Enterprise, esegui questo comando :

Termine chiave: in Gemini Enterprise, il termine app può essere utilizzato in modo intercambiabile con il termine motore nel contesto delle API. Un motore 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 multi-regione 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 multi-regione del datastore: global, us o eu
• APP_ID: l'ID dell'app che vuoi configurare.
• QUERY_PROMPT_TEMPLATE: il Nome risorsa dei template Model Armor che hai creato.
  Per ottenere il Nome risorsa, segui i passaggi descritti nella documentazione Visualizzare un template Model Armore copia il valore Nome risorsa.
• RESPONSE_PROMPT_TEMPLATE: il Nome risorsa dei template Model Armor che hai creato.
• FAIL_MODE: la modalità di funzionamento quando Model Armor non è disponibile: FAIL_CLOSED o FAIL_OPEN.
  Se FAIL_MODE non è definito, la modalità predefinita è FAIL_CLOSE, 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"
    }
  }
}

Verificare se il template Model Armor è abilitato

Dopo aver configurato il template Model Armor, verifica se l'app Gemini Enterprise esegue in modo proattivo lo screening e blocca i prompt e le risposte dell'assistente Gemini Enterprise, in base ai livelli di attendibilità impostati nei filtri Model Armor.

Quando il template Model Armor è configurato per Ispeziona e blocca le richieste che violano le norme, viene visualizzato il seguente messaggio di violazione delle norme:

Console

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

Messaggio di violazione delle norme di Model Armor

REST

Una risposta JSON che include quanto segue:

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

Rimuovere i template Model Armor da un'app Gemini Enterprise

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

Console

Per rimuovere i template Model Armor dall'app Gemini Enterprise:

1. Nella Google Cloud console, 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 per disattivarlo.

5. Fai clic su Salva e pubblica.

REST

Per rimuovere i template Model Armor dall'app Gemini Enterprise, esegui questo comando:

Termine chiave: in Gemini Enterprise, il termine app può essere utilizzato in modo intercambiabile con il termine motore nel contesto delle API. Un motore 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 Google Cloud progetto.
• ENDPOINT_LOCATION: la multi-regione 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 multi-regione 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": {}
  }
}

Configurare gli audit log

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

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

Abilitare gli audit log di accesso ai dati

Per abilitare gli audit log dell'accesso ai dati:

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

2. Seleziona API Model Armor.

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

4. Fai clic su Salva.

Esaminare gli audit log dell'accesso ai dati

Per esaminare gli audit log dell'accesso ai dati:

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

2. Cerca i seguenti nomi di metodi nei log:

   • methodName: "google.cloud.modelarmor.v1.ModelArmor.SanitizeUserPrompt" per visualizzare le richieste degli utenti sottoposte a screening.

   • google.cloud.modelarmor.v1.ModelArmor.SanitizeModelResponse per visualizzare le risposte sottoposte a screening.

Considerazioni sull'utilizzo di Model Armor

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

Token	I limiti dei token per le app Gemini Enterprise che utilizzano Model Armor sono determinati dai filtri specifici configurati in Model Armor. Per informazioni dettagliate su questi limiti, consulta i limiti dei token applicabili nella documentazione di 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 dalla modalità fail-open o fail-closed utilizzata.
Conformità	Sia Gemini Enterprise sia 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à per entrambi i prodotti per assicurarsi che soddisfino i requisiti normativi.
Screening dei documenti	Se un template Model Armor è configurato per eseguire lo screening delle richieste degli utenti, vengono sottoposti a screening anche i documenti inclusi nella richiesta. Lo screening viene eseguito quando aggiungi un documento alla richiesta. Se un documento viola le norme nel template configurato, viene eliminato e non viene incluso nella richiesta. Per l'elenco dei tipi di documenti supportati, consulta Screening dei documenti.