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

Fonctionnellement, l'extension de résumé 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. L'extension utilise une application frontale React associée à un service backend websocket pour envoyer et recevoir des données depuis et vers le modèle Gemini de Vertex AI.

Prérequis

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

Points abordés

  • Configurer et développer l'extension en local
  • Déployer l'extension en production pour que les autres utilisateurs de votre instance Looker puissent l'utiliser
  • Comment affiner les performances de l'extension et étendre ses fonctionnalités (facultatif)
  • Gérer votre extension déployée en production

Prérequis

  • Une instance Looker, via une licence Looker d'origine, une licence d'essai Looker Core active ou une licence Looker Core active.
  • 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 avec la facturation activée
  • API Cloud Run, API Vertex AI et API Artifact Registry activées sur le projet.
  • Accès à un environnement local avec la CLI gcloud installée. Les étapes de l'atelier de programmation partent du principe que vous utilisez 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 afin de pouvoir le tester et le développer localement. Le service aura accès à Vertex AI.

  1. Installez la version 18 ou ultérieure de Node 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 Web Socket 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 avec 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 à partir de laquelle votre backend local enverra et recevra des données du modèle Gemini de Vertex AI. 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 backend. Vous devez d'abord arrêter le processus de service, modifier le code, puis exécuter à nouveau npm start.

3. Configurer le frontend 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 project Dashboard-summarization. Le projet LookML vierge devrait maintenant s'ouvrir automatiquement dans l'IDE Looker dans l'onglet de votre navigateur actuel.
  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 le bouton "Enregistrer les modifications" en haut à droite pour enregistrer les modifications apportées au fichier.
  6. Dans un onglet de navigateur distinct, accédez à la liste des connexions de base de données de votre instance Looker. Suivez ces instructions si vous ne savez pas comment procéder.
  7. Choisissez le nom d'une connexion de 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 la 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 le bouton "Configure Git" (Configurer Git) en haut à droite. Sélectionnez "Configurer plutôt un dépôt nu". Sélectionnez "Créer un dépôt".
  2. Vous disposez désormais d'un dépôt nu de base dans lequel stocker les fichiers de votre projet LookML. Revenez au projet dans l'IDE Looker en sélectionnant "Retour au projet" ou en revenant manuellement.
  3. Sélectionnez le bouton "Valider LookML" en haut à droite. Le bouton deviendra "Valider les modifications et transférer".
  4. Sélectionnez le bouton "Valider les modifications et envoyer". 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 carte.
  8. Assurez-vous que le service de backend WebSocket local que vous avez configuré précédemment s'exécute.

Félicitations ! Vous pouvez désormais tester 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 backend websocket local et affichera la sortie Gemini de votre service backend directement dans la carte de l'extension de votre tableau de bord.

Lorsque votre serveur d'interface utilisateur local est en cours d'exécution, vous pouvez modifier le code source JavaScript de l'extension. Le serveur compilera et diffusera automatiquement les modifications. Vous devrez actualiser la page de votre extension ou de votre tableau de bord pour voir les modifications.

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 backend. Remplacez YOUR_REGION par la région dans laquelle vous souhaitez que votre dépôt se trouve.
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 nouvelle image Docker 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 lieux.
  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 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 backend WebSocket, et il s'exécute désormais 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 avoir au moins une instance de votre service 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 utilisateur 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 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 est automatiquement généré, contenant un fichier bundle.js et d'autres fichiers.
npm run build
  1. Ouvrez un navigateur Web et connectez-vous à votre instance Looker. Ouvrez le panneau de navigation latéral de gauche, puis activez le bouton "Mode développement" en bas.
  2. Dans le menu de navigation latéral de gauche, sélectionnez "Develop" (Développer), puis faites défiler la page 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. Sélectionnez le bouton "Valider LookML" en haut à droite. Le bouton change d'apparence et affiche "Valider les modifications et envoyer".
  2. Sélectionnez le bouton "Valider les modifications et envoyer". Ajoutez le message de votre choix et sélectionnez "Commit".
  3. Sélectionnez "Déployer en production" en haut à droite de l'IDE Looker.

Félicitations ! Vous avez maintenant autorisé tous les utilisateurs Looker de votre instance Looker à ajouter l'extension de synthèse des tableaux de bord Looker à leurs tableaux de bord. Lorsque d'autres utilisateurs de Looker utilisent l'extension, toutes les instances de l'extension appellent votre service backend WebSocket déployé 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 fichiers nouvellement 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 invitons à contribuer à l'extension et à l'aider à mieux répondre aux besoins de la communauté Looker. N'hésitez pas à créer une demande d'extraction sur 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 des tableaux de bord Looker, vous pouvez partager les insights de l'extension avec un public plus large. Suivez cette section pour autoriser votre extension à envoyer des résumés et des étapes suivantes à Google Chat ou Slack. Vous devez connaître 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 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 vers 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 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 à votre fichier. Cela configurera l'interface de votre extension pour 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 une liste d'espaces et de canaux auxquels envoyer des récapitulatifs.

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

L'extension fournit au modèle Gemini toutes les métadonnées et les 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 prescriptives en ajoutant autant de métadonnées et de contexte que possible au tableau de bord lui-même. Suivez ces étapes pour chaque tableau de bord auquel votre extension est associée :

  • Suivez ces instructions pour ajouter des détails au tableau de bord. Cela permet d'informer le LLM du contexte général du tableau de bord.
  • Pour ajouter des notes à la vignette de chaque tableau de bord, suivez ces instructions. Cela permet d'informer le LLM du contexte de chaque requête individuelle du 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 des modèles 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, puis effectue un dernier appel pour mettre en forme tous les résumés. Suivez cette section pour consigner les appels Vertex AI effectués par votre extension afin d'estimer et de surveiller les coûts et le trafic 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 pouvoir la tester. Vous avez également déployé l'extension dans Google Cloud pour 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