Obtenir des insights avec l'agent Insights sur les données

L'agent Insights sur les données est un agent "Conçu par Google". Il vous permet d'obtenir des insights sur vos données BigQuery. Avec l'agent Data Insights, vous n'avez pas besoin de connaissances préalables en SQL. Vous pouvez ainsi prendre des décisions métier éclairées et basées sur les données, et les analystes de données peuvent se concentrer sur des tâches plus complexes.

Cette page explique comment un administrateur de projet Google Cloud peut autoriser, créer et déployer l'agent Data Insights à l'aide de la consoleGoogle Cloud et de l'API REST. Cette page explique également comment un utilisateur final peut utiliser l'agent.

Présentation

L'agent Data Insights est conçu pour effectuer les opérations suivantes :

  • Comprendre l'intention de l'utilisateur : il analyse le contexte des sources de données connectées et la requête en langage naturel de l'utilisateur pour comprendre son objectif.
  • Génération de code SQL : sur la base de cette compréhension, il convertit la question de l'utilisateur en requête SQL syntaxiquement et sémantiquement correcte.
  • Récupérer les données : il exécute ensuite le code SQL généré pour extraire les données pertinentes directement de la source de données connectée, un ensemble de données BigQuery.
  • Fournir des insights : il présente les données récupérées sous forme de visualisations, telles que des graphiques et des tableaux, ou sous forme de résumés textuels pour répondre à la requête de l'utilisateur.

Exemples de requêtes que vous pouvez poser à l'agent Insights sur les données

Voici quelques exemples de requêtes que vous pouvez poser à l'agent Insights sur les données :

  • Agrégation et visualisation des données :
    • "Compare les ventes du deuxième trimestre de cette année dans la région Amérique latine à celles du deuxième trimestre de l'année dernière."
    • "Crée un graphique à barres comparant les cinq premiers pays de la région."
  • Analyse des tendances :
    • "Comment le volume d'appels sortants a-t-il varié au cours des six derniers mois, ventilé par zone géographique ?"
    • "Analyse les tendances de réservation des hôtels de Lisbonne classés plus de 3 étoiles"
  • Exploration de données :
    • "Quels facteurs sont corrélés à la valeur totale des ventes lorsqu'un client effectue un achat ? Donne-moi une carte de densité montrant la relation."
  • Analyse et reporting :
    • "Résume le tableau des opportunités et des comptes, et crée un bref rapport mettant en évidence les principales tendances."

Avant de commencer

Pour commencer à utiliser l'agent Data Insights dans Gemini Enterprise, procédez comme suit :

Accorder l'accès aux données BigQuery

Pour permettre à l'agent Data Insights d'afficher et d'interroger les données BigQuery, accordez les rôles Identity and Access Management (IAM) aux utilisateurs de l'agent :

Workflow

Voici le workflow global pour configurer et utiliser l'agent Data Insights :

Obtenir les détails de l'autorisation

Suivez ces étapes pour configurer l'autorisation. Les informations que vous obtenez sont nécessaires pour autoriser l'agent Data Insights à se connecter aux données BigQuery.

  1. Dans la console Google Cloud , accédez à la page Identifiants dans API et services.

    Accéder à "Identifiants"

  2. Sélectionnez le projet Google Cloud contenant l'ensemble de données BigQuery que vous souhaitez que l'agent interroge.

  3. Cliquez sur Créer des identifiants, puis sélectionnez ID client OAuth.

  4. Dans Type d'application, sélectionnez Application Web.

  5. Dans la section URI de redirection autorisés, ajoutez les URI suivants :

    • https://vertexaisearch.cloud.google.com/oauth-redirect
    • https://vertexaisearch.cloud.google.com/static/oauth/oauth.html

  6. Cliquez sur Créer.

  7. Dans le panneau Client OAuth créé, cliquez sur Télécharger au format JSON. Le fichier JSON téléchargé inclut les informations suivantes pour le projetGoogle Cloud sélectionné. Vous aurez besoin des informations suivantes pour créer une ressource d'autorisation :

    • Client ID (ID client) : CLIENT_ID
    • URI d'autorisation : 
      https://accounts.google.com/o/oauth2/v2/auth?client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fbigquery&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent
    • URI du jeton : TOKEN_URI
    • Secret du client : CLIENT_SECRET

