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 ulteriori passaggi 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

Dal punto di vista 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 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 frontend React accoppiata a un servizio backend websocket per inviare e ricevere dati da e verso il modello Gemini di Vertex AI.

Prerequisiti

  • Familiarità di base con lo 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
  • 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 è stato eseguito il deployment in produzione

Che cosa ti serve

  • Un'istanza Looker, tramite una licenza originale di Looker, una prova di Looker Core attiva o una licenza di Looker Core attiva.
  • Autorizzazioni develop e deploy per la tua istanza di 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.
  • L'API Cloud Run, l'API Vertex AI e l'API Artifact Registry devono essere 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 Node versione 18 o successiva nell'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 del file looker.ini, aggiorna:
  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 tuo segreto client è XYZ789 e l'URL della tua istanza Looker è https://mycompany.cloud.looker.com, il file looker.ini avrà il seguente 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 di LookML dalla tua estensione frontend con i dati sottoposti a query da Looker e richiederà il modello Gemini di Vertex AI. Il servizio trasmette 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. Configurare 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 principale 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 alla tua istanza 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 il pulsante "Salva modifiche" nell'angolo in alto a destra per salvare le modifiche al file.
  6. In una scheda del browser separata, vai all'elenco delle connessioni al database nell'istanza di 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" in alto a destra. Seleziona "Configura invece un repository senza componenti aggiuntivi". Seleziona "Crea repository".
  2. Ora hai un repository di base in cui archiviare i file di 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 cambia in "Esegui il commit delle modifiche ed esegui il push".
  4. Seleziona il pulsante "Esegui il commit delle modifiche e premi". Aggiungi i messaggi desiderati e seleziona "Esegui il commit".
  5. Seleziona "Deploy to Production" nell'angolo in alto a destra dell'IDE di Looker. A questo punto hai aggiunto l'estensione alla tua istanza di Looker.
  6. Vai a una dashboard di Looker a cui vuoi aggiungere l'estensione.
  7. Segui le istruzioni per aggiungere un riquadro di 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 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 le compilerà e pubblicherà automaticamente. Per visualizzare 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 per pubblicare qualsiasi istanza dell'estensione di sintesi della dashboard in qualsiasi dashboard della tua istanza di Looker. In questo modo, gli altri utenti di Looker potranno provare l'estensione nelle proprie dashboard senza dover configurare il 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. 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 utilizzata 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 una di 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 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 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 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 ogni utente mentre utilizza la tua 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 l'opzione "Modalità di sviluppo" in basso.
  2. Con la barra di navigazione laterale sinistra aperta, seleziona "Sviluppa", quindi scorri verso il basso e seleziona "dashboard-summarization", il progetto LookML dell'estensione. A questo punto dovresti essere 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 "File Browser". 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 il pulsante "Convalida LookML" nell'angolo in alto a destra. Il pulsante diventerà "Esegui commit delle modifiche e push".
  2. Seleziona il pulsante "Esegui il commit delle modifiche e premi". Aggiungi i messaggi desiderati e seleziona "Esegui il commit".
  3. Seleziona "Deploy to Production" 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. Ricrea 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, esegui commit e esegui il deployment delle modifiche al 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 attivare l'esportazione di Slack/Google Chat, perfezionare i riepiloghi e i passaggi successivi di Gemini e configurare il logging di Gemini.

6. [Facoltativo] Configura le funzionalità di esportazione

Ora che tu e i tuoi utenti 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 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 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 per 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 ilenv. Sostituisci YOUR_GOOGLE_CLIENT_ID con l'ID cliente. 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.

Attivare l'esportazione in 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.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 frontend dell'estensione potrà inviare le sue statistiche al canale Slack che preferisci.
  4. Se esegui il frontend dell'estensione localmente, ricostruisci l'estensione. In caso contrario, se stai eseguendo il deployment del frontend dell'estensione, esegui nuovamente il deployment del frontend dell'estensione.

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 di Chat di Google o a un canale Slack hardcoded specifico. 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 quanti più metadati e contesto alla dashboard stessa. Prova questi passaggi 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 la registrazione dei modelli Gemini

Ogni volta che un utente chiede all'estensione di creare riepiloghi per una dashboard, l'estensione eseguirà una chiamata a Vertex AI per ogni query nella dashboard, oltre a 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. Segui queste istruzioni solo se hai implementato il 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 in modo che anche altri utenti possano provarla. Ora tu e gli altri utenti potete accedere ai riepiloghi basati su Gemini e ai passaggi successivi direttamente dalle dashboard.

10. Passaggi successivi