Crea un'app di chat con Conversational Analytics e Looker

1. Prima di iniziare

Questo codelab ti guiderà nell'utilizzo dell'API Conversational Analytics (API CA) con Looker per creare la tua applicazione di chat per interrogare i dati. Per ottenere il massimo valore, devi avere familiarità con BigQuery, Looker, LLM e agenti e Python.

Cosa imparerai a fare

Dopo aver seguito questo codelab, avrai imparato:

• Come utilizzare Analisi conversazionale con Looker
• Come configurare e utilizzare l'app di avvio rapido Python Conversational Analytics (e come funziona l'app)
• I vantaggi dell'utilizzo di Looker per la modellazione semantica con Conversational Analytics

Che cosa ti serve

Per completare questo codelab, ti serviranno:

• Un'istanza di Looker con il Looker Block Dati demografici ASC installato
• Accesso all'API e agli sviluppatori alla tua istanza Looker
• Un ambiente locale con Python v3.11+, 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. Crea e prova la tua app di chat con BigQuery

Innanzitutto, configuriamo e proviamo l'app di avvio rapido Conversational Analytics con BigQuery come origine dati.

Autenticare e abilitare le API Cloud

1. Esegui l'autenticazione localmente con il tuo account utente:

gcloud auth login

2. 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

3. Imposta le credenziali predefinite dell'applicazione (ADC) e la fatturazione:

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

Configurare l'app di avvio rapido

4. Clona il repository GitHub della guida rapida nel tuo ambiente locale. Vedi il seguente comando di esempio:

git clone "https://github.com/looker-open-source/ca-api-quickstarts"

5. Vai alla directory ca-api-quickstarts che hai clonato:

cd ca-api-quickstarts

6. Crea un file secrets.toml nella directory .streamlit. YOUR_LOOKER_CLIENT_ID e YOUR_LOOKER_CLIENT_SECRET devono essere l'ID client e il client secret di Looker della tua istanza Looker. I contenuti del file devono essere i seguenti:

[cloud]
project_id = "YOUR_PROJECT_ID"

[looker]
client_id = "YOUR_LOOKER_CLIENT_ID"
client_secret = "YOUR_LOOKER_CLIENT_SECRET"

Puoi utilizzare il seguente comando di esempio per creare il file. Assicurati di sostituire i valori con l'ID progetto, l'ID client e il client secret:

cat > .streamlit/secrets.toml <<'EOF'
[cloud]
project_id = "YOUR_PROJECT_ID"

[looker]
client_id = "YOUR_LOOKER_CLIENT_ID"
client_secret = "YOUR_LOOKER_CLIENT_SECRET"
EOF

7. Installa i requisiti Python dell'app di avvio rapido:

pip install -r requirements.txt

8. Esegui l'app di avvio rapido:

streamlit run app.py

Stai eseguendo un'app Streamlit creata su misura, un framework di app Python open source che ti consente di prototipare app di dati interattive. Per saperne di più, consulta la documentazione di Streamlit.

9. Apri https://localhost:8501 nel browser che preferisci.

Prova l'app di avvio rapido

Ora ti trovi nella pagina degli agenti dell'app di avvio rapido. Non hai agenti di dati disponibili.

Che cos'è un agente AI per i dati? Gli agenti AI sono sistemi software che sfruttano l'AI per perseguire obiettivi e completare attività per conto degli utenti. Mostrano capacità di ragionamento, pianificazione e memoria e hanno un livello di autonomia tale da essere in grado di prendere decisioni, apprendere e adattarsi. Nel nostro caso d'uso, utilizziamo gli agenti AI per comprendere i nostri dati. Il comportamento di un agente è dettato dalle istruzioni di sistema definite per lui. Per saperne di più, consulta l'articolo Cosa sono gli agenti AI?.

10. Ora creiamo un agente dati che parli come un pirata nel modulo Crea agente:
11. Imposta il campo Nome visualizzato:

Pirate BQ Agent

2. Imposta il campo Istruzioni di sistema:

You are a pirate. Answer questions like a pirate

3. Seleziona l'opzione BigQuery.
4. Imposta il campo Progetto:

bigquery-public-data

5. Imposta il campo Dataset:

google_trends

6. Imposta il campo Table (Tabella):

top_rising_terms

11. Seleziona Crea agente.

Il modulo Create Agent dell'app di avvio rapido chiama l'endpoint create dataAgent dell'API CA tramite l'SDK Python di gcloud, passando le istruzioni di sistema e l'origine dati dell'agente. L'app utilizza l'SDK Python gcloud per tutte le chiamate API CA.

12. Ora passiamo alla pagina della chat tramite il menu di navigazione principale a sinistra. Il nostro nuovo agente è disponibile per la chat. Iniziamo una chat aggiungendo un prompt/messaggio: "Ciao, come stai?"
13. Ora scopriamo qualcosa di più su questo set di dati: "Che cosa contiene questo set di dati?"

Cosa succede quando invii un prompt (o un messaggio) nella chat? L'app invia il messaggio come payload all'endpoint chat dell'API CA. L'API CA utilizza in background le istruzioni di sistema e le informazioni dell'agente dati come contesto per il prompt e invia il prompt e il contesto a Gemini. Quindi, l'API CA trasmette in streaming la risposta di Gemini.

