Questa pagina è stata tradotta dall'API Cloud Translation.

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 i log di controllo per registrare le attività amministrative e di gestione delle risorse. Per saperne di più, consulta Log di controllo di Model Armor.

Per informazioni su come vengono calcolati i prezzi dei log, consulta la pagina 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 la pagina Prezzi di Model Armor.

Prima di iniziare

Completa queste attività prima di completare le attività rimanenti in questa pagina.

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 le API Model Armor.

Console

Enable the Model Armor API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the 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:

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
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.

Configura 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 Configura la protezione per i server Google e MCP remoti. Google Cloud (Anteprima)

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

Console

Nella console Google Cloud , 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, vedi Creare un modello Model Armor.
Nella sezione Configura la registrazione, seleziona le operazioni per le quali vuoi configurare la registrazione.
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 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.

Configura la registrazione nei parametri di base

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

Puoi attivare la registrazione delle operazioni di sanificazione per Vertex AI e per 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 console Google Cloud , vai alla pagina Model Armor.

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

gcloud

Puoi utilizzare uno dei seguenti flag per gestire la registrazione delle operazioni di pulizia nelle impostazioni del piano.

Per abilitare la registrazione, 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 disattivare la registrazione, 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 attivare o disattivare la registrazione per uno o entrambi i servizi utilizzando un unico comando.

Il seguente comando di esempio attiva la registrazione 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 del piano e attivare la registrazione delle operazioni di sanificazione. Quando utilizzi questo metodo, assicurati di impostare il parametro appropriato su true per attivare la registrazione:

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 attiva la registrazione 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 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 i log

Per visualizzare i log di Model Armor utilizzando Esplora log in Logging, segui questi passaggi:

Vai a Esplora log nella console Google Cloud . Per saperne di più, consulta Visualizza 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 attivato nel modello. Per un elenco di tutti i nomi dei servizi e dei tipirisorsa monitoratae, consulta Servizi e risorse monitorate.

Filtra i log di Model Armor

Puoi utilizzare le etichette dei log per filtrare i log di Model Armor per le operazioni di sanificazione e la registrazione dei modelli. Per farlo, segui queste istruzioni:

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 dell'operazione di sanificazione, puoi specificare un ID progetto, un nome cliente o un ID correlazione nella query.

Utilizzo di un ID progetto:

jsonPayload.@type="type.googleapis.com%2Fgoogle.cloud.modelarmor.logging.v1.SanitizeOperationLogEntry";project=PROJECT_ID

Utilizzo di un nome cliente:

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

Utilizzo di un ID correlazione:

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

Sostituisci quanto segue:

PROJECT_ID: l'ID progetto Google Cloud .
CLIENT_NAME: il nome del tuo cliente.
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 correlazione client. Questo ID è un identificatore univoco generato da te (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 nella richiesta.

Ecco il formato di esempio:

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.

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

Configura la sanificazione del traffico

Configurare la registrazione nei modelli

Console

REST

Python

Configura la registrazione nei parametri di base

Console

gcloud

REST

Python

Visualizza i log

Filtra i log di Model Armor

Correlare i log e gli eventi correlati

Configurazione logging