Schéma du journal des conversations

Ce document décrit la mise en page de la table, les colonnes, les types d'événements, les champs d'identité utilisateur et la structure de la charge utile JSON pour la journalisation des conversations d'analyse conversationnelle dans BigQuery. Pour en savoir plus sur le fonctionnement de la journalisation des conversations, consultez Présentation de la journalisation des conversations.

Mise en page et création automatique de tableaux

Créez l'ensemble de données de destination dans le même projet que l'agent de données avant d'activer la journalisation. L'agent de service de l'API Conversational Analytics crée la table à l'emplacement de l'ensemble de données lors du premier tour de parole consigné (ou ajoute les colonnes de schéma manquantes à une table compatible existante). La table créée automatiquement est partitionnée par jour sur timestamp (héritant de toute expiration de partition par défaut sur l'ensemble de données) et mise en cluster sur event_type, agent et user_id. Filtrez toujours sur timestamp lorsque vous interrogez la table.

Colonnes

Le tableau suivant décrit les colonnes de la table de destination de la journalisation des conversations.

Colonne Type Mode Sommaire
timestamp TIMESTAMP REQUIRED Heure UTC de l'événement. Colonne de partitionnement.
event_id STRING NULLABLE Identifiant unique de l'événement. Il reste le même si une écriture est relancée, ce qui vous permet de l'utiliser pour supprimer les doublons.
event_type STRING NULLABLE Type d'événement. Consultez Types d'événements.
agent STRING NULLABLE Type d'agent, et non le nom ou l'ID de votre agent (par exemple, ConversationalAnalyticsAgent). Pour distinguer les agents, utilisez l'ID de l'agent de données (voir Champs dans attributes).
session_id STRING NULLABLE Un seul tour, pas une conversation entière. Tous les événements d'une question et de sa réponse partagent un session_id. Pour regrouper les tours de parole en conversations, utilisez l'ID de conversation dans attributes.
invocation_id STRING NULLABLE Une exécution au cours d'un tour.
user_id STRING NULLABLE L'appelant qui a posé la question. Consultez la section Identité des utilisateurs.
trace_id STRING NULLABLE ID de trace OpenTelemetry (32 caractères hexadécimaux).
span_id STRING NULLABLE ID de cette opération dans l'arborescence d'exécution du tour.
parent_span_id STRING NULLABLE ID de l'opération parente.
content JSON NULLABLE Charge utile de l'événement. Sa forme dépend de event_type.
content_parts RECORD REPEATED Contenu en plusieurs parties, avec un élément par partie (par exemple, mime_type, uri, object_ref, text, part_index, part_attributes et storage_mode).
attributes JSON NULLABLE Métadonnées : ID de l'agent de données, ID de la conversation, clé utilisateur interne, version du modèle et utilisation détaillée des jetons.
latency_ms JSON NULLABLE Mesures de la latence, telles que total_ms et time_to_first_token_ms.
status STRING NULLABLE OK ou ERROR.
error_message STRING NULLABLE Détails de l'erreur. Il peut également être défini sur les lignes OK LLM_RESPONSE lorsque le modèle s'arrête pour une raison autre qu'un arrêt normal (par exemple, lorsqu'il atteint la limite maximale de jetons).
is_truncated BOOLEAN NULLABLE true si une valeur de texte de l'événement dépassait 512 000 caractères (500 * 1,024) et a été coupée. Les valeurs de coupe se terminent par ...[TRUNCATED]. La partie supprimée ne peut pas être récupérée.

Types d'événement

Le tableau suivant décrit les valeurs pouvant apparaître dans la colonne event_type, ainsi que les colonnes ou les champs JSON qui stockent les données de chaque événement.

