Crea agenti dati

Questo documento descrive come creare, modificare, gestire ed eliminare gli agenti di dati in BigQuery.

In BigQuery, puoi avere conversazioni con gli agenti di dati per porre domande sui dati di BigQuery utilizzando il linguaggio naturale. Gli agenti di dati contengono metadati delle tabelle e istruzioni di elaborazione delle query specifiche per il caso d'uso che definiscono il modo migliore per rispondere alle domande degli utenti su un insieme di fonti di conoscenza, come tabelle, viste o funzioni definite dall'utente (UDF) che selezioni.

Prima di iniziare

  1. Verify that billing is enabled for your Google Cloud project.

  2. Enable the BigQuery, Gemini Data Analytics, and Gemini for Google Cloud APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

Ruoli obbligatori

Per lavorare con gli agenti dati, devi disporre di uno dei seguenti ruoli Identity and Access Management dell'API Conversational Analytics:

  • Crea, modifica, condividi ed elimina tutti gli agenti dati nel progetto: Gemini Data Analytics Data Agent Owner (roles/geminidataanalytics.dataAgentOwner) sul progetto.
  • Crea, modifica, condividi ed elimina i tuoi data agent nel progetto: Gemini Data Analytics Data Agent Creator (roles/geminidataanalytics.dataAgentCreator) nel progetto. Questo ruolo ti concede automaticamente il ruolo Gemini Data Analytics Data Agent Owner per gli agenti dati che crei.
  • Visualizza e modifica tutti gli agenti dati nel progetto: Gemini Data Analytics Data Agent Editor (roles/geminidataanalytics.dataAgentEditor) a livello di progetto.
  • Visualizza tutti gli agenti di dati nel progetto: Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer).

Inoltre, per creare o modificare un agente dati, devi disporre dei seguenti ruoli:

Per lavorare con le risorse BigQuery, ad esempio visualizzare tabelle o eseguire query, consulta Ruoli BigQuery.

Best practice

Quando utilizzi l'analisi conversazionale, le query vengono eseguite automaticamente per rispondere alle tue domande. Potresti incorrere in addebiti imprevisti nei seguenti casi:

  • Se le tabelle sono grandi
  • Se le query utilizzano unioni di dati
  • Se le query effettuano molte chiamate alle funzioni AI

Per evitare questo problema, considera le dimensioni quando selezioni le fonti di conoscenza e, quando fai conversazioni, valuta la possibilità di utilizzare i join.

Genera insight

Se vuoi, puoi generare approfondimenti sui dati in Dataplex Universal Catalog per qualsiasi tabella che vuoi utilizzare come fonte di conoscenza.

Gli insight generati forniscono metadati della tabella che l'agente dati può utilizzare per aiutare a generare risposte alle tue domande.

Se non generi approfondimenti in anticipo, il sistema li genera automaticamente quando selezioni una tabella come fonte di conoscenza durante la creazione di un agente dati.

Utilizzare l'agente di dati di esempio

Se non hai familiarità con la configurazione degli agenti per l'analisi conversazionale, puoi visualizzare l'agente di esempio predefinito generato per ogni progettoGoogle Cloud . Puoi chattare con l'app e visualizzarne i parametri per vedere come è stata creata, ma non puoi modificarla.

Per visualizzare l'agente di esempio:

  1. Nella console Google Cloud , vai alla pagina Agenti di BigQuery.

    Vai ad Agenti

  2. Seleziona la scheda Catalogo agenti.

  3. Nella sezione Agenti di esempio di Google, fai clic sulla scheda dell'agente di esempio.

Crea un agente dati

Le sezioni seguenti descrivono come creare un agente dati.

Dopo aver creato un agente, puoi modificarne le impostazioni.

Configura le impostazioni di base

  1. Nella console Google Cloud , vai alla pagina Agenti di BigQuery.

    Vai ad Agenti

  2. Seleziona la scheda Catalogo agenti.

  3. Fai clic su Nuovo agente. Viene visualizzata la pagina Nuovo agente.

  4. Nella sezione Editor, nel campo Nome agente, digita un nome descrittivo per l'agente di dati, ad esempio Q4 sales data o User activity logs.

  5. Nel campo Descrizione dell'agente, digita una descrizione dell'agente di dati. Una buona descrizione spiega cosa fa l'agente, quali dati utilizza e ti aiuta a capire quando è l'agente di dati giusto con cui chattare, ad esempio, Ask questions about customer orders and revenue.

  6. Nella sezione Fonti di conoscenza, fai clic su Aggiungi fonte. Si apre la pagina Aggiungi fonte di conoscenza.

  7. Nella sezione Recenti, seleziona le tabelle, le viste o le UDF che vuoi utilizzare come fonti di conoscenza. Le funzioni definite dall'utente sono precedute da un indicatore "fx" nella consoleGoogle Cloud .

  8. Per visualizzare altre fonti di conoscenza, seleziona Mostra altro.

  9. (Facoltativo) Aggiungi una fonte di conoscenza non elencata nella sezione Recenti:

    1. Nella sezione Cerca, digita il nome dell'origine nel campo Cerca tabelle e premi Invio. Il nome dell'origine non deve essere esatto.

    2. Nella sezione Risultati di ricerca, seleziona una o più fonti.

  10. Fai clic su Aggiungi. Viene riaperta la nuova pagina dell'agente.

