API Conversational Analytics : créer des agents de données et interroger vos données

Ce produit ou cette fonctionnalité sont soumis aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les produits et fonctionnalités de pré-DG sont proposés "en l'état" et peuvent avoir une compatibilité limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Important : L'API Data QnA est obsolète. Si vous migrez depuis l'API Data QnA, consultez le guide de migration pour connaître les principales différences et les étapes requises pour la migration.

Les développeurs peuvent utiliser l'API Conversational Analytics, accessible via geminidataanalytics.googleapis.com, pour créer une interface de chat ou un agent de données optimisés par l'intelligence artificielle (IA). Ces outils répondent aux questions sur les données structurées dans BigQuery, Looker et Looker Studio en utilisant le langage naturel. L'API Conversational Analytics vous permet de fournir à votre agent de données des informations et des données sur l'entreprise (contexte), ainsi qu'un accès à des outils tels que SQL, Python et des bibliothèques de visualisation. Les réponses de l'agent sont présentées à l'utilisateur et peuvent être journalisées par l'application cliente afin de créer une expérience de chat de données qui soit fluide et auditable.

Découvrez comment et quand Gemini pour Google Cloud utilise vos données.

Cette technologie étant à un stade précoce, il se peut que les produits Gemini pour Google Cloudgénèrent des résultats qui semblent plausibles, mais qui sont en fait incorrects. Nous vous recommandons de vérifier tous les résultats des produits Gemini pour Google Cloud avant de les utiliser. Pour en savoir plus, consultez la page Gemini pour Google Cloud et l'IA responsable.

Remarque : Les offres de pré-DG en preview (1) sont destinées à être utilisées dans des environnements de test uniquement et ne doivent pas être utilisées dans un environnement de production ni pour traiter des données à caractère personnel ou d'autres données soumises à des exigences légales ou réglementaires, et (2) sont soumises aux "Conditions des offres de pré-DG" des Conditions spécifiques du service et à l'Avenant de consentement pour le programme Testeur de confiance de Gemini pour Google Cloud .

Premiers pas avec l'API Conversational Analytics

Pour commencer à utiliser l'API Conversational Analytics, vous pouvez d'abord consulter la documentation sur l'architecture et les concepts clés pour comprendre comment les agents traitent les requêtes, les workflows pour les créateurs et les utilisateurs d'agents, les modes de conversation et les rôles Identity and Access Management (IAM). Ensuite, pour commencer à créer des agents de données, vous pouvez choisir entre une expérience guidée avec les guides de démarrage rapide, les ateliers de programmation et les notebooks, ou une approche autonome en suivant les étapes de la section Configuration et prérequis.

Guides de démarrage rapide, ateliers de programmation et notebooks

Les ressources suivantes vous guident pour vous aider à faire vos premiers pas avec l'API Conversational Analytics :

• Application de démarrage rapide : utilisez cette application de démarrage rapide Streamlit pour l'intégration à l'API Conversational Analytics dans un environnement de test local.
• Atelier de programmation de l'API Conversational Analytics : suivez un tutoriel détaillé pour apprendre à utiliser le SDK Python avec les données BigQuery.
• Notebooks Colaboratory de l'API Conversational Analytics :
  • Notebook Colaboratory HTTP : fournit un guide interactif par étapes pour configurer votre environnement, créer un agent de données et exécuter des appels d'API à l'aide de requêtes HTTP.
  • Notebook Colaboratory du SDK Python : fournit un guide par étapes et interactif vous permettant de configurer votre environnement, créer un agent de données et exécuter des appels d'API à l'aide du SDK Python.

Configuration et prérequis

Avant d'utiliser l'API ou les exemples, effectuez les étapes suivantes :

• Activer l'API Conversational Analytics : décrit les conditions préalables à l'activation de l'API Conversational Analytics.
• Contrôle des accès à l'API Conversational Analytics avec IAM : décrit comment utiliser Identity and Access Management pour partager l'accès aux agents de données et le gérer.
• S'authentifier et se connecter à une source de données avec l'API Conversational Analytics : fournit des instructions pour s'authentifier auprès de l'API et configurer des connexions à vos données BigQuery, Looker et Looker Studio.

Créer un agent de données avec lequel interagir

Une fois que vous avez effectué les étapes précédentes, utilisez l'API Conversational Analytics pour créer un agent de données et interagir avec lui en procédant comme suit :

• Créer un agent de données à l'aide de HTTP : fournit un exemple complet de la création d'un agent de données avec lequel interagir à l'aide de requêtes HTTP directes avec Python.
• Créer un agent de données à l'aide du SDK Python : fournit un exemple complet de la création d'un agent de données avec lequel interagir à l'aide du SDK Python.
• Guider le comportement de l'agent avec un contexte créé : découvrez comment fournir un contexte créé pour guider le comportement de l'agent et améliorer la justesse des réponses. Vous pouvez également consulter des exemples de contexte créé avec des sources de données BigQuery et des sources de données Looker.
• Afficher une réponse d'agent de l'API Conversational Analytics sous forme de visualisation : illustre le traitement des spécifications de graphique à partir des réponses de l'API et leur affichage sous forme de visualisations à l'aide du SDK Python et de la bibliothèque Vega-Altair.

Bonnes pratiques

Consultez les guides suivants pour découvrir les bonnes pratiques d'utilisation de l'API Conversational Analytics :

