Incorporare Looker con l'analisi conversazionale

1. Prima di iniziare

Questo codelab ti guiderà nell'integrazione di una dashboard Looker incorporata con la chat basata su Analisi conversazionale per creare un'esperienza di dati unificata basata sul linguaggio naturale. Per ottenere il massimo valore, devi avere familiarità con l'incorporamento di Looker, Analisi conversazionale, JavaScript e React.

Cosa imparerai a fare

Dopo aver seguito questo codelab, avrai imparato a:

• Configurare l'applicazione di riferimento per l'incorporamento di Looker in locale
• Creare un componente React di chat con la libreria dei componenti di Looker
• Inviare il filtro della dashboard incorporata come contesto ad Analisi conversazionale
• Consentire alla chat basata su Analisi conversazionale di controllare i filtri della dashboard incorporata

Che cosa ti serve

Per completare questo codelab, ti serviranno:

• Un'istanza di Looker con il blocco Looker dei dati demografici ASC installato e l'incorporamento SSO abilitato
• Accesso API e sviluppatore alla tua istanza di Looker
• Un ambiente locale con Node v18, yarn, Git e gcloud installati
• Un progetto Cloud con questi ruoli IAM configurati per il tuo account utente:
• roles/bigquery.dataViewer Visualizzatore dati BigQuery
• roles/bigquery.user Utente BigQuery
• roles/looker.instanceUser Utente istanza Looker

2. Configurare Analisi conversazionale

Configuriamo l'agente di dati di Analisi conversazionale che la chat della dashboard incorporata utilizzerà per rispondere alle domande in linguaggio naturale.

Autenticarsi con gcloud

1. Autenticati con il tuo account utente nel tuo ambiente locale:

gcloud auth login

2. Imposta le Credenziali predefinite dell'applicazione (ADC) e il progetto di fatturazione su gcloud:

gcloud auth application-default login
gcloud auth application-default set-quota-project YOUR_PROJECT_ID

Abilitare le API di Analisi conversazionale

3. Abilita le API del progetto Cloud. Sostituisci YOUR_PROJECT_ID con l'ID del tuo progetto Google Cloud:

gcloud services enable geminidataanalytics.googleapis.com bigquery.googleapis.com cloudaicompanion.googleapis.com --project=YOUR_PROJECT_ID

Creare l'agente di dati

4. Apri Google Colab.
5. In Google Colab, carica questo notebook dal repository di riferimento per l'incorporamento di Looker.
6. Esegui tutti i passaggi del notebook. Avrai bisogno dell'ID progetto Cloud e dell'URI dell'istanza di Looker con una barra finale, ad esempio "https://my.looker.app/". Alla fine del notebook dovresti ottenere un risultato positivo.

Ora hai a disposizione un agente di dati di Analisi conversazionale pronto ad accettare i messaggi di chat, eseguire query sulle esplorazioni di Looker nella dashboard di Looker incorporata e restituire risultati e visualizzazioni.

3. Configurare il riferimento per l'incorporamento di Looker

Configuriamo l'applicazione di riferimento per l'incorporamento di Looker nel tuo ambiente locale in modo che tu possa provare l'esempio di integrazione della chat di Analisi conversazionale con una dashboard di Looker incorporata.

Clonare il repository

1. Clona il repository GitHub nel tuo ambiente locale. Di seguito è riportato un esempio di comando:

git clone "https://github.com/looker-open-source/LookerEmbedReference.git"

2. Vai alla directory LookerEmbedReference che hai clonato:

cd LookerEmbedReference

Configurare ed eseguire il server frontend locale

3. Installa le dipendenze nella directory Frontend

cd Frontend
yarn install

4. Configura un file .env nella directory principale Frontend con le credenziali. YOUR_LOOKER_INSTANCE_URI deve essere l'URI dell'istanza di Looker senza barra finale. Il contenuto del file deve essere il seguente:

PBL_CLIENT_PORT=3001 
API_HOST=http://localhost:3000
LOOKER_HOST=YOUR_LOOKER_INSTANCE_URI
LOOKER_API_HOST=YOUR_LOOKER_INSTANCE_URI:19999
LOOKERSDK_EMBED_HOST=YOUR_LOOKER_INSTANCE_URI

