Questo documento descrive come configurare Model Armor per registrare le seguenti operazioni:
- Operazioni che creano, aggiornano o eliminano un template
- Operazioni che sanificano un prompt dell'utente o una risposta del modello
Model Armor utilizza gli audit log per registrare le attività di amministrazione e 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 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 il logging per Model Armor, chiedi all'amministratore di concederti il ruolo IAM Amministratore Model Armor (roles/modelarmor.admin) sul template 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
Per poter utilizzare Model Armor, devi abilitare l'API Model Armor.
Console
Abilita l'API Model Armor, se non è già abilitata.
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 Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.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:
Installa Google Cloud CLI, quindi accedi a gcloud CLI con la tua identità federata. Dopo aver eseguito l'accesso, inizializza Google Cloud CLI eseguendo il comando seguente:
gcloud initSe non è già abilitata, 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 Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.gcloud services enable modelarmor.googleapis.com
Imposta l'override dell'endpoint API utilizzando gcloud CLI.
Imposta l'override dell'endpoint API utilizzando gcloud CLI
Questo passaggio è obbligatorio solo se utilizzi gcloud CLI. Imposta l'override dell'endpoint API per assicurarti che gcloud CLI instradi 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 multiregione in cui vuoi utilizzare Model Armor.
Configura la sanitizzazione del traffico
Per i server Google e Google Cloud MCP, configura la sanitizzazione del traffico tramite le impostazioni di base. Per saperne di più, consulta Configura la protezione per i server Google e MCPGoogle Cloud .
Configura il logging nei template
I template 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 deve registrare 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 template.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 sanitizzazione.
Console
Nella console Google Cloud , vai alla pagina Model Armor.
Verifica di visualizzare il progetto per cui hai attivato Model Armor.
Nella pagina Model Armor, fai clic su Crea template. Per saperne di più sulla creazione di template, consulta Crea un template Model Armor.
Nella sezione Configura il 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 template.LOCATION: la località del template.TEMPLATE_ID: l'ID del template.
Python
Per eseguire questo codice, innanzitutto configura un ambiente di sviluppo Python e installa 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 template.LOCATION: la località del template.TEMPLATE_ID: l'ID del template.
Configura il logging nelle impostazioni di base
Quando applichi le impostazioni di base al traffico proveniente dai modelli Gemini in Gemini Enterprise Agent Platform e dai server Google e Google Cloud MCP all'interno del tuo progetto, le impostazioni di base definiscono i filtri di sicurezza e protezione per le operazioni di sanitizzazione. Quando aggiorni le impostazioni di base di Model Armor, puoi specificare se Model Armor registra le operazioni di sanitizzazione.
Puoi attivare il logging delle operazioni di sanitizzazione per Agent Platform e i server Google e Google Cloud server MCP singolarmente. Se abilitati, i log includono il prompt e la risposta (per Agent Platform) o le chiamate allo strumento e le risposte dello strumento (per i server MCP), i risultati della valutazione di Model Armor e campi di metadati aggiuntivi.
Gli esempi seguenti mostrano come attivare il logging delle operazioni di sanitizzazione sia per la piattaforma agente sia per i server Google e Google Cloud MCP.
Console
Nella console Google Cloud , vai alla pagina Model Armor.
Verifica di visualizzare il progetto per cui hai attivato Model Armor.
Vai alla scheda Impostazioni prezzi minimi.
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 attivare il logging per Agent Platform e il flag --enable-google-mcp-server-cloud-logging per attivare il logging per i server Google e Google Cloud server MCP. Per disattivare
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 di Google e 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 attivare il logging, imposta aiPlatformFloorSetting.enableCloudLogging su true
per la piattaforma dell'agente e googleMcpServerFloorSetting.enableCloudLogging
su true per Google e i server MCP Google Cloud nel metodo UpdateFloorSetting.
Il seguente comando di esempio attiva il logging delle operazioni di sanificazione sia per Agent Platform sia per i server MCP di Google e 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, innanzitutto configura un ambiente di sviluppo Python e installa 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.
Visualizza e filtra 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.
Per saperne di più, consulta Visualizza i log utilizzando Esplora log.
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 sanitizzazione:
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 sanitizzazione:
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry"Per perfezionare ulteriormente i log delle operazioni di sanitizzazione, 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 client 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 di 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 delle regole di esclusione (anteprima): quando una regola di esclusione esegue l'override di un risultato del filtro o quando Model Armor ignora la valutazione della regola di esclusione, Model Armor compila i seguenti campi
labelsfacoltativi di primo livello nelle voci di logmodelarmor.googleapis.com/SanitizeOperation:modelarmor.googleapis.com/exclusion_rule_overridden_filters: un elenco separato da virgole di filtri i cui risultatiMATCH_FOUNDoEXECUTION_SKIPPEDsono stati sostituiti conNO_MATCH_FOUNDperché è stata trovata una corrispondenza con una regola esclusiva.modelarmor.googleapis.com/exclusion_rule_skipped_filters: un elenco separato da virgole di filtri per i quali è stata saltata la valutazione della regola esclusiva (ad esempio, quando un input supera il limite del payload di esclusione di 130.000 token (0,5 MB)).
Utilizza le seguenti query di esempio per filtrare i log di sanitizzazione in base alle etichette delle regole esclusive:
- Per trovare le richieste in cui un risultato del filtro è stato sostituito 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 sostituito 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 la valutazione della regola di esclusione è stata ignorata:
jsonPayload.@type="type.googleapis.com/google.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry" labels."modelarmor.googleapis.com/exclusion_rule_skipped_filters"="FILTER_NAME"Sostituisci
FILTER_NAMEcon il nome del filtro (PROMPT_INJECTION_AND_JAILBREAKoRESPONSIBLE_AI).
Correlare i log e gli eventi correlati
Per correlare log ed eventi per un'interazione specifica, puoi utilizzare un ID correlazione client di Model Armor. Questo ID è un identificatore univoco che generi (ad esempio un UUID) per monitorare 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 template.LOCATION: la località del template.TEMPLATE_ID: l'ID del template.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.
| Funzionalità | Cloud Audit Logs | Log della piattaforma |
|---|---|---|
| Scopo principale | Audit di sicurezza delle chiamate API (chi ha fatto cosa e quando) e monitoraggio della conformità. | Monitoraggio operativo, debug e analisi dettagliata degli eventi di sanitizzazione. |
| Operazioni API acquisite | Operazioni di creazione, lettura, aggiornamento, eliminazione ed elenco su modelli e impostazioni di prezzo minimo. Le operazioni di sanitizzazione (SanitizeUserPrompt,
SanitizeModelResponse) vengono registrate come metadati. |
Acquisisce tutte le richieste, ad esempio SanitizeUserPrompt e
SanitizeModelResponse. |
| Contenuto del payload | Non include il testo effettivo del prompt dell'utente o della risposta del modello per le operazioni di sanitizzazione. 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 sanitizzazione. |
| Meccanismo di attivazione | Impostazioni standard degli audit log IAM 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 template vengono generati automaticamente. | Attivato impostando il flag booleano log_sanitize_operations nei metadati del template o nelle impostazioni di base. |
| Condizioni di logging | Registra automaticamente le operazioni di creazione, lettura, aggiornamento, eliminazione ed elenco su modelli e impostazioni di prezzo minimo. | Registra i dati (prompt degli utenti 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 di filtro. |
| Volume e costo dei log | In genere sono più piccoli e prevedibili e comportano i prezzi standard di Cloud Logging. | Possono essere molto grandi e voluminosi, con un potenziale aumento significativo dei costi di Cloud Logging a causa di payload di grandi dimensioni e dell'utilizzo frequente. I payload di grandi dimensioni potrebbero essere suddivisi in più voci di log. |
| Considerazioni sulla sicurezza | Relativamente sicuro, poiché i dati del payload non vengono registrati. Per l'accesso sono necessarie autorizzazioni IAM speciali (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 | Attivalo per il monitoraggio generale della sicurezza e della conformità. | Non è consigliato per la produzione o per i dati sensibili, a meno che non venga indirizzato in modo sicuro a un sink con controllo degli accessi (ad esempio BigQuery con IAM rigoroso). |
L'abilitazione del logging in un template 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. Un traffico elevato e payload di grandi dimensioni possono comportare costi di logging sostanziali e potenziali volumi di log elevati che superano i limiti e richiedono 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 all'API: se un utente o un account di servizio chiama direttamente l'API Model Armor (ad esempio utilizzando
gcloud, librerie client o API REST),principalEmailcontiene l'indirizzo email di quell'utente o account di servizio. - Chiamata tramite un servizio Google Cloud integrato: se Model Armor si integra con un altro servizioGoogle Cloud , ad esempio Gemini Enterprise Agent Platform,
principalEmailcontiene l'identità di quel servizio, che in genere è un service account gestito da Google. Il formato degli agenti di servizio èservice-PROJECT_NUMBER@SERVICE_NAME.. 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 da utenti finali o service account gestiti dall'utente mostrano i loro indirizzi email, mentre le chiamate tramite altri servizi Google Cloud mostrano gli indirizzi email dei account di servizio gestiti da Google.