Atelier de programmation sur l'extension de synthèse du tableau de bord Looker

1. Avant de commencer

Dans cet atelier de programmation (1), vous allez configurer localement l'extension de synthèse du tableau de bord Looker afin de l'essayer et de la développer en local. Ensuite, (2) vous déploierez l'extension en production afin que d'autres utilisateurs Looker de votre instance Looker puissent l'utiliser. Enfin, (3) vous pouvez suivre des étapes supplémentaires pour affiner et améliorer les fonctionnalités de l'extension. Toutes les sections non facultatives doivent être remplies dans l'ordre séquentiel.

Présentation de l'extension de synthèse du tableau de bord Looker

D'un point de vue fonctionnel, l'extension de synthèse du tableau de bord Looker envoie les données de votre tableau de bord Looker au modèle Gemini de Vertex AI. Le modèle Gemini renvoie ensuite un résumé des données de votre tableau de bord et vous indique les prochaines étapes à suivre. L'extension affiche le résumé et les étapes suivantes sous la forme d'une vignette dans votre tableau de bord, qui s'intègre à votre expérience du tableau de bord. De plus, l'extension peut exporter le résumé et les étapes suivantes vers Slack ou Google Chat. Cette extension utilise une application d'interface React associée à un service de backend WebSocket pour envoyer et recevoir des données vers et depuis le modèle Gemini de Vertex AI.

Prérequis

  • Connaissances de base sur le développement de nœuds, Docker et Terraform
  • Bonne connaissance de la configuration d'un projet Looker LookML

Points abordés

  • Configurer et développer l'extension en local
  • Déployer l'extension en production pour que d'autres utilisateurs Looker de votre instance Looker puissent l'utiliser
  • Comment optimiser les performances de l'extension et étendre ses fonctionnalités, le cas échéant
  • Gérer votre extension déployée en production

Prérequis

  • Une instance Looker, via une licence Looker Original, un essai Looker Core actif ou une licence Looker Core active.
  • Autorisations develop et deploy sur votre instance Looker.
  • Autorisations de modifier un tableau de bord que vous souhaitez tester avec l'extension.
  • Une clé API Looker provenant de votre instance Looker.
  • Un projet Google Cloud pour lequel la facturation est activée
  • API Cloud Run, API Vertex AI et API Artifact Registry activées sur le projet.
  • Accès à un environnement local avec gcloud CLI installée. Les étapes de l'atelier de programmation supposent un environnement de type Linux.

2. Configurer le backend pour le développement local

Dans cette section, vous allez configurer le service de backend WebSocket pour que vous puissiez l'essayer et le développer en local. Le service aura accès à Vertex AI.

  1. Installez Node (version 18 ou ultérieure) dans votre environnement local. Suivez ces instructions pour installer Node.js.
  2. Clonez le dépôt de l'extension dans votre répertoire d'accueil local, puis accédez au répertoire racine du dépôt. Pour les besoins de cet atelier de programmation, tous les exemples de code partent du principe que le dépôt cloné se trouve dans votre répertoire d'accueil local.
cd ~
git clone git@github.com:looker-open-source/dashboard-summarization.git
  1. Accédez au répertoire racine du dépôt cloné et renommez le fichier .env.example en .env pour vous permettre de définir des variables d'environnement dans les sections suivantes de cet atelier de programmation.
cd ~/dashboard-summarization
mv .env.example .env
  1. Accédez au répertoire src du backend de socket Web du dépôt cloné. Ce répertoire contient le code source du serveur.
cd ~/dashboard-summarization/websocket-service/src
  1. Installez les dépendances du service à l'aide de NPM.
npm install
  1. Renommez le fichier looker-example.ini en looker.ini.
