Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Présentation de la journalisation des conversations

La journalisation des conversations de l'analyse conversationnelle vous permet d'enregistrer les conversations d'un agent de données dans une table BigQuery de votre projet. Vous pouvez ainsi examiner la qualité des réponses, suivre l'adoption et surveiller les coûts de vos agents d'analyse conversationnelle. Pour chaque tour, le journal capture la question de l'utilisateur, la réponse de l'agent, la latence, l'utilisation des jetons du modèle et les identifiants dont vous avez besoin pour regrouper les tours par agent, conversation et utilisateur. Les lignes sont écrites à l'aide du schéma BigQuery agent analytics via l'API BigQuery Storage Write (gRPC).

Ce qui est consigné

Chaque tour consigné écrit plusieurs lignes d'événements (events) dans la table de destination, qui enregistrent les informations suivantes :

La question de l'utilisateur.
La réponse de l'agent : le texte, les insights, les hypothèses, les questions de suivi suggérées, les sources de citation et les noms des résultats de données ou des graphiques.
Latence par tour.
Utilisation des jetons du modèle, version du modèle et motif d'arrêt (pourquoi le modèle a cessé de générer des jetons) pour chaque appel de modèle.
L'ID de l'agent de données et l'ID de la conversation, afin de pouvoir analyser plusieurs agents dans un même tableau.
Identifiant utilisateur. Pour en savoir plus sur les identifiants utilisateur, consultez Identité de l'utilisateur.
État et détails de l'erreur.

Ce qui n'est pas consigné

La journalisation des conversations n'enregistre pas les éléments suivants :

Les requêtes SQL exécutées par l'agent : le journal contient la réponse finale ainsi que les noms des résultats de données et des graphiques référencés, mais pas les requêtes qui les ont générés. La seule exception est lorsqu'un utilisateur demande explicitement à l'agent d'afficher ou d'expliquer le code SQL. Dans ce cas, le code SQL peut apparaître dans le texte de la réponse.
Appels d'outils de l'agent : chaque appel de modèle écrit une ligne LLM_RESPONSE, y compris les appels dans lesquels le modèle décide d'exécuter un outil. Avant l'écriture de la ligne, la sortie du modèle est supprimée, y compris le nom et les arguments de tout outil qu'il a appelé. Seuls l'utilisation des jetons, la version du modèle et le motif de fin sont conservés.
Commentaires des utilisateurs : les commentaires "J'aime" ou "Je n'aime pas" ne sont pas enregistrés.

Certaines conversations ne sont pas enregistrées du tout, comme celles du volet d'aperçu de BigQuery Studio. Pour en savoir plus sur les surfaces de conversation non compatibles, consultez Limites.

Fonctionnement de la journalisation des conversations

Lorsqu'un utilisateur discute avec un agent de données pour lequel la journalisation des conversations est activée, l'analyse conversationnelle traite chaque tour de parole en suivant les étapes suivantes :

