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. Verifica che la fatturazione sia attivata per il tuo progetto Google Cloud .

  2. Abilita le API BigQuery, Gemini Data Analytics, Gemini per Google Cloude Knowledge Catalog, se non sono già abilitate.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente disponi già di questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    Abilita le API

Ruoli obbligatori

Per lavorare con gli agenti di dati, devi disporre delle autorizzazioni Identity and Access Management (IAM) corrispondenti al tuo caso d'uso. Le sezioni seguenti elencano i ruoli richiesti in base al fatto che tu stia creando e pubblicando agenti, eseguendo il provisioning di agenti in Gemini Enterprise o scoprendo e utilizzando agenti su varie piattaforme. Per saperne di più, consulta Ruoli IAM dell'API Conversational Analytics.

  • Crea, modifica, pubblica, condividi ed elimina agenti:
    • Per creare data agent in un progetto: Gemini Data Analytics Data Agent Creator (roles/geminidataanalytics.dataAgentCreator) sul progetto. Questo ruolo ti concede automaticamente il ruolo Gemini Data Analytics Data Agent Owner sugli agenti di dati che crei.
    • Per modificare, condividere o eliminare un data agent: Gemini Data Analytics Data Agent Owner (roles/geminidataanalytics.dataAgentOwner) sull'agente o sul progetto.
    • Per modificare un data agent in un progetto: Gemini Data Analytics Data Agent Editor (roles/geminidataanalytics.dataAgentEditor) sul progetto.
    • Per visualizzare gli agenti dati in un progetto: Gemini Data Analytics Data Agent Visualizzatore (roles/geminidataanalytics.dataAgentViewer) nel progetto.
  • Esegui il provisioning degli agenti in Gemini Enterprise:
  • Scopri e utilizza gli agenti:
    • Per chattare con i data agent: Gemini Data Analytics Data Agent User (roles/geminidataanalytics.dataAgentUser).
    • Per visualizzare tutti gli agenti di dati nel progetto: Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer).
    • Per interagire con l'interfaccia di chat basata su Gemini in Data Studio: utente BigQuery Studio (roles/bigquery.studioUser) o utente Gemini in Google Cloud (roles/cloudaicompanion.user), ognuno dei quali fornisce l'autorizzazione cloudaicompanion.topics.create. Concedi questi ruoli a livello di progetto. Gli utenti richiedono anche il ruolo Visualizzatore asset Data Studio (roles/datastudio.viewer).
  • Aggiungi fonti di conoscenza a un agente:
    • Visualizzatore Data Catalog (roles/datacatalog.viewer) sul progetto.

Per avviare conversazioni, consulta i ruoli richiesti per le conversazioni.

Gli agenti agiscono per tuo conto e utilizzano le tue autorizzazioni. Gli agenti possono accedere solo ai dati e alle risorse a cui hai l'autorizzazione di accedere.

Best practice

L'analisi conversazionale esegue automaticamente le query per tuo conto per rispondere alle tue domande. Considera i seguenti fattori che potrebbero aumentare il costo delle query:

  • Dimensioni delle tabelle grandi
  • Utilizzo dell'unione dei dati nelle query
  • Chiamate frequenti alle funzioni AI all'interno delle query

Genera insight

Se vuoi, puoi generare insight sui dati in Knowledge Catalog per qualsiasi tabella che vuoi utilizzare come origine di conoscenza.

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

Se non generi insight generati in anticipo, il sistema li genera automaticamente quando selezioni una tabella come fonte di conoscenza durante la creazione di un data agent.

Utilizzare l'agente dati campionati

Se non hai dimestichezza con la configurazione degli agenti per l'analisi conversazionale, puoi visualizzare l'agente di esempio predefinito generato per ogni progettoGoogle Cloud . Puoi chattare con lui e visualizzarne i parametri per capire come è stato creato, ma non puoi modificarlo.

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

Passaggi iniziali

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

    Vai ad Agenti

  2. Seleziona la scheda Catalogo degli 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 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. Viene visualizzata la pagina Aggiungi fonte di conoscenza.

  7. Nella sezione Recenti, seleziona le tabelle, le visualizzazioni, i grafici o le funzioni definite dall'utente che vuoi utilizzare come fonti di conoscenza. Le funzioni definite dall'utente sono precedute da un indicatore "fx" nella console Google 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 visualizzata nuovamente la pagina del nuovo agente.

Personalizza 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 e non influiscono sulla tabella di origine.

Segui queste best practice quando crei le descrizioni di tabelle e 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 di dati non mostra di comprendere lo schema dopo aver configurato queste descrizioni, modifica manualmente le descrizioni 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, esamina 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 un campo facendo clic su 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 visualizzata di nuovo la pagina del nuovo agente.

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

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à di contesto, ad esempio metadati di tabelle e campi personalizzati o query verificate.

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

Se non ricevi una risposta soddisfacente dall'agente, aggiungi un contesto strutturato, come descrizioni, esempi o termini del glossario. Se ancora non ricevi una risposta soddisfacente, aggiungi istruzioni personalizzate come gli esempi nella tabella seguente.

Per altri esempi di istruzioni, fai clic su Mostra esempi.