Personalizzare le descrizioni di tabelle e campi

Per migliorare l'accuratezza dell'agente dati, puoi fornire facoltativamente metadati aggiuntivi della tabella. Solo l'agente dati utilizza questi metadati, che non influiscono sulla tabella di origine.

Segui queste best practice quando crei una tabella e le descrizioni dei campi:

  • Utilizza queste descrizioni come guida per capire come l'agente dati comprende lo schema. Se le descrizioni suggerite dall'agente sono corrette, puoi accettarle.

  • Se l'agente dati non mostra di comprendere lo schema dopo aver configurato queste descrizioni, modificale manualmente per fornire le informazioni corrette.

Per configurare le descrizioni di tabelle e campi:

  1. Nella sezione Fonti di conoscenza, fai clic sul link Personalizza per una tabella.

  2. Crea una descrizione della tabella. Puoi digitare una descrizione nel campo Descrizione tabella o accettare il suggerimento di Gemini.

  3. Nella sezione Campi, rivedi le descrizioni dei campi suggerite da Gemini.

  4. Seleziona le descrizioni dei campi che vuoi accettare e fai clic su Accetta suggerimenti. Seleziona le descrizioni che vuoi rifiutare e fai clic su Rifiuta suggerimenti.

  5. Modifica manualmente la descrizione di qualsiasi campo facendo clic su Modifica Modifica accanto al campo. Viene visualizzato il riquadro Modifica campo.

    1. Nel campo Descrizione, digita una descrizione del campo.
    2. Per salvare la descrizione del campo, fai clic su Aggiorna.

  6. Per salvare la descrizione e gli aggiornamenti dei campi, fai clic su Aggiorna. Viene riaperta la nuova pagina dell'agente.

  7. Ripeti questi passaggi per ogni tabella che deve essere personalizzata.

Configurare le funzionalità avanzate

Configura funzionalità avanzate facoltative come istruzioni per gli agenti, query verificate (in precedenza note come query dorate) e impostazioni.

Crea istruzioni per l'agente

L'agente deve comprendere il contesto delle domande degli utenti senza bisogno di istruzioni personalizzate. Crea istruzioni personalizzate per l'agente solo se devi modificare il comportamento dell'agente o migliorare il contesto in modi non già supportati da altre funzionalità contestuali, ad esempio metadati personalizzati di tabelle e campi o query verificate.

Nella sezione Istruzioni, digita le istruzioni per l'agente dei dati nel campo Istruzioni per l'agente. Poiché l'agente dati utilizza queste istruzioni per comprendere il contesto delle domande degli utenti e fornire risposte, rendi le istruzioni il più chiare possibile.

Se non ricevi una risposta soddisfacente dall'agente, aggiungi un contesto strutturato, ad esempio descrizioni o esempi. Se ancora non ricevi una risposta soddisfacente, aggiungi istruzioni personalizzate come negli esempi della tabella seguente. Per altri esempi di istruzioni, fai clic su Mostra esempi.

Tipo di informazione Descrizione Esempi
Campi chiave I campi più importanti per l'analisi. "I campi più importanti in questa tabella sono: ID cliente, ID prodotto, Data ordine."
Filtri e raggruppamento Campi che l'agente deve utilizzare per filtrare e raggruppare i dati. "Quando una domanda riguarda una cronologia o un periodo di tempo, utilizza sempre la colonna order_created_date". "Quando qualcuno dice "per prodotto", raggruppa in base alla colonna product_category."
Filtro predefinito Campi su cui filtrare per impostazione predefinita. "Se non diversamente indicato, filtra sempre i dati in base a order_status = 'Complete'."
Sinonimi e termini commerciali Termini alternativi per i campi chiave. "Se qualcuno chiede informazioni su "Entrate" o "Vendite", utilizza la colonna total_sale_amount." "Consideriamo "fedeli" i clienti con un valore di purchase_count superiore a 5."
Campi esclusi Campi che l'agente di dati deve evitare di utilizzare. "Non utilizzare mai questi campi: Data transazione derivata, Città derivata."
Relazioni di join Come sono correlate due o più tabelle e quali colonne vengono utilizzate per unirle. L'agente deve utilizzare i JOIN SQL standard sulle coppie di colonne per combinare i dati. Vedi la colonna Esempio. Attività del cliente
  • order_items.user_id = users.id
    (per collegare le vendite ai clienti)
  • events.user_id = users.id
    (per collegare l'attività del sito web ai clienti che hanno eseguito l'accesso)