• Gérer les coûts BigQuery pour vos agents : découvrez comment surveiller et gérer les coûts BigQuery pour vos agents de l'API Conversational Analytics en définissant des limites de dépenses au niveau des projets, des utilisateurs et des requêtes.
• Poser des questions efficaces : découvrez comment formuler des questions efficaces pour vos agents afin d'exploiter tout le potentiel de l'API Conversational Analytics.
• Résoudre les problèmes liés aux erreurs de l'API Conversational Analytics : résolvez les problèmes courants liés aux erreurs de l'API Conversational Analytics.
• Limites connues : fournit des informations détaillées sur les limites connues de l'API Conversational Analytics, y compris les limites des requêtes, des données, des visualisations et des questions.

Principales opérations d'API

L'API fournit les principaux points de terminaison suivants pour gérer les agents de données et les conversations :

Opération	Méthode HTTP	Point de terminaison	Description
Créer un agent	POST	/v1beta/projects/*/locations/*/dataAgents	Crée un agent de données.
Obtenir un agent	GET	/v1beta/projects/*/locations/*/dataAgents/*	Récupère les détails d'un agent de données spécifique.
Obtenir une stratégie Identity and Access Management	POST	/v1beta/projects/*/locations/*/dataAgents/*:getIamPolicy	Obtient les autorisations Identity and Access Management attribuées à chaque utilisateur pour un agent de données spécifique. Les utilisateurs disposant du rôle de propriétaire d'agent de données peuvent appeler ce point de terminaison pour consulter la stratégie Identity and Access Management de l'agent de données avant d'utiliser le point de terminaison setIAMpolicy pour partager un agent de données avec d'autres utilisateurs.
Définir une stratégie Identity and Access Management	POST	/v1beta/projects/*/locations/*/dataAgents/*:setIamPolicy	Définit la stratégie Identity and Access Management pour un agent de données spécifique. Les utilisateurs disposant du rôle de propriétaire d'agent de données doivent appeler ce point de terminaison pour partager un agent de données avec d'autres utilisateurs, ce qui met à jour leurs autorisations Identity and Access Management.
Mettre à jour un agent	PATCH	/v1beta/projects/*/locations/*/dataAgents/*	Modifie un agent de données existant.
Lister des agents	GET	/v1beta/projects/*/locations/*/dataAgents	Liste les agents de données disponibles dans un projet.
Lister les agents accessibles	GET	/v1beta/projects/*/locations/*/dataAgents:listaccessible	Liste les agents de données accessibles dans un projet. Un agent de données est considéré comme accessible si l'utilisateur qui appelle cette API dispose de l'autorisation get sur l'agent. Vous pouvez utiliser le champ creator_filter pour gérer les agents renvoyés par cette méthode : NONE (par défaut) : renvoie tous les agents de données auxquels l'utilisateur a accès, quel que soit leur créateur. CREATOR_ONLY : ne renvoie que les agents de données accessibles à l'utilisateur et créés par celui-ci. NOT_CREATOR_ONLY : ne renvoie que les agents de données accessibles à l'utilisateur et créés par d'autres.
Supprimer un agent	DELETE	/v1beta/projects/*/locations/*/dataAgents/*	Supprime un agent de données.
Créer une conversation	POST	/v1beta/projects/*/locations/*/conversations	Démarre une nouvelle conversation persistante.
Discuter en utilisant une référence à une conversation	POST	/v1beta/projects/*/locations/*:chat	Poursuit une conversation avec état en envoyant un message de chat qui fait référence à une conversation existante et au contexte de l'agent associé. Pour les conversations multitours, Google Cloud stocke et gère l'historique de la conversation.
Discuter en utilisant une référence à un agent de données	POST	/v1beta/projects/*/locations/*:chat	Envoie un message de chat sans état qui se réfère à un agent de données enregistré pour le contexte. Pour les conversations multitours, votre application doit gérer et fournir l'historique de la conversation à chaque requête.
Discuter en utilisant le contexte intégré	POST	/v1beta/projects/*/locations/*:chat	Envoie un message de chat sans état en fournissant tout le contexte directement dans la requête, sans utiliser d'agent de données enregistré. Pour les conversations multitours, votre application doit gérer et fournir l'historique de la conversation à chaque requête.
Obtenir une conversation	GET	/v1beta/projects/*/locations/*/conversations/*	Récupère les détails d'une conversation spécifique.
Lister les conversations	GET	/v1beta/projects/*/locations/*/conversations	Liste les conversations d'un projet spécifique.
Lister les messages d'une conversation	GET	/v1beta/projects/*/locations/*/conversations/*/messages	Liste les messages d'une conversation spécifique.

Envoyer des commentaires

Utilisez les liens suivants pour signaler un bug ou demander une fonctionnalité.

• Envoyer un rapport de bug
• Envoyer une demande de fonctionnalité

Autres ressources

Les ressources suivantes fournissent de la documentation de référence, des exemples et des outils pour vous aider à créer des applications avec l'API Conversational Analytics :

• Documentation de référence de l'API REST Conversational Analytics : fournit des descriptions détaillées des méthodes, des points de terminaison et des définitions de type pour les structures des requêtes et des réponses.
• Démos et outils Conversational Analytics : consultez des démos et des outils qui présentent les fonctionnalités de l'API et fournissent des modèles d'intégration pratiques.
• Agent Development Kit (ADK) : découvrez comment utiliser la fonction ask_data_insights dans l'ADK pour répondre à des questions sur vos données en langage naturel.