Tipo di informazioni 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 'nel tempo', utilizza sempre la colonna order_created_date." "Quando qualcuno dice 'per prodotto', raggruppa per la colonna product_category."
Filtro predefinito Campi su cui filtrare per impostazione predefinita. "Se non diversamente specificato, filtra sempre i dati in base a order_status = 'Complete'."
Sinonimi e termini aziendali Termini alternativi per i campi chiave. "Se qualcuno chiede informazioni su "Entrate" o "Vendite", utilizza la colonna total_sale_amount." "Consideriamo clienti "fedeli" quelli con purchase_count > 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 due o più tabelle sono correlate tra loro e quali colonne vengono utilizzate per unirle. L'agente deve utilizzare JOIN SQL standard su coppie di colonne per combinare i dati. Vedi la colonna Esempio. Attività dei clienti
  • order_items.user_id = users.id
    (per collegare le vendite ai clienti)
  • events.user_id = users.id
    (per collegare l'attività sul sito web ai clienti che hanno eseguito l'accesso)

Crea 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 affidabile, l'agente richiama la query esattamente come è stata 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 l'esecuzione di query.

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

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

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

    1. Nella sezione Query verificate, fai clic su Esamina i suggerimenti. Viene visualizzata la pagina Esamina le query verificate suggerite.
    2. Esamina le query verificate suggerite. Seleziona tutte le opzioni pertinenti per il tuo caso d'uso.
    3. Fai clic su Aggiungi. Viene visualizzata nuovamente la pagina del nuovo agente.

  2. Per creare una query verificata, 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 visualizzata nuovamente la pagina del nuovo agente.

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

Crea query verificate con parametri

Le query verificate parametrizzate estraggono i valori dalla domanda di un utente per l'agente di analisi conversazionale e forniscono risultati personalizzati.

Gli analisti e i builder possono creare modelli SQL riutilizzabili che contengono segnaposto per questi valori. I modelli sostituiscono dinamicamente i parametri in fase di runtime per rispondere a una gamma più ampia di domande degli utenti rispetto alle normali query verificate.

Quando un utente pone una domanda che corrisponde al pattern del template, l'agente di analisi conversazionale estrae i valori parametro dalla domanda, ad esempio il nome del prodotto, la regione e la data. Quindi, inserisce questi valori nella query con parametri. Le risposte corrispondenti del modello di query vengono visualizzate come verificate.

Le query verificate con parametri migliorano notevolmente la potenza e la flessibilità delle query verificate. Garantiscono risposte coerenti e affidabili per vari input e riducono il numero di singole query da gestire.

Come funziona

Un esperto, ad esempio un analista di dati, definisce una query verificata utilizzando una domanda modello, ad esempio "Quali sono state le vendite di @product nel @region?". Poi, l'esperto crea o modifica la query verificata utilizzando i parametri SQL, come mostrato nell'esempio seguente:

SELECT * FROM sales WHERE region = @region AND product = @product

Dopo aver salvato la query verificata, un utente può porre una domanda all'agente di analisi conversazionale in linguaggio naturale, ad esempio "Quali sono state le vendite di laptop in Nord America?".

Per rispondere alla domanda dell'utente, l'agente esegue i seguenti passaggi:

  1. Corrisponde alla domanda al pattern associato alla query verificata con parametri. L'agente utilizza la comprensione del linguaggio naturale (NLU) per identificare ed estrarre i valori per @region (Nord America) e @product (laptop) dalla domanda dell'utente.
  2. Sostituisce i valori estratti nei segnaposto @region e @product nel template SQL.
  3. Esegue la query SQL completa, ad esempio SELECT * FROM sales WHERE region = 'North America' AND product = 'Laptops'.
  4. Restituisce i risultati all'utente. Le corrispondenze sono sempre contrassegnate come verificate.

Suggerimenti per creare query con parametri efficaci

  • Utilizza nomi di parametri chiari. Utilizza nomi descrittivi per i parametri, ad esempio @start_date anziché @d1.
  • Crea descrizioni dettagliate dei parametri. Il modello linguistico di grandi dimensioni (LLM) per l'analisi conversazionale utilizza le descrizioni dei parametri per identificare i parametri e i relativi valori dalle domande degli utenti. Ad esempio, num_enrollments è un nome parametro efficace, mentre number of student enrollments from ages 5-14 è una descrizione del parametro che fornisce maggiori informazioni sulla query.
  • Garantisci una tipizzazione dei dati coerente. Assicurati che i tipi di dati previsti dalla query SQL corrispondano ai tipi di dati che probabilmente verranno estratti dalla domanda dell'utente.
  • Fornisci un ambito ben definito. Crea modelli per pattern di domande comuni e importanti in cui la costruzione della query è complessa o la logica non è intuitiva. In questo modo, l'LLM restituisce risultati ottimali.
  • Esegui test approfonditi. Esegui test con varie frasi in linguaggio naturale per assicurarti che i parametri vengano estratti correttamente.

Crea una query verificata con parametri

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

