Créer des agents de données

Ce document explique comment créer, modifier, gérer et supprimer des agents de données dans BigQuery.

Dans BigQuery, vous pouvez discuter avec des agents de données pour poser des questions sur les données BigQuery en langage naturel. Les agents de données contiennent des métadonnées de table et des instructions de traitement des requêtes spécifiques à un cas d'utilisation. Ils définissent la meilleure façon de répondre aux questions des utilisateurs sur un ensemble de sources de connaissances, telles que des tables, des vues ou des fonctions définies par l'utilisateur (UDF) que vous sélectionnez.

Avant de commencer

  1. Verify that billing is enabled for your Google Cloud project.

  2. Enable the BigQuery, Gemini Data Analytics, and Gemini for Google Cloud APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

Rôles requis

Pour utiliser les agents de données, vous devez disposer de l'un des rôles Identity and Access Management de l'API Conversational Analytics suivants :

  • Créer, modifier, partager et supprimer tous les agents de données du projet : propriétaire d'agent des données des analyses de données Gemini (roles/geminidataanalytics.dataAgentOwner) sur le projet.
  • Créez, modifiez, partagez et supprimez vos propres agents de données dans le projet : Créateur d'agent des données des analyses de données Gemini (roles/geminidataanalytics.dataAgentCreator) sur le projet. Ce rôle vous attribue automatiquement le rôle Propriétaire d'agent des données des analyses de données Gemini sur les agents de données que vous créez.
  • Afficher et modifier tous les agents de données du projet : Éditeur d'agent des données des analyses de données Gemini (roles/geminidataanalytics.dataAgentEditor) au niveau du projet.
  • Affichez tous les agents de données du projet : lecteur d'agent des données des analyses de données Gemini (roles/geminidataanalytics.dataAgentViewer).

De plus, vous devez disposer des rôles suivants pour créer ou modifier un agent de données :

Pour travailler avec des ressources BigQuery, comme afficher des tables ou exécuter des requêtes, consultez Rôles BigQuery.

Bonnes pratiques

Lorsque vous utilisez l'analyse conversationnelle, des requêtes sont automatiquement exécutées pour répondre à vos questions. Des frais imprévus peuvent vous être facturés dans les cas suivants :

  • Si vos tables sont volumineuses
  • Si les requêtes utilisent des jointures de données
  • Si les requêtes effectuent de nombreux appels aux fonctions d'IA

Pour éviter ce problème, tenez compte de la taille lorsque vous sélectionnez des sources de connaissances et, lorsque vous avez des conversations, pensez à utiliser des jointures.

Générer des insights

Vous pouvez éventuellement générer des insights sur les données dans Dataplex Universal Catalog pour n'importe quelle table que vous souhaitez utiliser comme source de connaissances.

Les insights générés fournissent des métadonnées de tableau que l'agent de données peut utiliser pour générer des réponses à vos questions.

Si vous ne générez pas d'insights au préalable, le système les génère automatiquement lorsque vous sélectionnez une table comme source de connaissances lors de la création d'un agent de données.

Utiliser l'agent d'exemples de données

Si vous ne savez pas comment configurer des agents pour l'analyse conversationnelle, vous pouvez éventuellement afficher l'exemple d'agent prédéfini généré pour chaque projetGoogle Cloud . Vous pouvez discuter avec lui et afficher ses paramètres pour voir comment il a été créé, mais vous ne pouvez pas le modifier.

Pour afficher l'agent exemple, procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page Agents de BigQuery.

    Accéder à Agents

  2. Sélectionnez l'onglet Catalogue d'agents.

  3. Dans la section Exemples d'agents par Google, cliquez sur la fiche de l'exemple d'agent.

Créer un agent de données

Les sections suivantes décrivent comment créer un agent de données.

Une fois que vous avez créé un agent, vous pouvez modifier ses paramètres.