Valeur event_type Description Colonnes et champs JSON renseignés
INVOCATION_STARTING Début d'un virage. Aucun
USER_MESSAGE_RECEIVED La question de l'utilisateur. content.text_summary
AGENT_RESPONSE La réponse de l'agent, sous la forme d'un objet structuré. content.text_summary (texte brut) et content.response (voir Structure de AGENT_RESPONSE)
LLM_RESPONSE Une ligne pour chaque appel de modèle, y compris les appels qui ont demandé un outil (non écrit lorsqu'un tour reçoit une réponse directement d'une requête validée, où attributes.fast_path est true). La sortie du modèle n'est pas stockée. Jetons : content.usage.prompt, content.usage.completion, content.usage.total. Modèle : attributes.model_version. Motif de fin : attributes.finish_reason. Utilisation détaillée : attributes.usage_metadata (par exemple, cached_content_token_count et thoughts_token_count).
INVOCATION_COMPLETED Fin d'un tour, avec latence par tour. content est vide. latency_ms.total_ms
EMBEDDING_SUGGESTION Suggestions pour le propriétaire de l'agent concernant les colonnes qui pourraient bénéficier des embeddings. Il n'apparaît que pour certains agents. content.reason, content.suggested_columns
INVOCATION_ERROR, AGENT_ERROR, LLM_ERROR Tour ayant échoué. status correspond à ERROR et content correspond à NULL. error_message (résumé d'une ligne avec les instructions SQL et les noms de table masqués)

Identité des utilisateurs

La colonne user_id contient l'adresse e-mail de l'appelant : l'adresse e-mail de l'utilisateur, l'adresse e-mail d'un compte de service lorsqu'un appelant d'API s'authentifie avec un compte de service, ou NULL si l'appelant n'a pas d'adresse e-mail (comme certaines identités de fédération d'identité de personnel). Une clé utilisateur interne est également enregistrée dans attributes.session_metadata.user_id sur chaque ligne. Vous pouvez ainsi compter les utilisateurs distincts avec internal_user_key (voir Créer la vue des événements inter-agents).

Pour attribuer des tours à vos propres utilisateurs finaux lorsque vous appelez l'API via un compte de service, enregistrez le mappage des utilisateurs dans votre application. L'API n'accepte pas d'identifiant d'utilisateur final pour la journalisation.

Champs dans attributes

Le tableau suivant présente les expressions GoogleSQL utilisées pour extraire les champs de métadonnées de la colonne JSON attributes.

Ce dont vous avez besoin Expression GoogleSQL
ID de l'agent de données JSON_VALUE(attributes, '$.session_metadata.state."data-agent-id"')
Nom complet de la ressource de l'agent de données JSON_VALUE(attributes, '$.adk.app_name')
ID de la conversation JSON_VALUE(attributes, '$.session_metadata.state."conversation-id"')
Clé utilisateur interne JSON_VALUE(attributes, '$.session_metadata.user_id')
Version du modèle (sur LLM_RESPONSE lignes) JSON_VALUE(attributes, '$.model_version')

Structure de AGENT_RESPONSE

Pour lire la réponse de l'agent sous forme de texte brut, utilisez JSON_VALUE(content, '$.text_summary'). Il combine les parties Markdown, hypothèse et insight de la réponse, ainsi que les éventuelles questions de clarification. Dans les lignes AGENT_RESPONSE, content.response est un objet JSON, et non une chaîne. Par conséquent, JSON_VALUE(content, '$.response') renvoie NULL.

Le tableau suivant décrit les chemins d'accès sous content.response.

Chemin d'accès sous content.response Type Sommaire
parts ARRAY<JSON> La réponse, en plusieurs parties.
parts[].markdown STRING Texte de la réponse (Markdown).
parts[].insight STRING Un insight tiré des données.
parts[].assumption STRING Une hypothèse formulée par l'agent.
parts[].data_result_artifact_name STRING Nom d'un résultat de données.
parts[].chart_artifact_name STRING Nom d'un graphique.
followup_questions ARRAY<STRING> Questions complémentaires suggérées.
clarifying_question STRING Définissez quand l'agent a posé une question de clarification à l'utilisateur au lieu de répondre.
citation_sources JSON Sources citées dans la réponse.

Étapes suivantes