Prima di creare o modificare una query, bozza la query, tenendo conto del pattern del linguaggio naturale e della tua domanda. Ad esempio, se chiedi "Do we know the total stock for organic bananas in the US-EAST warehouse?," puoi riscrivere la domanda come query verificata con parametri come "What is the total stock for @product in the @region warehouse?" L'agente trasforma questa domanda in una query SQL che aggiorni con i valori predefiniti.

Per creare una query verificata parametrizzata per un agente di dati, puoi creare una nuova query quando crei un nuovo agente oppure puoi modificare una query verificata esistente per un agente nuovo o esistente.

Le seguenti istruzioni utilizzano una query verificata di esempio da configurare con i parametri.

Seleziona una query verificata esistente suggerita da Gemini
  1. Nella sezione Query verificate di un agente nuovo o esistente, fai clic su Esamina i suggerimenti. Viene visualizzata la pagina Esamina le query verificate suggerite.
  2. Seleziona la casella di controllo accanto a una query verificata suggerita.
  3. Nella finestra della query, fai clic su Mostra altro per espandere la descrizione della query.
  4. Per aprire la query esistente, fai clic su Modifica.
  5. Per completare la configurazione della query, consulta Configura i parametri per la query verificata.
Crea un agente e poi una query verificata
  1. Consulta i passaggi iniziali e continua con il resto dei passaggi di configurazione fino a Query verificate.
  2. Nella console Google Cloud , nella sezione Query verificate del nuovo agente, fai clic su Aggiungi query. Viene visualizzata la pagina Aggiungi query verificata.
  3. Per completare la configurazione della query, consulta Configura i parametri per la query verificata.
Configura i parametri per la query verificata
  1. Nel campo Domanda, digita la domanda dell'utente a cui risponde la query verificata.
  2. Per specificare i parametri, utilizza il simbolo @ seguito dal nome di un parametro. Questa sintassi identifica un segnaposto che acquisisce un valore dalla domanda dell'utente. Utilizza una domanda in linguaggio naturale che mostri come verranno utilizzati i parametri nelle domande degli utenti. Ad esempio: "Qual è lo stock totale di @product nel magazzino @region?"

  3. Fai clic su Genera SQL. Il codice SQL è simile al seguente esempio:

       SELECT
       SUM(stock) AS total_stock
   FROM
       inventory
   WHERE
       product_id = @product
       AND region = @region;

  4. Per aggiungere valori predefiniti ai segnaposto nella query, fai clic su Gestisci parametri di query, quindi su Aggiungi parametro di query.

  5. Per il primo parametro, vengono visualizzati quattro campi: Nome, Tipo, Valore e Descrizione.

    • In Nome, copia @product dalla domanda e incollalo in questo campo.
    • In Tipo, seleziona STRING.
    • In Valore, inserisci organic bananas.
    • In Descrizione, inserisci una descrizione il più specifica possibile. Ad esempio, un prodotto situato in un magazzino regionale.

  6. Per il secondo parametro, fai clic su Aggiungi parametro di query.

    • In Nome, copia @region dalla domanda e incollalo in questo campo.
    • In Tipo, seleziona STRING.
    • In Valore, inserisci US-EAST.
    • In Descrizione, inserisci una descrizione il più specifica possibile, ad esempio a regional warehouse where products are located..

  7. Dopo aver compilato i campi per entrambi i parametri, fai clic su Salva.

Testa la query verificata con parametri
  1. Fai clic su Esegui e verifica che la query restituisca i risultati che ti aspetti.
  2. Per testare la query per gli utenti in una schermata successiva, copia l'intero campo della domanda.
  3. Fai clic su Salva per uscire dalla schermata Aggiungi query e tornare alla pagina Modifica dell'agente.
  4. Nella pagina Modifica dell'agente, incolla il campo della domanda che hai copiato in precedenza nella finestra Anteprima.
    1. Sostituisci la variabile @product con organic bananas.
    2. Sostituisci la variabile @region con US-EAST.
  5. Premi Invio. Verifica il risultato. In questo caso, una risposta valida è il numero totale di banane in stock nella regione US-EAST, ad esempio 1000.
  6. Per creare o modificare altre query verificate, ripeti questi passaggi in base alle tue esigenze.

Ora che hai salvato la query, un utente può porre la domanda "Conosciamo lo stock totale di banane biologiche nel magazzino US-EAST?" L'analisi conversazionale esegue quindi le seguenti operazioni:

  1. Corrisponde a questa domanda con il pattern.
  2. Estrae dalla domanda il parametro @product come @product = "organic bananas" e il parametro @region = "US-EAST".
  3. Esegue la query: SELECT SUM(stock) AS total_stock FROM inventory WHERE product_id = 'organic bananas' AND region = 'US-EAST';
  4. Restituisce il valore total_stock calcolato.

Creare o rivedere i termini del glossario

Puoi creare termini di glossario personalizzati di BigQuery locali per un agente o esaminare i termini del glossario aziendale importati da Knowledge Catalog che si applicano alle fonti di conoscenza selezionate per un agente.

  • Poiché i termini del glossario aziendale di Knowledge Catalog si applicano a livello globale alle risorse BigQuery, se utilizzi Knowledge Catalog, crea e gestisci i termini del glossario aziendale in Knowledge Catalog anziché per i singoli agenti.
  • Se devi modificare i termini del glossario aziendale importati da Knowledge Catalog, devi modificarli in Knowledge Catalog e tornare a BigQuery per visualizzarli.
  • I termini del glossario personalizzato di BigQuery rimangono in BigQuery. Non vengono visualizzati in Knowledge Catalog.
  • Se non utilizzi Knowledge Catalog, puoi creare termini di glossario personalizzati di BigQuery per i termini che devi definire per un agente specifico.

