Visualizzare gli intervalli di traccia di Model Armor

Questo documento descrive gli intervalli Model Armor all'interno delle tracce e come visualizzarne i dettagli. Per saperne di più sulle tracce, consulta Visualizzare le tracce dell'agente.

Informazioni su Cloud Trace e sull'osservabilità degli agenti

Una traccia rappresenta il percorso di una richiesta nelle varie parti dell'applicazione distribuita. Ogni traccia rappresenta una singola operazione end-to-end. Poiché le tracce sono composte da span, ovvero record per una singola funzione o operazione, consentono di seguire il flusso delle richieste ed esaminare i dati di latenza. Queste informazioni possono aiutarti a identificare la causa principale di un problema.

Cloud Trace è il sistema di tracciamento distribuito per Google Cloude fornisce funzionalità per esplorare le tracce o per analizzare i dati di traccia con SQL. Tuttavia, molti serviziGoogle Cloud , come Application Monitoring e Agent Registry, possono visualizzare i dati gestiti da Cloud Trace. Questi servizi ti consentono di visualizzare i dati di traccia nel contesto del servizio che stai utilizzando.

Prima di iniziare

  1. Abilita le API Cloud Trace, Cloud Logging, Telemetry e Model Armor.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin), che include l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

    Abilita le API

  2. Configura la tracciabilità per il tuo agente.
  3. Configura Model Armor su un gateway o su un Google Cloud server MCP.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per visualizzare i dati di traccia, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

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.

Per informazioni su altri ruoli di cui potresti aver bisogno, consulta Controllo dell'accesso a Cloud Trace e Controllo dell'accesso a Cloud Logging.

Payload supportati

Per un elenco dei payload supportati, consulta Payload supportati e non supportati.

Per una richiesta che contiene un payload non supportato, Model Armor genera uno span con un errore.

Nomi e attributi degli intervalli di Model Armor

Sono disponibili i seguenti intervalli di Model Armor:

  • Span principale: apply_guardrail "Google Cloud Model Armor"
  • Span secondario: Request Path
  • Span secondario: Response Path

Le sezioni seguenti elencano tutti gli attributi possibili di un intervallo Model Armor. Non tutti gli attributi sono presenti in ogni intervallo. Questi nomi degli attributi sono soggetti a modifica.

Attributi dello span principale

Lo span principale, apply_guardrail "Google Cloud Model Armor", ha i seguenti attributi:

  • cloud.provider: il cloud provider associato all'operazione.
  • cloud.region: la regione Google Cloud in cui si è verificata l'operazione.
  • gcp.project_id: l'ID del progetto in cui si è verificata l'operazione.
  • rpc.system: il framework o il protocollo di chiamata di procedura remota (RPC) sottostante utilizzato per l'operazione, ad esempio grpc.
  • service.name: il Google Cloud servizio associato all'operazione. Per gli intervalli di Model Armor, il valore di questo campo è modelarmor.

Attributi del percorso della richiesta

Lo span secondario Request Path ha i seguenti attributi:

  • gen_ai.security.target.type: il tipo di contenuti o azione a cui viene applicata la barriera protettiva. Nell'intervallo Request Path, questo valore è sempre input.
  • gen_ai.security.decision.type: il verdetto o l'azione che Model Armor ha applicato. Un valore di modify indica che Model Armor ha oscurato (de-identificato) i dati sensibili dai contenuti in base al modello fornito.
  • gen_ai.security.decision.code: un codice numerico per la decisione di sicurezza.
  • gen_ai.security.decision.reason: un motivo leggibile per l'utente per la decisione.
  • gen_ai.security.policy.id: il nome completo della risorsa del template Model Armor nel formato projects/PROJECT_ID/locations/LOCATION/templates/MODEL_ARMOR_TEMPLATE_ID.
  • gen_ai.security.policy.name: il nome del modello Model Armor utilizzato per l'operazione.
  • gcp.modelarmor.filter.match.state: indica se i contenuti hanno violato uno dei filtri Model Armor (chiamati anche detector).
  • gcp.modelarmor.violations: i filtri Model Armor che i contenuti hanno violato. Un valore di deidentified indica che Model Armor ha oscurato i dati sensibili dai contenuti in base al modello fornito.
  • gcp.modelarmor.rai.violation: le categorie di AI responsabile violate dai contenuti. Per saperne di più, consulta Filtro di sicurezza dell'AI responsabile.
  • error.type: un identificatore per l'errore riscontrato.

Attributi del percorso di risposta

Lo span secondario Response Path ha i seguenti attributi:

  • gen_ai.security.target.type: il tipo di contenuti o azione a cui viene applicata la barriera protettiva. Nell'intervallo Response Path, questo valore è sempre output.
  • gen_ai.security.decision.type: il verdetto o l'azione che Model Armor ha applicato. Un valore di modify indica che Model Armor ha oscurato (de-identificato) i dati sensibili dai contenuti in base al modello fornito.
  • gen_ai.security.decision.code: un codice numerico per la decisione di sicurezza.
  • gen_ai.security.decision.reason: un motivo leggibile per l'utente per la decisione.
  • gen_ai.security.policy.id: il nome completo della risorsa del template Model Armor nel formato projects/PROJECT_ID/locations/LOCATION/templates/MODEL_ARMOR_TEMPLATE_ID.
  • gen_ai.security.policy.name: il nome del modello Model Armor utilizzato per l'operazione.
  • gcp.modelarmor.filter.match.state: indica se i contenuti hanno violato uno dei filtri Model Armor (chiamati anche detector).
  • gcp.modelarmor.violations: i filtri Model Armor violati dai contenuti. Un valore di deidentified indica che Model Armor ha oscurato i dati sensibili dai contenuti in base al modello fornito.
  • gcp.modelarmor.rai.violation: le categorie di AI responsabile violate dai contenuti. Per saperne di più, consulta Filtro di sicurezza dell'AI responsabile.
  • error.type: un identificatore per l'errore riscontrato.

Visualizza i dettagli di un intervallo Model Armor

Per visualizzare uno span Model Armor e i relativi dettagli, inclusi gli attributi e il DAG, segui questi passaggi:

  1. Nella console Google Cloud , vai a Registro agenti.

    Vai al registry degli agenti

  2. Seleziona il progetto.
  3. Fai clic sul nome dell'agente.
  4. Fai clic sulla scheda Tracce.
  5. Fai clic sull'ID di una traccia che vuoi visualizzare. Se la traccia coinvolge un intervallo Model Armor, la traccia include l'intervallo apply_guardrail "Google Cloud Model Armor".

  6. Esplora la traccia:

    • Per visualizzare la traccia come un grafo diretto aciclico (DAG), fai clic sulla visualizzazione Grafico. Questa visualizzazione rappresenta la traccia di esecuzione di un agente come un diagramma nodo-link. I DAG enfatizzano le relazioni causali e le dipendenze tra i diversi intervalli di traccia e mostrano come un'operazione ne attivi un'altra. Ogni nodo del grafico è uno span.
    • Per visualizzare la traccia come sequenza temporale, fai clic sulla visualizzazione Sequenza temporale. Ogni barra della sequenza temporale rappresenta un intervallo.

  7. Fai clic su un intervallo per visualizzarne gli attributi.

In alternativa, fai clic su Visualizza in Cloud Trace per visualizzare tutti gli intervalli nel tuo progetto tramite Esplora tracce. Applica filtri di intervallo per cercare l'intervallo apply_guardrail "Google Cloud Model Armor".

Passaggi successivi