Configurer l'agent à l'aide de la console Google Cloud

Cette section explique comment autoriser, créer et déployer une instance de l'agent Data Insights à l'aide de la console Google Cloud . Vous pouvez également ajouter des autorisations utilisateur qui déterminent qui peut accéder à l'agent créé.

Autoriser et créer une instance d'agent

Pour autoriser et créer une instance d'agent Data Insights, procédez comme suit :

  1. Dans la console Google Cloud , accédez à Gemini Enterprise.

    Accéder à Gemini Enterprise

  2. Sélectionnez une application dans laquelle vous souhaitez créer l'agent.

  3. Dans le menu, cliquez sur Agents.

    La page Agents affiche les agents existants.

  4. Cliquez sur Ajouter un agent.

  5. Dans le volet Créer un agent, cliquez sur Créer dans la fiche Agent de données.

  6. Dans Autorisations, cliquez sur Ajouter une autorisation, puis saisissez les informations requises. Pour en savoir plus, consultez Obtenir une autorisation.

  7. Cliquez sur OK.

  8. Cliquez sur Suivant.

  9. Configurez votre agent comme suit :

    1. Saisissez le nom et la description de votre agent.
    2. Dans Ensemble de données BigQuery, cliquez sur Parcourir, puis effectuez l'une des opérations suivantes :
      • Sélectionnez un ensemble de données disponible, puis cliquez sur Sélectionner.
      • Saisissez le chemin d'accès à l'ensemble de données BigQuery requis, cliquez sur Rechercher, sélectionnez-le, puis cliquez sur Sélectionner.

    3. Facultatif : Cliquez sur Afficher plus pour afficher les options avancées.

    4. Sélectionnez les options d'accès aux tables appropriées. Si vous souhaitez imposer une liste d'autorisation ou une liste de blocage, spécifiez les chemins d'accès aux tables restreintes.

    5. Facultatif : Définissez la configuration de la requête en langage naturel pour fournir des personnalisations spécifiques à une traduction en langage naturel en code SQL ou Python. Vous pouvez également fournir un exemple de requête SQL à l'aide d'une requête en langage naturel, de son résultat SQL attendu et de sa réponse attendue. Cela améliore la qualité des sorties de l'agent.

      • Description du schéma : chaîne en langage naturel décrivant le schéma de l'ensemble de données BigQuery.
      • Requête en langage naturel vers une instruction SQL : requête en langage naturel transformée en instruction SQL.
      • Requête en langage naturel vers une instruction Python : requête en langage naturel transformée en instruction Python.

    6. Facultatif : Ajoutez des exemples de requêtes en langage naturel transformées en requêtes SQL :

      • Requête : exemple de requête en langage naturel qui doit être convertie en requête SQL. Par exemple, "Quels sont les noms et adresses e-mail des clients basés en Californie ?"
      • SQL attendu : chaîne illustrant un exemple de requête SQL correspondant à la requête en langage naturel. Par exemple, supposons que vous disposiez d'une table BigQuery nommée customers. Votre requête SQL attendue peut alors être SELECT customer_name, email FROM customers WHERE state = 'California'.
      • Réponse attendue : chaîne qui fournit la réponse attendue à la requête en exécutant la requête SQL attendue. Exemple :
      Here are the names and email addresses of your customers in California: \
* Customer name: Lara B, Email address: 222larabrown@gmail.com \
* Customer name: Alex A, Email address: baklavainthebalkans@gmail.com \
* Customer name: Bola C, Email address: cloudysanfrancisco@gmail.com \

  10. Cliquez sur Créer.

    L'instance de l'agent Data Insights apparaît dans la liste Agents.
    Pour commencer à utiliser l'agent, attendez que la colonne État de l'agent indique Activé pour votre instance.

Configurer l'agent à l'aide de l'API REST

Cette section explique comment autoriser, créer et déployer une instance d'agent Data Insights à l'aide de l'API REST.

