Codelab sulle estensioni di riepilogo della dashboard di Looker

1. Prima di iniziare

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

Panoramica delle estensioni di riepilogo della dashboard di Looker

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

Prerequisiti

  • Familiarità di base con lo sviluppo di nodi, Docker e Terraform
  • Familiarità con la configurazione di un progetto LookML per Looker

Cosa imparerai a fare

  • Come configurare e sviluppare l'estensione localmente
  • Eseguire il deployment dell'estensione in produzione in modo che altri utenti di Looker nella tua istanza di Looker possano utilizzarla
  • Come ottimizzare facoltativamente le prestazioni dell'estensione ed estenderne le funzionalità.
  • Come gestire l'estensione di cui hai eseguito il deployment in produzione

Che cosa ti serve

  • Un'istanza di Looker tramite una licenza originale di Looker, una prova di Looker Core attiva o una licenza Looker Core attiva.
  • Autorizzazioni develop e deploy per la tua istanza Looker.
  • Autorizzazioni per modificare una dashboard che vuoi provare con l'estensione.
  • Una chiave API Looker dalla tua istanza Looker.
  • Un progetto Google Cloud in cui è abilitata la fatturazione.
  • API Cloud Run, API Vertex AI e API Artifact Registry abilitate nel progetto.
  • Accesso a un ambiente locale con gcloud CLI installato. 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 in modo che tu possa provarlo e svilupparlo localmente. Il servizio avrà accesso a Vertex AI.

  1. Installa il nodo versione 18 o successiva installata nel tuo ambiente locale. Segui queste istruzioni per installare il nodo.
  2. Clona il repository dell'estensione nella tua home directory locale e vai alla directory root del repository. Ai fini di questo codelab, tutti gli esempi di codice presuppongono che il repository clonato si trovi nella tua home directory locale.
cd ~
git clone git@github.com:looker-open-source/dashboard-summarization.git
  1. Vai alla directory root del repository clonato e rinomina il file .env.example in .env per 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 per il 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, che includono quelli della chiave API Looker.
  3. base_url con l'URL dell'istanza di Looker nel formato: https://<YOUR_LOOKER_URL_MINUS_PROTOCOL>:19999
  4. Il testo tra le parentesi (intestazione della sezione) con l'host dell'URL dell'istanza di Looker.

Ad esempio, se il tuo ID client è ABC123, il client secret è XYZ789 e l'URL dell'istanza di Looker è https://mycompany.cloud.looker.com, il 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 il tuo ID progetto Google Cloud e impostalo sulla variabile di ambiente PROJECT. Sostituisci YOUR_PROJECT_ID con l'ID del tuo progetto.
export PROJECT="YOUR_PROJECT_ID"
  1. Vertex AI fornisce il modello Gemini in più regioni elencate qui. Determina la regione che 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 tuo servizio di backend websocket locale verrà eseguito su http://localhost:5000.

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 acquisirà i dati della dashboard e del LookML dall'estensione frontend con i dati sottoposti a query da Looker e richiederà il 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. Prima di tutto dovrai interrompere il processo del servizio, apportare modifiche al codice ed eseguire di nuovo npm start.

3. Configura il frontend per lo sviluppo locale

In questa sezione configurerai l'estensione frontend in modo che tu possa provarla e svilupparla a livello locale.

  1. Nello stesso ambiente locale dei passaggi precedenti, vai alla directory root del repository clonato e installa le dipendenze del server frontend per il frontend.
cd ~/dashboard-summarization
npm install
  1. Avvia il tuo server di sviluppo frontend locale
npm run develop
  1. Il tuo server frontend locale ora pubblica il codice JavaScript dell'estensione all'indirizzo http://localhost:8080/bundle.js.
  2. Apri un browser web e accedi all'istanza di Looker.
  3. Segui queste istruzioni per configurare un progetto LookML vuoto. Assegna un nome al riassunto della dashboard del progetto. Ora il progetto LookML vuoto dovrebbe essere 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 su come aggiungere un file a un progetto LookML.
  5. Sostituisci i contenuti del nuovo file manifest.lKML con i contenuti di manifest.lKML nella directory root del repository chiuso. Seleziona "Salva modifiche" nell'angolo in alto a destra per salvare le modifiche apportate al file.
  6. In una scheda del browser separata, vai all'elenco delle connessioni di database nella tua istanza Looker. In caso di dubbi, segui queste istruzioni.
  7. Scegli il nome di una connessione al database Looker. La connessione scelta non è importante. Se non hai l'autorizzazione per visualizzare le connessioni del 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 Looker. Crea un file del modello nel progetto LookML e denomina il file 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 virgolette con il nome della connessione al database 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". pulsante in alto a destra. Seleziona "Configura un repository semplice". Seleziona "Crea repository".
  2. Ora hai a disposizione un repository semplice di base in cui archiviare i file di progetto LookML. Torna al progetto nell'IDE di Looker selezionando "Torna al progetto" o tornare indietro manualmente.
  3. Seleziona la casella di controllo "Convalida LookML" nell'angolo in alto a destra. Il pulsante cambia in "Esegui il commit delle modifiche ed esegui il push".
  4. Seleziona ""Esegui il commit delle modifiche ed esegui il push". . Aggiungi i messaggi desiderati e seleziona "Esegui il commit".
  5. Seleziona "Deploy to Production" (Esegui il deployment in produzione). nell'angolo in alto a destra dell'IDE di Looker. A questo punto hai aggiunto l'estensione alla tua istanza di Looker.
  6. Vai alla 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 al tuo pannello sotto forma di riquadro.
  8. Assicurati che il servizio di backend websocket locale che hai configurato in precedenza sia in esecuzione.

