Introduzione all'analisi conversazionale in BigQuery

1. Introduzione

Ottenere approfondimenti dai dati spesso richiede tempo, impegno e competenze SQL approfondite. In questo codelab, esplorerai il catalogo degli agenti di BigQuery, una nuova piattaforma che fornisce approfondimenti istantanei basati sull'AI tramite agenti di dati conversazionali.

Andrai oltre la semplice conversione da testo a SQL creando un agente di dati curato. Scoprirai come arricchire l'agente con il contesto aziendale, le istruzioni di sistema e le query verificate per garantire risultati di elevata precisione. Infine, pubblicherai questo agente per l'utilizzo da parte di altri utenti della tua organizzazione.

Prerequisiti

• Una conoscenza di base di Google Cloud

Cosa imparerai a fare

• Come navigare nel catalogo degli agenti di BigQuery
• Come creare un agente personalizzato e definire le fonti di conoscenza
• Come utilizzare Gemini per generare metadati semantici
• Come aggiungere istruzioni di sistema e query verificate per guidare l'agente
• Come pubblicare e condividere gli agenti

Che cosa ti serve

• Un account Google Cloud e un progetto Google Cloud
• Conoscenza di base di BigQuery e SQL
• Un browser web come Chrome

2. Configurazione e requisiti

Scegliere un progetto

1. Accedi alla console Google Cloud e crea un nuovo progetto o riutilizzane uno esistente. Se non hai già un account Gmail o Google Workspace, devi crearne uno.

• Il nome del progetto è il nome visualizzato per i partecipanti a questo progetto. È una stringa di caratteri non utilizzata dalle API di Google. Puoi aggiornarlo in qualsiasi momento.
• L'ID progetto è univoco in tutti i progetti Google Cloud ed è immutabile (non può essere modificato dopo l'impostazione). La console Cloud genera automaticamente una stringa univoca; in genere non ti interessa quale sia. Nella maggior parte dei codelab, dovrai fare riferimento all'ID progetto (in genere identificato come PROJECT_ID). Se non ti piace l'ID generato, puoi generarne un altro casuale. In alternativa, puoi provare a crearne uno e verificare se è disponibile. Non può essere modificato dopo questo passaggio e rimane per tutta la durata del progetto.
• Per tua informazione, esiste un terzo valore, un numero di progetto, utilizzato da alcune API. Scopri di più su tutti e tre questi valori nella documentazione.

Attenzione: un ID progetto è univoco a livello globale e non può essere utilizzato da nessun altro dopo averlo selezionato. Sei l'unico utente di questo ID. Anche se un progetto viene eliminato, l'ID non può essere riutilizzato

Nota: se utilizzi un account Gmail, puoi lasciare la località predefinita impostata su Nessuna organizzazione. Se utilizzi un account Google Workspace, scegli una località che abbia senso per la tua organizzazione.

2. Successivamente, dovrai abilitare la fatturazione nella console Cloud per utilizzare le risorse/API Cloud. L'esecuzione di questo codelab non costerà molto, se non nulla. Per arrestare le risorse ed evitare addebiti di fatturazione oltre questo tutorial, puoi eliminare le risorse che hai creato o eliminare il progetto. I nuovi utenti di Google Cloud possono usufruire del programma di prova senza costi di 300$.

3. Prima di iniziare

Concedere i ruoli richiesti

Vai alla pagina IAM del progetto e concediti il ruolo Proprietario dell'agente di dati di Gemini Data Analytics:

Questo ruolo ti concede l'autorizzazione a creare, modificare, condividere ed eliminare tutti gli agenti di dati nel progetto.

Abilitare le API richieste

Utilizza il menu di navigazione della barra laterale o il menu di ricerca nella parte superiore della pagina per andare a BigQuery > Agenti.

Fai clic su Abilita l'API Data Analytics con Gemini:

Abilita sia l'API Gemini in BigQuery sia l'API Gemini for Google Cloud:

Ora dovresti visualizzare la nuova pagina dell'agente:

4. Creare un agente

Creiamo il tuo primo agente di dati utilizzando il set di dati pubblico internazionale di Google Trends. Questo set di dati è utile per porre domande sui termini di ricerca di tendenza a livello internazionale e su come questi interessi si confrontano storicamente.

Iniziamo assegnando un nome e una breve descrizione all'agente. Questa descrizione viene utilizzata esclusivamente per consentire ad altri utenti di comprendere lo scopo dell'agente.

Nome agente

Google Trends Agent

Descrizione agente

Data agent for the Google Trends International Top Terms public dataset

Fonti di conoscenza

