Utilizzare l'agente di data engineering per creare e modificare pipeline di dati

Questo documento mostra come utilizzare l'agente di data engineering in BigQuery e Dataform per creare e modificare pipeline di dati.

L'agente di data engineering consente di creare, modificare e gestire pipeline di dati per caricare ed elaborare i dati in BigQuery. Con l'agente di data engineering, puoi utilizzare i prompt in linguaggio naturale per generare pipeline di dati da varie origini dati o adattare le pipeline di dati esistenti in base alle tue esigenze di data engineering.

L'agente genera e organizza il codice della pipeline di dati direttamente all'interno dei repository Dataform. L'agente opera nello spazio di lavoro Dataform, quindi le pipeline Dataform sono disponibili automaticamente per l'agente.

Per altri esempi di prompt che puoi utilizzare con l'agente di data engineering, consulta Prompt di esempio.

Puoi anche utilizzare l'API dell'agente di data engineering, che utilizza il protocollo A2A, per interagire con l'agente.

Limitazioni

L'agente di data engineering presenta le seguenti limitazioni:

• L'agente di data engineering non supporta i comandi in linguaggio naturale per i seguenti tipi di file:
  • Notebooks
  • Preparazione dei dati
• L'agente di data engineering non può eseguire pipeline. Devi esaminare ed eseguire o pianificare le pipeline.
• L'agente di data engineering non può cercare link web o URL forniti tramite istruzioni o prompt diretti.
• Quando importi file in un file di istruzioni dell'agente, la sintassi di importazione @ supporta solo i percorsi che iniziano con ./, / o una lettera.
• La funzionalità di anteprima dei dati è supportata solo per tabelle, dichiarazioni o query con il flag hasOutput impostato su true.
• L'agente di data engineering è soggetto alle limitazioni generali della tecnologia AI.

Prima di iniziare

Prima di utilizzare l'agente di data engineering, completa i passaggi descritti in questa sezione.

Abilitare Gemini in BigQuery

Assicurati che Gemini in BigQuery sia abilitato per il tuo Google Cloud progetto. Per saperne di più, consulta Configurare Gemini in BigQuery.

Abilitare le API richieste

Nota: se non hai l'autorizzazione per abilitare le API, chiedi all'amministratore del progetto di abilitarle per te dalla dashboard API e servizi. In alternativa, l'amministratore del progetto può concederti il ruolo Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin) nella Google Cloud console, che ti consente di abilitare e disabilitare le API per il progetto corrente.

console

Abilita le seguenti API nella Google Cloud console per il Google Cloud progetto che utilizzi con l'API Conversational Analytics.

Abilita l'API Gemini Data Analytics

Abilita l'API Gemini for Google Cloud

Abilita l'API BigQuery

Suggerimento:dopo aver abilitato un'API, aggiorna la pagina della console per verificare che sia abilitata.

Google Cloud

gcloud

Per abilitare l'API Gemini Data Analytics, l'API Gemini for Google Cloud e l'API BigQuery, utilizza il Google Cloud CLI ed esegui i seguenti gcloud services enable comandi:

gcloud services enable geminidataanalytics.googleapis.com --project=PROJECT_ID
gcloud services enable cloudaicompanion.googleapis.com --project=PROJECT_ID
gcloud services enable bigquery.googleapis.com --project=PROJECT_ID

Sostituisci PROJECT_ID con l'ID progetto Google Cloud .

Ruoli obbligatori

Per ottenere l'autorizzazione necessaria per utilizzare l'agente di data engineering, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

• Editor di codice Dataform (roles/dataform.codeEditor)
• Utente job BigQuery (roles/bigquery.jobUser)
• Gemini Data Analytics Stateless Chat User (roles/geminidataanalytics.dataAgentStatelessUser)

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

Questo ruolo predefinito contiene l' geminidataanalytics.locations.useDataEngineeringAgent autorizzazione, necessaria per utilizzare l'agente di data engineering.

Potresti anche ottenere questa autorizzazione con ruoli personalizzati o altri ruoli predefiniti.

Prerequisiti per l'integrazione di Knowledge Catalog

Per ottenere l'autorizzazione necessaria per integrare l'agente di data engineering con Knowledge Catalog, chiedi all'amministratore di concederti il ruolo IAM Editor di Dataplex Catalog (roles/dataplex.catalogEditor) nel progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene l' geminidataanalytics.locations.useDataEngineeringAgent autorizzazione, necessaria per integrare l'agente di data engineering con Knowledge Catalog.

Potresti anche ottenere questa autorizzazione con ruoli personalizzati o altri ruoli predefiniti.

Devi anche abilitare l'API Knowledge Catalog.

Criptare i dati con le chiavi di Cloud Key Management Service