Creare query verificate

Un agente utilizza le query verificate in due modi:

  • Se un agente può utilizzare una query verificata per rispondere a una domanda che gli poni, per garantire una risposta attendibile, l'agente richiama la query esattamente come è scritta.
  • Se l'agente non può utilizzare la query verificata per rispondere a una domanda, la utilizza comunque come riferimento per comprendere i dati e le best practice per interrogarli.

Puoi selezionare query verificate da un elenco generato dal sistema o crearne di personalizzate.

Per creare una query verificata per l'agente dati, precedentemente nota come query dorata, segui questi passaggi:

  1. Seleziona una o più query verificate suggerite da Gemini:

    1. Nella sezione Query verificate, fai clic su Rivedi suggerimenti. Viene visualizzata la pagina Esamina le query verificate suggerite.
    2. Esamina le query verificate suggerite. Seleziona tutte le opzioni pertinenti al tuo caso d'uso.
    3. Fai clic su Aggiungi. Viene riaperta la nuova pagina dell'agente.

  2. Per creare una query verificata personalizzata, fai clic su Aggiungi query. Si apre la pagina Aggiungi query verificata.

    1. Nel campo Domanda, digita la domanda dell'utente a cui risponde la query verificata.
    2. Fai clic su Genera SQL per consentire a Gemini di generare una query verificata che corrisponda alla domanda dell'utente che hai specificato.
    3. Modifica la query verificata, se vuoi.
    4. Fai clic su Esegui e verifica che la query restituisca i risultati che ti aspetti.
    5. Fai clic su Aggiungi. Viene riaperta la nuova pagina dell'agente.

  3. Ripeti questi passaggi in base alle necessità per creare altre query verificate.

Configura le impostazioni

Nella sezione Impostazioni, puoi configurare le seguenti impostazioni facoltative:

  1. Crea etichette per organizzare le tue risorse Google Cloud . Le etichette sono coppie chiave-valore che consentono di raggruppare oggetti correlati fra loro o con altre risorse Google Cloud .

    1. Nella sezione Impostazioni, fai clic su Gestisci etichette.
    2. Fai clic su Aggiungi etichetta.
    3. Nei campi chiave e valore, inserisci la coppia chiave-valore per l'etichetta.
    4. Se vuoi aggiungere altre etichette, fai di nuovo clic su Aggiungi etichetta.
    5. Per eliminare un'etichetta, fai clic su Elimina.
    6. Al termine, fai clic su Aggiungi. Viene riaperta la nuova pagina dell'agente.

  2. (Facoltativo) Imposta un limite di dimensioni per le query elaborate dall'agente dati. Nella sezione Impostazioni, digita un valore nel campo Byte massimi fatturati. Devi impostare questo limite su 10485760 o un valore superiore, altrimenti riceverai il seguente messaggio di errore:

Value error. In BigQuery on-demand pricing charges are
rounded up to the nearest MB, with a minimum of 10 MB of data processed
per query. So, max bytes billed must be set to greater or equal to
10485760.

Se non specifichi un valore, maximum bytes billed viene impostato per impostazione predefinita sulla quota di utilizzo delle query al giorno del progetto. La quota di utilizzo giornaliero è illimitata, a meno che tu non abbia specificato una quota personalizzata.

Continua alla sezione successiva per mettere l'agente in modalità bozza o pubblicarlo.

Visualizzare l'anteprima e pubblicare l'agente

  1. Nella sezione Anteprima, digita una domanda utente di esempio nel campo Fai una domanda e poi premi Invio. Per verificare che l'agente restituisca i dati che ti aspetti, esamina la sua risposta. Se la risposta non è quella che ti aspettavi, modifica le impostazioni nella sezione Editor per perfezionare la configurazione dell'agente dati finché non ottieni risposte soddisfacenti. Puoi continuare a testare e modificare l'agente per migliorarne i risultati.

  2. Fai clic su Salva.

  3. Per mettere l'agente di dati in modalità bozza, che puoi modificare di nuovo in un secondo momento, fai clic su Torna indietro per tornare alla pagina Catalogo agenti. Poiché l'agente è ora in modalità bozza, viene visualizzato nella sezione I miei agenti bozza della scheda Catalogo agenti.

    Per pubblicare l'agente, rimani nella pagina di creazione dell'agente e vai al passaggio successivo.

  4. Fai clic su Pubblica per pubblicare l'agente dati e renderlo disponibile per l'utilizzo nel progetto. Puoi creare conversazioni con l'agente dati utilizzando BigQuery Studio e utilizzando Looker Studio Pro se hai un abbonamento a Looker Studio. Puoi anche creare la tua interfaccia per chattare con l'agente di dati utilizzando l'API Conversational Analytics.

  5. (Facoltativo) Nella finestra di dialogo Il tuo agente è stato pubblicato, fai clic su Condividi per condividere l'agente dati con altri utenti.

    1. Nel riquadro Autorizzazioni di condivisione, fai clic su Aggiungi entità.

    2. Nel campo Nuove entità, inserisci una o più entità.

    3. Fai clic sull'elenco Seleziona un ruolo.

    4. Nell'elenco Ruolo, seleziona uno dei seguenti ruoli:

      • Gemini Data Analytics Data Agent User (roles/geminidataanalytics.dataAgentUser): concede l'autorizzazione a chattare con il data agent.
      • Gemini Data Analytics Data Agent Editor (roles/geminidataanalytics.dataAgentEditor): concede l'autorizzazione per modificare il data agent.
      • Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer): concede l'autorizzazione a visualizzare il data agent.

  6. Fai clic su Salva.

  7. Per tornare alla nuova pagina dell'agente, fai clic su Chiudi. Subito dopo aver salvato o pubblicato l'agente, puoi visualizzarlo nel catalogo degli agenti.