Configurer les paramètres de base

  1. Dans la console Google Cloud , accédez à la page Agents de BigQuery.

    Accéder à Agents

  2. Sélectionnez l'onglet Catalogue d'agents.

  3. Cliquez sur New agent (Nouvel agent). La page Nouvel agent s'ouvre.

  4. Dans la section Éditeur, dans le champ Nom de l'agent, saisissez un nom descriptif pour l'agent de données (par exemple, Q4 sales data ou User activity logs).

  5. Dans le champ Description de l'agent, saisissez une description de l'agent de données. Une bonne description explique ce que fait l'agent, les données qu'il utilise et vous aide à savoir quand il s'agit du bon agent de données avec lequel discuter (par exemple, Ask questions about customer orders and revenue).

  6. Dans la section Sources de connaissances, cliquez sur Ajouter une source. La page Ajouter une source de connaissances s'ouvre.

  7. Dans la section Récents, sélectionnez les tables, vues ou UDF que vous souhaitez utiliser comme sources de connaissances. Les UDF sont précédées d'un indicateur "fx" dans la consoleGoogle Cloud .

  8. Pour afficher d'autres sources de connaissances, sélectionnez Afficher plus.

  9. Facultatif : Ajoutez une source de connaissances qui ne figure pas dans la section Récents :

    1. Dans la section Rechercher, saisissez le nom de la source dans le champ Rechercher des tables, puis appuyez sur Entrée. Le nom de la source n'a pas besoin d'être exact.

    2. Dans la section Résultats de recherche, sélectionnez une ou plusieurs sources.

  10. Cliquez sur Ajouter. La page du nouvel agent s'ouvre à nouveau.

Personnaliser les descriptions des tables et des champs

Pour améliorer la précision de l'agent de données, vous pouvez éventuellement fournir des métadonnées de table supplémentaires. Seul l'agent de données utilise ces métadonnées, qui n'affectent pas la table source.

Suivez ces bonnes pratiques lorsque vous créez des descriptions de tables et de champs :

  • Utilisez ces descriptions pour comprendre comment l'agent de données comprend le schéma. Si les descriptions suggérées par l'agent sont correctes, vous pouvez les accepter.

  • Si l'agent de données ne semble pas comprendre le schéma après que vous avez configuré ces descriptions, ajustez-les manuellement pour fournir les informations correctes.

Pour configurer les descriptions des tables et des champs, procédez comme suit :

  1. Dans la section Sources de connaissances, cliquez sur le lien Personnaliser pour un tableau.

  2. Créez une description de la table. Vous pouvez saisir une description dans le champ Description du tableau ou accepter la suggestion de Gemini.

  3. Dans la section Champs, examinez les descriptions de champs suggérées par Gemini.

  4. Sélectionnez les descriptions de champ que vous souhaitez accepter, puis cliquez sur Accepter les suggestions. Sélectionnez les descriptions que vous souhaitez refuser, puis cliquez sur Refuser les suggestions.

  5. Modifiez manuellement la description d'un champ en cliquant sur Modifier à côté du champ. Le volet Modifier le champ s'ouvre.

    1. Dans le champ Description, saisissez une description du champ.
    2. Pour enregistrer la description du champ, cliquez sur Mettre à jour.

  6. Pour enregistrer la description et les modifications apportées aux champs, cliquez sur Mettre à jour. La page du nouvel agent s'ouvre à nouveau.

  7. Répétez ces étapes pour chaque tableau à personnaliser.

Configurer les fonctionnalités avancées

Configurez les fonctionnalités avancées facultatives, telles que les instructions pour les agents, les requêtes validées (anciennement appelées requêtes de référence) et les paramètres.

Créer des instructions pour l'agent

L'agent doit comprendre le contexte des questions des utilisateurs sans avoir besoin d'instructions personnalisées. Ne créez des instructions personnalisées pour l'agent que si vous devez modifier son comportement ou améliorer le contexte d'une manière qui n'est pas déjà prise en charge par d'autres fonctionnalités de contexte (par exemple, les métadonnées personnalisées des tables et des champs, ou les requêtes validées).

Dans la section Instructions, saisissez les instructions pour l'agent de données dans le champ Instructions pour l'agent. Étant donné que l'agent de données utilise ces instructions pour comprendre le contexte des questions des utilisateurs et fournir des réponses, veillez à ce qu'elles soient aussi claires que possible.