Puoi criptare i dati a livello di set di dati o di progetto con le chiavi di Cloud Key Management Service gestite dal cliente predefinite in BigQuery. Per saperne di più, consulta Impostare una chiave predefinita del set di dati e Impostare una chiave predefinita del progetto.

Puoi criptare il codice della pipeline a livello di progetto impostando una chiave di Cloud Key Management Service Dataform predefinita.

Configurare i perimetri dei Controlli di servizio VPC

Se utilizzi i Controlli di servizio VPC, devi configurare il perimetro per proteggere Dataform, BigQuery e l'API Conversational Analytics. Per saperne di più, consulta API Dataform, BigQuery, e Conversational Analytics.

Generare una pipeline di dati con l'agente di data engineering

Per utilizzare l'agente di data engineering in BigQuery, seleziona una delle seguenti opzioni:

Pipeline BigQuery

Puoi utilizzare l'agente di data engineering nell'interfaccia delle pipeline BigQuery procedendo nel seguente modo:

1. Vai alla pagina BigQuery.

   Vai a BigQuery

2. Nell'editor di query, fai clic su arrow_drop_down Crea nuova > Pipeline.

3. Seleziona un'opzione per le credenziali di esecuzione, quindi fai clic su Inizia. Queste credenziali non vengono utilizzate dall'agente, ma sono necessarie per eseguire la pipeline di dati generata.

4. Fai clic su Prova l'esperienza dell'agente per la pipeline di dati.

5. Nel campo Chiedi all'agente , inserisci un prompt in linguaggio naturale per generare una pipeline di dati, ad esempio:

     Create dimension tables for a taxi trips star schema from
     new_york_taxi_trips.tlc_green_trips_2022. Generate surrogate keys and all
     the descriptive attributes.
   

   Dopo aver inserito un prompt, fai clic su Invia.

6. L'agente di data engineering genera una pipeline di dati in base al prompt.

L'agente di data engineering genera una bozza proposta di una pipeline di dati. Puoi fare clic su un nodo della pipeline per esaminare la query SQLX generata. Per applicare la pipeline di dati suggerita dall'agente, fai clic su Applica.

Dataform

Puoi utilizzare l'agente di data engineering in Dataform procedendo nel seguente modo:

1. Vai a Dataform.

   Vai a Dataform

2. Seleziona un repository.

3. Seleziona o crea uno spazio di lavoro di sviluppo.

4. Nello spazio di lavoro, fai clic su Chiedi all'agente.

5. Nel prompt Chiedi all'agente visualizzato, inserisci un prompt in linguaggio naturale per generare una pipeline di dati, ad esempio:

     Create dimension tables for a taxi trips star schema from
     new_york_taxi_trips.tlc_green_trips_2022. Generate surrogate keys and all
     the descriptive attributes.
   

   Dopo aver inserito un prompt, fai clic su Invia.

Dopo aver inviato il prompt, l'agente di data engineering genera una pipeline di dati e modifica i file SQLX di Dataform in base al prompt. L'agente applica queste modifiche direttamente ai file dello spazio di lavoro.

Modificare una pipeline di dati

Per modificare la pipeline di dati, fai clic Chiedi all'agente, quindi inserisci un prompt che suggerisca una modifica alla pipeline di dati.

Esamina le modifiche proposte dall'agente di data engineering, quindi fai clic su Applica per applicarle.

Puoi anche modificare manualmente una query SQLX selezionando un nodo della pipeline e poi facendo clic su Apri.

Esaminare una pipeline di dati

Puoi fare clic su un nodo della pipeline in una pipeline di dati generata dall'agente di data engineering per esaminarla.

• La scheda Configurazione mostra la query SQLX generata associata al nodo.
• La scheda Anteprima dati mostra la tabella di input e output del file. Puoi visualizzare l'anteprima della trasformazione dei dati tramite questo nodo facendo clic su Esegui attività per eseguire l'attività con o senza dipendenze.

Risolvere gli errori della pipeline di dati

Se riscontri errori durante la generazione della pipeline di dati, verifica di aver completato tutti i prerequisiti per eseguire l'agente di data engineering. Per saperne di più, consulta Prima di iniziare.

Eseguire un'indagine di Gemini Cloud Assist

Anteprima

Questa funzionalità è soggetta ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Per risolvere ulteriormente i problemi della pipeline, puoi utilizzare l'agente di data engineering per eseguire un'analisi delle cause principali e suggerire consigli per la risoluzione dei problemi.

Questa funzionalità utilizza le indagini di Gemini Cloud Assist (anteprima) ed è disponibile solo per gli utenti con un contratto di assistenza Premium. Per saperne di più sull' attivazione delle indagini di Gemini Cloud Assist, consulta Risolvere i problemi con le indagini di Gemini Cloud Assist.