Puoi utilizzare il seguente comando di esempio per creare il file:

cat > .env <<'EOF'
PBL_CLIENT_PORT=3001 
API_HOST=http://localhost:3000
LOOKER_HOST=YOUR_LOOKER_INSTANCE_URI
LOOKER_API_HOST=YOUR_LOOKER_INSTANCE_URI:19999
LOOKERSDK_EMBED_HOST=YOUR_LOOKER_INSTANCE_URI
EOF

5. Esegui il server di sviluppo frontend:

yarn run dev

Configurare ed eseguire il server di backend in locale

6. Apri una nuova shell, un nuovo terminale, una nuova console o una nuova scheda. Vai alla directory Backend-Node e installa le dipendenze. Assicurati di mantenere in esecuzione la shell/il terminale precedente con il server frontend.

cd ../Backend-Node
yarn install

7. Configura un file .env nella directory principale Backend-Node con le credenziali:

• YOUR_LOOKER_CLIENT_ID è l'ID client di Looker.
• YOUR_LOOKER_CLIENT_SECRET è il secret client di Looker.
• YOUR_LOOKER_EMBED_SECRET è il tuo secret di incorporamento.
• YOUR_PROJECT_ID è l'ID progetto Cloud.
• YOUR_LOOKER_INSTANCE_URI_WITH_TRAILING_SLASH è l'URI dell'istanza di Looker con una barra finale.
• YOUR_LOOKER_INSTANCE_URI è l'URI dell'istanza di Looker senza barra finale.

Il contenuto del file deve essere il seguente:

PBL_BACKEND_PORT=3000
LOOKERSDK_API_VERSION=4.0
LOOKERSDK_BASE_URL=YOUR_LOOKER_INSTANCE_URI_WITH_TRAILING_SLASH
LOOKERSDK_CLIENT_ID=YOUR_LOOKER_CLIENT_ID
LOOKERSDK_CLIENT_SECRET=YOUR_LOOKER_CLIENT_SECRET

LOOKERSDK_EMBED_HOST=YOUR_LOOKER_INSTANCE_URI
LOOKERSDK_EMBED_SECRET=YOUR_LOOKER_EMBED_SECRET

CLOUD_AGENT_ID=looker_embed_reference_data_agent
CLOUD_PROJECT_ID=YOUR_PROJECT_ID

Puoi utilizzare il seguente comando di esempio per creare il file. Sostituisci tutte le credenziali di conseguenza:

cat > .env <<'EOF'
PBL_BACKEND_PORT=3000
LOOKERSDK_API_VERSION=4.0
LOOKERSDK_BASE_URL=YOUR_LOOKER_INSTANCE_URI_WITH_TRAILING_SLASH
LOOKERSDK_CLIENT_ID=YOUR_LOOKER_CLIENT_ID
LOOKERSDK_CLIENT_SECRET=YOUR_LOOKER_CLIENT_SECRET

LOOKERSDK_EMBED_HOST=YOUR_LOOKER_INSTANCE_URI
LOOKERSDK_EMBED_SECRET=YOUR_LOOKER_EMBED_SECRET

CLOUD_AGENT_ID=looker_embed_reference_data_agent
CLOUD_PROJECT_ID=YOUR_PROJECT_ID
EOF

8. Esegui il server di sviluppo backend:

yarn run dev

Ora il server di sviluppo frontend è in esecuzione e pubblica il codice JavaScript per l'applicazione web. Anche il server di sviluppo backend è in esecuzione per gestire le richieste di URL di incorporamento SSO e le richieste proxy agli endpoint di Analisi conversazionale.

4. Provare l'esempio

Proviamo l'applicazione web ora in esecuzione in locale nel tuo ambiente.

Avviare una conversazione

1. Apri l'indirizzo https://localhost:3001 nel browser che preferisci.
2. Vai alla pagina Dashboard incorporata con chat nel riquadro di navigazione principale a sinistra.
3. Una volta caricato il componente di chat a destra, digita: "Ciao, chi sei?"
4. Prendi nota della risposta.

L'applicazione ha creato automaticamente un oggetto di conversazione di Analisi conversazionale conversazione per tenere traccia della cronologia chat e ha caricato l'interfaccia di chat. Quando hai posto una domanda all'interfaccia di chat, il frontend ha inviato un messaggio utente al server di backend Node locale. Poi ha inviato la richiesta e la risposta dall'endpoint di chat di Analisi conversazionale tramite proxy.

