Schema del log delle conversazioni

Questo documento descrive il layout della tabella, le colonne, i tipi di eventi, i campi dell'identità utente e la struttura del payload JSON per il logging delle conversazioni di analisi conversazionale in BigQuery. Per una panoramica del funzionamento del logging delle conversazioni, consulta la panoramica del logging delle conversazioni.

Layout e creazione automatica delle tabelle

Crea il set di dati di destinazione nello stesso progetto dell'agente di dati prima di abilitare il logging. L'agente di servizio dell'API Conversational Analytics crea la tabella nella località del set di dati al primo turno registrato (o aggiunge eventuali colonne dello schema mancanti a una tabella compatibile esistente). La tabella creata automaticamente è partizionata per giorno su timestamp (ereditando l'eventuale scadenza della partizione predefinita nel set di dati) e raggruppata in cluster su event_type, agent e user_id. Filtra sempre in base a timestamp quando esegui query sulla tabella.

Colonne

La tabella seguente descrive le colonne della tabella di destinazione del logging delle conversazioni.

Colonna Tipo Modalità Sommario
timestamp TIMESTAMP REQUIRED Ora UTC dell'evento. Colonna di partizionamento.
event_id STRING NULLABLE ID univoco dell'evento. Rimane invariato se viene eseguito un nuovo tentativo di scrittura, quindi puoi utilizzarlo per rimuovere i duplicati.
event_type STRING NULLABLE Tipo di evento. Consulta Tipi di eventi.
agent STRING NULLABLE Il tipo di agente, non il nome o l'ID dell'agente (ad esempio, ConversationalAnalyticsAgent). Per distinguere gli agenti, utilizza l'ID agente dati (consulta Campi all'interno di attributes).
session_id STRING NULLABLE Un turno, non un'intera conversazione. Tutti gli eventi per una domanda e la relativa risposta condividono un session_id. Per raggruppare i turni in conversazioni, utilizza l'ID conversazione in attributes.
invocation_id STRING NULLABLE Un'esecuzione all'interno di un turno.
user_id STRING NULLABLE Il chiamante che ha posto la domanda. Consulta Identità utente.
trace_id STRING NULLABLE ID traccia OpenTelemetry (32 caratteri esadecimali).
span_id STRING NULLABLE ID di questa operazione nell'albero di esecuzione del turno.
parent_span_id STRING NULLABLE ID dell'operazione padre.
content JSON NULLABLE Payload evento. La sua forma dipende da event_type.
content_parts RECORD REPEATED Contenuti in più parti, con un elemento per parte (ad esempio, mime_type, uri, object_ref, text, part_index, part_attributes e storage_mode).
attributes JSON NULLABLE Metadati: ID agente di dati, ID conversazione, chiave utente interna, versione del modello e utilizzo dettagliato dei token.
latency_ms JSON NULLABLE Misure di latenza, come total_ms e time_to_first_token_ms.
status STRING NULLABLE OK o ERROR.
error_message STRING NULLABLE Dettagli errore. Può anche essere impostato su OK LLM_RESPONSE righe quando il modello si arresta per un motivo diverso da un arresto normale (ad esempio, quando raggiunge il limite massimo di token).
is_truncated BOOLEAN NULLABLE true se un valore di testo nell'evento ha superato i 512.000 caratteri (500 * 1,024) ed è stato tagliato. I valori di taglio terminano con ...[TRUNCATED]. La parte rimossa non può essere recuperata.

Tipi di evento

La tabella seguente descrive i valori che possono essere visualizzati nella colonna event_type e le colonne o i campi JSON che memorizzano i dati per ogni evento.

Valore event_type Descrizione Colonne e campi JSON compilati
INVOCATION_STARTING Inizio di una svolta. Nessuno
USER_MESSAGE_RECEIVED La domanda dell'utente. content.text_summary
AGENT_RESPONSE La risposta dell'agente, sotto forma di oggetto strutturato. content.text_summary (testo normale) e content.response (consulta la sezione Struttura di AGENT_RESPONSE)
LLM_RESPONSE Una riga per ogni chiamata al modello, incluse le chiamate che hanno richiesto uno strumento (non scritta quando un turno riceve una risposta direttamente da una query verificata, dove attributes.fast_path è true). L'output del modello non viene archiviato. Token: content.usage.prompt, content.usage.completion, content.usage.total. Modello: attributes.model_version. Motivo del completamento: attributes.finish_reason. Utilizzo dettagliato: attributes.usage_metadata (ad esempio, cached_content_token_count e thoughts_token_count).
INVOCATION_COMPLETED Fine di un turno, con latenza per turno. content è vuoto. latency_ms.total_ms
EMBEDDING_SUGGESTION Suggerimenti per il proprietario dell'agente sulle colonne che potrebbero trarre vantaggio dagli embedding. Viene visualizzato solo per alcuni agenti. content.reason, content.suggested_columns
INVOCATION_ERROR, AGENT_ERROR, LLM_ERROR Svolta non riuscita. status è ERROR e content è NULL. error_message (riepilogo di una riga con istruzioni SQL e nomi delle tabelle oscurati)

Identità utente

La colonna user_id contiene l'indirizzo email del chiamante: l'indirizzo email dell'utente, l'indirizzo email di un service account quando un chiamante API si autentica con un account di servizio o NULL se il chiamante non ha un indirizzo email (ad esempio alcune identità di Workforce Identity Federation). In ogni riga di attributes.session_metadata.user_id viene registrata anche una chiave utente interna, in modo da poter conteggiare gli utenti distinti con internal_user_key (consulta Crea la visualizzazione degli eventi tra agenti).

Per attribuire i turni ai tuoi utenti finali quando chiami l'API tramite un service account, registra la mappatura degli utenti nella tua applicazione. L'API non accetta un identificatore dell'utente finale per il logging.

Campi all'interno di attributes

La tabella seguente mostra le espressioni GoogleSQL utilizzate per estrarre i campi dei metadati dalla colonna JSON attributes.

Cosa serve Espressione GoogleSQL
ID agente per i dati JSON_VALUE(attributes, '$.session_metadata.state."data-agent-id"')
Nome completo della risorsa dell'agente di dati JSON_VALUE(attributes, '$.adk.app_name')
ID conversazione JSON_VALUE(attributes, '$.session_metadata.state."conversation-id"')
Chiave utente interna JSON_VALUE(attributes, '$.session_metadata.user_id')
Versione del modello (su LLM_RESPONSE righe) JSON_VALUE(attributes, '$.model_version')

Struttura di AGENT_RESPONSE

Per leggere la risposta dell'agente come testo normale, utilizza JSON_VALUE(content, '$.text_summary'). Combina le parti di Markdown, ipotesi e insight della risposta, nonché eventuali domande di chiarimento. Nelle righe AGENT_RESPONSE, content.response è un oggetto JSON, non una stringa, quindi JSON_VALUE(content, '$.response') restituisce NULL.

La tabella seguente descrive i percorsi in content.response.

Percorso in content.response Tipo Sommario
parts ARRAY<JSON> La risposta, in parte.
parts[].markdown STRING Testo della risposta (Markdown).
parts[].insight STRING Un insight ricavato dai dati.
parts[].assumption STRING Un'ipotesi fatta dall'agente.
parts[].data_result_artifact_name STRING Nome di un risultato dei dati.
parts[].chart_artifact_name STRING Nome di un grafico.
followup_questions ARRAY<STRING> Domande aggiuntive suggerite.
clarifying_question STRING Imposta questa opzione quando l'agente ha posto all'utente una domanda di chiarimento anziché rispondere.
citation_sources JSON Fonti citate nella risposta.

Passaggi successivi