Puoi utilizzare l'agente di data engineering per risolvere gli errori della pipeline di dati seguendo questi passaggi:

1. Nella pipeline o nello spazio di lavoro di sviluppo, fai clic sulla scheda Esecuzioni.

2. Nell'elenco delle esecuzioni, trova l'esecuzione della pipeline di dati non riuscita. Puoi identificare le esecuzioni non riuscite nella colonna Stato.

   

3. Passa il mouse sopra l'icona, quindi fai clic su Indaga. L'agente di data engineering esegue un'analisi delle cause principali (RCA) sull'esecuzione della pipeline di dati per gli errori.

   

4. Al termine dell'analisi, l'agente di data engineering genera un report nella sezione Osservazioni e ipotesi. Il report include:

   • Osservazioni e punti dati estratti dai log di esecuzione della pipeline di dati.
   • Cause probabili dell'errore.
   • Un insieme di passaggi o consigli pratici per risolvere il problema identificato.

Con il report di risoluzione dei problemi dell'agente di data engineering, puoi implementare manualmente i consigli. Puoi anche chiedere all'agente di data engineering di applicare la correzione per te seguendo questi passaggi:

1. Copia i suggerimenti nel report di risoluzione dei problemi.
2. Torna all'agente di data engineering:
   1. Se utilizzi le pipeline BigQuery, vai alla pagina delle pipeline, quindi fai clic su Chiedi all'agente.
   2. Se utilizzi Dataform, fai clic su Chiedi all'agente.
3. Incolla i suggerimenti nel prompt, quindi chiedi all'agente di data engineering di apportare le correzioni direttamente alla pipeline di dati.
4. Fai clic su Invia.

Creare istruzioni dell'agente

Le istruzioni dell'agente sono istruzioni in linguaggio naturale per il Data Engineer Agent che ti consentono di archiviare istruzioni persistenti in modo che l'agente segua un insieme di regole personalizzate e predefinite. Utilizza le istruzioni dell'agente se vuoi che i risultati dell'agente siano coerenti in tutta l'organizzazione, ad esempio con le convenzioni di denominazione o per applicare una guida di stile.

Puoi creare un file di contesto GEMINI.MD come file di istruzioni dell'agente per l'agente di data engineering. Puoi creare file di istruzioni dell'agente da utilizzare nello spazio di lavoro locale oppure puoi utilizzare gli stessi file di istruzioni in più pipeline di dati con un repository esterno.

Per creare istruzioni dell'agente:

1. In Chiedi all'agente, fai clic su Istruzioni della pipeline.
2. Nel riquadro Istruzioni per la pipeline, fai clic su Crea file di istruzioni.

3. Nel file GEMINI.MD visualizzato, inserisci le istruzioni in linguaggio naturale.

   L'esempio seguente mostra un file di istruzioni dell'agente con diverse regole:

     1. All event-specific tables MUST be prefixed with `cs_event_`.
     2. The primary key for any player activity table is a composite key of `player_id` and `event_timestamp_micros`.
     3. Filter out any player actions where `mana_spent` is greater than `max_mana_pool`. This is considered a data anomaly.
   

4. Fai clic su Salva.

Per informazioni su come strutturare al meglio i file di istruzioni dell'agente, consulta Best practice con i file di istruzioni dell'agente.

Caricare le istruzioni dell'agente da un repository esterno

Per riutilizzare un insieme di istruzioni dell'agente in più pipeline di dati, collega un repository esterno:

1. In Chiedi all'agente, fai clic su Istruzioni della pipeline.
2. In Repository esterno, seleziona Usa le istruzioni del repository esterno .
3. Nei campi forniti, specifica un repository che contiene le istruzioni dell'agente che vuoi utilizzare con la pipeline di dati.
4. Fai clic su Salva.

Prompt di esempio

Le sezioni seguenti forniscono prompt di esempio che puoi utilizzare con l'agente di data engineering per sviluppare la pipeline di dati.

Aggregare i dati esistenti in una nuova tabella

Con questo prompt, l'agente di data engineering utilizza lo schema e gli esempi per dedurre il raggruppamento dei dati per chiave. In genere, l'agente configura una nuova tabella con descrizioni di tabelle e colonne.

  Create a daily sales report from the
  bigquery-public-data.thelook_ecommerce.order_items table into a
  reporting.daily_sales_aggregation table.

Creare una nuova colonna derivata e aggiungere controlli di qualità dei dati alla nuova tabella

Questo prompt mostra come aggiungere una tabella e una colonna e specificare contemporaneamente i controlli di qualità per la tabella:

  Create a new table named staging.products from
  bigquery-public-data.thelook_ecommerce.products and add a calculated column
  named gross_profit, which is the retail_price minus the cost.


  Also, add the following assertions: ID must not be null and must be unique.
  The retail_price must be greater than or equal to the cost. The department
  column can only contain 'Men' or 'Women'.