Per creare termini del glossario personalizzati per un agente, segui questi passaggi:

  1. Nella sezione Glossario della pagina Editor dell'agente, fai clic su Aggiungi termine.
  2. Nella sezione Termini personalizzati, puoi modificare o eliminare i termini personalizzati esistenti.
  3. Per creare uno o più nuovi termini, fai clic su Crea termine.
    1. Inserisci un Termine, una Definizione e uno o più Sinonimi separati da una virgola.
    2. Per creare il termine, fai clic su Aggiungi.
    3. Se vuoi eliminare il nuovo termine, fai clic su Elimina.
  4. Per creare altri termini personalizzati, ripeti questi passaggi.

Segui questi passaggi per visualizzare i termini del glossario aziendale importati da Knowledge Catalog:

  1. Nella sezione Glossario della pagina Editor dell'agente, fai clic su Aggiungi termine.
  2. Vai alla sezione di pagina denominata Importato da Dataplex.
  3. Per modificare i termini importati in Knowledge Catalog, fai clic su Vai ai glossari Dataplex.
  4. Dopo aver modificato i termini in Knowledge Catalog, puoi tornare alla pagina Editor dell'agente per visualizzare i termini modificati.

Configura le impostazioni

Nella sezione Impostazioni, puoi configurare le seguenti impostazioni facoltative:

  1. Nella sezione Modello, scegli i tipi di modelli disponibili per gli utenti in una conversazione con l'agente. Per impostazione predefinita, sono disponibili sia i modelli in anteprima sia quelli in disponibilità generale. I modelli in anteprima potrebbero utilizzare l'endpoint globale.

  2. Crea etichette per organizzare le tue risorseGoogle 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 visualizzata nuovamente la pagina del nuovo agente.

  3. Imposta un limite di dimensioni per le query elaborate dal data agent. Nella sezione Impostazioni, digita un valore nel campo Numero massimo di byte 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.

Visualizza l'anteprima e pubblica 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 risposta dell'agente. Se la risposta non è quella prevista, modifica le impostazioni nella sezione Editor per perfezionare la configurazione dell'agente di 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 in bozza della scheda Catalogo degli agenti.

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

  4. Fai clic su Pubblica per aprire il riquadro Canali di pubblicazione e pubblicare l'agente di dati, rendendolo disponibile per l'utilizzo nel progetto.

  5. (Facoltativo) Nella finestra di dialogo Il tuo agente è stato pubblicato, fai clic su Condividi per condividere l'agente di 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 pagina del nuovo agente, fai clic su Chiudi. Subito dopo aver salvato o pubblicato l'agente, puoi visualizzarlo nel Catalogo degli agenti.

Puoi creare conversazioni con l'agente di dati utilizzando BigQuery Studio o Data Studio. Puoi anche creare la tua interfaccia per chattare con l'agente di dati utilizzando l'API Conversational Analytics. Per informazioni sulla pubblicazione in Data Studio, consulta Pubblica un agente di dati in Data Studio. Per informazioni sulla pubblicazione in Gemini Enterprise, consulta Pubblica un agente di dati in Gemini Enterprise.

Gestisci gli agenti di 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.
  • I miei agenti in bozza: agenti che non hai ancora pubblicato. Non puoi condividere agenti bozza.
  • Condivisi da altri membri della tua organizzazione: agenti creati da altri e condivisi con te. Se altri ti concedono le autorizzazioni, puoi modificare questi agenti condivisi.

Modifica un agente di dati

Per modificare un agente di dati, segui questi passaggi:

  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 di 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 Torna indietro.

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

Condividere un agente di dati

Segui questi passaggi per condividere un data agent pubblicato. Non puoi condividere agenti in 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 per 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 per visualizzare il data agent.

  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 dati

  1. Vai alla pagina Agenti di BigQuery.

    Vai ad Agenti

  2. Seleziona la scheda Catalogo degli agenti.

  3. Nella sezione I miei agenti o I miei agenti bozza della scheda Catalogo 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.

Pubblica un agente di dati in Data Studio

Quando pubblichi l'agente e lo condividi con gli utenti di Data Studio, l'agente viene visualizzato automaticamente per questi utenti, che possono chattare con l'agente nella pagina Chatta con i tuoi dati di Data Studio.

Crea e pubblica l'agente in Data Studio

In qualità di data analyst, puoi creare, modificare e pubblicare un agente in Data Studio completando i seguenti passaggi:

  1. Crea o modifica il tuo agente di dati in BigQuery.
  2. Pubblica l'agente. Quando pubblichi l'agente, seleziona Data Studio come opzione di pubblicazione.
  3. Segui le istruzioni per condividere l'agente, concedendo i ruoli di Identity and Access Management appropriati agli utenti di Data Studio.

