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

1. Avant de commencer

Dans cet atelier de programmation, vous allez (1) configurer l'extension de résumé de tableau de bord Looker en local pour pouvoir la tester et la développer. Ensuite (2), vous déploierez l'extension en production afin que les 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.

Présentation de l'extension de résumé du tableau de bord Looker

D'un point de vue fonctionnel, l'extension de synthèse des tableaux 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 une prescription des prochaines étapes. L'extension affiche le résumé et les prochaines étapes sous forme de vignette dans votre tableau de bord, s'intégrant ainsi à votre expérience. L'extension peut également exporter le résumé et les prochaines étapes vers Slack ou Google Chat. L'extension utilise une application frontend React associée à un service backend WebSocket pour envoyer et recevoir des données vers et depuis le modèle Gemini de Vertex AI.

Prérequis

  • Connaissances de base du développement Node, de Docker et de Terraform
  • Connaissances de 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 Looker de votre instance puissent l'utiliser
  • Découvrez 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, soit avec une licence Looker (Original), soit avec un essai Looker Core actif, soit avec une licence Looker Core active.
  • Les autorisations develop et deploy sur votre instance Looker.
  • Autorisations pour modifier un tableau de bord que vous souhaitez tester avec l'extension.
  • Une clé API Looker de votre instance Looker.
  • Un projet Google Cloud avec la facturation activée.
  • Les API Cloud Run, Vertex AI et Artifact Registry sont activées sur le projet.
  • Accès à un environnement local avec gcloud CLI installé. 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 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.
  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 cet atelier de programmation, tous les exemples de code supposent que votre 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 pouvoir définir des variables d'environnement dans les sections ultérieures de cet atelier de programmation.
cd ~/dashboard-summarization
mv .env.example .env
  1. Accédez au répertoire src du backend WebSocket 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 le fichier looker.ini, mettez à jour les éléments suivants :
  2. Remplacez client_id et client_secret par ceux de votre clé API Looker.
  3. Le base_url avec l'URL de votre instance Looker au format suivant : https://<YOUR_LOOKER_URL_MINUS_PROTOCOL>:19999
  4. Le texte entre 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 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. Déterminez l'ID de votre 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 fournit le modèle Gemini dans plusieurs régions listées ici. 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. Démarrez maintenant votre service local.
npm start
  1. Votre service de backend WebSocket local s'exécutera sur http://localhost:5000.

Vous avez terminé de configurer le service de backend WebSocket dans votre environnement local.

Ce service sert d'interface entre votre extension de frontend et le modèle Gemini de Vertex AI. Le service récupère les données LookML et de tableau de bord de votre extension de frontend avec les données interrogées à partir de Looker, puis invite le modèle Gemini de Vertex AI. Le service diffusera ensuite la réponse de Gemini à l'extension frontend pour qu'elle s'affiche dans votre tableau de bord.

Vous pouvez également modifier le code source du service de backend. Vous devrez 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 l'interface utilisateur pour la tester et la développer en local.

  1. Dans le même environnement local que lors des é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 désormais 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 "summarization-dashboard". Le projet LookML vide devrait maintenant s'ouvrir automatiquement dans l'IDE Looker dans l'onglet de navigateur actuel.
  4. Créez un fichier manifeste du projet à la racine du projet LookML. Le fichier s'appellera manifest.lkml. Si vous ne savez pas comment faire, suivez ces instructions pour ajouter un fichier à un projet LookML.
  5. Remplacez le contenu du nouveau fichier manifest.lkml par celui du fichier manifest.lkml 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 autre onglet de navigateur, accédez à la liste des connexions de base de données dans votre instance Looker. Si vous ne savez pas comment faire, suivez ces instructions.
  7. Choisissez le nom d'une connexion à une base de données Looker. Le choix de la connexion n'a pas d'importance. Si vous n'êtes pas autorisé à afficher 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 de navigateur contenant votre projet LookML ouvert dans un IDE Looker. Créez un fichier de modèle dans votre projet LookML et nommez-le "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 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 pour enregistrer votre projet. Sélectionnez le bouton "Configurer Git" en haut à droite. Sélectionnez "Set up a bare repository instead" (Configurer un dépôt vide à la place). Sélectionnez "Créer un dépôt".
  2. Vous disposez maintenant d'un dépôt vide de base pour stocker les fichiers de votre projet LookML. Revenez au projet dans l'IDE Looker en sélectionnant "Retour au projet" ou en revenant manuellement en arrière.
  3. Sélectionnez le bouton "Valider le LookML" en haut à droite. Le bouton devient "Valider les modifications et envoyer".
  4. Sélectionnez le bouton "Commit changes and push" (Valider les modifications et les envoyer). Ajoutez le message de votre choix, puis sélectionnez "Valider".
  5. Sélectionnez "Déployer en production" en haut à droite de l'IDE Looker. Vous avez 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 tuile d'extension à votre tableau de bord. Ajoutez votre nouvelle extension à votre tableau de bord sous forme de vignette.
  8. Assurez-vous que le service de backend WebSocket local que vous avez configuré précédemment est en cours d'exécution.

Félicitations ! Vous pouvez désormais essayer l'extension de résumé 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 le bloc de l'extension de votre tableau de bord.

Tant que votre serveur frontend 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 recharger 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 configurer le service de backend WebSocket pour diffuser toutes les instances de votre extension de synthèse de tableau de bord sur n'importe quel tableau de bord de votre instance Looker. Cela permettra aux autres utilisateurs Looker de 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 le développement local dans le même environnement local.

  1. Suivez ces instructions pour configurer un identifiant par défaut de l'application dans votre environnement local avec l'ID de votre projet pour les 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 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 WebSocket 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 votre ID de projet. Enregistrez les modifications apportées au fichier.
  2. Envoyez une compilation à l'aide de Cloud Build. Elle créera l'image Docker du service de backend et la transférera dans 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 l'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 dans votre dépôt cloné.
