Codelab sulle estensioni di riepilogo della dashboard di Looker

1. Prima di iniziare

In questo codelab (1) configurerai l'estensione di riepilogo della dashboard di Looker in locale per provarla e svilupparla localmente. Poi (2) devi eseguire il deployment dell'estensione in produzione in modo che altri utenti di Looker nella tua istanza di Looker possano utilizzarla. Infine, (3) puoi seguire passaggi aggiuntivi per perfezionare e migliorare la funzionalità dell'estensione. Tutte le sezioni non facoltative devono essere completate in ordine sequenziale.

Panoramica dell'estensione di riepilogo della dashboard di Looker

A livello funzionale, l'estensione di riepilogo della dashboard di Looker invia i dati della dashboard di Looker al modello Gemini di Vertex AI. Il modello Gemini restituisce quindi un riepilogo dei dati della dashboard e una prescrizione dei passaggi successivi. L'estensione mostra il riepilogo e i passaggi successivi come riquadro nella dashboard, integrandosi nell'esperienza della dashboard. Inoltre, l'estensione può esportare il riepilogo e i passaggi successivi in Slack o Google Chat. L'estensione utilizza un'applicazione frontend React accoppiata a un servizio di backend websocket per inviare e ricevere dati da e verso il modello Gemini di Vertex AI.

Prerequisiti

  • Conoscenza di base dello sviluppo di Node, Docker e Terraform
  • Familiarità con la configurazione di un progetto LookML di Looker

Cosa imparerai a fare

  • Come configurare e sviluppare l'estensione localmente
  • Come eseguire il deployment dell'estensione in produzione in modo che altri utenti di Looker nell'istanza di Looker possano utilizzarla
  • Come ottimizzare facoltativamente il rendimento dell'estensione ed estenderne la funzionalità.
  • Come gestire l'estensione di cui è stato eseguito il deployment in produzione

Che cosa ti serve

  • Un'istanza di Looker, tramite una licenza originale di Looker, una prova attiva di Looker Core o una licenza Looker Core attiva.
  • develop e deploy nella tua istanza Looker.
  • Autorizzazioni per modificare una dashboard che vuoi provare con l'estensione.
  • Una chiave API Looker della tua istanza Looker.
  • Un progetto Google Cloud con la fatturazione abilitata.
  • API Cloud Run, API Vertex AI e API Artifact Registry abilitate nel progetto.
  • Accesso a un ambiente locale con gcloud CLI installata. I passaggi del codelab presuppongono un ambiente in stile Linux.

2. Configura il backend per lo sviluppo locale

In questa sezione configurerai il servizio di backend websocket da provare e sviluppare localmente. Il servizio avrà accesso a Vertex AI.

  1. Installa Node versione 18 o successive nel tuo ambiente locale. Segui queste istruzioni per installare Node.
  2. Clona il repository dell'estensione nella home directory locale e vai alla directory radice del repository. Ai fini di questo codelab, tutti gli esempi di codice presuppongono che il repository clonato si trovi nella home directory locale.
cd ~
git clone git@github.com:looker-open-source/dashboard-summarization.git
  1. Vai alla directory principale del repository clonato e rinomina il file .env.example in .env per consentirti di impostare le variabili di ambiente nelle sezioni successive di questo codelab.
cd ~/dashboard-summarization
mv .env.example .env
  1. Vai alla directory src del backend del socket web del repository clonato. Questa directory contiene il codice sorgente del server.
cd ~/dashboard-summarization/websocket-service/src
  1. Installa le dipendenze del servizio con NPM.
npm install
  1. Rinomina il file looker-example.ini in looker.ini.