Condividere l'agente con gli utenti di Data Studio

Puoi condividere gli agenti direttamente con gli utenti di Data Studio copiando un link che apre una conversazione con l'agente in Data Studio oppure puoi inviare un'email per informare l'utente che ha accesso a un agente.

Per condividere un link diretto all'agente, puoi copiare l'URL dedicato dell'agente in questi modi:

  • Dal catalogo degli agenti: seleziona Apri azioni > seleziona Copia link > seleziona Data Studio.
  • Dalla visualizzazione dei dettagli dell'agente: seleziona Copia link agente > seleziona Data Studio.
  • Dal menu extra Condividi: seleziona Copia link all'agente in Data Studio.
  • Dopo aver fatto clic su Salva nel riquadro Autorizzazioni di condivisione, seleziona Copia link.

Per inviare una notifica via email che informa i destinatari del loro accesso a un agente, seleziona Invia email nel riquadro Condividi autorizzazioni. Le notifiche via email vengono inviate solo agli utenti o ai gruppi con cui hai appena condiviso l'agente in quella sessione di modifica. Tutti i membri di un gruppo ricevono la notifica via email, anche se un determinato utente dispone già dell'autorizzazione a livello di agente per l'agente. L'email include il nome dell'utente che ha condiviso l'agente, il nome dell'agente e un link per aprirlo in Data Studio.

Pubblica un agente dati in Gemini Enterprise

Puoi pubblicare un agente di dati BigQuery in Gemini Enterprise in modo che gli utenti aziendali possano eseguire query e analizzare i dati utilizzando il linguaggio naturale direttamente in Gemini Enterprise. Questo processo in genere prevede la collaborazione tra analisti dei dati, amministratori di Gemini Enterprise e utenti aziendali. Per ulteriori informazioni sui ruoli richiesti per questi utenti, vedi Ruoli richiesti.

Per pubblicare un agente dati in Gemini Enterprise, completa i seguenti passaggi:

  1. Esamina i prerequisiti.
  2. Crea e pubblica l'agente di dati in BigQuery.
  3. Esegui il provisioning dell'agente in Gemini Enterprise.
  4. Scopri e chatta con l'agente.

Esamina i prerequisiti

Il modo consigliato per pubblicare gli agenti di analisi conversazionale BigQuery è utilizzare Agent Registry. Segui i prerequisiti riportati in questa sezione per assicurarti che l'agente sia rilevabile in Gemini Enterprise.

In alternativa, puoi pubblicare l'agente utilizzando il JSON della scheda A2A. Se utilizzi questo metodo, consulta Crea e pubblica l'agente di dati in BigQuery.

Per utilizzare Agent Registry, devi prima configurare Agent Gateway con il mapping delle regioni appropriato. La regione di archiviazione dell'agente di dati BigQuery e l'associazione del registry di Agent Gateway in Gemini Enterprise devono corrispondere.

Puoi configurare la regione di archiviazione per l'agente nella sezione Regione dell'editor dell'agente nell'interfaccia utente web di BigQuery. Non puoi modificare la regione dopo aver salvato l'agente.

La seguente immagine mostra le opzioni di regione disponibili in Agent Gateway:

Opzioni di regione disponibili in Agent Gateway per i registry degli agenti.

In qualità di amministratore di Gemini Enterprise, configura un Agent Gateway per la tua applicazione Gemini Enterprise completando i seguenti passaggi:

  1. Configura un Agent Gateway che includa l'associazione di Agent Registry corrispondente alla regione dell'agente di dati. Le opzioni includono Stati Uniti, UE o Globale.
  2. In Gemini Enterprise, apri l'applicazione, vai a Sicurezza > Configurazione e poi inserisci il nome della risorsa gateway nella sezione Configurazione di Agent Gateway. Per istruzioni dettagliate, consulta Instrada il traffico di Gemini Enterprise tramite Agent Gateway.

Crea e pubblica l'agente di dati in BigQuery

In qualità di analista dei dati, crei, configuri e pubblichi un agente in BigQuery completando i seguenti passaggi:

  1. In BigQuery, crea o modifica il tuo agente di dati.
  2. Nella sezione Regione, verifica che la regione di archiviazione corrisponda alle origini dati e alla configurazione dell'Agent Gateway. Le opzioni includono Stati Uniti, UE o Globale.
  3. Fai clic su Pubblica o su Pubblica aggiornamenti se l'agente è stato pubblicato in precedenza.
  4. Nel riquadro Canali di pubblicazione, in Canali aggiuntivi, scegli il metodo di pubblicazione:
    • Se BigQuery e Gemini Enterprise si trovano nello stesso progetto, nella sezione Registry degli agenti, seleziona la casella di controllo Registra questo agente.
      • Se vuoi rimuovere l'agente dal registry, fai clic su Annulla registrazione.
    • Se BigQuery e Gemini Enterprise si trovano in progetti diversi, nella sezione Integra tramite A2A (Agent2Agent), fai clic su Copia JSON per copiare i dati JSON dell'endpoint A2A, quindi condividi i dati JSON con l'amministratore di Gemini Enterprise. Questi dati JSON vengono utilizzati quando provisioni l'agente nella sezione Gemini Enterprise.
  5. Fai clic su Pubblica o Pubblica aggiornamenti.
  6. Condividi l'agente con gli utenti e i gruppi che devono accedervi, concedendo loro il ruolo Gemini Data Analytics Data Agent User (roles/geminidataanalytics.dataAgentUser).

