Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Configurazione logging

Questo documento descrive come configurare Model Armor per registrare le seguenti operazioni:

Operazioni che creano, aggiornano o eliminano un modello
Operazioni che sanificano un prompt dell'utente o una risposta del modello

Model Armor utilizza gli audit log per registrare le attività amministrative e di gestione delle risorse. Per saperne di più, consulta Audit logging di Model Armor.

Per informazioni sui prezzi dei log, consulta i prezzi di Cloud Logging. Potrebbero essere applicati anche costi di utilizzo di Model Armor in base al volume di dati elaborati. Per maggiori dettagli, consulta i prezzi di Model Armor Pricing .

Prima di iniziare

Prima di iniziare, completa le seguenti attività.

Ottenere le autorizzazioni richieste

Per ottenere le autorizzazioni necessarie per configurare il logging per Model Armor, chiedi all'amministratore di concederti il ruolo IAM Amministratore di Model Armor (roles/modelarmor.admin) sul modello Model Armor. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Abilita API

Prima di poter utilizzare Model Armor, devi abilitare l'API Model Armor.

Console

Abilita l'API Model Armor.
Ruoli richiesti per abilitare le API
Per abilitare le API, devi disporre del ruolo IAM Amministratore di Service Usage (roles/serviceusage.serviceUsageAdmin), che contiene l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.
Abilitare l'API
Seleziona il progetto in cui vuoi attivare Model Armor.

gcloud

Prima di iniziare, segui questi passaggi utilizzando Google Cloud CLI con l'API Model Armor:

Nella Google Cloud console, attiva Cloud Shell.

Attiva Cloud Shell

Nella parte inferiore della Google Cloud console viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già inclusa e installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.
Imposta l'override dell'endpoint API utilizzando gcloud CLI.

Impostare l'override dell'endpoint API utilizzando gcloud CLI

Questo passaggio è necessario solo se utilizzi gcloud CLI per abilitare l'API Model Armor. Devi impostare manualmente l'override dell'endpoint API per assicurarti che gcloud CLI indirizzi correttamente le richieste al servizio Model Armor.

Esegui il comando seguente per impostare l'endpoint API per il servizio Model Armor.

gcloud config set api_endpoint_overrides/modelarmor "https://modelarmor.LOCATION.rep.googleapis.com/"

Sostituisci LOCATION con la regione in cui vuoi utilizzare Model Armor.

Configurare la sanificazione del traffico

Per i server MCP e Google, configura la sanificazione del traffico tramite le impostazioni di base. Google Cloud Per saperne di più, consulta Configurare la protezione per i server Google Cloud MCP e Google.

Configurare il logging nei modelli

I modelli definiscono i filtri e le soglie per le diverse categorie di sicurezza. Quando crei o aggiorni un modello Model Armor, puoi specificare se Model Armor registra determinate operazioni. Utilizza i seguenti flag nei metadati del modello:

log_template_operations: un valore booleano che ti consente di registrare le operazioni di creazione, aggiornamento, lettura ed eliminazione dei modelli.
log_sanitize_operations: un valore booleano che ti consente di registrare l'intero contenuto dei prompt dell'utente e delle risposte del modello durante le operazioni di sanificazione.

Console

Nella Google Cloud console, vai alla pagina Model Armor.

Vai a Model Armor
Verifica di visualizzare il progetto per il quale hai attivato Model Armor.
Nella pagina Model Armor, fai clic su Crea modello. Per saperne di più sulla creazione di modelli, consulta Creare un modello Model Armor.
Nella sezione Configura logging, seleziona le operazioni per le quali vuoi configurare il logging.
Fai clic su Crea.

REST

  curl -X POST \
      -d '{ "filterConfig": {}, "templateMetadata": { "logTemplateOperations": true, "logSanitizeOperations": true } }' \
      -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.
LOCATION: la località del modello.
TEMPLATE_ID: l'ID del modello.

Python

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Python e installare l'SDK Python di Model Armor.

   request = modelarmor_v1.CreateTemplateRequest(
     parent="projects/PROJECT_ID/locations/LOCATION",
     template_id="TEMPLATE_ID",
     template={
        "name": "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
        "filter_config": {},
        "template_metadata": {
           "log_template_operations": True,
           "log_sanitize_operations": True
        }
     }
   )
   response = client.create_template(request=request)

Sostituisci quanto segue:

PROJECT_ID: l'ID del progetto a cui appartiene il modello.
LOCATION: la località del modello.
TEMPLATE_ID: l'ID del modello.

Configurare il logging nelle impostazioni di base