Autoriser l'agent

En tant qu'administrateur, créez une ressource d'autorisation dans Gemini Enterprise. Cela permet à l'agent Data Insights d'accéder aux données BigQuery.

  1. Créez la ressource d'autorisation.

    REST

    L'exemple suivant montre comment créer une ressource d'autorisation à l'aide de la méthode authorizations.create.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 -H "X-Goog-User-Project: PROJECT_NUMBER" \
 "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/authorizations?authorizationId=AUTHORIZATION_ID" \
 -d '{
   "name": "projects/PROJECT_NUMBER/locations/LOCATION/authorizations/AUTHORIZATION_ID",
   "serverSideOauth2": {
     "clientId": "CLIENT_ID",
     "clientSecret": "CLIENT_SECRET",
     "authorizationUri": "AUTHORIZATION_URI",
     "tokenUri": "TOKEN_URI"
}
}'

    Remplacez les éléments suivants :

    • PROJECT_NUMBER : numéro de votre projet Google Cloud .
    • LOCATION : emplacement de votre projet Google Cloud .
    • AUTHORIZATION_ID : ID que vous devez fournir pour identifier la ressource d'autorisation.
    • CLIENT_ID : ID client que vous avez obtenu à l'étape précédente.
    • CLIENT_SECRET : code secret du client que vous avez obtenu à l'étape précédente.
    • AUTHORIZATION_URI : URI d'autorisation que vous avez obtenu à l'étape précédente.
    • TOKEN_URI : URI du jeton que vous avez obtenu à l'étape précédente.

Créer une instance d'agent

En tant qu'administrateur de projet Google Cloud , vous pouvez créer une instance d'agent Data Insights. Pour cela, vous devez indiquer l'ID du projet et l'ID de l'ensemble de données BigQuery que vous souhaitez interroger à l'aide de votre agent.

REST

L'exemple suivant montre comment créer une instance d'agent Data Insights à l'aide de la méthode agents.create. Pour en savoir plus sur les champs avancés que vous pouvez ajouter à cet exemple, consultez Ajouter des configurations avancées pour l'agent.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: PROJECT_NUMBER" \
  "https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents" \
  -d '{
    "displayName": "AGENT_DISPLAY_NAME",
    "description": "AGENT_DESCRIPTION",
    "icon": {
       "uri": "AGENT_ICON_URI"
     },
    "managed_agent_definition": {
      "tool_settings": {
        "tool_description": "AGENT_DESCRIPTION"
      },
      "data_science_agent_config": {
        "bq_project_id": "BIGQUERY_PROJECT_ID",
        "bq_dataset_id": "BIGQUERY_DATASET_ID"
      }
    },
    "authorization_config": {
      "tool_authorizations" : [
        "AUTHORIZATION_RESOURCE_NAME"
      ]
    }
  }'

Remplacez les éléments suivants :

  • PROJECT_NUMBER : numéro de votre projet Google Cloud .
  • LOCATION : emplacement de votre application Gemini Enterprise.
  • APP_ID : ID de l'application.
  • AGENT_DISPLAY_NAME : nom de votre instance d'agent Data Insights.
  • AGENT_ICON_URI : champ facultatif permettant de fournir un URI pour l'icône de l'agent.
  • AGENT_DESCRIPTION : description de votre instance d'agent Data Insights indiquant l'objectif de l'agent ou les détails de sa source de données BigQuery.
  • BIGQUERY_PROJECT_ID : ID du projetGoogle Cloud contenant l'ensemble de données BigQuery.
  • BIGQUERY_DATASET_ID : ID de l'ensemble de données BigQuery contenant les données à interroger.
  • AUTHORIZATION_RESOURCE_NAME : nom de la ressource d'autorisation que vous avez obtenue dans la section précédente.

Ajouter des configurations avancées pour l'agent

Vous pouvez éventuellement définir le champ nlQueryConfig pour fournir des personnalisations spécifiques à la traduction en langage naturel en code SQL ou Python. Vous pouvez également fournir un exemple SQL à l'aide d'une requête en langage naturel, de la sortie SQL attendue et de la réponse attendue. Cela améliore la qualité des réponses de l'agent. L'extrait de code suivant montre comment configurer ces champs avancés :