Esegui il provisioning dell'agente in Gemini Enterprise

In qualità di amministratore di Gemini Enterprise, rendi l'agente di dati disponibile agli utenti della tua applicazione utilizzando uno dei seguenti metodi:

Opzione 1: importa da Agent Registry

Per importare l'agente registrato, segui questi passaggi:

  1. Se Gemini Enterprise si trova in un progetto diverso da quello BigQuery, completa i seguenti passaggi per registrare manualmente l'agente in Agent Registry. In caso contrario, salta questo passaggio:
    1. Nella console Google Cloud , vai a Agent Registry nello stesso progetto di Gemini Enterprise, seleziona la scheda Agenti e poi fai clic su Aggiungi agente.
    2. Nel riquadro Dettagli agente, seleziona A2A per Tipo.
    3. In Regione, seleziona la regione corrispondente alla configurazione dell'agente di dati e dell'Agent Gateway.
    4. Seleziona Incolla JSON, incolla i dati JSON dell'endpoint A2A da BigQuery e poi fai clic su Salva.
  2. In Gemini Enterprise, fai clic sul nome dell'app a cui vuoi aggiungere l'agente.
  3. Nel menu di navigazione, fai clic su Agenti > fai clic su Aggiungi agente.
  4. Nel riquadro Scegli un tipo di agente, individua Agenti dal registro degli agenti e fai clic su Aggiungi.
  5. Nel riquadro Aggiungi agente, cerca l'agente per nome, ID Agent Registry, tipo, producer o caso d'uso oppure individua la scheda dell'agente nell'elenco.
  6. Nella scheda dell'agente, fai clic su Aggiungi agente.
  7. Nel passaggio Esamina i dettagli dell'agente, esamina i metadati dell'agente compilati dalla scheda A2A dell'agente, inclusi nome, descrizione, URL dell'agente, funzionalità e competenze, quindi fai clic su Avanti.
  8. Nel passaggio Autentica l'agente, seleziona il modo in cui Gemini Enterprise esegue l'autenticazione con il provider dell'agente:
    • Credenziali predefinite gestite da Google: Google gestisce automaticamente le credenziali OAuth. Non è necessario configurare o inserire manualmente le credenziali del client.
    • OAuth personalizzato: seleziona questa opzione solo se la tua organizzazione richiede credenziali client OAuth personalizzate e inserisci l'ID client, il client secret, l'URL di autorizzazione e l'URL token.
  9. Fai clic su Fine.
  10. L'agente viene visualizzato nella tabella Agenti con lo stato Attivato e il tipo di agente A2A (personalizzato).
  11. Condividi l'agente con gli utenti o i gruppi che devono avere accesso.

Opzione 2: importa utilizzando il file JSON della carta A2A

Se BigQuery e Gemini Enterprise si trovano in progetti diversi, segui questi passaggi per importare l'agente utilizzando il JSON della scheda A2A:

  1. In Gemini Enterprise, fai clic sul nome dell'app a cui vuoi aggiungere l'agente.
  2. Nel menu di navigazione, fai clic su Agenti > fai clic su Aggiungi agente.
  3. Nel riquadro Scegli un tipo di agente, individua Agente personalizzato tramite A2A e fai clic su Aggiungi.
  4. Nel campo JSON della scheda dell'agente, inserisci il JSON della scheda dell'agente ricevuto dall'analista dei dati.
  5. Fai clic su Visualizza dettagli agente > fai clic su Avanti.
  6. Nel passaggio Autorizzazione agente, seleziona il metodo di autenticazione:
    • Credenziali predefinite gestite da Google: Google gestisce automaticamente le credenziali OAuth senza richiedere l'inserimento o la generazione manuale di un ID client e di un client secret.
    • OAuth personalizzato: seleziona questa opzione se vuoi fornire manualmente credenziali OAuth personalizzate, seguendo i passaggi descritti in Registra e gestisci gli agenti A2A.
  7. Nel passaggio Autorizzazioni strumento, fai clic su Fine.
  8. L'agente viene visualizzato nella tabella Agenti con lo stato Abilitato e il tipo di agente A2A (personalizzato).
  9. Condividi l'agente con gli utenti o i gruppi che devono accedervi.

Scopri e utilizza un agente

Puoi scoprire e utilizzare un agente dati in Gemini Enterprise utilizzando uno di questi metodi:

  • Rilevamento manuale: individua un data agent nella galleria di agenti e utilizzalo con uno di questi metodi:
    • Sfoglia la galleria: seleziona l'agente e avvia una chat dedicata.
    • Link diretto: utilizza l'URL dedicato dell'agente per aprire Gemini Enterprise direttamente in una sessione con quell'agente di dati BigQuery specifico.
    • Intento mirato: richiama l'agente con @mention (ad esempio, @sales_pipeline_agent) nella chat principale di Gemini Enterprise.
    • Orchestrazione perfetta: poni una domanda analitica generale (ad esempio, "Qual è l'andamento della nostra pipeline di vendita negli ultimi 3 mesi?") e Gemini Enterprise indirizza automaticamente la query all'agente di dati pertinente.