cd ~/dashboard-summarization/websocket-service/terraform
  1. Déterminez l'emplacement de Google Cloud Run sur 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. Consultez l'étape 6 pour obtenir l'URL de votre image Docker. 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 de l'URL Cloud Run déployée pour la section suivante.

Félicitations ! Vous avez déployé votre service de backend WebSocket, qui s'exécute désormais sur Google Cloud Run. Toutes les instances de votre extension de synthèse de tableaux 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 de backend WebSocket en cours d'exécution sur Cloud Run. La persistance de votre service de backend maintient l'intégrité des données diffusées entre votre service de backend WebSocket et le frontend de votre extension, et permet de maintenir la session de chaque utilisateur lorsqu'il utilise votre extension.

5. Déployer l'interface en production

Dans cette dernière section, vous allez effectuer les dernières étapes du déploiement du frontend de l'extension pour qu'il soit disponible pour tous les utilisateurs Looker de 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 de l'URL Cloud Run de la section précédente. Enregistrez les modifications apportées à votre fichier. Cela redirigera l'interface de production de l'extension 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 panneau de navigation de gauche et activez l'option "Mode Développement" en bas de l'écran.
  2. Une fois le panneau de navigation de gauche ouvert, sélectionnez "Develop" (Développer), puis faites défiler la page vers le bas et sélectionnez "dashboard-summarization", le projet LookML de votre extension. Vous devriez maintenant vous trouver dans l'IDE Looker pour le projet LookML.
  3. Dans l'explorateur de fichiers, faites glisser et déposez tous les fichiers du répertoire "dist" généré précédemment dans le répertoire racine du projet. Suivez ces instructions si vous avez besoin d'aide.
  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 de l'URL Cloud Run de la fin de la section précédente. Enregistrez les modifications apportées au fichier.

  1. Sélectionnez le bouton "Valider le LookML" en haut à droite. Le bouton devient "Valider les modifications et envoyer".
  2. Sélectionnez le bouton "Commit changes and push" (Valider les modifications et les envoyer). Ajoutez le message de votre choix, puis sélectionnez "Valider".
  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 résumé de tableau de bord Looker à leurs tableaux de bord. Lorsque d'autres utilisateurs Looker utilisent l'extension, toutes les instances de l'extension appellent votre service de 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 aviez 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 résumé 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 à 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 prochaines étapes de Gemini, et configurer la journalisation Gemini.

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

Maintenant que vous et vos utilisateurs Looker avez testé l'extension de synthèse des tableaux de bord Looker, partageons les insights de l'extension avec un public plus large. Suivez cette section pour permettre à votre extension d'envoyer des résumés et des prochaines étapes à Google Chat ou Slack. Vous devez être familiarisé avec la configuration d'OAuth pour poursuivre cette section de l'atelier de programmation.

Activer l'exportation Google Chat

  1. Activez 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 à votre fichier. Cela configurera le frontend de votre extension pour qu'il puisse envoyer ses insights à l'espace Google Chat de votre choix.
  6. Si vous exécutez le frontend de votre extension en local, recompilez-la. Sinon, si vous déployez le frontend de votre extension, redéployez-le.

Activer l'exportation vers Slack

  1. Suivez les étapes 1 et 2 de la documentation officielle pour les développeurs Slack afin de 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 du canal Slack vers lequel vous souhaitez exporter les résumés.
  3. Modifiez le .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 du canal. Enregistrez les modifications apportées à votre fichier. Cela configurera le frontend de votre extension pour qu'il puisse envoyer ses insights au canal Slack de votre choix.
  4. Si vous exécutez le frontend de votre extension en local, recompilez-la. Sinon, si vous déployez le frontend de votre extension, redéployez-le.

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 des résumés qu'à un espace Google Chat ou un canal Slack spécifiques codés 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 chaînes auxquels envoyer des résumés.

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

L'extension invite le modèle Gemini avec toutes les métadonnées et les données de requête du tableau de bord. Vous pouvez améliorer la précision, le niveau de 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. Essayez ces étapes pour chaque tableau de bord dont votre extension fait partie :

  • Suivez ces instructions pour ajouter des détails au tableau de bord. Cela aidera le LLM à comprendre le contexte général du tableau de bord.
  • Suivez ces instructions pour ajouter des notes à chaque tuile du tableau de bord. Cela aidera le LLM à comprendre le contexte de chaque requête individuelle dans le tableau de bord. Les petites notes contextuelles seront prises en compte dans les résumés générés.

Plus vous ajoutez d'informations à vos tableaux de bord, plus les résumés et les prochaines étapes de l'extension seront pertinents. Vous pouvez modifier le code pour inclure des métadonnées de tableau de bord supplémentaires dans la requête adressé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, plus un appel final pour mettre en forme tous les résumés. Suivez cette section pour enregistrer 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 de votre service de backend WebSocket déployé.
  2. Suivez ces instructions pour configurer un récepteur de journaux qui acheminera 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 résumé du tableau de bord Looker en local pour que vous puissiez la tester. Vous avez également déployé l'extension sur Google Cloud pour que d'autres utilisateurs puissent l'essayer. Vous et les autres utilisateurs pouvez désormais accéder aux résumés et aux prochaines étapes générés par Gemini directement dans vos tableaux de bord.

10. Étape suivante