"dataScienceAgentConfig": {
  "nlQueryConfig": {
    "nl2sqlPrompt": "NL_TO_SQL_INSTRUCTIONS",
    "nl2pyPrompt": "NL_TO_PYTHON_INSTRUCTIONS",
    "nl2sqlExample": {
      "query": "EXAMPLE_NL_QUERY",
      "expectedSql": "EXPECTED_SQL_QUERY",
      "expectedResponse": "EXPECTED_SQL_RESPONSE"
    },
    "schemaDescription": "NL_DESCRIPTION_OF_BQ_DATASET"
  }
}

Remplacez les éléments suivants :

  • NL_TO_SQL_INSTRUCTIONS : requête en langage naturel transformée en instruction SQL.
  • NL_TO_PYTHON_INSTRUCTIONS : requête en langage naturel transformée en instruction Python.
  • EXAMPLE_NL_QUERY : exemple de requête en langage naturel qui doit être convertie en requête SQL. Par exemple, "Quels sont les noms et adresses e-mail des clients basés en Californie ?"
  • EXPECTED_SQL_QUERY : chaîne illustrant un exemple de requête SQL correspondant à la requête en langage naturel. Par exemple, supposons que vous disposiez d'une table BigQuery nommée customers. Votre requête SQL attendue peut alors être "SELECT customer_name, email FROM customers WHERE state = 'California'".

  • EXPECTED_SQL_RESPONSE : chaîne fournissant la réponse attendue pour la requête et la requête SQL attendue. Exemple :

    Here are the names and email addresses of your customers in California: \
* Customer name: Lara B, Email address: 222larabrown@gmail.com \
* Customer name: Alex A, Email address: baklavainthebalkans@gmail.com \
* Customer name: Bola C, Email address: cloudysanfrancisco@gmail.com \

  • NL_DESCRIPTION_OF_BQ_DATASET : chaîne en langage naturel qui décrit le schéma de l'ensemble de données BigQuery.

Déployer l'instance

Une fois l'instance de l'agent Data Insights créée, vous pouvez la déployer en tant qu'administrateur pour que les utilisateurs finaux puissent l'utiliser.

REST

  1. Déployez l'agent. L'exemple suivant montre comment déployer l'agent créé à l'aide de la méthode agents.deploy. Le déploiement de l'agent est une opération de longue durée (LRO).

    curl -X POST \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 -H "X-Goog-User-Project: PROJECT_NUMBER" \
 "https://discoveryengine.googleapis.com/v1alpha/AGENT_RESOURCE_NAME:deploy" \
 -d '{
   "name":"AGENT_RESOURCE_NAME"
 }'

    Remplacez les éléments suivants :

    • PROJECT_NUMBER : numéro de votre projet Google Cloud .
    • AGENT_RESOURCE_NAME : nom de ressource de l'agent que vous avez obtenu dans la section précédente lorsque vous avez créé l'agent.

  2. Obtenez l'état de l'opération de déploiement. L'exemple suivant montre comment obtenir l'état de l'opération de déploiement à l'aide de la méthode operations.get.

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://discoveryengine.googleapis.com/v1alpha/DEPLOY_OPERATION_NAME"

    Remplacez DEPLOY_OPERATION_NAME par le nom de l'opération de longue durée que vous avez obtenu à l'étape précédente lors du déploiement de l'agent.

    Dans la réponse, si la valeur du champ done est true, le déploiement est terminé. Si la valeur du champ done est false, le déploiement est en cours.

Ajouter ou modifier des utilisateurs et leurs autorisations

Ajoutez ou modifiez des comptes principaux dans votre instance d'agent Data Insights, et attribuez-leur des rôles IAM (Identity and Access Management) spécifiques en procédant comme suit :