Complimenti! Ora puoi provare l'estensione riassunto di Looker Dashboard nella tua dashboard. L'estensione invierà i metadati della tua 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 vedere le modifiche, devi ricaricare la pagina dell'estensione o della dashboard.

4. Esegui il deployment del backend in produzione

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

  1. Per i passaggi successivi, segui queste istruzioni per configurare una credenziale predefinita dell'applicazione nel tuo ambiente locale con l'ID del tuo progetto.
  2. Crea un repository Artifact Registry per le immagini Docker del tuo 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. Accedi alla directory src del backend del socket web 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 l'ID della tua regione e del tuo progetto. Salva le modifiche apportate al file.
  2. Invia con Cloud Build una 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 si trova all'indirizzo YOUR_REGION-docker.pkg.dev/YOUR_PROJECT_ID/dashboard-summarization-repo/websocketserviceimage:latest. Sostituisci YOUR_PROJECT_ID con l'ID del tuo progetto. Sostituisci YOUR_REGION con la regione del passaggio 2 che hai utilizzato per creare il repository Artifact Registry.
  2. Passa alla directory websocket-service/terraform nel repository clonato.
cd ~/dashboard-summarization/websocket-service/terraform
  1. Determina 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 conoscere l'URL dell'immagine Docker. Sostituisci YOUR_REGION con la regione scelta nel passaggio 8 precedente. Salva le modifiche apportate al file.
  3. Esegui il deployment delle risorse utilizzate dal tuo servizio di backend con 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 tuo servizio di backend websocket, che ora è in esecuzione su Google Cloud Run. Ora tutte le istanze dell'estensione Riepilogo dashboard di Looker possono comunicare con il tuo servizio di backend. Ti consigliamo di avere sempre almeno un'istanza del tuo servizio di backend websocket in esecuzione su Cloud Run. La persistenza del servizio di backend mantiene l'integrità del flusso di dati tra il servizio di backend websocket e il frontend dell'estensione e consente di gestire la sessione di ciascun utente quando utilizza l'estensione.

5. Esegui il deployment del frontend in produzione

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

  1. Vai alla directory root del repository clonato.
cd ~/dashboard-summarization
  1. Modifica ilenv. Sostituisci YOUR_CLOUD_RUN_URL con l'endpoint URL di Cloud Run della sezione precedente. Salva le modifiche apportate al file. Questo punterà il frontend dell'estensione di produzione al servizio di backend websocket in esecuzione su Cloud Run.
  2. Crea il codice JavaScript dell'estensione. Verrà generata automaticamente una directory dist contenente un file bundle.js e altri file.
npm run build
  1. Apri un browser web e accedi all'istanza di Looker. Apri il riquadro di navigazione a sinistra e attiva "Modalità di sviluppo" pulsante di attivazione/disattivazione in basso.
  2. Con il menu di navigazione laterale sinistro aperto, seleziona "Sviluppa", quindi scorri verso il basso e seleziona "dashboard-summarization", il progetto LookML della tua estensione. A questo punto dovresti trovarti nell'IDE di Looker per il progetto LookML.
  3. Trascina tutti i file della directory dist generata in precedenza nella directory radice del progetto nel "Browser file". Se hai bisogno di ulteriore assistenza, segui queste istruzioni.
  4. Apri il file manifest.lkml nell'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 la casella di controllo "Convalida LookML" nell'angolo in alto a destra. Il pulsante cambia in "Esegui il commit delle modifiche ed esegui il push".
  2. Seleziona ""Esegui il commit delle modifiche ed esegui il push". . Aggiungi i messaggi desiderati e seleziona "Esegui il commit".
  3. Seleziona "Deploy to Production" (Esegui il deployment in produzione). nell'angolo in alto a destra dell'IDE di Looker.