Creare funzioni definite dall'utente come parte della definizione del modello

L'agente di data engineering può anche configurare il DDL per creare funzioni definite dall'utente (UDF). Anche se l'agente non creerà effettivamente la funzione definita dall'utente, puoi crearla eseguendo la pipeline di dati. Queste funzioni definite dall'utente possono essere utilizzate nelle definizioni dei modelli nella pipeline di dati.

  Create a user-defined function (UDF) named get_age_group that takes an integer
  age as input and returns a string representing the age group ('Gen Z',
  'Millennial', 'Gen X', 'Baby Boomer').


  Use this UDF on the age column from the
  bigquery-public-data.thelook_ecommerce.users table to create a new view called
  reporting.user_age_demographics that includes user_id, age, and the calculated
  age_group.

Best practice

Per migliorare i risultati quando lavori con l'agente di data engineering e Dataform, ti consigliamo di:

Utilizzare le istruzioni dell'agente per le richieste comuni. Se applichi spesso determinate tecniche o se apporti spesso le stesse correzioni all'agente, utilizza le istruzioni dell'agente come posizione centralizzata per archiviare istruzioni e richieste comuni.

Utilizzare i piani dell'agente. I piani dell'agente possono essere utili per suddividere le attività complesse della pipeline. I piani dell'agente possono anche mostrare le ipotesi e le intenzioni dell'agente, quindi ti consigliamo di esaminarli per assicurarti che all'agente venga fornito il contesto corretto.

Dopo aver esaminato un piano, puoi modificarlo chiedendo all'agente di data engineering di fornire feedback e modifiche. Ad esempio:

In the plan, ensure that all of the intermediate tables are views.

In alcuni casi, può essere utile chiedere all'agente di generare un piano che non richieda la tua approvazione esplicita. L'atto di creare il piano dell'agente costringe l'agente di data engineering a suddividere le sue azioni, il che spesso porta a risultati migliori. Puoi forzare l'agente a generare un piano ed eseguirlo automaticamente. Ad esempio:

Create a plan for a pipeline that finds the
top N pick up and drop off locations in NYC. You have my explicit pre-approval
to go ahead and execute this plan.

Scrivere in modo chiaro. Indica chiaramente la tua richiesta ed evita di essere vago. Se possibile, fornisci le origini dati di origine e di destinazione quando inserisci un prompt, come mostrato nell'esempio seguente:

  Extract data from the sales.customers table in the us_west_1 region, and load
  it into the reporting.dim_customers table in BigQuery. Match the schema of the
  destination table.

Fornire richieste dirette e con ambito specifico. Fai una domanda alla volta e mantieni i prompt concisi. Per i prompt con più di una domanda, elenca ogni parte distinta della domanda per migliorare la chiarezza, come mostrato nell'esempio seguente:

  1. Create a new table named staging.events_cleaned. Use raw.events as the
     source. This new table should filter out any records where the user_agent
     matches the pattern '%bot%'. All original columns should be included.

  2. Next, create a table named analytics.user_sessions. Use
     staging.events_cleaned as the source. This table should calculate the
     duration for each session by grouping by session_id and finding the
     difference between the MAX(event_timestamp) and MIN(event_timestamp).

Fornire istruzioni esplicite ed enfatizzare i termini chiave. Puoi aggiungere enfasi ai termini o ai concetti chiave nei prompt ed etichettare determinati requisiti come importanti, come mostrato nell'esempio seguente:

  When creating the staging.customers table, it is *VERY IMPORTANT* that you
  transform the email column from the source table bronze.raw_customers.
  Coalesce any NULL values in the email column to an empty string ''.

Specificare l'ordine delle operazioni. Per le attività ordinate, struttura il prompt in elenchi, in cui gli elementi elencati sono suddivisi in passaggi piccoli e mirati, come mostrato nell'esempio seguente:

  Create a pipeline with the following steps:
  1. Extract data from the ecomm.orders table.
  2. Join the extracted data with the marts.customers table on customer_id.
  3. Load the final result into the reporting.customer_orders table.

Perfeziona ed esegui l'iterazione. Continua a provare frasi e approcci diversi per vedere quali producono i risultati migliori. Se l'agente genera SQL non valido o altri errori, guidalo con esempi o documentazione pubblica.

  The previous query was incorrect because it removed the timestamp. Please
  correct the SQL. Use the TIMESTAMP_TRUNC function to truncate the
  event_timestamp to the nearest hour, instead of casting it as a DATE. For
  example: TIMESTAMP_TRUNC(event_timestamp, HOUR).