mv looker-example.ini looker.ini
  1. All'interno dell'aggiornamento del file looker.ini:
  2. client_id e client_secret con quelli della tua chiave API Looker.
  3. Il base_url con l'URL dell'istanza di Looker nel formato: https://<YOUR_LOOKER_URL_MINUS_PROTOCOL>:19999
  4. Il testo tra le parentesi (l'intestazione della sezione) con l'host dell'URL dell'istanza Looker.

Ad esempio, se il tuo ID client è ABC123, il tuo client secret è XYZ789 e l'URL della tua istanza di Looker è https://mycompany.cloud.looker.com, il tuo file looker.ini avrà esattamente questo aspetto:

[mycompany]
base_url=https://mycompany.cloud.looker.com:19999
client_id=ABC123
client_secret=XYZ789
verify_ssl=true
  1. Determina l'ID progetto Google Cloud e impostalo nella variabile di ambiente PROJECT. Sostituisci YOUR_PROJECT_ID con l'ID progetto.
export PROJECT="YOUR_PROJECT_ID"
  1. Vertex AI fornisce il modello Gemini in più regioni elencate qui. Determina la regione da cui il backend locale invierà e riceverà i dati dal modello Gemini di Vertex AI. Imposta la regione nella variabile di ambiente REGION. Sostituisci YOUR_VERTEX_REGION con la tua regione, ad esempio us-central1.
export REGION="YOUR_VERTEX_REGION"
  1. Ora avvia il servizio locale.
npm start
  1. Il servizio di backend websocket locale verrà eseguito su http://localhost:5000.

Ora hai completato la configurazione del servizio di backend websocket nel tuo ambiente locale.

Il servizio funge da interfaccia tra l'estensione frontend e il modello Gemini di Vertex AI. Il servizio prenderà i dati del dashboard e di LookML dall'estensione frontend con i dati interrogati da Looker e chiederà al modello Gemini di Vertex AI. Il servizio trasmetterà in streaming la risposta di Gemini all'estensione frontend da visualizzare nella dashboard.

Puoi anche apportare modifiche al codice sorgente del servizio di backend. Devi prima arrestare il processo del servizio, apportare modifiche al codice e poi eseguire di nuovo npm start.

3. Configura il frontend per lo sviluppo locale

In questa sezione configurerai l'estensione frontend da provare e sviluppare localmente.

  1. Nello stesso ambiente locale dei passaggi precedenti, vai alla directory principale del repository clonato e installa le dipendenze del server frontend per il frontend.
cd ~/dashboard-summarization
npm install
  1. Avvia il server di sviluppo frontend locale
npm run develop
  1. Il server frontend locale ora pubblica il codice JavaScript dell'estensione all'indirizzo http://localhost:8080/bundle.js.
  2. Apri un browser web e accedi alla tua istanza di Looker.
  3. Segui queste istruzioni per configurare un progetto LookML vuoto. Assegna un nome al riepilogo della dashboard del progetto. Ora dovresti visualizzare il progetto LookML vuoto aperto automaticamente nell'IDE di Looker nella scheda del browser corrente.
  4. Crea un file manifest del progetto nella radice del progetto LookML. Il file si chiamerà manifest.lkml. Se non sai come fare, segui queste istruzioni per aggiungere un file a un progetto LookML.
  5. Sostituisci i contenuti del nuovo file manifest.lkml con i contenuti di manifest.lkml nella directory principale del repository chiuso. Seleziona il pulsante "Salva modifiche" nell'angolo in alto a destra per salvare le modifiche al file.
  6. In una scheda separata del browser, vai all'elenco delle connessioni al database nella tua istanza di Looker. Se non sai come fare, segui queste istruzioni.
  7. Scegli il nome di una connessione al database Looker. Non importa quale connessione scegli. Se non disponi dell'autorizzazione per visualizzare le connessioni al database, contatta l'amministratore di Looker e chiedi il nome di una connessione al database di Looker.
  8. Torna alla scheda del browser con il progetto LookML aperto in un IDE di Looker. Crea un file del modello nel tuo progetto LookML e chiamalo dashboard-summarization.
  9. Sostituisci i contenuti del file dashboard-summarization.model.lkml con l'esempio di codice riportato di seguito. Assicurati di sostituire la stringa tra le virgolette doppie con il nome della connessione al database che hai scelto nel passaggio 9. Salva le modifiche apportate al file.
connection: "<YOUR_CONNECTION_NAME>"
  1. Configura un repository in cui salvare il progetto. Seleziona il pulsante "Configura Git" in alto a destra. Seleziona "Configura invece un repository bare". Seleziona "Crea repository".
  2. Ora hai un repository bare di base in cui archiviare i file del progetto LookML. Torna al progetto nell'IDE di Looker selezionando "Torna al progetto" o tornando indietro manualmente.
  3. Seleziona il pulsante "Convalida LookML" nell'angolo in alto a destra. Il pulsante cambierà in "Esegui commit delle modifiche e push".
  4. Seleziona il pulsante "Esegui commit delle modifiche e push". Aggiungi il messaggio che preferisci e seleziona "Commit".
  5. Seleziona "Deploy to Production" (Esegui il deployment in produzione) nell'angolo in alto a destra dell'IDE di Looker. Ora hai aggiunto l'estensione alla tua istanza Looker.
  6. Vai a una dashboard di Looker a cui vuoi aggiungere l'estensione.
  7. Segui le istruzioni per aggiungere un riquadro dell'estensione alla dashboard. Aggiungi la nuova estensione alla dashboard come riquadro.
  8. Assicurati che il servizio di backend websocket locale che hai configurato in precedenza sia in esecuzione.

Complimenti! Ora puoi provare l'estensione di riepilogo della dashboard di Looker nella tua dashboard. L'estensione invierà i metadati della dashboard al servizio di backend websocket locale e mostrerà l'output di Gemini dal servizio di backend direttamente nel riquadro dell'estensione della dashboard.

Mentre il server frontend locale è in esecuzione, puoi apportare modifiche al codice sorgente JavaScript dell'estensione e il server creerà e pubblicherà automaticamente le modifiche. Per visualizzare le modifiche, devi ricaricare l'estensione o la pagina della dashboard.

4. Esegui il deployment del backend in produzione

In questa sezione configurerai il servizio di backend websocket per gestire qualsiasi istanza dell'estensione di riepilogo della dashboard in qualsiasi dashboard dell'istanza di Looker. In questo modo, altri utenti di Looker possono provare l'estensione nelle proprie dashboard senza dover configurare un proprio servizio di backend. Questi passaggi presuppongono che tu abbia già eseguito il deployment del backend per lo sviluppo locale nello stesso ambiente locale.

  1. Segui queste istruzioni per configurare una credenziale predefinita dell'applicazione nel tuo ambiente locale con l'ID progetto per i passaggi successivi.
  2. Crea un repository Artifact Registry per le immagini Docker del servizio di backend. Sostituisci YOUR_REGION con la regione in cui vuoi che si trovi il repository.
gcloud artifacts repositories create dashboard-summarization-repo \
    --repository-format=docker \
    --location=YOUR_REGION \
  1. Vai alla directory src del backend WebSocket del repository clonato.
cd ~/dashboard-summarization/websocket-service/src
  1. Modifica il file cloudbuild.yaml e sostituisci tutte le istanze di YOUR_REGION e YOUR_PROJECT_ID con la tua regione e il tuo ID progetto. Salva le modifiche apportate al file.
  2. Invia una build utilizzando Cloud Build che creerà l'immagine Docker del servizio di backend e ne eseguirà il push nel repository Artifact Registry che hai appena creato. Sostituisci YOUR_REGION con la regione in cui vuoi utilizzare il servizio Cloud Build.
gcloud builds submit --region=YOUR_REGION --config cloudbuild.yaml
  1. Ricorda che l'URL dell'immagine Docker appena creata è YOUR_REGION-docker.pkg.dev/YOUR_PROJECT_ID/dashboard-summarization-repo/websocketserviceimage:latest. Sostituisci YOUR_PROJECT_ID con l'ID progetto. Sostituisci YOUR_REGION con la regione del passaggio 2 che hai utilizzato per creare il repository Artifact Registry.
  2. Vai alla directory websocket-service/terraform nel repository clonato.
cd ~/dashboard-summarization/websocket-service/terraform
  1. Determina in quale località di Google Cloud Run vuoi eseguire il servizio di backend websocket. Scegli tra queste località.
  2. Modifica il file variables.tf e sostituisci YOUR_PROJECT_ID e YOUR_DOCKER_IMAGE_URL con i valori appropriati. Controlla il passaggio 6 per l'URL dell'immagine Docker. Sostituisci YOUR_REGION con la regione che hai scelto nel passaggio 8 precedente. Salva le modifiche apportate al file.
  3. Esegui il deployment delle risorse che il servizio di backend utilizzerà utilizzando Terraform.
terraform init
terraform plan
terraform apply
  1. Salva l'endpoint URL di Cloud Run di cui è stato eseguito il deployment per la sezione successiva.

Complimenti! Hai eseguito il deployment del servizio di backend WebSocket e ora è in esecuzione su Google Cloud Run. Ora tutte le istanze dell'estensione Riepilogo dashboard di Looker possono comunicare con il servizio di backend. Ti consigliamo di avere sempre almeno un'istanza del servizio di backend websocket in esecuzione su Cloud Run. La persistenza del servizio di backend mantiene l'integrità dello streaming di dati tra il servizio di backend WebSocket e il frontend dell'estensione e aiuta a mantenere la sessione di ogni utente mentre utilizza l'estensione.

5. Esegui il deployment del frontend in produzione

In quest'ultima sezione, eseguirai i passaggi finali per il deployment del frontend dell'estensione in modo che sia disponibile per tutti gli utenti Looker nella tua istanza Looker.

  1. Vai alla directory principale del repository clonato.
cd ~/dashboard-summarization
  1. Modifica il file .env. Sostituisci YOUR_CLOUD_RUN_URL con l'endpoint URL di Cloud Run della sezione precedente. Salva le modifiche apportate al file. In questo modo, il frontend dell'estensione di produzione punterà al servizio di backend WebSocket in esecuzione su Cloud Run.
  2. Crea il JavaScript dell'estensione. Verrà generata automaticamente una directory dist con un file bundle.js e altri file.
npm run build
  1. Apri un browser web e accedi alla tua istanza di Looker. Apri il menu di navigazione laterale a sinistra e attiva il pulsante di attivazione/disattivazione della "Modalità sviluppatore" in basso.
  2. Con il riquadro di navigazione a sinistra aperto, seleziona "Sviluppo", scorri verso il basso e seleziona "dashboard-summarization", il progetto LookML della tua estensione. Ora dovresti trovarti nell'IDE di Looker per il progetto LookML.
  3. Trascina tutti i file nella directory dist generata in precedenza nella directory principale del progetto in "Esplora file". Se hai bisogno di ulteriore assistenza, segui queste istruzioni.
  4. Apri il file manifest.lkml all'interno dell'IDE di Looker. All'interno del file, sostituisci la riga
url: "http://localhost:8080/bundle.js"

con

file: "bundle.js"

Sostituisci YOUR_CLOUD_RUN_URL con l'endpoint URL di Cloud Run alla fine dell'ultima sezione. Salva le modifiche apportate al file.

  1. Seleziona il pulsante "Convalida LookML" nell'angolo in alto a destra. Il pulsante cambierà in "Esegui commit delle modifiche e push".
  2. Seleziona il pulsante "Esegui commit delle modifiche e push". Aggiungi il messaggio che preferisci e seleziona "Commit".
  3. Seleziona "Deploy to Production" (Esegui il deployment in produzione) nell'angolo in alto a destra dell'IDE di Looker.

Complimenti! Ora hai consentito a tutti gli utenti di Looker della tua istanza di Looker di aggiungere l'estensione di riepilogo della dashboard di Looker alle loro dashboard. Man mano che altri utenti di Looker utilizzano l'estensione, tutte le istanze dell'estensione effettueranno chiamate al servizio di backend websocket di cui è stato eseguito il deployment in esecuzione su Google Cloud Run.

Tieni presente che, se apporti modifiche al codice sorgente, devi:

  1. Ricrea il JavaScript dell'estensione
  2. Sostituisci i file generati che avevi aggiunto al progetto LookML con i file appena generati dalla directory dist.
  3. Convalida, esegui il commit e il deployment delle modifiche al progetto LookML in produzione

Prova l'estensione di riepilogo della dashboard di Looker. Ti invitiamo a contribuire all'estensione e ad aiutarla a soddisfare meglio le esigenze della community di Looker. Non esitare a creare una richiesta di pull nel repository.

Consulta le seguenti sezioni facoltative per attivare l'esportazione di Slack/Google Chat, perfezionare i riepiloghi e i passaggi successivi di Gemini e configurare la registrazione di Gemini.

6. [Facoltativo] Configurare le funzionalità di esportazione

Ora che tu e i tuoi utenti Looker avete provato l'estensione di riepilogo delle dashboard di Looker, condividiamo le informazioni dell'estensione con un pubblico più ampio. Segui questa sezione per consentire all'estensione di inviare riepiloghi e passaggi successivi a Google Chat o Slack. Per continuare con questa sezione del codelab, devi avere familiarità con la configurazione di OAuth.

Attivare l'esportazione di Google Chat

  1. Abilita l'API Chat nel tuo progetto Google Cloud.
  2. Segui il passaggio 1 delle istruzioni di configurazione di OAuth di Google Workspace. Per gli ambiti devi includere spaces.messages.create.
  3. Segui il passaggio 2 delle istruzioni di configurazione di OAuth di Google Workspace. Aggiungi l'URL dell'istanza di Looker come URI in "Origini JavaScript autorizzate", ad esempio https://mycompany.cloud.looker.com. Prendi nota dell'ID client generato.
  4. Determina l'ID dello spazio di Google Chat in cui vuoi esportare i riepiloghi. Se non sai come fare, segui queste istruzioni.
  5. Modifica il file .env. Sostituisci YOUR_GOOGLE_CLIENT_ID con l'ID client. Sostituisci YOUR_GOOGLE_SPACE_ID con l'ID dello spazio di Chat di Google. Salva le modifiche apportate al file. In questo modo, il frontend dell'estensione viene configurato in modo da poter inviare i relativi approfondimenti allo spazio di Chat di Google che preferisci.
  6. Se esegui il frontend dell'estensione localmente, ricompila l'estensione. Altrimenti, se stai eseguendo il deployment del frontend dell'estensione, esegui nuovamente il deployment.

Abilitare l'esportazione di Slack

  1. Segui i passaggi 1 e 2 della documentazione ufficiale per gli sviluppatori di Slack per configurare un'applicazione OAuth. Per gli ambiti devi includere chat:write e channels:read. Prendi nota dell'ID client e del client secret generati.
  2. Determina l'ID del canale Slack in cui vuoi esportare i riepiloghi.
  3. Modifica il file .env. Sostituisci YOUR_SLACK_CLIENT_ID con l'ID client. Sostituisci YOUR_SLACK_CLIENT_SECRET con il client secret. Sostituisci YOUR_SLACK_CHANNEL_ID con l'ID canale. Salva le modifiche apportate al file. In questo modo, il front-end dell'estensione potrà inviare i suoi approfondimenti al canale Slack che preferisci.
  4. Se esegui il frontend dell'estensione localmente, ricompila l'estensione. Altrimenti, se stai eseguendo il deployment del frontend dell'estensione, esegui nuovamente il deployment.

Ora l'estensione può esportare i riepiloghi direttamente in Slack o Google Chat. Tieni presente che l'estensione può inviare riepiloghi solo a uno spazio Google Chat o a un canale Slack specifici codificati. Puoi aggiungere ulteriori ambiti OAuth e modificare il codice per recuperare e visualizzare un elenco di spazi e canali a cui inviare i riepiloghi.

7. [Facoltativo] Perfeziona il riepilogo e i passaggi successivi

L'estensione richiede al modello Gemini tutti i metadati della dashboard ed esegue query sui dati. Puoi migliorare l'accuratezza, il livello di dettaglio e la profondità dei riepiloghi e dei passaggi prescrittivi aggiungendo quanti più metadati e contesto possibili alla dashboard stessa. Prova questi passaggi per ogni dashboard di cui fa parte la tua estensione:

  • Segui queste istruzioni per aggiungere i dettagli della dashboard. In questo modo, il modello LLM avrà un contesto generale della dashboard.
  • Segui queste istruzioni per aggiungere note al riquadro di ogni dashboard. In questo modo, il modello LLM potrà comprendere il contesto di ogni singola query nella dashboard. Le piccole note contestuali verranno prese in considerazione nei riepiloghi generati.

Più informazioni puoi aggiungere alle dashboard, migliori saranno i riepiloghi e i passaggi successivi dell'estensione. Puoi modificare il codice per includere metadati aggiuntivi della dashboard nel prompt per il modello Gemini.

8. (Facoltativo) Configura la registrazione dei log del modello Gemini

Ogni volta che un utente chiede all'estensione di creare riepiloghi per un dashboard, l'estensione effettua una chiamata a Vertex AI per ogni query nel dashboard più una chiamata finale per formattare tutti i riepiloghi. Segui questa sezione per registrare le chiamate Vertex AI effettuate dalla tua estensione in modo da poter stimare e monitorare i costi e il traffico di Vertex AI. Devi seguire queste istruzioni solo se hai eseguito il deployment del servizio di backend websocket.

  1. Determina la posizione Cloud Run del servizio di backend websocket di cui è stato eseguito il deployment.
  2. Segui queste istruzioni per configurare un sink di log che indirizzerà i log a BigQuery. La destinazione del sink deve essere BigQuery. Imposta il filtro di inclusione con il seguente esempio di codice, sostituendo YOUR_CLOUD_RUN_LOCATION con la posizione di Cloud Run del passaggio precedente.
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. Complimenti!

Hai configurato localmente l'estensione di riepilogo della dashboard di Looker per provarla. Hai anche eseguito il deployment dell'estensione su Google Cloud in modo che anche altri utenti possano provarla. Ora tu e altri utenti potete accedere ai riepiloghi e ai passaggi successivi basati su Gemini direttamente dalle dashboard.

10. Passaggi successivi