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 ulteriori dettagli, consulta Prezzi di Model Armor.

Prima di iniziare

Prima di iniziare, completa le seguenti attività.

Ottieni 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.

Imposta l'override dell'endpoint API utilizzando gcloud CLI

Questo passaggio è necessario solo se utilizzi gcloud CLI con Model Armor e vuoi utilizzare una regione o una multi-regione diversa dalla multi-regione us predefinita. 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 o la multi-regione in cui vuoi utilizzare Model Armor.

Configurare la sanificazione del traffico

Per i server Google e Google Cloud MCP, 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 server 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 template:

• 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 i contenuti completi dei prompt degli utenti e delle risposte del modello durante le operazioni di sanificazione.

  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"

   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)
   

Configurare la registrazione nei dati 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 il logging delle operazioni di sanificazione per Agent Platform e 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 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 il logging delle operazioni di sanificazione sia per la piattaforma dell'agente sia per i server 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

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"

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}")

Visualizzare e filtrare i log di Model Armor

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

1. Nella console Google Cloud , vai alla pagina Esplora log.

   Vai a Esplora log

   Per saperne di più, consulta Visualizza i log utilizzando Esplora log.

2. Nel riquadro delle 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 dell'operazione di sanificazione, puoi specificare un nome client, un ID correlazione o un'etichetta di valutazione della regola di esclusione (anteprima) 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"
       

     • Utilizzando 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 client. Utilizza uno dei seguenti valori:

         • CLIENT_NAME_UNSPECIFIED: valore predefinito, utilizzato quando il nome del cliente non è specificato.
         • VERTEX_AI: per l'integrazione con Gemini Enterprise Agent Platform.
         • LOAD_BALANCER: per l'integrazione che utilizza il bilanciatore del carico come estensione del servizio.
         • LANGCHAIN: per l'integrazione con LangChain.
         • GEMINI_ENTERPRISE_BUSINESS: per l'integrazione con Gemini Enterprise - Versione Business.
         • 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 e Frontline).
         • SECURE_WEB_PROXY: per l'integrazione con Secure Web Proxy.

       • CORRELATION_ID: l'identificatore univoco che generi per una richiesta specifica.

     • Utilizzo delle etichette regola di esclusione (Anteprima): quando una regola di esclusione override un risultato del filtro o quando Model Armor salta la valutazione della regola di esclusione, Model Armor compila i seguenti campi labels facoltativi di primo livello nelle voci di log modelarmor.googleapis.com/SanitizeOperation:

       • modelarmor.googleapis.com/exclusion_rule_overridden_filters: un elenco separato da virgole di filtri i cui risultati MATCH_FOUND o EXECUTION_SKIPPED sono stati sostituiti con NO_MATCH_FOUND perché è stata trovata una corrispondenza con una regola di esclusione.
       • modelarmor.googleapis.com/exclusion_rule_skipped_filters: un elenco separato da virgole di filtri la cui valutazione della regola di esclusione è stata ignorata (ad esempio, quando un input supera il limite di 130.000 token (0,5 MB) del payload di esclusione).

       Utilizza le seguenti query di esempio per filtrare i log di sanificazione in base alle etichette delle regole di esclusione:

       • Per trovare le richieste in cui il risultato di un filtro è stato ignorato da una regola di esclusione:

       jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
       labels."modelarmor.googleapis.com/exclusion_rule_overridden_filters":"FILTER_NAME"
       

       • Per trovare le richieste in cui il rilevamento di prompt injection e jailbreaking è stato ignorato da una regola di esclusione:

       jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
       labels."modelarmor.googleapis.com/exclusion_rule_overridden_filters"="PROMPT_INJECTION_AND_JAILBREAK"
       

       • Per trovare le richieste in cui è stata ignorata la valutazione della regola di esclusione:

       jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"
       labels."modelarmor.googleapis.com/exclusion_rule_skipped_filters"="FILTER_NAME"
       

       Sostituisci FILTER_NAME con il nome del filtro (PROMPT_INJECTION_AND_JAILBREAK o RESPONSIBLE_AI).

Correlare i log e gli eventi correlati

Per correlare log ed eventi per un'interazione specifica, puoi utilizzare un ID 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 template Model Armor o delle impostazioni di base e Cloud Audit Logs.

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 negli audit log

Quando visualizzi gli audit log, Cloud Audit Logs acquisisce l'identità del chiamante nel campo protoPayload.authenticationInfo.principalEmail. L'identità registrata dipende dal modo in cui viene chiamata l'API Model Armor:

• Chiamata diretta 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.
• Invocatione tramite un servizio Google Cloud integrato: se Model Armor si integra con un altro servizioGoogle Cloud come Gemini Enterprise Agent Platform, allora principalEmail contiene l'identità del servizio, che in genere è un account di servizio gestito da Google. 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 service agent 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 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.

Passaggi successivi

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