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 Log di controllo di Model Armor.

Per informazioni sui prezzi dei log, consulta la sezione 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 Prezzi di Model Armor.

Prima di iniziare

Prima di iniziare, completa le seguenti attività.

Ottenere le autorizzazioni richieste

Per ottenere le autorizzazioni necessarie per configurare la registrazione per Model Armor, chiedi all'amministratore di concederti il ruolo IAM Model Armor Admin (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 dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente disponi già di questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin). 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 console Google Cloud , attiva Cloud Shell.

Attiva Cloud Shell

Nella parte inferiore della console Google Cloud 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à 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.

Imposta 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 questo comando 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 di Google e Google Cloud , configura la sanificazione del traffico tramite le impostazioni di base. Per saperne di più, consulta Configura la protezione per i server Google e Google Cloud MCP.

Configurare la registrazione nei modelli

I modelli definiscono i filtri e le soglie per diverse categorie di sicurezza e protezione. Quando crei o aggiorni un template 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 consente di registrare le operazioni di creazione, aggiornamento, lettura ed eliminazione dei modelli.
log_sanitize_operations: un valore booleano che consente di registrare l'intero contenuto dei prompt degli utenti e delle risposte del modello durante le operazioni di sanificazione.

Console

Nella console Google Cloud , 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, vedi Crea 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 posizione 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 posizione 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 nei server Google e Google Cloud MCP all'interno del tuo progetto, le impostazioni di base definiscono i filtri di sicurezza per le operazioni di sanificazione. Quando aggiorni le impostazioni di base di Model Armor, puoi specificare se i log di Model Armor sanitizzano le operazioni.

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

Gli esempi seguenti mostrano come abilitare la registrazione delle operazioni di pulizia sia per Agent Platform sia per i server Google e Google Cloud MCP.

Console

Nella console Google Cloud , 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 piano.
Nella sezione Log, seleziona le caselle di controllo Vertex AI e MCP gestito da Google per attivare la registrazione per ogni servizio.
Fai clic su Salva.

gcloud

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

Il seguente comando di esempio abilita la registrazione delle operazioni di sanificazione per i server Agent Platform, Google e Google Cloud MCP:

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 Google e Google Cloud MCP nel metodo UpdateFloorSetting.

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

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 console Google Cloud , vai alla pagina Esplora log.

Vai a Esplora log

Per saperne di più, vedi Visualizza 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 Servizi e risorse monitorati.
- Per visualizzare solo i log di Model Armor per le operazioni di sanitizzazione:
```
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 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 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 cliente. 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 tramite il bilanciatore del carico come estensione di servizio.
    - LANGCHAIN: Per l'integrazione con LangChain.
    - GEMINI_ENTERPRISE_BUSINESS: Per l'integrazione con Gemini Enterprise - Business edition.
    - GOOGLE_MCP_SERVER: Per l'integrazione con Google e i server MCP gestiti da Google.
    - AGENT_GATEWAY: Per l'integrazione con Agent Gateway.
    - 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 log ed eventi per un'interazione specifica, puoi utilizzare un ID di correlazione client 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 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 posizione 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 attivare 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 della 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	Crea, leggi, aggiorna, elimina ed elenca operazioni su modelli e impostazioni del piano. Le operazioni di sanificazione (`SanitizeUserPrompt`, `SanitizeModelResponse`) vengono registrate come metadati.	Acquisisce tutte le richieste come `SanitizeUserPrompt` e `SanitizeModelResponse`.
Contenuti del payload	Non include il prompt utente o il testo della risposta del modello effettivi per le operazioni di pulizia. Contiene metadati come chiamante, metodo, risorsa, timestamp e 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 attivazione	Impostazioni degli audit log IAM standard per l'API Model Armor. Google Cloud I log degli accessi ai dati spesso richiedono l'abilitazione esplicita. I log di controllo per le operazioni sui modelli vengono generati automaticamente.	Attivato 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 di modelli e impostazioni di base.	Registra i dati (prompt dell'utente e risposte del modello) per qualsiasi richiesta del piano dati, indipendentemente dal fatto che Sensitive Data Protection sia abilitato o che sia stata trovata una corrispondenza con un'impostazione di filtro.
Volume e costo dei log	In genere più piccoli e prevedibili, con prezzi standard di Cloud Logging.	Possono essere molto grandi e voluminosi, il che potrebbe comportare costi significativi per 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 sicuro, in quanto i dati del payload non vengono registrati. Richiede autorizzazioni IAM speciali per l'accesso (ad esempio, ruoli IAM specifici per visualizzare i log di controllo).	Contiene dati utente potenzialmente sensibili (PII, informazioni riservate). Accessibile a chiunque disponga delle autorizzazioni di visualizzazione dei log (ad esempio, `roles/logging.privateLogViewer`).
Suggerimento	Attiva 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 prompt e risposte non elaborati in Logging. Questi dati potrebbero includere dati utente sensibili, informazioni che consentono l'identificazione personale (PII) o informazioni riservate. Un traffico elevato e 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 nei log di controllo

Quando visualizzi gli audit log, Cloud Audit Logs acquisisce 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, librerie client o API REST), principalEmail contiene l'indirizzo email di quell'utente o account di servizio.
Invocation through an integrated Google Cloud service: If Model Armor integrates with another Google Cloud service such as Gemini Enterprise Agent Platform, then principalEmail contains that service's identity, which is typically a Google-managed service account. Il formato per i service agent è 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 Gemini Enterprise Agent Platform.

Per distinguere i chiamanti, esamina il campo principalEmail nella voce di log dell'audit. Le chiamate dagli utenti finali o dai service account gestiti dagli utenti mostrano i loro indirizzi email, mentre le chiamate tramite altri servizi Google Cloud mostrano gli indirizzi email dei 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

Imposta l'override dell'endpoint API utilizzando gcloud CLI

Configurare la sanificazione del traffico

Configurare la registrazione 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 nei log di controllo

Configurazione logging