Ora aggiungi le fonti di conoscenza. Una fonte di conoscenza è una tabella BigQuery, una vista o una funzione definita dall'utente che l'agente può utilizzare per rispondere alle domande.

Per questa demo, aggiungi una sola tabella per semplicità. Tuttavia, tieni presente che puoi aggiungere fino a 50 fonti di conoscenza per agente per gestire scenari di dati più complessi.

Inserisci la seguente tabella nella casella di ricerca, seleziona la casella e fai clic su Aggiungi:

bigquery-public-data.google_trends.international_top_terms

Contesto strutturato

Per migliorare l'accuratezza dell'agente di dati, aggiungi un contesto strutturato alla tabella e alle colonne. Fai clic su Customise:

Nota: in questo modo puoi aggiungere descrizioni a livello di tabella e colonna. Poiché l'origine è un set di dati pubblico che non può essere modificato direttamente, questi override aiutano l'agente a comprendere i dati senza alterare la tabella originale.

Gemini genera automaticamente suggerimenti per le descrizioni. Fai clic su Accetta accanto a Descrizione tabella:

Per applicare le descrizioni a tutte le colonne, seleziona Seleziona tutte le righe e poi fai clic su Accetta suggerimenti:

(Facoltativo) Modifica manualmente campi specifici facendo clic sull'icona di modifica accanto al nome di una colonna.

Fai clic su Aggiorna nella parte inferiore della pagina per salvare le modifiche e tornare all'editor dell'agente.

Istruzioni

La finestra di dialogo delle istruzioni dell'agente è il punto in cui puoi fornire all'agente indicazioni aggiuntive per interpretare ed eseguire query sulle origini dati. È incluso quanto segue:

• Sinonimi: termini alternativi per i campi chiave.
• Campi chiave: i campi più importanti per l'analisi.
• Campi esclusi: campi che l'agente di dati deve evitare.
• Filtro e raggruppamento: campi che l'agente deve utilizzare per filtrare e raggruppare i dati.
• Relazioni di unione: come vengono combinate due o più tabelle in base a campi comuni.

Per saperne di più sulle sfumature tra le istruzioni dell'agente (indicazioni supplementari in formato libero) e il contesto strutturato, consulta la guida al contesto creata per l'API Analisi conversazionale.

Per le best practice sulle istruzioni dell'agente, consulta la guida Creare un agente di dati.

Copia e incolla le seguenti istruzioni:

### System Instruction

* You are an expert data analyst for the Google Trends International public dataset.
* Always filter on yesterday's refresh_date = DATE_SUB(CURRENT_DATE(), INTERVAL 1 DAY).
* If yesterday returns no data, filter on 2 days ago's refresh_date = DATE_SUB(CURRENT_DATE(), INTERVAL 2 DAY).
* Default to country-level results (one row per term).
* "Top" queries must deduplicate snapshot rows.
* Only include week or score when the user explicitly asks for trends over time.
* This is an international dataset and does not include any data for the United States.

### Additional Descriptions

#### 1. Core model:

* refresh_date selects the daily Top-25 term set.
* week + score are historical weekly values attached to those terms.
* Filtering week does not change which terms appear.

#### 2. Deduplication rule (critical):

* Snapshot rows repeat across weeks and regions.
* For "top" queries, always GROUP BY term (country-level) and compute rank as MIN(rank).

#### 3. Defaults:

* Country-level results only.
* Use region_code only if the user explicitly asks for regions.
* Limit results unless the user asks otherwise.

#### 4. Time series usage:

* Only include week or score when the user asks for trends over time, historical context, or week-over-week score changes.

#### 5. Field guidance:

* Prefer country_code or region_code for filters.
* country_name / region_name are for display only.
* score is normalized; compare trends within a term, not across terms.

Query verificate

Le query verificate, in precedenza note come query dorate, vengono utilizzate come riferimento per l'agente per migliorare l'accuratezza delle risposte. Definiscono la struttura della risposta di un agente e aiutano a insegnare all'agente la logica di business utilizzata dalla tua organizzazione.

Aggiungiamo due esempi per il tuo agente. Fai clic su Aggiungi query e copia / incolla la seguente domanda e query:

Domanda 1:

What are the top search terms in the UK right now?

Query 1:

SELECT term, MIN(rank) AS rank
FROM `bigquery-public-data.google_trends.international_top_terms`
WHERE refresh_date = DATE_SUB(CURRENT_DATE(), INTERVAL 1 DAY)
  AND country_code = 'GB'
GROUP BY term
ORDER BY rank
LIMIT 25;

Prima di salvare questa query, eseguiamola per assicurarci che sia valida.

Per me va bene. Fai clic su Aggiungi per salvare la query verificata.

