Introduzione all'analisi conversazionale in BigQuery

1. Introduzione

Ottenere informazioni 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 insight istantanei basati sull'AI tramite agenti di dati conversazionali.

Andrai oltre la semplice conversione da testo a SQL creando un agente di dati curato. Imparerai ad arricchire l'agente con il contesto aziendale, le istruzioni di sistema e le query verificate per garantire risultati estremamente accurati. 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 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 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 ancora 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 sempre aggiornarlo.
• 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, di solito non ti interessa di cosa si tratta. Nella maggior parte dei codelab, dovrai fare riferimento all'ID progetto (in genere identificato come PROJECT_ID). Se l'ID generato non ti piace, puoi generarne un altro casuale. In alternativa, puoi provare a crearne uno e vedere 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 altri dopo che lo hai 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 posizione predefinita impostata su Nessuna organizzazione. Se utilizzi un account Google Workspace, scegli una posizione adatta alla tua organizzazione.

2. Successivamente, devi abilitare la fatturazione in Cloud Console per utilizzare le risorse/API Cloud. Completare questo codelab non costa molto, se non nulla. Per arrestare le risorse ed evitare addebiti oltre a quelli previsti in questo tutorial, puoi eliminare le risorse che hai creato o il progetto. I nuovi utenti di Google Cloud possono beneficiare del programma prova senza costi di 300$.

3. Prima di iniziare

Concedere a te i ruoli richiesti

Vai alla pagina IAM del progetto e concediti il ruolo Gemini Data Analytics Data Agent Owner:

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

Abilita le API richieste

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

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

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

Ora dovresti vedere la nuova pagina dell'agente:

4. Crea un agente

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

Iniziamo assegnando un nome e una breve descrizione all'agente. Questa descrizione viene utilizzata esclusivamente per aiutare gli altri utenti a 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 informazioni

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

Per questa demo, aggiungi una sola tabella per semplificare le cose. 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 dati, aggiungi un contesto strutturato alla tabella e alle colonne. Fai clic su Customise:

Nota:in questo modo è possibile 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 in fondo alla pagina per salvare le modifiche e tornare all'editor di agenti.

Istruzioni

La finestra di dialogo delle istruzioni dell'agente è il punto in cui puoi fornire all'agente ulteriori indicazioni 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.
• Filtri 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 scoprire di più sulle sfumature tra le istruzioni dell'agente (indicazioni supplementari in formato libero) e il contesto strutturato, consulta la guida al contesto creato per l'API Conversational Analytics.

Per le best practice sulle istruzioni dell'agente, consulta la guida alla creazione di agenti 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, precedentemente 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 l'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, diamo un'occhiata ai 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 qualsiasi 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 il Numero massimo di byte fatturati.

Etichette

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

Numero massimo di byte fatturati

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

10000000000

10.000.000.000 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 al giorno del progetto.

5. Salvataggio e condivisione dell'agente

Anteprima

È tutto pronto. Prima di procedere, testiamo l'agente. 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 fare qualche domanda con parole tue:

Salva

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

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

Il supporto per ulteriori piattaforme 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 il potere 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 le autorizzazioni per tutti gli agenti all'interno di quel progetto Google Cloud.
• Livello agente: per un controllo più granulare, puoi concedere ruoli per un agente specifico. Questa funzionalità è utile quando vuoi che un utente abbia accesso a un determinato agente dati senza visualizzare gli altri nel progetto.

Per una suddivisione dettagliata di come gestire l'accesso, consulta la documentazione dell'API Conversational Analytics 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 dati Gemini Data Analytics (roles/geminidataanalytics.dataAgentOwner) - Crea, modifica, condividi ed elimina tutti gli agenti dati
2. Gemini Data Analytics Data Agent Creator (roles/geminidataanalytics.dataAgentCreator): crea, modifica, condividi ed elimina i tuoi data agent
3. Gemini Data Analytics Data Agent Editor (roles/geminidataanalytics.dataAgentEditor) - Accesso in chat e in modifica agli agenti dati
4. Data Analytics Data Agent User (roles/geminidataanalytics.dataAgentUser) - Accesso in chat e in visualizzazione agli agenti dati
5. Visualizzatore agenti dati Gemini Data Analytics (roles/geminidataanalytics.dataAgentViewer): accesso in visualizzazione (sola lettura) agli agenti dati

6. Crea 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 sono i termini di tendenza in Inghilterra (puoi sostituire questa località con una a tua scelta):

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

Decompressione del flusso di risposta

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

1. Ragionamento: l'agente prima "riflette" sul prompt. Espandi il pulsante Mostra il ragionamento per visualizzare informazioni dettagliate 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 perfezionare manualmente la query in BigQuery Studio.
4. Risultati dei dati: l'agente presenta i risultati della query in un formato tabellare chiaro.
5. Visualizzazione: viene visualizzato un grafico insieme a una breve descrizione. L'agente deduce automaticamente il tipo di visualizzazione migliore (ad es. un grafico a linee multiserie) per i tuoi dati.
6. Approfondimenti sui dati: l'agente riassume le tendenze e i punti chiave rilevati 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

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

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

Inserisci il seguente prompt (assicurati di sostituire "tabellone del Monopoli" 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. Nessuna sorpresa, anche se è interessante notare un picco significativo nell'agosto 2021, in concomitanza con l'inaugurazione dell'attrazione Monopoly Lifesized a Londra.

7. Esplorare il catalogo agenti

Prima di concludere, esploriamo il catalogo degli agenti. Fai clic su Catalogo agenti nella parte superiore della finestra:

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

• I miei agenti: gli agenti attualmente pubblicati.
• Le mie bozze di agenti: configurazioni che hai salvato ma non ancora pubblicato.
• Condivisi da altri membri della tua organizzazione: agenti creati da colleghi a cui hai l'autorizzazione di accesso.
• 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: l'analisi conversazionale in BigQuery è basata sull'API Conversational Analytics. È possibile accedere alle funzionalità disponibili nella console anche in modo programmatico tramite l'API, il che ti offre la massima flessibilità per visualizzare i messaggi e integrarli con agenti e origini dati aggiuntivi.

8. Conclusione

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

Materiali di riferimento

• Panoramica dell'analisi conversazionale in BigQuery
• Panoramica dell'API Conversational Analytics