Dopo aver scoperto l'agente, puoi interagire con lui seguendo questa procedura:

  • Autenticati: completa l'accesso OAuth una tantum per autenticarti in modo sicuro in BigQuery.
  • Chat: poni domande in linguaggio naturale all'agente. Le richieste vengono elaborate dall'agente e la risposta viene trasmessa in streaming a Gemini Enterprise come testo, Markdown, grafici o tabelle.
  • Visualizza la cronologia delle conversazioni: le conversazioni vengono salvate automaticamente nel riquadro della cronologia.

Monitorare gli agenti e le conversazioni

Puoi monitorare le prestazioni, l'adozione, la latenza e i costi dei tuoi agenti dati e delle loro conversazioni utilizzando Google Cloud Observability in BigQuery. Quando abiliti l'osservabilità dell'agente, puoi visualizzare metriche come le seguenti:

  • Il numero di agenti utilizzati nelle conversazioni
  • Il numero di utenti che hanno posto domande
  • Il numero di conversazioni create
  • Gli agenti che hanno risposto al maggior numero di domande
  • Le fonti di conoscenza di uso comune
  • Coinvolgimento dell'utente
  • Utilizzo dei token previsto
  • Latenza di risposta oraria

Prima di iniziare

Abilita le API Cloud Trace, Cloud Monitoring e API Cloud Logging, se non sono già abilitate.

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente disponi già di questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

Abilita le API

Ruoli e autorizzazioni richiesti

Per abilitare l'osservabilità degli agenti, devi disporre delle seguenti autorizzazioni sul tuo progetto:

  • cloudaicompanion.gibqObservabilitySettings.create
  • cloudaicompanion.gibqObservabilitySettings.list
  • cloudaicompanion.gibqObservabilitySettings.update
  • cloudaicompanion.settingBindings.gibqObservabilitySettingsCreate
  • cloudaicompanion.settingBindings.gibqObservabilitySettingsList
  • cloudaicompanion.settingBindings.gibqObservabilitySettingsUse
  • geminidataanalytics.dataAgents.create
  • geminidataanalytics.operations.get
  • observability.traceScopes.create
  • resourcemanager.projects.update
  • serviceusage.services.enable
  • serviceusage.values.test

Per ottenere le autorizzazioni necessarie per monitorare gli agenti utilizzando metriche, tracce e log, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Abilita l'osservabilità

L'osservabilità degli agenti è disabilitata per impostazione predefinita. Un amministratore può abilitarlo per il tuo progetto o la tua organizzazione. Per attivare l'osservabilità per i tuoi agenti, seleziona una delle seguenti opzioni:

Console

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

    Vai ad Agenti

  2. Seleziona la scheda Monitoraggio.

  3. Se l'osservabilità è disattivata, segui le istruzioni per attivarla.

Google Cloud CLI

  1. Crea un'impostazione di osservabilità:

    gcloud gemini gibq-observability-settings create SETTING_NAME \
  --conversational-analytics-setting-metrics-enabled \
  --conversational-analytics-setting-traces-enabled \
  --project=PROJECT_ID \
  --location=global

    Sostituisci quanto segue:

    • SETTING_NAME: un nome per l'impostazione di osservabilità.
    • PROJECT_ID: il tuo ID progetto.

  2. Collega l'impostazione di osservabilità al tuo progetto:

    gcloud gemini gibq-observability-settings setting-bindings create BINDING_NAME \
  --gibq-observability-setting=SETTING_NAME \
  --target=projects/PROJECT_ID \
  --location=global \
  --project=PROJECT_ID

    Sostituisci BINDING_NAME con un nome per l'associazione dell'impostazione. Ti consigliamo di utilizzare binding-PROJECT_ID per il nome dell'associazione.

API

  1. Crea un'impostazione di osservabilità:

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d '{
          "conversational_analytics_setting": {
            "metrics_enabled": true
          }
        }' \
    "https://cloudaicompanion.googleapis.com/v1/projects/PROJECT_ID/locations/global/gibqObservabilitySettings?gibq_observability_setting_id=SETTING_NAME"

    Sostituisci quanto segue:

    • SETTING_NAME: un nome per l'impostazione di osservabilità.
    • PROJECT_ID: il tuo ID progetto.

  2. Collega l'impostazione di osservabilità al tuo progetto:

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d '{
          "target": "projects/PROJECT_ID",
          "product": "GEMINI_IN_BIGQUERY"
        }' \
    "https://cloudaicompanion.googleapis.com/v1/projects/PROJECT_ID/locations/global/gibqObservabilitySettings/SETTING_NAME/settingBindings?setting_binding_id=BINDING_NAME"

    Sostituisci BINDING_NAME con un nome per l'associazione dell'impostazione. Ti consigliamo di utilizzare binding-PROJECT_ID come nome dell'associazione.

Visualizza metriche