Quando applichi le impostazioni di base al traffico dei modelli Gemini in Gemini Enterprise Agent Platform e ai server MCP e Google all'interno del tuo progetto, le impostazioni di base definiscono i filtri di sicurezza per le operazioni di sanificazione. Google Cloud Quando aggiorni le impostazioni di base di Model Armor, puoi specificare se Model Armor registra le operazioni di sanificazione.

Puoi abilitare il logging delle operazioni di sanificazione per Agent Platform e per i server MCP e Google Cloud Google separatamente. Se abilitati, i log includono il prompt e la risposta (per Agent Platform) o le chiamate e le risposte degli strumenti (per i server MCP), i risultati della valutazione di Model Armor e i campi di metadati aggiuntivi.

Gli esempi seguenti mostrano come abilitare il logging delle operazioni di sanificazione sia per Agent Platform sia per i server MCP e Google. Google Cloud

Console

Nella Google Cloud console, vai alla pagina Model Armor.

Vai a Model Armor
Verifica di visualizzare il progetto per il quale hai attivato Model Armor.
Vai alla scheda Impostazioni di base.
Nella sezione Log, seleziona le caselle di controllo Vertex AI e MCP gestito da Google per abilitare il logging per ogni servizio.
Fai clic su Salva.

gcloud

Utilizza il flag --enable-vertex-ai-cloud-logging per abilitare il logging per Agent Platform e il --enable-google-mcp-server-cloud-logging flag per abilitare il logging per i server MCP e Google Google Cloud . Per disabilitare il logging, utilizza i flag --no-enable-vertex-ai-cloud-logging e --no-enable-google-mcp-server-cloud-logging.

Il seguente comando di esempio abilita il logging delle operazioni di sanificazione sia per Agent Platform sia per i server MCP e Google: Google Cloud

gcloud model-armor floorsettings update \
--full-uri='projects/PROJECT_ID/locations/global/floorSetting' \
--enable-vertex-ai-cloud-logging \
--enable-google-mcp-server-cloud-logging

Sostituisci PROJECT_ID con l'ID del tuo progetto.

REST

Per abilitare il logging, imposta aiPlatformFloorSetting.enableCloudLogging su true per Agent Platform e googleMcpServerFloorSetting.enableCloudLogging su true per i server MCP e Google nel metodo UpdateFloorSetting . Google Cloud

Il seguente comando di esempio abilita il logging delle operazioni di sanificazione sia per Agent Platform sia per i server MCP e Google Google Cloud :

curl -X PATCH \
 -d '{ "aiPlatformFloorSetting":{ "enableCloudLogging": true}, "googleMcpServerFloorSetting":{ "enableCloudLogging": true}}' \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://modelarmor.googleapis.com/v1/projects/PROJECT_ID/locations/global/floorSetting?updateMask=aiPlatformFloorSetting.enableCloudLogging,googleMcpServerFloorSetting.enableCloudLogging"

Sostituisci PROJECT_ID con l'ID del tuo progetto.

Python

Per eseguire questo codice, devi innanzitutto configurare un ambiente di sviluppo Python e installare l'SDK Python di Model Armor.

from google.cloud.modelarmor import v1 as modelarmor_v1
from google.protobuf import field_mask_pb2

# TODO: Initialize the ModelArmorClient, "client"
# client = modelarmor_v1.ModelArmorClient()

project_id = "PROJECT_ID"
location = "global"

floor_setting_name = f"projects/{project_id}/locations/{location}/floorSetting"

request = modelarmor_v1.UpdateFloorSettingRequest(
    floor_setting=modelarmor_v1.FloorSetting(
        name=floor_setting_name,
        ai_platform_floor_setting=modelarmor_v1.FloorSetting.AiPlatformFloorSetting(
            enable_cloud_logging=True
        ),
        google_mcp_server_floor_setting=modelarmor_v1.FloorSetting.GoogleMcpServerFloorSetting(
            enable_cloud_logging=True
        ),
    ),
    update_mask=field_mask_pb2.FieldMask(
        paths=["ai_platform_floor_setting.enable_cloud_logging", "google_mcp_server_floor_setting.enable_cloud_logging"]
    )
)

try:
    response = client.update_floor_setting(request=request)
    print("Successfully updated floor settings logging.")
    print(response)
except Exception as e:
    print(f"An error occurred: {e}")

Sostituisci PROJECT_ID con l'ID del tuo progetto.

Visualizzare e filtrare i log di Model Armor

Per visualizzare e filtrare i log di Model Armor, utilizza Esplora log in Logging:

Nella Google Cloud console, vai alla pagina Esplora log.

Vai a Esplora log

