Configura il logging per Model Armor

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 ulteriori informazioni, vedi Panoramica dei log di controllo 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) nel 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

  1. Enable the Model Armor API.

    Enable the API

  2. 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:

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

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

    3. Esegui questo comando per attivare Model Armor.

      gcloud services enable modelarmor.googleapis.com --project=PROJECT_ID

    Sostituisci PROJECT_ID con l'ID del progetto.

    Configurare il logging 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.

    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 

       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.

    Visualizza i log

    Accedi ai log di Model Armor utilizzando Esplora log in Cloud Logging. Per saperne di più, consulta Visualizzare i log utilizzando Esplora log. Filtra 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 monitorati.

    Filtra i log di Model Armor

    Utilizza le etichette dei log per filtrare i log di Model Armor per le operazioni di sanificazione e la registrazione dei log dei modelli.

    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, il nome del cliente o l'ID correlazione nella query.

    • Utilizzo di un ID progetto:

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

    • Utilizzo del nome di un client:

      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' Google Cloud ID progetto.
    • 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 i log e gli eventi relativi a una determinata interazione, devi disporre di un ID correlazione client. Si tratta di un identificatore univoco generato (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 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.