Aggiungiamo un altro esempio per un caso d'uso più complesso. Fai clic su Gestisci query e aggiungi:

Domanda 2:

Show the last 12 weeks of interest for the current top 5 terms in Auckland.

Risposta 2:

WITH top5 AS (
  SELECT term, MIN(rank) AS rank
  FROM `bigquery-public-data.google_trends.international_top_terms`
  WHERE refresh_date = DATE_SUB(CURRENT_DATE(), INTERVAL 1 DAY)
    AND country_code = 'NZ'
    AND region_code = 'NZ-AUK'
  GROUP BY 1
  ORDER BY 2
  LIMIT 5
),
series AS (
  SELECT term, week, score,
    ROW_NUMBER() OVER (PARTITION BY term ORDER BY week DESC) AS rn
  FROM `bigquery-public-data.google_trends.international_top_terms`
  WHERE refresh_date = DATE_SUB(CURRENT_DATE(), INTERVAL 1 DAY)
    AND country_code = 'NZ'
    AND region_code = 'NZ-AUK'
    AND term IN (SELECT term FROM top5)
)
SELECT week, term, score
FROM series
WHERE rn <= 12
ORDER BY 1 DESC, 3

Prima di passare alla sezione successiva, esaminiamo i suggerimenti generati da Gemini:

Qui puoi vedere alcune query verificate suggerite. Quando crei un nuovo agente in futuro, questo è un ottimo punto di partenza. Assicurati solo di convalidare tutte le query che aggiungi.

Glossario

Aggiungiamo un termine al glossario. Se la tua attività utilizza Dataplex, questi termini vengono importati direttamente dal glossario aziendale in Dataplex Universal Catalog.

Fai clic su Aggiungi termine e copia / incolla il seguente esempio:

Termine:

refresh_date

Definizione:

Snapshot date that selects the daily Top 25 term set. All rows for that date belong to the same "what's trending now" snapshot. Attach Historical week and score values after this selection.

Sinonimi:

today, latest, current, now, recent

Quindi, fai clic su Aggiungi e poi su Salva.

Impostazioni dell'agente

Nella sezione Impostazioni, puoi configurare le etichette e i byte fatturati massimi.

Etichette

Le etichette sono coppie chiave-valore utilizzate per organizzare le risorse Google Cloud in gruppi logici. Per mantenere questo lab concentrato, lascia vuote le etichette.

Byte fatturati massimi

Per evitare di generare accidentalmente query costose, impostiamo un limite per i byte fatturati massimi per query. Se la query dell'agente elabora byte superiori a questo limite, la query ha esito negativo senza addebiti. Inserisci il seguente valore:

10000000000

10.000.000.000 di byte corrispondono a circa 9,3 GB. Se non specifichi un valore, i byte fatturati massimi vengono impostati per impostazione predefinita sulla quota di utilizzo delle query del progetto al giorno.

5. Salvare e condividere l'agente

Anteprima

Ecco fatto. Testiamo l'agente prima di procedere. Sul lato destro dello schermo puoi testare dinamicamente l'agente mentre apporti modifiche alla configurazione. L'anteprima utilizza automaticamente i nuovi metadati che fornisci senza salvare o pubblicare le modifiche.

Chiediamo a quali dati ha accesso l'agente. Non esitare a porre alcune domande con le tue parole:

Salva

Dopo aver testato alcuni prompt, Salva e poi Pubblica l'agente:

La pubblicazione dell'agente lo renderà disponibile in BigQuery Studio, nell'API Analisi conversazionale e in Looker Studio Pro (soggetto a licenza):

Il supporto per altre superfici e integrazioni è previsto per le release future.

Condividi

Dovresti visualizzare un messaggio di conferma della pubblicazione dell'agente. Ora puoi condividere questo agente con altri utenti.

Quando condividi un agente con altri utenti, controlli il loro livello di accesso assegnando loro un ruolo specifico. Questi ruoli determinano se un collaboratore può semplicemente visualizzare l'agente o se ha la possibilità di modificarne e gestirne la configurazione.

È importante notare che questi ruoli possono essere applicati a due livelli diversi:

• A livello di progetto: la concessione di un ruolo a livello di progetto fornisce all'utente queste autorizzazioni per tutti gli agenti all'interno di quel progetto Google Cloud.
• A livello di agente: per un controllo più granulare, puoi concedere ruoli per un agente specifico. Questa opzione è utile quando vuoi che un utente abbia accesso a un agente di dati specifico senza visualizzare gli altri nel progetto.

Per una suddivisione dettagliata di come gestire l'accesso, consulta la documentazione dell'API Analisi conversazionale sugli ambiti IAM tipici e sulle autorizzazioni specifiche incluse in ogni ruolo predefinito.