Per saperne di più, consulta Visualizzare i log utilizzando Esplora log.
Nel riquadro della query, inserisci una delle seguenti query per filtrare i log di Model Armor:
- Per visualizzare tutti i log di Model Armor, inclusi gli audit log e i log delle operazioni di sanificazione:
```
protoPayload.serviceName="modelarmor.googleapis.com" OR jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
```
- Per visualizzare solo gli audit log di Model Armor:
```
protoPayload.serviceName="modelarmor.googleapis.com"
```
  Per un elenco di tutti i nomi dei servizi e dei tipi di risorsa monitorata, consulta Risorse e servizi monitorati.
- Per visualizzare solo i log di Model Armor per le operazioni di sanificazione:
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
```
  Per perfezionare ulteriormente i log delle operazioni di sanificazione, puoi specificare un nome client o un ID di correlazione nella query.
  - Utilizzo di un nome client: quando Model Armor si integra con servizi come Gemini Enterprise Agent Platform o Gemini Enterprise, puoi utilizzare il nome client per filtrare i log per un'integrazione specifica.
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
labels."modelarmor.googleapis.com/client_name"="CLIENT_NAME"
```
  - Utilizzo di un ID di correlazione:
```
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
labels."modelarmor.googleapis.com/client_correlation_id"="CORRELATION_ID"
```
  Sostituisci quanto segue:
  - CLIENT_NAME: il nome del tuo client. Utilizza uno dei seguenti valori:
    - CLIENT_NAME_UNSPECIFIED: valore predefinito, utilizzato quando il nome del client non è specificato.
    - VERTEX_AI: per l'integrazione con Gemini Enterprise Agent Platform.
    - LOAD_BALANCER: per l'integrazione utilizzando l'estensione del servizio Load Balancer come a.
    - LANGCHAIN: per l'integrazione con LangChain.
    - GEMINI_ENTERPRISE_BUSINESS: per l'integrazione con Gemini Enterprise – versione Business.
    - GOOGLE_MCP_SERVER: per l'integrazione con i server MCP gestiti da Google e Google.
    - AGENT_GATEWAY: per l'integrazione con il gateway dell'agente.
    - GEMINI_ENTERPRISE_NON_BUSINESS : per l'integrazione con le versioni di Gemini Enterprise diverse da Business (Standard, Plus, Frontline).
    - SECURE_WEB_PROXY : per l'integrazione con Secure Web Proxy.
  - CORRELATION_ID: l'identificatore univoco che generi per una richiesta specifica.

Correlare i log e gli eventi correlati

Per correlare i log e gli eventi per un'interazione specifica, puoi utilizzare un ID di correlazione client di Model Armor. Questo ID è un identificatore univoco che generi (ad esempio, un UUID) che monitora una richiesta specifica nel tuo sistema. Per impostare un ID di correlazione client in un'intestazione curl, utilizza l'opzione -H per includere un'intestazione personalizzata MA-Client-Correlation-Id nella richiesta.

Ecco il formato di esempio:

uuid=$(uuidgen) \
curl -X POST -d  '{"userPromptData": { "text": "USER_PROMPT" } }' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "MA-Client-Correlation-Id:${uuid}" \
    "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID:sanitizeUserPrompt"

curl -X POST \
    -d  '{"modelResponseData": { "text": "MODEL_RESPONSE" }, "userPrompt": "USER_PROMPT" }' \
    -H "Content-Type: application/json" \
    -H "MA-Client-Correlation-Id:${uuid}" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://modelarmor.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID:sanitizeModelResponse"

Sostituisci quanto segue:

PROJECT_ID: l'ID del progetto a cui appartiene il modello.
LOCATION: la località del modello.
TEMPLATE_ID: l'ID del modello.
USER_PROMPT: il prompt fornito al modello.
MODEL_RESPONSE: la risposta ricevuta dal modello.

Log della piattaforma e Cloud Audit Logs

È importante distinguere tra i log che puoi abilitare all'interno di un modello Model Armor o delle impostazioni di base e Cloud Audit Logs.