Complimenti! Ora hai abilitato tutti gli utenti di Looker nella tua istanza di Looker ad aggiungere l'estensione riepilogo della dashboard di Looker alle proprie dashboard. Poiché gli altri utenti di Looker utilizzano l'estensione, tutte le sue istanze chiameranno il 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. Crea di nuovo il codice JavaScript dell'estensione
  2. Sostituisci i file generati che hai aggiunto al progetto LookML con i file appena generati dalla directory dist.
  3. Convalida, sottoponi a commit ed esegui il deployment delle modifiche del progetto LookML in produzione

Prova l'estensione 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 abilitare l'esportazione in Slack/Google Chat, ottimizzare i riepiloghi di Gemini e i passaggi successivi e configurare il logging di Gemini.

6. [Facoltativo] Configurare le funzionalità di esportazione

Ora che tu e i tuoi utenti di Looker avete provato l'estensione Summarization di Looker Dashboard, consenti di condividere gli insight dell'estensione con un pubblico più ampio. Segui questa sezione per consentire alla tua estensione di inviare riepiloghi e passaggi successivi a Google Chat o Slack. Dovresti avere familiarità con la configurazione di OAuth per continuare con questa sezione del codelab.

Attivare l'esportazione di Google Chat

  1. Abilitare l'API Chat nel tuo progetto Google Cloud.
  2. Segui il passaggio 1 delle istruzioni per la configurazione di OAuth di Google Workspace. Per gli ambiti, devi includere spaces.messages.create.
  3. Segui il passaggio 2 delle istruzioni per la configurazione di OAuth di Google Workspace. Aggiungi l'URL dell'istanza 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. In caso di dubbi, segui queste istruzioni.
  5. Modifica ilenv. Sostituisci YOUR_GOOGLE_CLIENT_ID con l'ID client. Sostituisci YOUR_GOOGLE_SPACE_ID con l'ID spazio di Google Chat. Salva le modifiche apportate al file. In questo modo, il frontend della tua estensione verrà configurato in modo da poter inviare i relativi approfondimenti allo spazio di Google Chat che vuoi.
  6. Se esegui in locale il frontend dell'estensione, ricrea l'estensione. In caso contrario, se stai eseguendo il deployment del frontend della tua estensione, esegui nuovamente il deployment del frontend dell'estensione.

Abilita esportazione Slack

  1. Segui i passaggi 1 e 2 della documentazione ufficiale per gli sviluppatori su 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 ilenv. 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 frontend della tua estensione verrà configurato in modo da poter inviare i relativi insight al canale Slack desiderato.
  4. Se esegui in locale il frontend dell'estensione, ricrea l'estensione. In caso contrario, se stai eseguendo il deployment del frontend della tua estensione, esegui nuovamente il deployment del frontend dell'estensione.

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

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

L'estensione richiede al modello Gemini tutti i dati delle query e dei metadati della dashboard. Puoi migliorare l'accuratezza, i dettagli e la profondità dei riepiloghi e dei passaggi prescrittivi aggiungendo il maggior numero di metadati e contesto alla dashboard stessa. Prova questa procedura per ogni dashboard di cui fa parte l'estensione:

  • Segui queste istruzioni per aggiungere dettagli alla dashboard. Ciò aiuterà a informare l'LLM del contesto generale della dashboard.
  • Segui queste istruzioni per aggiungere note al riquadro di ogni dashboard. Ciò è utile per informare l'LLM del contesto di ogni singola query nella dashboard. Le piccole note contestuali contribuiranno ai riepiloghi generati.

Maggiori sono le informazioni che puoi aggiungere alle tue dashboard, migliori sono i riassunti dell'estensione e i passaggi successivi. Puoi modificare il codice per includere ulteriori metadati della dashboard nel prompt del modello Gemini.

8. [Facoltativo] Configura il logging del modello Gemini

Ogni volta che un utente chiede all'estensione di creare riepiloghi per una dashboard, l'estensione effettua una chiamata a Vertex AI per ogni query nella dashboard e 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 località di Cloud Run del servizio di backend WebSocket di cui hai eseguito il deployment.
  2. Segui queste istruzioni per configurare un sink di log che eseguirà il routing dei log a BigQuery. La destinazione del sink deve essere BigQuery. Imposta il filtro di inclusione con il seguente esempio di codice, sostituendo il campo YOUR_CLOUD_RUN_LOCATION con la località 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 Summarization di Looker Dashboard per provarla. Hai anche eseguito il deployment dell'estensione su Google Cloud, così anche altri utenti possono provarla. Ora tu e gli altri utenti potete accedere ai riepiloghi basati su Gemini e ai passaggi successivi direttamente dalle dashboard.

10. Passaggi successivi