Console

  1. Dans la console Google Cloud , accédez à Gemini Enterprise.

    Accéder à Gemini Enterprise

  2. Sélectionnez une application contenant votre instance d'agent Data Insights.

  3. Dans le menu, cliquez sur Agents.

    La page Agents affiche les agents existants.

  4. Cliquez sur l'agent pour lequel vous souhaitez ajouter ou modifier des utilisateurs.

    Par défaut, un agent nouvellement créé n'a aucun utilisateur.

  5. Dans le tableau Utilisateurs autorisés, cliquez sur Ajouter un utilisateur.

  6. Sélectionnez un type de membre dans la liste des types disponibles.

  7. Saisissez l'identité du membre en fonction du type, puis attribuez-lui un ou plusieurs rôles.

    • Pour un utilisateur, un groupe ou un compte de service, la chaîne de membre est une adresse e-mail.
    • Pour un domaine, la chaîne de membre est un nom de domaine valide.
    • Pour un compte principal, la chaîne de membre est un compte principal valide. Par exemple, principal://iam.googleapis.com/locations/global/workforcePools/pool-1/subject/subject-1.
    • Pour un ensemble de comptes principaux, la chaîne de membre est un ensemble de comptes principaux valide. Par exemple, principalSet://iam.googleapis.com/locations/global/workforcePools/pool-1/group/group-1.
    • Pour les domaines et les ensembles de comptes principaux, tous les utilisateurs et groupes d'utilisateurs de ces domaines et ensembles de comptes principaux se voient attribuer les mêmes rôles. Pour sécuriser l'accès à l'agent, sélectionnez des groupes individuels et des ensembles de domaines ou de comptes principaux contrôlés, puis attribuez-leur des rôles avec le minimum de droits.

  8. Cliquez sur Enregistrer.

    La stratégie IAM est mise à jour et l'utilisateur est ajouté à la liste des utilisateurs autorisés.

  9. Pour modifier les autorisations attribuées, cliquez sur Actions, sélectionnez Modifier, puis effectuez l'une des actions suivantes :

    • Modifiez les rôles attribués.
    • Ajoutez un autre rôle.
    • Cliquez sur Supprimer pour supprimer un rôle. Vous devez attribuer au moins un rôle à un utilisateur.

Modifier l'état de fonctionnement de l'instance

Une fois l'instance d'agent Data Insights créée, l'agent est activé par défaut. Vous pouvez modifier son état de fonctionnement sur Désactivé, Suspendu, Activé ou Supprimé en procédant comme suit :

Console

  1. Dans la console Google Cloud , accédez à Gemini Enterprise.

    Accéder à Gemini Enterprise

  2. Sélectionnez une application contenant votre instance d'agent Data Insights.

  3. Dans le menu, cliquez sur Agents.

    La page Agents affiche les agents existants.

  4. Cliquez sur Actions pour vos agents, puis sélectionnez l'une des options suivantes :

    • Suspendu : pour rendre l'agent temporairement indisponible. Toutefois, les utilisateurs disposant d'un niveau d'autorisation quelconque pour l'agent d'accès peuvent toujours le voir.
    • Désactivé : pour rendre l'agent indisponible pour tous les utilisateurs, à l'exception de celui qui l'a créé.
    • Activé : pour rendre l'agent disponible pour tous les utilisateurs, quel que soit leur niveau d'autorisation pour l'agent d'accès.
    • Supprimer : pour supprimer l'instance d'agent.

Utiliser l'agent

Pour obtenir des insights sur vos données à l'aide de votre agent, procédez comme suit :

Application

  1. Dans le menu de navigation de l'application, cliquez sur Agents.

  2. Cliquez sur View all agents (Afficher tous les agents).

  3. Sélectionnez votre instance d'agent Data Insights.

  4. Si votre agent nécessite une autorisation supplémentaire, cliquez sur Autoriser et fournissez les informations d'autorisation.

  5. Cliquez sur Ajouter des fichiers pour inclure des fichiers en tant que sources de données supplémentaires que l'agent peut utiliser.

  6. Cliquez sur Sources pour sélectionner les sources que l'agent doit inclure afin de fournir les insights les plus pertinents.

  7. Saisissez vos questions ou requêtes, puis appuyez sur Entrée ou cliquez sur Envoyer.