Si vous n'obtenez pas de réponse satisfaisante de l'agent, ajoutez du contexte structuré, comme des descriptions ou des exemples. Si vous n'obtenez toujours pas de réponse satisfaisante, ajoutez des instructions personnalisées comme dans les exemples du tableau suivant. Pour obtenir d'autres exemples d'instructions, cliquez sur Afficher des exemples.

Type d'information Description Exemples
Champs clés Champs les plus importants pour l'analyse. "Les champs les plus importants de ce tableau sont : "Numéro client", "ID produit" et "Date de la commande"."
Filtrer et regrouper Champs que l'agent doit utiliser pour filtrer et regrouper les données. "Lorsqu'une question porte sur un calendrier ou sur une période, utilisez toujours la colonne order_created_date." "Quand quelqu'un dit "par produit", regroupe les données par colonne product_category."
Filtrage par défaut Champs sur lesquels filtrer par défaut. "Sauf indication contraire, filtrez toujours les données sur order_status = 'Complete'."
Synonymes et termes commerciaux Termes alternatifs pour les champs clés. "Si quelqu'un pose des questions sur les revenus ou les ventes, utilisez la colonne "total_sale_amount"." "Nous considérons comme "fidèles" les clients dont la valeur purchase_count est supérieure à 5."
Champs exclus Champs que l'agent de données doit éviter d'utiliser. "Ne jamais utiliser ces champs : "Date de transaction déduite", "Ville déduite"."
Relations de jointure La façon dont deux tables ou plus sont liées entre elles, et les colonnes utilisées pour les joindre. L'agent doit utiliser des jointures SQL standard sur des paires de colonnes pour combiner les données. Consultez la colonne d'exemple. Activité client
  • order_items.user_id = users.id
    (pour associer les ventes aux clients)
  • events.user_id = users.id
    (pour associer l'activité sur le site Web aux clients connectés)

Créer des requêtes validées

Un agent utilise les requêtes validées de deux manières :

  • Si un agent peut utiliser une requête validée pour répondre à une question que vous lui posez, il l'invoque exactement telle qu'elle est écrite afin de fournir une réponse fiable.
  • Si l'agent ne peut pas utiliser la requête validée pour répondre à une question, il l'utilise quand même comme référence pour comprendre les données et les bonnes pratiques pour les interroger.

Vous pouvez sélectionner des requêtes validées dans une liste générée par le système ou créer les vôtres.

Pour créer une requête validée pour l'agent de données, anciennement appelée requête de référence, procédez comme suit :

  1. Sélectionnez une ou plusieurs requêtes validées suggérées par Gemini :

    1. Dans la section Requêtes validées, cliquez sur Examiner les suggestions. La page Examiner les requêtes validées suggérées s'ouvre.
    2. Examinez les requêtes validées suggérées. Sélectionnez toutes les options qui s'appliquent à votre cas d'utilisation.
    3. Cliquez sur Ajouter. La page du nouvel agent s'ouvre à nouveau.

  2. Pour créer votre propre requête validée, cliquez sur Ajouter une requête. La page Ajouter une requête validée s'ouvre.

    1. Dans le champ Question, saisissez la question de l'utilisateur à laquelle la requête validée répond.
    2. Cliquez sur Générer du code SQL pour que Gemini génère une requête validée correspondant à la question de l'utilisateur que vous avez spécifiée.
    3. Si vous le souhaitez, modifiez la requête validée.
    4. Cliquez sur Exécuter et vérifiez que la requête renvoie les résultats attendus.
    5. Cliquez sur Ajouter. La page du nouvel agent s'ouvre à nouveau.

  3. Répétez ces étapes autant de fois que nécessaire pour créer d'autres requêtes validées.

Configurer les paramètres

Dans la section Paramètres, vous pouvez configurer les paramètres facultatifs suivants :

  1. Créez des libellés pour organiser vos ressourcesGoogle Cloud . Les étiquettes sont des paires clé/valeur qui vous permettent de regrouper des objets associés ou de les combiner à d'autres Google Cloud ressources.

    1. Dans la section Paramètres, cliquez sur Gérer les libellés.
    2. Cliquez sur Ajouter une étiquette.
    3. Dans les champs key et value, saisissez la paire clé/valeur pour le libellé.
    4. Si vous souhaitez ajouter d'autres libellés, cliquez à nouveau sur Ajouter un libellé.
    5. Pour supprimer un libellé, cliquez sur Supprimer.
    6. Lorsque vous avez terminé, cliquez sur Ajouter. La page du nouvel agent s'ouvre à nouveau.

  2. Facultatif : Définissez une limite de taille pour les requêtes traitées par l'agent de données. Dans la section Paramètres, saisissez une valeur dans le champ Nombre maximal d'octets facturés. Vous devez définir cette limite sur 10485760 ou plus, sinon le message d'erreur suivant s'affiche :

Value error. In BigQuery on-demand pricing charges are
rounded up to the nearest MB, with a minimum of 10 MB of data processed
per query. So, max bytes billed must be set to greater or equal to
10485760.

Si vous ne spécifiez pas de valeur, maximum bytes billed est défini par défaut sur le quota d'utilisation des requêtes par jour du projet. Le quota d'utilisation par jour est illimité, sauf si vous avez spécifié un quota personnalisé.

Passez à la section suivante pour placer l'agent en mode brouillon ou le publier.

Prévisualiser et publier l'agent

  1. Dans la section Prévisualiser, saisissez un exemple de question d'utilisateur dans le champ Poser une question, puis appuyez sur Entrée. Pour vérifier que l'agent de données renvoie les données attendues, examinez sa réponse. Si la réponse ne correspond pas à vos attentes, modifiez les paramètres de la section Éditeur pour affiner la configuration de l'agent de données jusqu'à obtenir des réponses satisfaisantes. Vous pouvez continuer à tester et à modifier votre agent pour affiner ses résultats.

  2. Cliquez sur Enregistrer.

  3. Pour placer l'agent de données en mode brouillon, que vous pourrez modifier ultérieurement, cliquez sur Retour pour revenir à la page Catalogue d'agents. Comme votre agent est désormais en mode brouillon, il s'affiche dans la section Mes agents brouillons de l'onglet Catalogue d'agents.

    Pour publier votre agent, restez sur la page de création de l'agent et passez à l'étape suivante.

  4. Cliquez sur Publier pour publier l'agent de données et le rendre disponible dans le projet. Vous pouvez créer des conversations avec l'agent de données à l'aide de BigQuery Studio et de Looker Studio Pro si vous disposez d'un abonnement Looker Studio. Vous pouvez également créer votre propre interface pour discuter avec l'agent de données à l'aide de l'API Conversational Analytics.

  5. Facultatif : Dans la boîte de dialogue Votre agent a été publié, cliquez sur Partager pour partager l'agent de données avec d'autres utilisateurs.

    1. Dans le volet Autorisations de partage, cliquez sur Ajouter un compte principal.

    2. Dans le champ Nouveaux comptes principaux, saisissez un ou plusieurs comptes principaux.

    3. Cliquez sur la liste Sélectionner un rôle.

    4. Dans la liste Rôle, sélectionnez l'un des rôles suivants :

      • Utilisateur d'agent des données des analyses de données Gemini (roles/geminidataanalytics.dataAgentUser) : accorde l'autorisation de discuter avec l'agent de données.
      • Éditeur d'agent des données des analyses de données Gemini (roles/geminidataanalytics.dataAgentEditor) : permet de modifier l'agent de données.
      • Lecteur d'agent des données des analyses de données Gemini (roles/geminidataanalytics.dataAgentViewer) : accorde l'autorisation d'afficher l'agent de données.

  6. Cliquez sur Enregistrer.

  7. Pour revenir à la page du nouvel agent, cliquez sur Fermer. Immédiatement après avoir enregistré ou publié votre agent, vous pouvez le voir dans le catalogue d'agents.

Gérer les agents de données

Vous trouverez les agents existants dans l'onglet Catalogue d'agents, qui se compose de trois sections :

  • Mes agents : liste de tous les agents que vous créez et publiez. Vous pouvez modifier et partager des agents publiés avec d'autres utilisateurs.
  • Mes brouillons d'agents : agents que vous n'avez pas encore publiés. Vous ne pouvez pas partager les agents en brouillon.
  • Partagés par d'autres membres de votre organisation : agents créés et partagés avec vous par d'autres utilisateurs. Si d'autres utilisateurs vous accordent des autorisations, vous pouvez modifier ces agents partagés.

Modifier un agent de données

Pour modifier un agent de données, procédez comme suit :

  1. Accédez à la page Agents de BigQuery.

    Accéder à Agents

  2. Sélectionnez l'onglet Catalogue d'agents.

  3. Recherchez la fiche de l'agent de données que vous souhaitez modifier.

  4. Pour ouvrir l'agent de données dans l'éditeur d'agents, cliquez sur Ouvrir les actions > cliquez sur Modifier sur la fiche de l'agent.

  5. Modifiez la configuration de l'agent de données si nécessaire.

  6. Pour enregistrer vos modifications sans les publier, cliquez sur Enregistrer.

  7. Pour publier vos modifications, cliquez sur Publier . Dans la boîte de dialogue Partager, vous pouvez partager l'agent avec d'autres utilisateurs ou cliquer sur Annuler.

  8. Pour revenir au volet Agents, cliquez sur Retour.

    Icône de retour pour revenir à la page "Agents" depuis la page de modification de l'agent.

Partager un agent de données

Pour partager un agent de données publié, procédez comme suit. Vous ne pouvez pas partager d'agents en brouillon.

  1. Accédez à la page Agents de BigQuery.

    Accéder à Agents

  2. Sélectionnez l'onglet Catalogue d'agents.

  3. Recherchez la fiche de l'agent de données que vous souhaitez modifier.

  4. Pour ouvrir l'agent de données dans l'éditeur d'agents, cliquez sur Ouvrir les actions > cliquez sur Modifier sur la fiche de l'agent.

  5. Pour partager l'agent de données avec d'autres utilisateurs, cliquez sur Partager.

  6. Dans le volet Autorisations de partage, cliquez sur Ajouter un compte principal.

  7. Dans le champ Nouveaux comptes principaux, saisissez un ou plusieurs comptes principaux.

  8. Cliquez sur la liste Sélectionner un rôle.

  9. Dans la liste Rôle, sélectionnez l'un des rôles suivants :

    • Utilisateur d'agent des données des analyses de données Gemini (roles/geminidataanalytics.dataAgentUser) : permet de discuter avec l'agent de données.
    • Éditeur d'agent des données des analyses de données Gemini (roles/geminidataanalytics.dataAgentEditor) : permet de modifier l'agent de données.
    • Lecteur d'agent des données des analyses de données Gemini (roles/geminidataanalytics.dataAgentViewer) : autorise l'affichage de l'agent de données.

  10. Cliquez sur Enregistrer.

  11. Pour revenir à la page de modification de l'agent, cliquez sur Fermer.

  12. Pour revenir au volet Agents, cliquez sur Retour.

    Icône de retour pour revenir à la page "Agents" depuis la page de modification de l'agent.

Supprimer un agent de données

  1. Accédez à la page Agents de BigQuery.

    Accéder à Agents

  2. Sélectionnez l'onglet Catalogue d'agents.

  3. Dans la section Mes agents ou Agents brouillons de l'onglet Catalogue d'agents, recherchez la fiche de l'agent de données que vous souhaitez supprimer.

  4. Cliquez sur Ouvrir les actions > Supprimer.

  5. Dans la boîte de dialogue Supprimer l'agent ?, cliquez sur Supprimer.

Emplacements

Les analyses conversationnelles fonctionnent à l'échelle mondiale. Vous ne pouvez pas choisir la région à utiliser.

Étapes suivantes