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 di AI analizzando in modo proattivo i prompt e le risposte forniti dall'assistente Gemini Enterprise. Questo aiuta a proteggere da vari rischi e garantisce pratiche di AI responsabile. Model Armor è supportato in tutte le versioni 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 rilevatori di Sensitive Data Protection.

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 forzata del modello. Per saperne di più, consulta Definire il tipo di applicazione forzata.

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

• Se il tipo di applicazione forzata è 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 sottoposti a screening o fornire risposte a query non sottoposte a screening
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 service account:

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

  • Per creare i modelli Model Armor, devi disporre del ruolo Amministratore di Model Armor (roles/modelarmor.admin).

  • Per chiamare le API Model Armor, devi disporre del ruolo Utente di 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.
  • Se il modello Model Armor si trova in un progetto diverso dall' app Gemini Enterprise, il progetto del modello deve concedere il ruolo Utente di Model Armor (roles/modelarmor.user) al service account dell'app Gemini Enterprise. L'ID del 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 Creare un'app.

Creare un modello Model Armor

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

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

• Puoi creare modelli Model Armor a livello centrale in un progetto e riutilizzarli in progetti diversi. Se utilizzi un modello tra progetti, assicurati che le autorizzazioni tra progetti siano configurate come descritto in Prima di iniziare.

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

  Nota: dopo aver creato un modello Model Armor o 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 la registrazione cloud nel modello 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 modello 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 risultati dello 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 modelli Model Armor

I passaggi seguenti descrivono come aggiungere i modelli 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 Modello Model Armor per i prompt dell'utente e Modelli Model Armor per gli output di risposta, inserisci il Nome risorsa dei modelli Model Armor che hai creato.

   Nota: per ottenere il Nome risorsa, segui i passaggi descritti nella documentazione Visualizzare un modello Model Armor e copia il valore Nome risorsa. Puoi utilizzare i modelli Model Armor creati nello stesso progetto dell'app Gemini Enterprise o utilizzare i modelli Model Armor di un altro progetto. Se utilizzi un modello 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, fai clic sul pulsante di attivazione/disattivazione Consenti le interazioni utente in caso di errore di elaborazione di Model Armor in modo che sia impostato su Off. 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 modelli 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 modelli Model Armor che hai creato.
  Per ottenere il Nome risorsa, segui i passaggi descritti nella documentazione Visualizzare un modello Model Armor e copia il valore Nome risorsa.

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

• RESPONSE_PROMPT_TEMPLATE: il Nome risorsa dei modelli Model Armor che hai creato. Puoi utilizzare i modelli Model Armor creati nello stesso progetto o in un progetto diverso.

• FAIL_MODE: la modalità di funzionamento 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"
    }
  }
}

Verificare se il modello Model Armor è abilitato

Dopo aver configurato il modello 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 modello 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 modelli Model Armor da un'app Gemini Enterprise

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

Console

Per rimuovere i modelli 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 in modo che sia impostato su Off.

5. Fai clic su Salva e pubblica.

REST

Per rimuovere i modelli 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 risultati dello 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 logging per Model Armor.

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

Abilitare gli audit log dell'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 l'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 utente 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:

Anonimizzazione e mascheramento	Quando Model Armor utilizza un modello Sensitive Data Protection per la scansione di prompt o risposte, Model Armor verifica se il contenuto corrisponde ai criteri del rilevatore definiti nel modello. Sebbene Sensitive Data Protection supporti l'anonimizzazione in base a la configurazione del modello, Model Armor non restituisce i dati anonimizzati o mascherati a Gemini Enterprise. Se il contenuto attiva uno dei rilevatori di Sensitive Data Protection e il tipo di applicazione forzata è INSPECT_AND_BLOCK, Gemini Enterprise blocca la richiesta o la risposta anziché anonimizzarla.
Limiti e quote dei token	Sebbene non esistano limiti diretti ai token quando utilizzi Model Armor con Gemini Enterprise, la velocità effettiva totale delle valutazioni di Model Armor è comunque regolata 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 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 di documenti e immagini	Oltre ai prompt di testo, l'integrazione di Model Armor supporta documenti (ad esempio PDF) e immagini. L'integrazione di Model Armor esegue lo screening dei seguenti file solo quando li carichi nell'assistente Gemini Enterprise: Documenti (ad esempio PDF, CSV e file di testo). Immagini che carichi direttamente. Immagini contenute in altri file e documenti che carichi direttamente. Se un file o un'immagine all'interno di un documento viola le norme configurate, l'intero file o documento viene eliminato ed escluso dalla richiesta. Per l'elenco dei tipi di documenti supportati, consulta Screening dei documenti.
Interazioni e agenti sottoposti a screening	Se un modello Model Armor è configurato per eseguire lo screening delle richieste utente, in Gemini Enterprise vengono sottoposte a screening solo le interazioni con i seguenti agenti: 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 sottoposte a screening.

Passaggi successivi

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