Filtrare la dashboard incorporata

Ora acquisisci familiarità con la dashboard incorporata e interagisci con essa.

5. Scorri la dashboard incorporata. Tieni presente che copre i dati del censimento in più dimensioni e metriche.
6. Puoi filtrare la dashboard in base a Stato e Contea in alto a sinistra. Imposta il filtro sulla dashboard su Texas. Poi seleziona il pulsante con la freccia circolare evidenziata in blu per eseguire di nuovo la dashboard.
7. Nota come i dati di tutte le visualizzazioni siano filtrati in base allo stato Texas.

Porre una domanda con il contesto della dashboard

Ora che abbiamo filtrato la dashboard, continuiamo a esaminare i dati nella dashboard.

8. Invia "Dimmi le 5 contee con l'affitto più basso" nella chat.
9. Tieni presente che il prompt per Analisi conversazionale ora contiene le parole aggiuntive "Filtra in base alla dimensione 'state.state_name' che è Texas".
10. Ora, tieni presente che la query e i dati della risposta sono filtrati in base allo stato Texas.
11. Inoltre, dopo che sono stati restituiti i risultati dei dati, la dashboard incorporata è stata eseguita di nuovo con il filtro Contea impostato sulle 5 contee definite nei dati del risultato.

Ora puoi continuare a esaminare i dati del censimento, con le 5 contee filtrate in modo pratico.

Complimenti! Hai configurato e provato un semplice esempio di dashboard incorporata integrata con una chat di Analisi conversazionale.

5. Creare un componente di chat

Per capire cosa succede dietro le quinte, esploriamo prima il componente Chat. Supponiamo che tu sappia come incorporare una dashboard di Looker con l' SDK Embed di Looker.

Utilizzare la libreria dei componenti di Looker

1. Apri il file del componente Chat all'indirizzo Frontend/src/components/EmbedChat/components/chat.js nel tuo IDE preferito o nel terminale.
2. Il componente Chat è creato con i componenti React dell'interfaccia utente standard di Looker dal pacchetto della Libreria dei componenti di Looker.

La libreria dei componenti di Looker consente l'integrazione perfetta tra i contenuti di Looker e la tua applicazione fornendo componenti React predefiniti che si allineano agli stili e ai componenti di una dashboard di Looker incorporata.

Inviare un messaggio utente

L'interfaccia di chat deve inviare un prompt dell'utente ad Analisi conversazionale.

3. Verso la fine del file del componente Chat, il componente Chat contiene il sottocomponente ChatInput, che fornisce il campo di immissione per il prompt di un utente.
4. Al momento dell'invio, il metodo showAndSendUserPrompt invia il prompt dell'utente ad Analisi conversazionale (tramite proxy tramite il backend Node).

Trasmettere e visualizzare i messaggi di sistema

Dopo che l'utente ha inviato un messaggio ad Analisi conversazionale, dobbiamo visualizzare la sua risposta.

5. Verso la fine del file del componente Chat, il componente Chat contiene il sottocomponente MessageList, che contiene la logica per visualizzare i messaggi di Analisi conversazionale in base al tipo di messaggio.
6. Il metodo streamAndParseResponse gestisce la risposta tentando costantemente di analizzare i messaggi di sistema validi dalla risposta JSON di streaming. Ogni volta che un messaggio di sistema valido viene analizzato correttamente, viene visualizzato in MessageList.

Ti consigliamo vivamente di visualizzare i messaggi di sistema di Analisi conversazionale non appena arrivano per un'esperienza utente più reattiva.

La risposta di Analisi conversazionale a un prompt dell'utente è costituita da più messaggi di sistema che riguardano le origini dati su cui è stata eseguita la query, la query, i risultati, le visualizzazioni e altro ancora. Se l'utente attende l'arrivo di tutti i messaggi di sistema, potrebbe presumere che si tratti di problemi di prestazioni o dell'applicazione.

Ora hai esplorato come il componente Chat, creato con la libreria dei componenti di Looker, invia un messaggio utente e trasmette la risposta.

6. Inviare i filtri della dashboard ad Analisi conversazionale