Le metriche vengono raccolte dopo l'attivazione dell'osservabilità. I dati non vengono sottoposti a backfill. Per visualizzare le metriche dell'agente, seleziona una delle seguenti opzioni:

BigQuery

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

    Vai ad Agenti

  2. Seleziona la scheda Monitoraggio.

Cloud Monitoring

  1. Nella console Google Cloud , vai alla pagina Dashboard di Cloud Monitoring.

    Vai a Dashboard

  2. Nel riquadro Le mie dashboard, cerca la dashboard denominata BigQuery Conversational Analytics.

  3. Per aprire la dashboard, fai clic sul suo nome.

  4. (Facoltativo) Crea una dashboard personalizzata.

  5. (Facoltativo) Per visualizzare le metriche singolarmente, vai alla pagina Esplora metriche.

    Vai a Esplora metriche

    Le metriche degli agenti includono l'utilizzo degli agenti, le chiamate ai modelli, l'utilizzo degli strumenti, l'integrità, la latenza e l'utilizzo dei token.

Debug delle chiamate al modello

Puoi visualizzare la sequenza di operazioni all'interno di un turno di conversazione, come le chiamate al modello e le chiamate agli strumenti, per aiutarti a risolvere gli errori e la latenza.

  1. Nella console Google Cloud , vai alla pagina Esplora tracce di Cloud Monitoring.

    Vai a Trace tracce

  2. Fai clic su un intervallo da esaminare.

  3. Esamina le informazioni nel riquadro Dettagli.

  4. (Facoltativo) Crea una dashboard di traccia personalizzata.

Conserva le tracce

I dati di Cloud Trace vengono archiviati in un set di dati di osservabilità per 30 giorni. Per archiviare i dati di traccia più a lungo, sposta i dati di traccia in un set di dati BigQuery.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per esporre le tracce in tempo reale a BigQuery creando un set di dati collegato, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Sposta i dati di traccia in BigQuery

Per conservare i dati di tracciamento:

  1. Apri Cloud Shell.

  2. Trova la posizione del tuo bucket _Trace:

    gcloud beta observability buckets list --location=-

    Prendi nota della posizione del bucket _Trace per il passaggio successivo.

  3. Crea un set di dati collegato nel tuo progetto BigQuery che rimandi al tuo bucket _Trace:

    gcloud beta observability buckets datasets links create \
    projects/PROJECT_ID/locations/LOCATION/buckets/_Trace/datasets/Spans/links/LINK_NAME \
    --dataset=Spans \
    --bucket=_Trace \
    --location=LOCATION \
    --project=PROJECT_ID

    Sostituisci quanto segue:

    • PROJECT_ID: il tuo ID progetto
    • LOCATION: la località del bucket _Trace del passaggio precedente
    • LINK_NAME: un nome per il set di dati collegato

  4. Crea un set di dati standard in cui archiviare le tracce storiche. Il seguente comando imposta la scadenza predefinita della partizione su 90 giorni (7.776.000 secondi):

    bq --location=LOCATION mk \
    --dataset \
    --default_partition_expiration=7776000 \
    --description="Archive storage for historical traces" \
    PROJECT_ID:STORAGE_DATASET

    Sostituisci STORAGE_DATASET con un nome per il set di dati.

  5. Crea una tabella partizionata vuota nel set di dati di archiviazione con lo stesso schema del set di dati collegato. Il partizionamento per data ti aiuta a gestire la conservazione dei dati e i costi delle query. Per creare la tabella, esegui questa query nell'editor SQL:

    CREATE TABLE `PROJECT_ID.STORAGE_DATASET.TABLE_NAME`
PARTITION BY DATE(start_time)
AS
SELECT *
FROM `PROJECT_ID.LINK_NAME._AllSpans`
WHERE FALSE;

    Sostituisci TABLE_NAME con un nome per la tabella.

  6. Crea una query pianificata per copiare ogni giorno i dati di traccia dal set di dati collegato alla tabella dell'archivio. La seguente query copia i dati del giorno precedente:

    INSERT INTO `PROJECT_ID.STORAGE_DATASET.TABLE_NAME`
SELECT *
FROM `PROJECT_ID.LINK_NAME._AllSpans`
WHERE start_time >=
  TIMESTAMP_SUB(TIMESTAMP_TRUNC(CURRENT_TIMESTAMP(), DAY), INTERVAL 1 DAY)
  AND start_time < TIMESTAMP_TRUNC(CURRENT_TIMESTAMP(), DAY);

Per saperne di più, consulta la sezione su come trovare ed esplorare le tracce.

Disattiva l'osservabilità

Per disattivare l'osservabilità per i tuoi agenti di dati, aggiorna l'impostazione di osservabilità:

gcloud gemini gibq-observability-settings update SETTING_NAME \
    --no-conversational-analytics-setting-metrics-enabled \
    --no-conversational-analytics-setting-traces-enabled \
    --project=PROJECT_ID \
    --location=global

Sostituisci quanto segue:

  • SETTING_NAME: il nome dell'impostazione di osservabilità che hai creato per attivare l'osservabilità. Se hai attivato l'osservabilità utilizzando la console Google Cloud , il nome dell'impostazione è default.
  • PROJECT_ID: il tuo ID progetto.

Passaggi successivi