Gestisci agenti dati

Puoi trovare gli agenti esistenti nella scheda Catalogo degli agenti, che è composta da tre sezioni:

  • I miei agenti: un elenco di tutti gli agenti che crei e pubblichi. Puoi modificare e condividere gli agenti pubblicati con altri utenti.
  • Le mie bozze di agenti: gli agenti che non hai ancora pubblicato. Non puoi condividere agenti bozza.
  • Condivisi da altri membri della tua organizzazione: agenti creati e condivisi con te da altri utenti. Se altri ti concedono autorizzazioni, puoi modificare questi agenti condivisi.

Modificare un agente dati

Per modificare un agente dei dati:

  1. Vai alla pagina Agenti di BigQuery.

    Vai ad Agenti

  2. Seleziona la scheda Catalogo agenti.

  3. Individua la scheda dell'agente dati che vuoi modificare.

  4. Per aprire l'agente di dati nell'editor degli agenti, fai clic su Apri azioni > fai clic su Modifica nella scheda dell'agente.

  5. Modifica la configurazione dell'agente dati in base alle esigenze.

  6. Per salvare le modifiche senza pubblicarle, fai clic su Salva.

  7. Per pubblicare le modifiche, fai clic su Pubblica . Nella finestra di dialogo Condividi, puoi condividere l'agente con altri utenti o fare clic su Annulla.

  8. Per tornare al riquadro Agenti, fai clic su Indietro.

    Icona Indietro per tornare alla pagina Agenti dalla pagina di modifica dell'agente.

Condividere un agente dati

Per condividere un agente dati pubblicato: Non puoi condividere agenti bozza.

  1. Vai alla pagina Agenti di BigQuery.

    Vai ad Agenti

  2. Seleziona la scheda Catalogo agenti.

  3. Individua la scheda dell'agente dati che vuoi modificare.

  4. Per aprire l'agente di dati nell'editor degli agenti, fai clic su Apri azioni > fai clic su Modifica nella scheda dell'agente.

  5. Per condividere l'agente dati con altri utenti, fai clic su Condividi.

  6. Nel riquadro Autorizzazioni di condivisione, fai clic su Aggiungi entità.

  7. Nel campo Nuove entità, inserisci una o più entità.

  8. Fai clic sull'elenco Seleziona un ruolo.

  9. Nell'elenco Ruolo, seleziona uno dei seguenti ruoli:

    • Gemini Data Analytics Data Agent User (roles/geminidataanalytics.dataAgentUser): concede l'autorizzazione a chattare con il data agent.
    • Gemini Data Analytics Data Agent Editor (roles/geminidataanalytics.dataAgentEditor): concede l'autorizzazione a modificare l'agente dati.
    • Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer): concede l'autorizzazione per visualizzare l'agente dati.

  10. Fai clic su Salva.

  11. Per tornare alla pagina di modifica dell'agente, fai clic su Chiudi.

  12. Per tornare al riquadro Agenti, fai clic su Torna indietro.

    Icona Indietro per tornare alla pagina Agenti dalla pagina di modifica dell'agente.

Eliminare un agente di dati

  1. Vai alla pagina Agenti di BigQuery.

    Vai ad Agenti

  2. Seleziona la scheda Catalogo agenti.

  3. Nella sezione I miei agenti o Agenti bozza della scheda Catalogo degli agenti, individua la scheda dell'agente di dati che vuoi eliminare.

  4. Fai clic su Apri azioni > Elimina.

  5. Nella finestra di dialogo Eliminare l'agente?, fai clic su Elimina.

Località

L'analisi conversazionale opera a livello globale, quindi non puoi scegliere la regione da utilizzare.

Passaggi successivi