Ora vediamo come includere i filtri della dashboard nel prompt di un utente in modo che Analisi conversazionale possa filtrare la query con il contesto della dashboard (i relativi filtri).

Ascoltare l'evento di modifica del filtro della dashboard

1. Apri il file del componente EmbedChat all'indirizzo Frontend/src/components/EmbedChat/EmbedChat.js, che rappresenta la pagina dell'applicazione contenente la dashboard incorporata integrata con il componente Chat esplorato in precedenza.
2. Il componente EmbedChat ascolta l'evento "dashboard:filters:changed" dalla dashboard incorporata con il metodo .on(...) dell'SDK Embed. Poi il componente memorizza i filtri attuali nel relativo stato del filtro.

Inviare lo stato del filtro ad Analisi conversazionale

3. Il componente EmbedChat passa i filtri al componente Chat, che converte ogni filtro in una stringa come "Filter on dimension '...' being ..." nel metodo showAndSendUserPrompt da aggiungere al prompt dell'utente.

Il nome o la chiave del filtro di una dashboard non è necessariamente uguale al nome effettivo della dimensione. Devi mappare la chiave del filtro al nome effettivo della dimensione in modo che Analisi conversazionale comprenda le dimensioni su cui filtrare.

In questo caso, ad esempio nel componente Chat, l'oggetto FIELD_FILTER_MAP mappa il nome della dimensione "state.state_name" alla chiave del filtro "State 📍". Poi il metodo showAndSendUserPrompt utilizza la mappa per determinare il nome della dimensione su cui filtrare.

7. Controllare i filtri della dashboard dalla chat

Infine, vediamo come consentire al componente Chat di controllare i filtri della dashboard incorporata.

Determinare i filtri da impostare

1. Il metodo streamAndParseResponse del componente Chat controlla sempre la presenza di un messaggio di sistema con i risultati dei dati di Analisi conversazionale.
2. Ogni volta che il metodo streamAndParseResponse analizza un messaggio di sistema con i risultati dei dati, verifica se le dimensioni nei dati corrispondono alle dimensioni nei filtri.
3. In caso affermativo, il metodo streamAndParseResponse converte le colonne di dati in filtri della dashboard. Questa volta il metodo utilizza di nuovo FIELD_FILTER_MAP, ma al contrario, convertendo dal nome della dimensione alla chiave del filtro. I valori del filtro sono i valori nella colonna di dati.

Inviare l'evento di modifica del filtro alla dashboard incorporata

4. Con i filtri della dashboard desiderati, il metodo streamAndParseResponse chiama il metodo setFilters del componente Chat con i filtri desiderati.
5. Viene chiamato il metodo setDashboardFilters del componente EmbedChat, che invia due eventi, "dashboard:filters:update" con i filtri e "dashboard:run" alla dashboard incorporata in successione immediata utilizzando il metodo send dell'SDK Embed.
6. L'evento "dashboard:filters:update" modifica i filtri della dashboard incorporata, mentre l'evento "dashboard:run" esegue di nuovo le query della dashboard con i nuovi filtri.

Devi inviare "dashboard:run" dopo l'evento "dashboard:filters:update". L'evento "dashboard:filters:update" non esegue automaticamente di nuovo le query della dashboard.

8. Conclusioni e punti chiave

Hai configurato il tuo esempio funzionante di dashboard di Looker incorporata integrata con la chat di Analisi conversazionale. Hai imparato a consentire l'esplorazione dei dati basata sul linguaggio naturale con la dashboard di Looker incorporata e Analisi conversazionale.

• Hai creato un componente di chat con la libreria dei componenti di Looker.
• Hai passato il contesto della dashboard di Looker incorporata ad Analisi conversazionale per semplificare l'esplorazione dei dati.
• Hai consentito ad Analisi conversazionale di controllare i filtri della dashboard incorporata per un contesto migliorato durante l'esplorazione dei dati.

Passaggi successivi

• Scopri di più sulle funzionalità di Analisi conversazionale.
• Aggiorna l'app di esempio di riferimento per l'incorporamento di Looker in modo che funzioni con le tue dashboard di Looker incorporate.
• Prova gli altri casi d'uso di incorporamento disponibili nell'app di esempio di riferimento per l'incorporamento di Looker in esecuzione in locale.