14. Poni un'altra domanda, ad esempio:
15. "Quali località di [inserisci stato] sono presenti nel set di dati?"
16. "Puoi darmi i dati delle ultime due settimane per [città, stato]?"
17. "Puoi creare una visualizzazione?"

Hai appena avuto una conversazione in più turni con il tuo agente di dati e i tuoi dati BigQuery nella tua applicazione di chat.

3. Modellare ed esplorare i dati in Looker

Ora modelliamo ed esploriamo gli stessi dati BigQuery in Looker.

Esegui query sui dati del censimento di BigQuery

Cosa succede quando ci connettiamo a un set di dati relazionale più grande? Per prima cosa, creiamo un nuovo agente.

1. Torna al modulo Crea agente della pagina degli agenti.
2. Imposta il campo Nome visualizzato:

BQ Census Agent

2. Imposta il campo Istruzioni di sistema:

You are really excited about census data, you love learning about the demographics in your area because you want to come up with marketing campaigns for your company

3. Seleziona l'opzione BigQuery.
4. Imposta il campo Progetto:

bigquery-public-data

5. Imposta il campo Dataset:

census_bureau_acs

6. Imposta il campo Table (Tabella):

blockgroup_2018_5yr

2. Seleziona Crea agente.
3. Poni all'agente appena creato entrambe le domande:
4. "Quali dati hai?"
5. "Puoi mostrarmi un'anteprima dei miei dati?"

Quando chiedi all'agente un'anteprima dei dati, puoi notare che la tabella non ha una posizione leggibile associata, ma solo un identificatore geografico (geo_id).

Utilizzare Looker per modellare i dati del censimento

Ora utilizzeremo un modello LookML per definire i dati del censimento di BigQuery. Risolviamo i problemi che abbiamo appena visto.

4. Accedi all'istanza di Looker.
5. Vai ai file del blocco di dati demografici ACS selezionando Sviluppa nel menu di navigazione principale a sinistra e poi marketplace_acs_census-v2.
6. Diamo un'occhiata a una visualizzazione di Looker. Apri la directory imported_project, la directory acs_census-v2 e la directory geography.
7. Infine, apri il file cbsa.view.
8. Alla riga 17, possiamo vedere che LookML sta creando una tabella derivata. In altre parole, questo codice crea una nuova tabella combinata unendo due set di dati pubblici BigQuery, uno con i dati del censimento e l'altro con i dati dei confini geografici. LookML ci consente di unire più set di dati creando una tabella derivata persistente su cui eseguire query.

Una tabella derivata persistente (PDT) è una tabella creata da Looker e archiviata nel tuo database (in questo caso, BigQuery). È una vista materializzata di una query complessa. Anziché eseguire la stessa query costosa ogni volta che un utente richiede un report, Looker può eseguire query in modo più efficiente sulla PDT precalcolata per aumentare le prestazioni e ridurre il tempo di esecuzione delle query.

Inoltre, l'unione è definita nel codice controllabile in base alla versione (LookML) anziché nelle istruzioni di sistema, il che rende lo sviluppo di agenti più scalabile. Con LookML, puoi definire ipotesi e vincoli specifici relativi ai tuoi dati per supportare gli utenti mentre interagiscono con i dati tramite un agente dati.

Esplorare i dati censuari modellati di Looker

Eseguiamo una query rapida in un'esplorazione per dimostrare che abbiamo un'unica origine dati centralizzata da interrogare.

9. Nel menu di navigazione principale a sinistra, seleziona Esplora, poi Blocco di dati del censimento e infine Stato e contea.
10. Seleziona la misura Istruzione > Diploma di scuola superiore.
11. Seleziona le seguenti dimensioni:
12. Area geografica > Gruppo di isolati
13. Area geografica > Contea > Nome della contea
14. Area geografica > Stato > Stato.
15. Esegui la query (in alto a destra) e vedrai che gli ID geografici (chiamati "Gruppo di isolati") sono ora associati a stringhe leggibili.
16. Apri la scheda di visualizzazione e vedrai questi dati in una mappa.

4. Provare l'app di chat con Looker

Ora creiamo un agente dati per Looker.

1. Vai al modulo Crea agente della pagina dell'agente dell'app di avvio rapido:
2. Imposta il campo Nome visualizzato:

Cartoon character data analyst

2. Imposta il campo Istruzioni di sistema:

You are [fill in your favorite cartoon character, Bugs Bunny is a favorite]. Answer questions like that cartoon character

3. Seleziona l'opzione Looker.
4. Imposta il campo Url sull'URL dell'istanza di Looker: "https://..."
5. Imposta il campo Modello:

data_block_acs_bigquery

6. Imposta il campo Esplora:

cbsa