Funzionalità	Cloud Audit Logs	Log della piattaforma
Scopo principale	Audit di sicurezza delle chiamate API (chi ha fatto cosa, quando) e monitoraggio della conformità.	Monitoraggio operativo, debug e analisi dettagliata degli eventi di sanificazione.
Operazioni API acquisite	Operazioni di creazione, lettura, aggiornamento, eliminazione ed elenco su modelli e impostazioni di base. Le operazioni di sanificazione (`SanitizeUserPrompt`, `SanitizeModelResponse`) vengono registrate come metadati.	Acquisisce tutte le richieste come `SanitizeUserPrompt` e `SanitizeModelResponse`.
Contenuti del payload	Non include il testo effettivo del prompt dell'utente o della risposta del modello per le operazioni di sanificazione. Contiene metadati come il chiamante, il metodo, la risorsa, il timestamp e lo stato.	Include il payload completo, ad esempio il testo del prompt o della risposta, i risultati del filtro e altri dettagli della sanificazione.
Meccanismo di abilitazione	Impostazioni degli audit log IAM standard Google Cloud per l' API Model Armor. I log di accesso ai dati spesso richiedono l'abilitazione esplicita. Gli audit log per le operazioni sui modelli vengono generati automaticamente.	Abilitato impostando il flag booleano `log_sanitize_operations` nei metadati del modello o nelle impostazioni di base.
Condizioni di logging	Registra automaticamente le operazioni di creazione, lettura, aggiornamento, eliminazione ed elenco su modelli e impostazioni di base.	Registra i dati (prompt dell'utente e risposte del modello) per tutte le richieste del piano dati, indipendentemente dal fatto che Sensitive Data Protection sia abilitato o che sia stata trovata una corrispondenza con un'impostazione del filtro.
Volume e costo dei log	In genere più piccoli e prevedibili, con i prezzi standard di Cloud Logging.	Possono essere molto grandi e voluminosi, il che potrebbe comportare costi significativi di Cloud Logging a causa di payload di grandi dimensioni e utilizzo frequente. I payload di grandi dimensioni potrebbero essere suddivisi in più voci di log.
Considerazioni sulla sicurezza	Relativamente sicuri in quanto i dati del payload non vengono registrati. Richiede autorizzazioni IAM speciali per l'accesso (ad esempio, ruoli IAM specifici per visualizzare gli audit log).	Contiene dati utente potenzialmente sensibili (PII, informazioni riservate). Accessibile a chiunque disponga delle autorizzazioni di visualizzazione dei log (ad esempio, `roles/logging.privateLogViewer`).
Suggerimento	Abilita per il monitoraggio generale della sicurezza e della conformità.	Non consigliato per la produzione o i dati sensibili, a meno che non vengano indirizzati in modo sicuro a un sink con controllo dell'accesso (ad esempio, BigQuery con IAM rigoroso).

L'abilitazione del logging in un modello scrive i prompt e le risposte non elaborati in Logging. Questi dati potrebbero includere dati utente sensibili, informazioni che consentono l'identificazione personale (PII) o informazioni riservate. Il traffico elevato e i payload di grandi dimensioni possono comportare costi di logging elevati e la possibilità che i volumi di log superino i limiti e richiedano una gestione attenta.

Identità del chiamante negli audit log

Quando visualizzi gli audit log, Cloud Audit Logs acquisiscono l'identità del chiamante nel campo protoPayload.authenticationInfo.principalEmail. L'identità registrata dipende da come viene chiamata l'API Model Armor:

Richiamo diretto dell'API: se un utente o un account di servizio chiama direttamente l'API Model Armor (ad esempio, utilizzando gcloud, le librerie client o le API REST), principalEmail contiene l'indirizzo email dell'utente o dell'account di servizio.
Richiamo tramite un servizio integrato Google Cloud : se Model Armor si integra con un altro Google Cloud servizio come Gemini Enterprise Agent Platform, principalEmail contiene l'identità del servizio, che in genere è un account di servizio gestito da Google. Il formato per gli agenti di servizio è service-PROJECT_NUMBER@SERVICE_NAME.iam.gserviceaccount.com. Ad esempio, una chiamata che ha origine da una funzionalità di Gemini Enterprise Agent Platform utilizza un agente di servizio di Gemini Enterprise Agent Platform.

Per distinguere i chiamanti, esamina il campo principalEmail nella voce di log dell'audit. Le chiamate dagli utenti finali o dagli account di servizio gestiti dall'utente mostrano i relativi indirizzi email, mentre le chiamate tramite altri Google Cloud servizi mostrano gli indirizzi email degli account di servizio gestiti da Google.

Configurazione logging Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Prima di iniziare

Ottenere le autorizzazioni richieste

Abilita API

Console

gcloud

Impostare l'override dell'endpoint API utilizzando gcloud CLI

Configurare la sanificazione del traffico

Configurare il logging nei modelli

Console

REST

Python

Configurare il logging nelle impostazioni di base

Console

gcloud

REST

Python

Visualizzare e filtrare i log di Model Armor

Correlare i log e gli eventi correlati

Log della piattaforma e Cloud Audit Logs

Identità del chiamante negli audit log

Configurazione logging