mv looker-example.ini looker.ini
  1. Dans la mise à jour du fichier looker.ini:
  2. client_id et client_secret par ceux de votre clé API Looker.
  3. base_url par l'URL de votre instance Looker au format https://<YOUR_LOOKER_URL_MINUS_PROTOCOL>:19999.
  4. Texte entre les crochets (l'en-tête de section) avec l'hôte de l'URL de votre instance Looker.

Par exemple, si votre ID client est ABC123, votre code secret de client est XYZ789 et l'URL de votre instance Looker est https://mycompany.cloud.looker.com, votre fichier looker.ini se présentera exactement comme suit:

[mycompany]
base_url=https://mycompany.cloud.looker.com:19999
client_id=ABC123
client_secret=XYZ789
verify_ssl=true
  1. Identifiez votre ID de projet Google Cloud et définissez-le dans votre variable d'environnement PROJECT. Remplacez YOUR_PROJECT_ID par l'ID de votre projet.
export PROJECT="YOUR_PROJECT_ID"
  1. Vertex AI propose le modèle Gemini dans plusieurs régions listées sur cette page. Déterminez la région dans laquelle votre backend local enverra des données au modèle Gemini de Vertex AI et en recevra. Définissez la région dans votre variable d'environnement REGION. Remplacez YOUR_VERTEX_REGION par votre région, par exemple us-central1.
export REGION="YOUR_VERTEX_REGION"
  1. À présent, démarrez votre service local.
npm start
  1. Votre service de backend WebSocket local s'exécutera sur http://localhost:5000.

Vous avez maintenant terminé la configuration du service de backend WebSocket dans votre environnement local.

Le service sert d'interface entre votre extension d'interface et le modèle Gemini de Vertex AI. Le service récupérera les données du tableau de bord et LookML de votre extension d'interface avec les données interrogées depuis Looker et les requêtes du modèle Gemini de Vertex AI. Le service diffusera ensuite la réponse de Gemini vers l'extension de frontend à afficher dans votre tableau de bord.

Vous pouvez également modifier le code source du service de backend. Vous devez d'abord arrêter le processus de service, modifier le code, puis exécuter à nouveau npm start.

3. Configurer l'interface pour le développement local

Dans cette section, vous allez configurer l'extension de frontend pour l'essayer et la développer en local.

  1. Dans le même environnement local qu'aux étapes précédentes, accédez au répertoire racine de votre dépôt cloné et installez les dépendances du serveur frontend pour votre frontend.
cd ~/dashboard-summarization
npm install
  1. Démarrer votre serveur de développement frontend local
npm run develop
  1. Votre serveur frontend local diffuse maintenant le code JavaScript de l'extension à l'adresse http://localhost:8080/bundle.js.
  2. Ouvrez un navigateur Web et connectez-vous à votre instance Looker.
  3. Suivez ces instructions pour configurer un projet LookML vide. Nommez le projet Dashboard-summarization. Le projet LookML vide devrait maintenant s'ouvrir automatiquement dans l'IDE Looker, dans l'onglet actuel de votre navigateur.
  4. Créez un fichier manifeste de projet à la racine du projet LookML. Le fichier sera nommé manifest.lkml. Si vous ne savez pas comment procéder, suivez ces instructions pour ajouter un fichier à un projet LookML.
  5. Remplacez le contenu du nouveau fichier manifest.lKML par le contenu du fichier manifest.lKML qui se trouve dans le répertoire racine de votre dépôt fermé. Sélectionnez "Enregistrer les modifications". dans l'angle supérieur droit pour enregistrer les modifications apportées au fichier.
  6. Dans un autre onglet de navigateur, accédez à la liste des connexions à la base de données de votre instance Looker. Si vous ne savez pas comment faire, suivez ces instructions.
  7. Choisissez le nom d'une connexion à la base de données Looker. Peu importe la connexion que vous choisissez. Si vous n'êtes pas autorisé à voir les connexions à la base de données, contactez votre administrateur Looker et demandez-lui le nom d'une connexion à la base de données Looker.
  8. Revenez à l'onglet du navigateur où votre projet LookML est ouvert dans un IDE Looker. Créez un fichier de modèle dans votre projet LookML et nommez le fichier "dashboard-summarization".
  9. Remplacez le contenu de votre fichier Dashboard-summarization.model.lKML par l'exemple de code ci-dessous. Veillez à remplacer la chaîne entre guillemets doubles par le nom de connexion à la base de données que vous avez choisi à l'étape 9. Enregistrez les modifications apportées au fichier.
connection: "<YOUR_CONNECTION_NAME>"
  1. Configurez un dépôt dans lequel enregistrer votre projet. Sélectionnez "Configure Git" (Configurer Git). en haut à droite. Sélectionnez "Configurer un dépôt simple à la place". Sélectionnez "Créer un dépôt".
  2. Vous disposez désormais d'un référentiel simple pour stocker vos fichiers de projet LookML. Revenez au projet dans l'IDE Looker en sélectionnant "Retour au projet" ou revenez en arrière manuellement.
  3. Cochez la case "Valider LookML". dans le coin supérieur droit. Le bouton deviendra "Valider les modifications et transférer".
  4. Cochez la case "Valider les modifications et les transférer" . Ajoutez le message de votre choix et sélectionnez "Commit".
  5. Sélectionnez "Deploy to Production" (Déployer en production). dans le coin supérieur droit de l'IDE Looker. Vous avez maintenant ajouté l'extension à votre instance Looker.
  6. Accédez au tableau de bord Looker auquel vous souhaitez ajouter l'extension.
  7. Suivez les instructions pour ajouter une vignette d'extension à votre tableau de bord. Ajoutez votre nouvelle extension à votre tableau de bord en tant que vignette.
  8. Assurez-vous que le service de backend WebSocket local que vous avez configuré précédemment s'exécute.

Félicitations ! Vous pouvez maintenant essayer l'extension de synthèse du tableau de bord Looker dans votre tableau de bord. Votre extension enverra les métadonnées de votre tableau de bord à votre service de backend WebSocket local et affichera la sortie Gemini de votre service de backend directement dans la vignette de l'extension de votre tableau de bord.

Lorsque votre serveur frontend local est en cours d'exécution, vous pouvez modifier le code source JavaScript de l'extension. Le serveur génère et diffuse automatiquement les modifications. Pour voir les modifications, vous devez actualiser la page de votre extension ou de votre tableau de bord.

4. Déployer le backend en production

Dans cette section, vous allez maintenant configurer le service de backend websocket pour diffuser toutes les instances de l'extension de synthèse de votre tableau de bord sur n'importe quel tableau de bord de votre instance Looker. Les autres utilisateurs de Looker pourront ainsi tester l'extension dans leurs propres tableaux de bord sans avoir à configurer leur propre service de backend. Cette procédure suppose que vous avez déjà déployé le backend pour un développement local dans le même environnement local.

  1. Suivez ces instructions pour configurer des identifiants par défaut de l'application dans votre environnement local avec l'ID de votre projet lors des prochaines étapes.
  2. Créez un dépôt Artifact Registry pour les images Docker de votre service de backend. Remplacez YOUR_REGION par la région dans laquelle vous souhaitez placer votre dépôt.
gcloud artifacts repositories create dashboard-summarization-repo \
    --repository-format=docker \
    --location=YOUR_REGION \
  1. Accédez au répertoire src du backend de socket Web de votre dépôt cloné.
cd ~/dashboard-summarization/websocket-service/src
  1. Modifiez le fichier cloudbuild.yaml et remplacez toutes les instances de YOUR_REGION et YOUR_PROJECT_ID par votre région et l'ID de votre projet. Enregistrez les modifications apportées au fichier.
  2. Envoyez à l'aide de Cloud Build une compilation qui générera l'image Docker du service de backend et la transférera vers le dépôt Artifact Registry que vous venez de créer. Remplacez YOUR_REGION par la région dans laquelle vous souhaitez utiliser le service Cloud Build.
gcloud builds submit --region=YOUR_REGION --config cloudbuild.yaml
  1. N'oubliez pas que l'URL de votre image Docker que vous venez de créer est YOUR_REGION-docker.pkg.dev/YOUR_PROJECT_ID/dashboard-summarization-repo/websocketserviceimage:latest. Remplacez YOUR_PROJECT_ID par l'ID de votre projet. Remplacez YOUR_REGION par la région de l'étape 2 que vous avez utilisée pour créer votre dépôt Artifact Registry.
  2. Accédez au répertoire websocket-service/terraform de votre dépôt cloné.
cd ~/dashboard-summarization/websocket-service/terraform
  1. Déterminez l'emplacement de Google Cloud Run dans lequel vous souhaitez exécuter votre service de backend WebSocket. Choisissez parmi ces zones.
  2. Modifiez le fichier variables.tf et remplacez YOUR_PROJECT_ID et YOUR_DOCKER_IMAGE_URL par les valeurs appropriées. Vérifiez l'URL de votre image Docker à l'étape 6. Remplacez YOUR_REGION par la région que vous avez choisie à l'étape 8 précédente. Enregistrez les modifications apportées au fichier.
  3. Déployez les ressources que votre service de backend utilisera à l'aide de Terraform.
terraform init
terraform plan
terraform apply
  1. Enregistrez le point de terminaison d'URL Cloud Run déployé pour la section suivante.

Félicitations ! Vous avez déployé votre service de backend WebSocket, qui s'exécute maintenant sur Google Cloud Run. Toutes les instances de l'extension de synthèse du tableau de bord Looker peuvent désormais communiquer avec votre service de backend. Nous vous recommandons de toujours disposer d'au moins une instance de votre service de backend WebSocket en cours d'exécution sur Cloud Run. La persistance de votre service de backend préserve l'intégrité du flux de données entre votre service de backend WebSocket et l'interface de votre extension, et contribue à maintenir la session de chaque utilisateur lorsqu'il utilise l'extension.

5. Déployer l'interface en production

Dans cette dernière section, vous effectuerez les dernières étapes du déploiement de l'interface de l'extension afin qu'elle soit accessible à tous les utilisateurs Looker dans votre instance Looker.

  1. Accédez au répertoire racine de votre dépôt cloné.
cd ~/dashboard-summarization
  1. Modifiez le fichier .Fichier env. Remplacez YOUR_CLOUD_RUN_URL par le point de terminaison d'URL Cloud Run de la section précédente. Enregistrez les modifications apportées au fichier. L'interface de l'extension de production pointera ainsi vers votre service de backend WebSocket exécuté sur Cloud Run.
  2. Créez le code JavaScript de l'extension. Un répertoire dist sera automatiquement généré avec un fichier bundle.js et d'autres fichiers.
npm run build
  1. Ouvrez un navigateur Web et connectez-vous à votre instance Looker. Ouvrez le menu de navigation latéral de gauche et activez le mode Développement. en bas de l'écran.
  2. Dans le menu de navigation latéral de gauche, sélectionnez "Develop" (Développer), puis faites défiler l'écran vers le bas et sélectionnez "dashboard-summarization" (Résumé du tableau de bord), le projet LookML de votre extension. Vous devriez à présent vous trouver dans l'IDE Looker du projet LookML.
  3. Glissez-déposez tous les fichiers du répertoire "dist" précédemment généré vers le répertoire racine du projet, dans "File Browser" (Explorateur de fichiers). Si vous avez besoin d'aide, suivez ces instructions.
  4. Ouvrez le fichier manifest.lkml dans l'IDE Looker. Dans le fichier, remplacez la ligne
url: "http://localhost:8080/bundle.js"

avec

file: "bundle.js"

Remplacez YOUR_CLOUD_RUN_URL par le point de terminaison d'URL Cloud Run indiqué à la fin de la dernière section. Enregistrez les modifications apportées au fichier.

  1. Cochez la case "Valider LookML". dans le coin supérieur droit. Le bouton deviendra "Valider les modifications et transférer".
  2. Cochez la case "Valider les modifications et les transférer" . Ajoutez le message de votre choix et sélectionnez "Commit".
  3. Sélectionnez "Deploy to Production" (Déployer en production). dans le coin supérieur droit de l'IDE Looker.

Félicitations ! Vous avez maintenant autorisé tous les utilisateurs Looker de votre instance Looker à ajouter l'extension de synthèse du tableau de bord Looker à leurs tableaux de bord. Lorsque d'autres utilisateurs de Looker utilisent l'extension, toutes ses instances effectuent des appels vers le service de backend WebSocket déployé qui s'exécute sur Google Cloud Run.

N'oubliez pas que si vous apportez des modifications au code source, vous devez:

  1. Recompiler le code JavaScript de votre extension
  2. Remplacez les fichiers générés que vous avez ajoutés au projet LookML par les nouveaux fichiers générés à partir du répertoire dist.
  3. Valider, valider et déployer les modifications du projet LookML en production

Essayez l'extension de synthèse du tableau de bord Looker ! Nous vous encourageons à contribuer à l'extension et à l'aider à mieux répondre aux besoins de la communauté Looker. N'hésitez pas à effectuer une demande d'extraction dans le dépôt.

Consultez les sections facultatives suivantes pour activer l'exportation Slack/Google Chat, affiner les résumés et les étapes suivantes de Gemini, et configurer la journalisation Gemini.

6. [Facultatif] Configurer les fonctionnalités d'exportation

Maintenant que vous et vos utilisateurs Looker avez essayé l'extension de synthèse du tableau de bord Looker, vous pouvez partager les informations de l'extension avec une audience plus large. Suivez cette section pour autoriser votre extension à envoyer des résumés et les prochaines étapes à Google Chat ou Slack. Vous devez vous familiariser avec la configuration OAuth pour poursuivre cette section de l'atelier de programmation.

Activer l'exportation Google Chat

  1. activer l'API Chat dans votre projet Google Cloud ;
  2. Suivez l'étape 1 des instructions de configuration OAuth de Google Workspace. Pour les niveaux d'accès, vous devez inclure spaces.messages.create.
  3. Suivez l'étape 2 des instructions de configuration OAuth de Google Workspace. Ajoutez l'URL de votre instance Looker en tant qu'URI sous "Origines JavaScript autorisées", par exemple https://mycompany.cloud.looker.com. Notez l'ID client généré.
  4. Déterminez l'ID de l'espace Google Chat vers lequel vous souhaitez exporter les résumés. Si vous ne savez pas comment faire, suivez ces instructions.
  5. Modifiez le fichier .Fichier env. Remplacez YOUR_GOOGLE_CLIENT_ID par l'ID client. Remplacez YOUR_GOOGLE_SPACE_ID par l'ID de l'espace Google Chat. Enregistrez les modifications apportées au fichier. Cette action permet de configurer l'interface de votre extension afin de pouvoir envoyer ses insights à l'espace Google Chat de votre choix.
  6. Si vous exécutez l'interface de votre extension localement, recompilez-la. Si vous déployez l'interface de votre extension, redéployez l'interface de votre extension.

Activer l'exportation Slack

  1. Suivez les étapes 1 et 2 de la documentation officielle pour les développeurs Slack pour configurer une application OAuth. Pour les niveaux d'accès, vous devez inclure chat:write et channels:read. Notez l'ID client et le code secret du client générés.
  2. Déterminez l'ID de la chaîne Slack vers laquelle vous souhaitez exporter les résumés.
  3. Modifiez le fichier .Fichier env. Remplacez YOUR_SLACK_CLIENT_ID par l'ID client. Remplacez YOUR_SLACK_CLIENT_SECRET par le code secret du client. Remplacez YOUR_SLACK_CHANNEL_ID par l'ID de la chaîne. Enregistrez les modifications apportées au fichier. Cela permet de configurer l'interface de votre extension afin qu'elle puisse envoyer ses insights au canal Slack de votre choix.
  4. Si vous exécutez l'interface de votre extension localement, recompilez-la. Si vous déployez l'interface de votre extension, redéployez l'interface de votre extension.

Votre extension peut désormais exporter ses résumés directement vers Slack ou Google Chat. N'oubliez pas que l'extension ne peut envoyer de résumés qu'à un espace Chat Google ou à une chaîne Slack spécifique codé en dur. Vous pouvez ajouter des habilitations OAuth supplémentaires et modifier le code pour récupérer et afficher la liste des espaces et des canaux auxquels envoyer des résumés.

7. [Facultatif] Affiner le résumé et les étapes suivantes

L'extension envoie au modèle Gemini toutes les métadonnées et données de requêtes du tableau de bord. Vous pouvez améliorer la précision, le détail et la profondeur des résumés et des étapes normatives en ajoutant autant de métadonnées et de contexte au tableau de bord lui-même. Essayez ces étapes pour chaque tableau de bord dont votre extension fait partie:

  • Pour ajouter des détails au tableau de bord, suivez ces instructions. Cela aidera le LLM à se familiariser avec le contexte général du tableau de bord.
  • Pour ajouter des notes à la vignette de chaque tableau de bord, suivez ces instructions. Cela permettra d'informer le LLM du contexte de chaque requête individuelle sur le tableau de bord. Les petites remarques contextuelles seront prises en compte dans les résumés générés.

Plus vous ajouterez d'informations à vos tableaux de bord, meilleurs seront les résumés et les prochaines étapes de l'extension. Vous pouvez modifier le code pour inclure des métadonnées de tableau de bord supplémentaires dans la requête destinée au modèle Gemini.

8. [Facultatif] Configurer la journalisation du modèle Gemini

Chaque fois qu'un utilisateur demande à l'extension de créer des résumés pour un tableau de bord, l'extension appelle Vertex AI pour chaque requête du tableau de bord et effectue un dernier appel pour mettre en forme tous les résumés. Suivez cette section pour enregistrer les appels Vertex AI passés par votre extension. Vous pourrez ainsi estimer et surveiller les coûts et le trafic de Vertex AI. Vous ne devez suivre ces instructions que si vous avez déployé le service de backend Websocket.

  1. Déterminez l'emplacement Cloud Run du service de backend WebSocket déployé.
  2. Suivez ces instructions pour configurer un récepteur de journaux qui achemine les journaux vers BigQuery. La destination du récepteur doit être BigQuery. Définissez le filtre d'inclusion avec l'exemple de code suivant en remplaçant YOUR_CLOUD_RUN_LOCATION par l'emplacement Cloud Run de l'étape précédente.
resource.type = "cloud_run_revision"
resource.labels.service_name = "websocket-service"
resource.labels.location = "YOUR_CLOUD_RUN_LOCATION"
 severity>=DEFAULT
jsonPayload.component="dashboard-summarization-logs"

9. Félicitations !

Vous avez configuré l'extension de synthèse du tableau de bord Looker localement pour que vous puissiez l'essayer. Vous avez également déployé l'extension sur Google Cloud afin que d'autres utilisateurs puissent également l'essayer. Vous et les autres utilisateurs pouvez désormais accéder aux résumés générés par Gemini et aux prochaines étapes directement depuis vos tableaux de bord.

10. Étape suivante