7. Seleziona Crea agente.
8. Vai alla pagina della chat e seleziona l'agente appena creato.
9. Iniziamo una chat aggiungendo un prompt/messaggio: "Ciao, come stai?"
10. Chiediamo all'agente di descrivere il set di dati: "Quali dati sono disponibili?"
11. Poniamo altre domande:
12. "Quale contea di New York ha la popolazione più numerosa?"
13. "E per quanto riguarda il maggior numero di diplomati delle scuole superiori pro capite?"
14. "Puoi darmi la popolazione per genere e stato?"
15. "Vorrei vedere un grafico a barre dei 10 stati con la popolazione più numerosa".

Vedi la visualizzazione del grafico a barre nella conversazione? L'API CA ha inviato un messaggio all'app con una specifica del grafico Vega. La specifica del grafico Vega contiene i dati e le configurazioni della visualizzazione, come colori, assi, tipo di grafico e così via. Con la specifica, l'app Streamlit lo ha visualizzato come un grafico Vega interattivo che puoi visualizzare e con cui puoi interagire. L'API CA ti consente non solo di eseguire query, ma anche di visualizzare i dati con gli agenti dati, producendo configurazioni di visualizzazione standard per una facile visualizzazione.

5. Cos'altro può fare l'app di avvio rapido?

Ora hai:

• Configurare l'app di chat localmente
• È stato creato un agente dati BigQuery e un agente dati Looker
• Conversazioni con gli agenti dei dati
• Scoperto i vantaggi della modellazione semantica di Looker come contesto per le tue chat

Proviamo le altre funzionalità dell'app di avvio rapido:

1. Ricarica la pagina web dell'app di avvio rapido e vai alla pagina della chat.
2. Puoi visualizzare le conversazioni passate con tutti i rispettivi messaggi degli agenti BigQuery e Looker. Il frontend dell'app non memorizza le conversazioni o i messaggi passati, ma li recupera dall'API CA.

L'API CA fornisce endpoint per tutte le conversazioni passate e i relativi messaggi. L'app recupera le conversazioni passate dall'endpoint Elenca conversazioni dell'API CA. L'app recupera quindi tutti i messaggi passati della conversazione dall'endpoint List messages. Quando invii un messaggio a una conversazione, l'API CA può associare i messaggi a una conversazione per includere tutti i messaggi precedenti nella conversazione come contesto per una conversazione multi-turn più utile.

3. Ora vai alla pagina degli agenti e seleziona il tuo agente Looker dall'elenco.
4. Puoi aggiornare le configurazioni dell'agente o eliminarlo, se vuoi. Nessun agente viene memorizzato nel frontend dell'app.

L'app chiama gli endpoint forniti dall'API CA per elencare, creare, aggiornare ed eliminare gli agenti. L'app utilizza la funzionalità dell'API CA per archiviare e gestire i propri agenti. L'API CA fornisce anche altre operazioni sugli agenti.

6. Sfide facoltative ed esplorazione più approfondita

Se vuoi, puoi cogliere l'occasione per familiarizzare con Conversational Analytics e l'app di avvio rapido. In alternativa, puoi provare a modificare l'app di avvio rapido. Puoi provare alcuni dei suggerimenti e delle sfide riportati di seguito o passare direttamente alla sezione finale.

Acquisire maggiore familiarità con l'API CA e l'app di avvio rapido

• Scopri di più sulle istruzioni di sistema approfondite per controllare il comportamento dell'agente.
• Configura un altro agente dati che rimandi a un nuovo set di dati BigQuery.
• Installa un nuovo blocco Looker nell'istanza di Looker, crea un agente e indirizzalo a un nuovo set di dati di Looker.

Sfide relative alla modifica rapida dell'app

• Conosci l'incorporamento di Looker? In questo caso, prova a incorporare una dashboard Looker all'interno dell'app di avvio rapido. Valuta la possibilità di utilizzare il componente iframe di Streamlit.
• Trova un set di dati pubblico contenente URL di video e aggiorna la logica di rendering della chat dell'app per mostrare un video nella chat.

7. Conclusione e punti chiave

Hai risposto fino all'ultima domanda! Hai creato un'app di chat, agenti di dati e chattato con i tuoi dati utilizzando l'API Conversational Analytics. Rivediamo alcune funzionalità e concetti chiave.

Funzionalità di Analisi conversazionale

Abbiamo esaminato molte delle funzionalità di analisi conversazionale, come la possibilità di:

• Crea, aggiorna, elenca, recupera ed elimina agenti di dati.
• Indica agli agenti di dati BigQuery o Looker come origine dati.
• Crea, elenca e recupera conversazioni e i rispettivi messaggi.
• Produci specifiche del grafico Vega per la visualizzazione immersiva nelle conversazioni.
• Utilizzare i messaggi passati in una conversazione come contesto utile per i messaggi futuri.

Vantaggi dell'utilizzo di Looker con l'API CA

Looker offre una modellazione semantica centralizzata, verificabile e governabile dei tuoi dati. In combinazione con l'analisi conversazionale, Looker offre un modo scalabile per fornire il contesto per gli agenti di dati.

Passaggi successivi

• Per ulteriori guide, funzionalità e casi d'uso, consulta la documentazione di Conversational Analytics.
• Rimani al passo con gli aggiornamenti e contribuisci al repository dell'applicazione di avvio rapido.