I ruoli predefiniti per Analisi conversazionale sono i seguenti:

1. Proprietario dell'agente di dati di Gemini Data Analytics (roles/geminidataanalytics.dataAgentOwner) - Crea, modifica, condividi ed elimina tutti gli agenti di dati
2. Creatore dell'agente di dati di Gemini Data Analytics (roles/geminidataanalytics.dataAgentCreator) - Crea, modifica, condividi ed elimina i tuoi agenti di dati
3. Editor dell'agente di dati di Gemini Data Analytics (roles/geminidataanalytics.dataAgentEditor) - Accesso in chat e in modifica agli agenti di dati
4. Utente agente di dati di Gemini Data Analytics (roles/geminidataanalytics.dataAgentUser) - Accesso in chat e in visualizzazione agli agenti di dati
5. Visualizzatore dell'agente di dati di Gemini Data Analytics (roles/geminidataanalytics.dataAgentViewer) - Accesso in visualizzazione (sola lettura) agli agenti di dati

6. Creare una conversazione con un agente

Usciamo dalla scheda Condividi e creiamo una nuova conversazione:

Quando fai clic su Crea conversazione, viene generata una nuova conversazione senza titolo.

Chiediamo quali termini sono di tendenza in Inghilterra (non esitare a sostituirli con una località a tua scelta):

Based on the top 10 terms in England, how did they trend for the past 3 months?

Decodificare lo stream di risposte

In genere, l'agente di dati segue lo stesso stream di risposte quando risponde alle domande:

1. Ragionamento: l'agente prima "riflette" sul prompt. Espandi il pulsante Mostra ragionamento per visualizzare approfondimenti passo passo sul processo decisionale dell'agente.
2. Riepilogo: l'agente genera un riepilogo di alto livello della query, del report risultante e della visualizzazione.
3. SQL generato: espandi la sezione Ecco la query... per esaminare l'SQL. Fai clic su Apri nell'editor per ottimizzare manualmente la query in BigQuery Studio.
4. Risultati dei dati: l'agente presenta i risultati della query in un formato tabulare chiaro.
5. Visualizzazione: accanto a una breve descrizione viene visualizzato un grafico. L'agente deduce automaticamente il tipo di visualizzazione migliore (ad es. un grafico a linee a più serie) per i tuoi dati.
6. Approfondimenti sui dati: l'agente riepiloga le tendenze e i risultati chiave trovati nei risultati.
7. Domande di follow-up: infine, l'agente suggerisce domande di follow-up pertinenti per aiutarti a continuare l'analisi.

Supporto di BigQuery ML

Chiediamo se l'agente di dati può eseguire alcune previsioni in base a questi risultati. Questa operazione utilizza le funzioni di BigQuery ML per prevedere i punti futuri.

Nota: per maggiori dettagli sulle funzioni ML supportate, consulta la documentazione.

Inserisci il seguente prompt (assicurati di sostituire "monopoly board" con un termine pertinente per la tua query):

Can you predict and visualize how monopoly board will trend in the next 4 weeks?

Puoi vedere che AI_FORECAST è stato utilizzato per prevedere una serie temporale. Non sorprende, anche se è interessante notare un picco significativo nell'agosto 2021, che coincide con la grande apertura dell'attrazione Monopoly Lifesized a Londra.

7. Esplorare il catalogo degli agenti

Esploriamo il catalogo degli agenti prima di concludere. Fai clic su Catalogo degli agenti nella parte superiore della finestra:

Questa pagina funge da hub centrale per la gestione degli agenti di dati, organizzata nelle seguenti sezioni:

• I miei agenti: gli agenti attualmente pubblicati.
• Le mie bozze di agenti: le configurazioni che hai salvato ma non ancora pubblicato.
• Condiviso da altri membri della tua organizzazione: agenti creati da colleghi a cui hai l'autorizzazione ad accedere.
• Agenti di esempio di Google: esempi preconfigurati per aiutarti a iniziare.

Per qualsiasi agente gestito, puoi modificare le configurazioni, duplicare gli agenti e gestire le autorizzazioni di condivisione.

Nota: Analisi conversazionale in BigQuery è basato sull'API Analisi conversazionale. È possibile accedere in modo programmatico tramite l'API anche alle funzionalità disponibili nella console, il che ti offre la massima flessibilità per visualizzare i messaggi e integrarli con altri agenti e origini dati.

8. Conclusione

Congratulazioni, hai creato un agente di dati di Analisi conversazionale. Consulta i materiali di riferimento per saperne di più.

Materiali di riferimento

• Panoramica di Analisi conversazionale in BigQuery
• Panoramica dell'API Analisi conversazionale