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 la pagina dei 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

Completa queste attività prima di completare le attività rimanenti in questo documento.

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

Devi abilitare le API Model Armor prima di poter utilizzare 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.
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 Model Context Protocol (MCP) gestiti da Google, configura la sanificazione del traffico tramite le impostazioni di base. Per saperne di più, consulta Configurare la protezione per i server MCP gestiti da Google e Google Cloud remoti. (Anteprima)

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 consente la registrazione delle operazioni di creazione, aggiornamento, lettura ed eliminazione dei modelli.
log_sanitize_operations: un valore booleano che consente la registrazione delle operazioni di sanificazione. I log includono il prompt e la risposta, i risultati della valutazione di Model Armor e campi di metadati aggiuntivi.

Console

Nella Google Cloud console, vai alla pagina Model Armor.

Vai a Model Armor
Verifica di visualizzare il progetto su cui 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 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

Le impostazioni di base stabiliscono filtri di sicurezza di base per tutti i modelli Gemini in Vertex AI e i server Model Context Protocol (MCP) gestiti da Google (anteprima) all'interno del tuo progetto. Quando aggiorni le impostazioni di base di Model Armor, puoi specificare se le operazioni di sanificazione di Model Armor vengono registrate.

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

Console

Nella Google Cloud console, vai alla pagina Model Armor.

Vai a Model Armor
Verifica di visualizzare il progetto su cui hai attivato Model Armor.
Vai alla scheda Impostazioni di base.
Nella sezione Log, seleziona MCP gestito da Google.
Fai clic su Salva.

gcloud

Puoi utilizzare uno dei seguenti flag per gestire il logging delle operazioni di sanificazione nelle impostazioni di base.

Per abilitare il logging, utilizza uno dei seguenti flag:

Per Vertex AI, utilizza il flag --enable-vertex-ai-cloud-logging.
Per i server MCP gestiti da Google, utilizza il flag --enable-google-mcp-server-cloud-logging.

Per disabilitare il logging, utilizza uno dei seguenti flag:

Per Vertex AI, utilizza il flag --no-enable-vertex-ai-cloud-logging.
Per i server MCP gestiti da Google, utilizza il flag --no-enable-google-mcp-server-cloud-logging.

**Nota**: puoi abilitare o disabilitare il logging per uno o entrambi i servizi utilizzando un singolo comando.

Il seguente comando di esempio abilita il logging delle operazioni di sanificazione sia per Vertex AI sia per i server MCP gestiti da Google:

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

Puoi utilizzare il metodo UpdateFloorSetting per aggiornare le impostazioni di base e abilitare il logging delle operazioni di sanificazione. Quando utilizzi questo metodo, assicurati di impostare il parametro appropriato su true per abilitare il logging:

Per Vertex AI, imposta aiPlatformFloorSetting.enableCloudLogging su true.
Per i server MCP gestiti da Google, imposta googleMcpServerFloorSetting.enableCloudLogging su true.

Il seguente comando di esempio abilita il logging delle operazioni di sanificazione sia per Vertex AI sia per i server MCP gestiti da Google:

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 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 i log

Per visualizzare i log di Model Armor, puoi utilizzare Esplora log in Logging. Procedi come segue:

Vai a Esplora log nella Google Cloud console. Per saperne di più, consulta Visualizzare i log utilizzando Esplora log.
Filtra i log in base al nome del servizio modelarmor.googleapis.com.
Cerca le voci correlate alle operazioni che hai abilitato nel modello. Per un elenco di tutti i nomi dei servizi e dei tipi di risorsa monitorata, consulta Risorse e servizi monitorati.

Filtrare i log di Model Armor

Puoi utilizzare le etichette dei log per filtrare i log di Model Armor per le operazioni di sanificazione e il logging dei modelli. Per farlo:

Esegui la seguente query in Esplora log per filtrare i log delle 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 è integrato con servizi come Vertex AI 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:

labels."modelarmor.googleapis.com/client_correlation_id"="CORRELATION_ID"

Sostituisci quanto segue:

CLIENT_NAME: il nome del tuo client, ad esempio VERTEX_AI.
CORRELATION_ID: l'identificatore univoco che generi per una richiesta specifica.

Correlare log ed eventi correlati

Per correlare log ed eventi per un'interazione specifica, puoi utilizzare un ID di correlazione client. 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 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.

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

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 i log

Filtrare i log di Model Armor

Correlare log ed eventi correlati

Configurazione logging