Configuration : le propriétaire d'un agent active la journalisation des conversations, puis sélectionne un ensemble de données de destination et un nom de table existants dans le projet de l'agent dans BigQuery Studio.
Demande : un utilisateur envoie une question à l'agent. Dans BigQuery Studio, les utilisateurs voient une notification indiquant que leurs conversations sont enregistrées.
Contrôle de confidentialité : avant que l'agent ne commence à travailler sur le tour, un contrôle de confidentialité lit les métadonnées des tables de sources de connaissances de l'agent à l'aide des identifiants de l'utilisateur qui discute. Cette vérification confirme qu'aucune des tables n'utilise la sécurité au niveau des lignes (règles d'accès aux lignes), la sécurité au niveau des colonnes (tags avec stratégie) ou le masquage dynamique des données. Si la vérification détecte une règle ou ne peut pas confirmer qu'il n'y en a pas, le tour n'est pas consigné, et l'agent répond quand même à la question de l'utilisateur.
Répondre : l'agent répond à l'utilisateur comme d'habitude.
Écriture : l'agent de service de l'API Conversational Analytics du projet (service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.) écrit les lignes de journal dans la table de destination via l'API Storage Write (gRPC). Lors du premier tour enregistré, l'agent de service crée la table si elle n'existe pas déjà.
Requête : les lignes s'affichent généralement quelques secondes après la fin de la réponse. Le délai de livraison n'est pas garanti.

Les erreurs de journalisation n'entraînent jamais l'échec d'un tour, et la vérification de la confidentialité et l'écriture du journal peuvent ajouter de la latence. Une autorisation manquante sur l'ensemble de données de journal, un ensemble de données inexistant ou un quota épuisé n'entraîne pas l'échec de la requête de chat. L'analyse conversationnelle ne signale pas les échecs de journalisation dans l'interface de chat ni dans Cloud Logging.

Confidentialité, gouvernance des données et sécurité

Lorsque vous activez la journalisation des conversations pour un agent, vérifiez comment les notifications aux utilisateurs finaux, l'accès aux données, le chiffrement et les contrôles réseau s'appliquent à vos journaux.

Avis aux utilisateurs finaux et contenu enregistré

Les avis et règles suivants régissent ce que la journalisation des conversations enregistre et qui peut consulter les données enregistrées :

Avis destiné aux utilisateurs finaux dans BigQuery Studio : lorsque la journalisation des conversations est activée pour un agent, les utilisateurs qui discutent avec l'agent dans BigQuery Studio voient l'avis suivant chaque fois que la journalisation des conversations est activée, y compris sur l'écran de nouvelle conversation avant que l'utilisateur n'envoie une première requête :

Tous les prompts et toutes les réponses sont enregistrés dans BigQuery, et les utilisateurs disposant d'autorisations pour l'ensemble de données peuvent y accéder.
Vos responsabilités lorsque vous utilisez l'API : si vous activez la journalisation des conversations (journalisation des traces) sur un agent de données et que vous le mettez à la disposition des utilisateurs finaux via votre propre application ou intégration, Google ne peut pas afficher d'avis à ces utilisateurs. Vous êtes responsable de toutes les notifications, divulgations ou consentements qui s'appliquent aux conversations enregistrées en vertu de la loi applicable et de vos accords avec vos utilisateurs finaux. Pour en savoir plus, consultez Sécurité, confidentialité, risques et conformité pour l'API Conversational Analytics.
Contenu du journal et qui peut le voir : la table de destination stocke le contenu des questions et réponses conformément aux règles de confidentialité suivantes :
- Questions et réponses complètes : les réponses peuvent inclure des valeurs renvoyées par vos sources de connaissances. Toute personne pouvant lire la table de journaux peut voir les données que l'agent a renvoyées à un utilisateur, y compris les données qu'elle ne peut pas lire dans les tables sources. N'accordez l'accès en lecture à l'ensemble de données de journal qu'aux personnes autorisées à voir ce contenu.
- Identifiants utilisateur et emplacement d'écriture : la colonne user_id identifie l'appelant qui a posé la question (voir Identité de l'utilisateur), et les lignes ne sont écrites que dans la destination que vous configurez dans le projet de l'agent.
- Tables avec sécurité au niveau des lignes, sécurité au niveau des colonnes ou masquage des données : si les sources de connaissances d'un agent utilisent la sécurité au niveau des lignes (règles d'accès aux lignes), la sécurité au niveau des colonnes (tags avec stratégie) ou le masquage dynamique des données, ses tours ne sont pas enregistrés. La vérification de la confidentialité ignore les tables de bigquery-public-data et ne prend en compte que les tables et les vues que vous sélectionnez comme sources de connaissances, et non les tables derrière une vue :
  - Une vue sur une table qui utilise ces règles peut réussir la vérification, de sorte que ses tours peuvent être enregistrés. Avant d'activer la journalisation, assurez-vous que les tables derrière les vues n'utilisent pas de règles d'accès aux lignes, de tags avec stratégie ni de masquage des données.
  - Si vous ajoutez l'une de ces règles à une table source ultérieurement, les lignes qui ont déjà été enregistrées restent dans la table de journal. Si votre règle de conservation ou de gouvernance interdit de conserver ces lignes, supprimez-les.

Contrôle des accès, chiffrement et sécurité réseau

Vous pouvez gérer la conservation, l'accès, le chiffrement et la sécurité du périmètre de vos journaux de conversation à l'aide des paramètres suivants :

Conservation et contrôle des accès sur l'ensemble de données de journal : configurez la conservation, les rôles d'ensemble de données, les règles de table et les journaux d'audit pour votre table de destination :
- Conservation : Google ne supprime pas les lignes de journal. Définissez un délai d'expiration de partition sur l'ensemble de données ou la table de journaux qui correspond à votre stratégie (par exemple, 90 jours).
- Moindre privilège : séparez l'ensemble de données de journaux de vos autres ensembles de données afin que l'accès en écriture de l'agent de service de l'API Conversational Analytics partagé reste éloigné de vos autres tables. Accordez aux analystes le rôle roles/bigquery.dataViewer sur l'ensemble de données de journaux, ou donnez-leur accès uniquement aux vues autorisées ou aux ensembles de données autorisés.
- Contrôles au niveau des colonnes et des lignes sur la table de journaux : vous pouvez appliquer des tags avec stratégie, le masquage des données ou des règles d'accès aux lignes à la table de journaux elle-même, par exemple sur content ou user_id. Ces commandes de table de journaux n'affectent pas le contrôle de confidentialité de la source de connaissances.
- Journaux d'audit : les modifications apportées à un agent de données sont enregistrées dans les journaux d'audit des activités d'administration. Dans les journaux d'audit BigQuery, la création de tables et les mises à jour de métadonnées par l'agent de service sont consignées sous bigquery.googleapis.com, et les ajouts de lignes via l'API Storage Write (gRPC) sont consignés sous bigquerystorage.googleapis.com.
CMEK, VPC Service Controls et résidence des données : les contrôles de chiffrement, de périmètre et d'emplacement suivants s'appliquent à la journalisation des conversations :
- CMEK : si l'ensemble de données de journaux utilise des clés Cloud KMS gérées par le client (CMEK), attribuez au compte de service de chiffrement BigQuery (bq-PROJECT_NUMBER@bigquery-encryption.) le rôle roles/cloudkms.cryptoKeyEncrypterDecrypter sur la clé. La CMEK sur un agent de données chiffre la ressource de l'agent, et non la table de journaux (voir Clés de chiffrement gérées par le client).
- VPC Service Controls : si vous utilisez un périmètre de service, incluez geminidataanalytics.googleapis.com et bigquery.googleapis.com dans le périmètre contenant le projet de l'agent. L'agent de service écrit dans la table de journaux à partir de l'infrastructure gérée par Google. Par conséquent, si le périmètre limite bigquery.googleapis.com, ajoutez une règle d'entrée comme suit. Remplacez PROJECT_NUMBER par le numéro de projet de l'agent :
```
- ingressFrom:
    identities:
    - serviceAccount:service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.
    sources:
    - accessLevel: "*"
  ingressTo:
    operations:
    - serviceName: bigquery.googleapis.com
      methodSelectors:
      - permission: bigquery.tables.get
      - permission: bigquery.tables.create
      - permission: bigquery.tables.update
      - permission: bigquery.tables.updateData
    resources:
    - projects/PROJECT_NUMBER
```
  Pour en savoir plus, consultez Configurer la sécurité du périmètre avec VPC Service Controls.
- Résidence des données : les lignes de journal et la table créée automatiquement sont stockées dans l'emplacement de l'ensemble de données de journal, où s'appliquent les règles d'administration d'emplacement des ressources (gcp.resourceLocations).

Limites

La journalisation des conversations présente les limites suivantes :

Le volet Aperçu de l'éditeur d'agent BigQuery Studio n'est pas consigné.
Les conversations directes sans agent de données ne sont pas enregistrées.
Les agents qui utilisent un champ d'application de recherche au lieu de tables spécifiques, ou qui ne déclarent aucune table BigQuery, ne sont pas consignés. Les agents qui configurent des graphiques de propriétés BigQuery en tant que sources de connaissances ne sont pas consignés.
Le code SQL généré, les appels d'outils et les événements de requête ou d'outil Agent Development Kit (ADK) (TOOL_STARTING, TOOL_COMPLETED, TOOL_ERROR et LLM_REQUEST) ne sont pas consignés. Seuls la réponse et les noms de ses résultats de données et graphiques sont consignés. Les tours de conversation auxquels une réponse est apportée directement à partir d'une requête validée n'écrivent pas de lignes LLM_RESPONSE, et les tours de conversation de requête validée ayant échoué ne sont pas consignés.
Les commentaires des utilisateurs (J'aime ou Je n'aime pas) ne sont pas enregistrés.
Les tours ne sont pas enregistrés si les sources de connaissances utilisent des règles d'accès aux lignes, une sécurité au niveau des colonnes (tags avec stratégie) ou le masquage des données, ou si la vérification de la confidentialité ne peut pas être effectuée. La vérification ne parcourt pas les vues pour accéder aux tables sous-jacentes.
Seuls les agents de table BigQuery sont compatibles. Les sources de données Looker, Data Studio, AlloyDB, Spanner et Cloud SQL ne sont pas compatibles.
L'ensemble de données de destination doit déjà exister dans le même projet que l'agent.
Les modifications de schéma apportées aux tables existantes sont uniquement additives. Un type ou un mode de colonne en conflit arrête les écritures dans cette table.
Chaque tour éligible est consigné sans paramètre d'échantillonnage. Échantillonnez plutôt au moment de la requête (voir Échantillonner les questions et réponses de tous les agents pour examen).
La colonne agent contient le type d'agent plutôt que le nom à afficher de l'agent. Utilisez l'ID de l'agent de données dans attributes.
Les appelants d'API qui utilisent un compte de service pour de nombreux utilisateurs finaux voient l'adresse e-mail de ce compte de service sur chaque ligne.
Les valeurs textuelles de plus de 512 000 caractères (500 * 1,024) sont coupées avec le suffixe ...[TRUNCATED], et la partie supprimée ne peut pas être récupérée.
Les écritures sont effectuées au mieux, avec un nombre limité de nouvelles tentatives. Les tours qui ne parviennent pas à écrire ne sont pas consignés, et les nouvelles tentatives peuvent parfois produire des lignes en double (utilisez event_id pour les dédupliquer).
Un agent n'hérite pas du paramètre d'observabilité au niveau du projet.

Tarifs

Conversational Analytics ne facture pas séparément la journalisation des conversations. Votre projet paie les tarifs BigQuery standards pour l'ingestion de données de l'API BigQuery Storage Write (gRPC), le stockage et les requêtes d'analyse. L'ingestion de l'API BigQuery Storage Write (gRPC) inclut 2 Tio d'utilisation sans frais par mois pour chaque compte de facturation, partagés entre l'utilisation de l'API Storage Write (gRPC). Filtrez les requêtes sur timestamp pour réduire le nombre d'octets analysés. La vérification de la confidentialité avant l'activation lit les métadonnées de la table et exécute des requêtes dry run sans frais.