Visão geral do agente de engenharia de dados

Com o agente de engenharia de dados, é possível criar, modificar e resolver problemas de pipelines de dados no BigQuery usando comandos de linguagem natural. O agente de engenharia de dados oferece os seguintes recursos para simplificar seus fluxos de trabalho de engenharia de dados e ingerir dados no BigQuery:

• Integração do Dataform: o agente gera e organiza o código do pipeline de dados diretamente nos repositórios e espaços de trabalho do Dataform.
• Geração de planos: o agente pode resumir o raciocínio e gerar um plano que permite revisar e verificar o plano do agente antes de continuar.
• Validação de código: o agente valida e corrige automaticamente erros de compilação de qualquer código gerado para garantir que o pipeline de dados esteja funcional.
• Organização automática de dados: o agente organiza os dados e transforma dados brutos em tabelas estruturadas sem intervenção manual.
• Instruções personalizadas: o agente é compatível com instruções personalizadas que permitem definir regras específicas e diretrizes reutilizáveis em linguagem natural.
• Contexto externo: o agente está integrado ao Knowledge Catalog para mais contexto
• Controle de pipeline: é possível revisar e personalizar os planos de agentes gerados antes da execução de qualquer ação.
• Otimização: o agente pode otimizar a performance no seu pipeline de dados
• Solução de problemas e correção: o agente pode solucionar falhas de pipeline e corrigir o código.
• Recomendações interativas: o agente oferece recomendações interativas e contextuais no início e ao longo da sessão.
• Enriquecimento de metadados do Knowledge Catalog: o agente pode gerar automaticamente metadados do Knowledge Catalog com base nas configurações de tabela e enviá-los para o Knowledge Catalog durante a execução do pipeline.

Onde você pode usar o agente de engenharia de dados

Você pode usar o agente de engenharia de dados com os seguintes métodos:

• Crie pipelines de dados na interface de pipelines do BigQuery ou no Dataform.
• Instale a extensão do Google Cloud Data Agent Kit no Visual Studio Code para criar pipelines de dados no ambiente de desenvolvimento integrado (IDE).
• Use a API Data Engineering Agent.

Como o agente de engenharia de dados usa seus dados

Para gerar respostas de maior qualidade, o agente de engenharia de dados pode recuperar mais dados e metadados do BigQuery e do Knowledge Catalog, incluindo linhas de amostra de tabelas do BigQuery e perfis de verificação de dados gerados no Knowledge Catalog. O agente não usa esses dados para treinamento. Eles são usados apenas como contexto adicional durante as conversas para informar as respostas.

Onde o agente de engenharia de dados processa seus dados

Para mais informações sobre os locais em que o agente de engenharia de dados processa seus dados, consulte Onde o Gemini no BigQuery processa seus dados.

Limitações

O agente de engenharia de dados tem as seguintes limitações:

• O Agente de Engenharia de Dados não é compatível com comandos em linguagem natural para os seguintes tipos de arquivo:
  • Notebooks
  • Preparação de dados
• O agente de engenharia de dados não pode executar pipelines. Você precisa revisar e executar ou programar pipelines.
• O agente de engenharia de dados não pode pesquisar links da Web ou URLs fornecidos por instruções ou comandos diretos.
• Ao importar arquivos em um arquivo de instruções do agente, a sintaxe de importação @ aceita apenas caminhos que começam com ./, / ou uma letra.
• O recurso prévia dos dados só é compatível com tabelas, declarações ou consultas em que a flag hasOutput está definida como true.
• O agente de engenharia de dados está sujeito às limitações gerais da tecnologia de IA.
• Ao criar pipelines em tabelas externas do Apache Iceberg gerenciadas pelo catálogo do ambiente de execução do Lakehouse (antigo BigLake metastore), todas as limitações do catálogo do ambiente de execução do Lakehouse se aplicam. Principalmente, o agente não pode gerar mutações de gravação (como INSERT, UPDATE, DELETE ou MERGE) nem instruções DDL (como CREATE TABLE ou DROP TABLE) em tabelas do Iceberg. Para mais informações, consulte Conceitos de endpoint do catálogo REST do Apache Iceberg.

Recursos e personalizações do agente

As seções a seguir descrevem outros recursos do agente e métodos para personalizar o agente de engenharia de dados.

Instruções para o agente

As instruções do agente são instruções em linguagem natural para o agente de engenharia de dados que permitem armazenar instruções permanentes para que o agente siga um conjunto de regras personalizadas e predefinidas. Use instruções do agente se quiser que os resultados dele sejam consistentes em toda a organização, por exemplo, com convenções de nomenclatura ou para aplicar um guia de estilo.

Para criar instruções de agente para o Data Engineering Agent, crie um arquivo de contexto GEMINI.MD como um arquivo de instruções de agente.

Práticas recomendadas com arquivos de instruções do agente

Ao usar instruções do agente, recomendamos o seguinte:

• Todos os caminhos de arquivo no Dataform são relativos à raiz do repositório. Use caminhos relativos para qualquer sintaxe @file.md para importar corretamente instruções para GEMINI.md.
• Os arquivos importados em GEMINI.md podem conter outras importações, o que cria uma estrutura aninhada. Para evitar recursão infinita, GEMINI.md tem uma profundidade máxima de importação de cinco níveis.
• Para compartilhar instruções em pipelines de dados, armazene-as em um repositório central do Dataform e vincule-as ao repositório de trabalho do Dataform. Você pode usar instruções locais para substituir regras centrais de comportamento específico do pipeline.
• Para garantir a consistência no seu projeto, você pode vincular arquivos de convenção de nomenclatura ou guias de estilo e instruir o agente a seguir essas diretrizes ao trabalhar com seus pipelines de dados.
• Você pode sugerir camadas de dados no arquivo de instruções para agrupar diferentes tipos de dados.
• Usar cabeçalhos e listas no arquivo de instruções do agente ajuda a organizar e esclarecer as instruções para o Data Engineering Agent.
• Crie nomes de arquivos significativos e agrupe instruções semelhantes em um arquivo. Organize as regras de forma lógica por categoria, recurso ou funcionalidade com cabeçalhos em Markdown.
• Para evitar instruções conflitantes, defina claramente as condições específicas em que cada instrução se aplica.
• Itere e refine seus comandos e fluxo de trabalho. O comportamento do agente muda com o tempo com os lançamentos e upgrades de modelo. Por isso, recomendamos iterar suas regras com comandos diferentes para identificar áreas que precisam de melhorias. Mantenha o arquivo de regras sincronizado com as mudanças no pipeline de dados.

O exemplo a seguir mostra um arquivo de instruções do agente chamado GEMINI.md que utiliza nossas práticas recomendadas para o uso eficiente do agente de engenharia de dados:

  ### Naming Conventions

  * Datasets: [business_domain]_[use_case] (e.g., ecommerce_sales)

  * Tables:
      - Raw/External: raw_[source_name]
      - Staging: stg_[business_entity]
      - Dimension: dim_[dimension_name]
      - Fact: fct_[fact_name]

  * Dataform Folders:
      - sources
      - staging
      - marts
      - dataProducts

  * Views: vw_[view_name]

  * Columns: snake_case (e.g., order_id, customer_name)

  ## Cloud Storage data load
  * When ingesting data from Cloud Storage, create external tables.

  ## Null handling
  * Filter out null id values

  ## String normalization
  * Standardize string columns by converting to lower case

  ## Data Cleaning Guidelines
  @./generic_cleaning.md

Importar outros arquivos locais como instruções do agente

Também é possível importar outros arquivos de instruções para o agente de engenharia de dados no arquivo GEMINI.md com a sintaxe @file.md. Para mais informações, consulte Processador de importação de memória.

Preparação automática de dados

É possível usar o agente de engenharia de dados para transformar dados brutos e não processados em tabelas estruturadas adequadas para análise de dados. Quando solicitado, o agente primeiro faz uma amostragem de até 1.000.000 de registros de cada tabela padrão ou externa. Em seguida, o agente faz uma análise detalhada dos dados executando consultas de criação de perfil nessa amostra. Depois de gerar transformações de dados, o agente repete esse processo de amostragem e criação de perfil para avaliar a qualidade das transformações. Essas transformações de preparação de dados podem incluir a correção de inconsistências, outliers ou incompatibilidades de tipo. Em seguida, o agente de engenharia de dados cria um plano que descreve as etapas de organização propostas para você revisar e refinar antes de qualquer ação.

O agente de engenharia de dados também inicia a análise de preparação de dados sempre que você adiciona uma tabela bruta, como uma tabela externa baseada em CSV. Você pode analisar o plano de tratamento de dados e ajustá-lo com comandos de conversa.

A amostragem de dados e o perfilamento usam recursos do BigQuery e estão sujeitos aos preços do BigQuery.

O agente de engenharia de dados é compatível com as seguintes transformações de preparação de dados:

• Limpeza de dados. O agente pode analisar dados brutos e sugerir oportunidades de limpeza, como remover outliers, preencher valores ausentes ou inconsistentes (imputação de dados), corrigir dados duplicados ou padronizar formatos de dados, por exemplo, números de telefone ou endereços.
• Transformações estruturais. Quando um esquema de destino é fornecido, o agente pode desagrupar ou extrair valores dos tipos JSON, ARRAY ou STRUCT, mesclar várias colunas em uma ou dividir uma coluna em várias.
• Detecção e conversão de tipos de dados. O agente pode analisar os dados para determinar os tipos de campo adequados. Em seguida, o agente pode realizar uma conversão de tipo segura para resolver inconsistências de formatação nos campos de data, hora, data/hora ou carimbo de data/hora.
• Conversão de unidades. O agente pode converter automaticamente várias unidades em um campo para uma unidade consistente e padronizar seus dados.

Para garantir a precisão, o agente usa amostras representativas dos seus dados para detectar problemas e validar a lógica de transformação.

Gerar e revisar planos de agentes

O agente de engenharia de dados pode gerar planos que fornecem um resumo e uma visão geral dos objetivos e das etapas necessárias para concluir uma solicitação. Quando você faz solicitações complexas ao agente que exigem muitas mudanças, recomendamos pedir que ele forneça um plano para que você possa revisar as intenções dele antes de tomar qualquer ação. Um plano do agente de engenharia de dados geralmente consiste no seguinte:

• O objetivo do agente para uma solicitação específica
• Uma visão geral das etapas que o agente planeja seguir
• Quaisquer suposições feitas pelo agente
• Arquivos que o agente planeja modificar
• Todas as etapas de otimização ou limpeza que ele planeja realizar
• Um plano de execução por fases

No comando, inclua a necessidade de revisar e aprovar o plano para que o agente não realize nenhuma ação sem sua aprovação explícita. Exemplo:

Create a plan for a pipeline that finds the
top N pick up and drop off locations in NYC. I want to review the plan and
approve it before you create the pipeline.

O agente também pode gerar um plano automaticamente e pedir sua aprovação. Isso pode acontecer quando um comando é muito ambíguo ou se o agente precisa de mais clareza para atender à sua solicitação.

Para conferir as práticas recomendadas sobre o uso de planos de agente, consulte Práticas recomendadas.

Adicionar contexto do Knowledge Catalog

O agente de engenharia de dados usa o Knowledge Catalog anexando termos do glossário a tabelas e colunas do BigQuery e gerando verificações de perfil de dados. Os termos do glossário podem marcar colunas que exigem mais contexto, como colunas que contêm informações de identificação pessoal (PII) que exigem instruções de tratamento especial, ou identificar colunas correspondentes com nomes diferentes em várias tabelas.

O Knowledge Catalog também usa o criação de perfil de dados, que oferece ao agente uma compreensão melhor da distribuição de dados nas colunas da tabela e ajuda a criar declarações de qualidade de dados mais específicas.

O agente também pode usar o Knowledge Catalog para descobrir e consultar tabelas do Apache Iceberg. Para mais informações, consulte Criar pipelines em tabelas do Apache Iceberg.

Adicionar verificações de qualidade de dados a uma tabela

Quando você pede ao agente para adicionar verificações de qualidade, ele infere verificações razoáveis para a tabela com base no esquema e nas amostras. Você também pode adicionar afirmações opinativas como parte do comando. Exemplo:

  Add data quality checks for bigquery-public-data.thelook_ecommerce.users.

Durante a execução do pipeline, os resultados de todas as asserções do Dataform são publicados automaticamente no Knowledge Catalog (prévia). Esses resultados preenchem o painel de qualidade de dados do Knowledge Catalog com um status de aprovação ou reprovação. Cada execução substitui os painéis de qualidade de dados publicados por execuções anteriores do Dataform, mas não afeta os painéis criados pelas verificações de dados do Knowledge Catalog.

Aprimoramento automático de dados

Os metadados padrão do BigQuery, como conjuntos de dados, tabelas e visualizações, ficam disponíveis automaticamente no Knowledge Catalog.

Também é possível definir metadados personalizados para suas tabelas e visualizações diretamente no bloco de configuração dos arquivos .sqlx. Após a conclusão de uma ação, o Dataform inicia automaticamente uma sincronização de metadados com o Knowledge Catalog. Esse processo de enriquecimento atualiza o Knowledge Catalog com os metadados semânticos definidos na configuração do SQLX.

Use a chave de metadados para especificar informações para o Knowledge Catalog. O processo de enriquecimento é compatível com as seguintes construções de metadados:

• Visão geral: documentação e texto de resumo da entrada. Requer a versão 3.0.37 ou mais recente do Dataform Core.
• Aspectos genéricos: detalhes semânticos, como sistema de tabela e informações de tipo. Requer a versão 3.0.52 ou mais recente do Dataform Core.

O exemplo de configuração a seguir mostra como adicionar uma visão geral e aspectos genéricos de metadados a uma configuração de tabela para o Knowledge Catalog:

config {
  type: "table",
  metadata: {
    overview: "This table provides standardized trip data.",
    extraProperties: {
        generic: {
              system: "BigQuery",
              type: "table"
        }
      }
  }
}

Para verificar o status de uma atualização de metadados, consulte Inspecionar registros de execução do espaço de trabalho para fluxos de trabalho do Dataform ou Ver execuções manuais anteriores para pipelines do BigQuery.

Para verificar os metadados sincronizados, pesquise o recurso no Knowledge Catalog. Para mais informações, consulte Pesquisar recursos.

Otimize os pipelines de dados

Você pode pedir ao agente para otimizar seus pipelines de dados. Ao gerar DDL para novas tabelas, o agente de engenharia de dados recomenda o particionamento e o clustering com base nos padrões de uso de dados analisados. Além disso, o agente pode aplicar automaticamente outras otimizações de pipeline. Exemplos de possíveis otimizações:

• Remoção de colunas para reduzir a leitura de dados do armazenamento e atuar como um fator principal de custo e desempenho.
• Pushdowns de predicado para filtrar dados no início do plano de execução e reduzir significativamente o volume processado por operações subsequentes.
• Eliminação de subexpressões comuns para melhorar a eficiência, identificando e computando a lógica de transformação compartilhada apenas uma vez, evitando práticas ineficientes, como varredura e junção de tabelas grandes várias vezes.
• Modelos incrementais para processar apenas dados novos ou alterados desde a última execução, em vez de recriar tabelas inteiras a cada execução.

Criar pipelines em tabelas do Apache Iceberg

O agente de engenharia de dados oferece suporte à geração e compilação de pipelines do Dataform em tabelas do Apache Iceberg gerenciadas pelo catálogo de ambientes de execução do Lakehouse (antigo BigLake metastore). Com esse recurso, é possível consultar e combinar tabelas regionais de formato de código aberto (armazenadas no Cloud Storage) diretamente com as tabelas do BigQuery. Para mais informações, consulte Conceitos de endpoint do catálogo REST do Apache Iceberg.

Por exemplo, você pode pedir ao agente para consultar uma tabela do Apache Iceberg no catálogo de ambiente de execução do Lakehouse:

Include the stackoverflow_post_history_iceberg table in this pipeline.

Nos comandos, não é necessário especificar caminhos de quatro partes totalmente qualificados, por exemplo, project.catalog.dataset.table. É possível se referir às tabelas do Apache Iceberg usando nomes padrão em linguagem natural ou identificadores lógicos, por exemplo, the StackOverflow post history table ou post_history. O agente invoca automaticamente pesquisas semânticas no catálogo usando o Knowledge Catalog para resolver e vincular as tabelas corretas do Apache Iceberg ao seu espaço de trabalho de pipeline.

Para usar esse recurso, seu repositório do Dataform precisa usar a versão 3.0.33 ou mais recente do Dataform Core.

Recomendações interativas

O agente de engenharia de dados analisa o status de compilação do seu espaço de trabalho, o histórico de execução e o estado da conversa ativa para fornecer recomendações úteis diretamente na interface de chat. Essas sugestões aparecem automaticamente quando você abre um espaço de trabalho e durante toda a sessão para fornecer recomendações de configuração, solução de problemas e otimizações que orientam seu fluxo de trabalho.

Para usar uma recomendação, clique em uma das sugestões em Recomendações de IA. Isso vai carregar o comando na barra de entrada do chat, que pode ser editada ou personalizada antes de ser enviada ao agente. Você também pode passar o cursor sobre uma sugestão para ver o comando exato.

Práticas recomendadas

Para melhorar os resultados ao trabalhar com o agente de engenharia de dados e o Dataform, recomendamos que você faça o seguinte:

Use instruções do agente para solicitações comuns. Se você costuma aplicar determinadas técnicas ou fazer as mesmas correções no agente, use as instruções do agente como um local centralizado para armazenar instruções e solicitações comuns.

Use planos de agente, que podem ajudar a dividir tarefas complexas do pipeline. Os planos do agente também podem mostrar as proposições e intenções dele. Por isso, recomendamos que você revise esses planos para garantir que o contexto correto seja fornecido ao agente.

Depois de analisar um plano, você pode editá-lo pedindo ao agente de engenharia de dados feedback e mudanças. Exemplo:

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

Em alguns casos, pode ser útil pedir ao agente para gerar um plano que não precise da sua aprovação explícita. O ato de fazer o agente planejar força o Data Engineering Agent a detalhar as ações, o que geralmente leva a resultados melhores. Você pode forçar o agente a gerar e executar um plano automaticamente. Exemplo:

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.

Escreva com clareza. Faça seu pedido de forma clara e evite ser vago. Sempre que possível, forneça fontes de dados de origem e destino ao fazer solicitações, como mostrado no exemplo a seguir:

  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.

Faça solicitações diretas e específicas. Faça uma pergunta por vez e mantenha as instruções concisas. Para comandos com mais de uma pergunta, liste cada parte distinta da pergunta para melhorar a clareza, como mostrado no exemplo a seguir:

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

Dê instruções explícitas e enfatize os termos-chave. Você pode enfatizar termos ou conceitos-chave nos comandos e rotular determinados requisitos como importantes, conforme mostrado no exemplo a seguir:

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

Especificar a ordem das operações. Para tarefas ordenadas, estruture o comando em listas, em que os itens listados são divididos em etapas pequenas e focadas, conforme mostrado no exemplo a seguir:

  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.

Refine e itere. Teste frases e abordagens diferentes para saber produz os melhores resultados. Se o agente gerar SQL inválido ou outros erros, dê exemplos ou documentação pública para orientá-lo.

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

Avaliar pipelines de dados

Para avaliar a eficácia de um pipeline de dados gerado pelo agente de engenharia de dados, use a ferramenta EvalBench. O EvalBench é um framework de código aberto que oferece suporte a avaliações de agentes multiturno. O EvalBench funciona como um pacote de testes de unidade automatizados, permitindo configurar cenários multiturno, adicionar pontuadores determinísticos e com tecnologia de LLM e gerenciar o ciclo de vida dos pipelines do Dataform.

Ao simular comandos em linguagem natural em um sandbox isolado, o EvalBench mede a eficiência com que o agente entende instruções, chama as ferramentas certas e gera o código correto do pipeline. O EvalBench pode verificar seus pipelines de dados fazendo o seguinte:

• Validação de regras personalizadas: verifique se o agente segue rigorosamente as diretrizes de codificação, convenções de nomenclatura e práticas recomendadas específicas da sua organização.
• Evitar regressões de código: teste as mudanças no pipeline antes da implantação para garantir que as atualizações do agente ou as modificações do esquema não interrompam a funcionalidade atual.
• Gerar comparativos de qualidade: receba pontuações objetivas e automatizadas para correção de SQL, precisão de execução de ferramentas e confiabilidade de pipelines.

Executar uma avaliação de pipeline de dados

É possível executar o EvalBench nos dois modos a seguir:

• Sandbox dinâmico: o EvalBench provisiona um novo repositório e espaço de trabalho temporários do Dataform no início de uma execução de avaliação, executa os cenários de teste e destrói automaticamente todos os recursos criados após a conclusão. Esse modo não modifica nenhum código de produção, repositório de produção ou conjunto de dados do BigQuery, e não deixa artefatos restantes no seu projeto Google Cloud . O modo sandbox dinâmico é adequado para pipelines de CI/CD automatizados, testes de regressão noturnos e pontuação de comparativo de mercado objetivo em que é necessário um isolamento estrito do ambiente.

• Workspace estático: o EvalBench se conecta a um repositório e workspace do Dataform gerenciados pelo usuário e pula a criação e exclusão automatizadas de scripts. Esse modo permite que o agente em avaliação modifique e crie novos arquivos SQLX no espaço de trabalho atual enquanto processa casos de avaliação. O modo de espaço de trabalho estático é adequado para engenharia de comandos ativa, iteração de rubricas e depuração local, em que é necessário inspecionar os arquivos SQLX gerados diretamente no espaço de trabalho do Dataform após a execução.

Antes de começar

Para receber as permissões necessárias para executar o EvalBench, peça ao administrador para conceder a você os seguintes papéis do IAM na conta de serviço ou identidade do usuário que executa o EvalBench:

• Administrador do Dataform (roles/dataform.admin)
• Editor de dados do BigQuery (roles/bigquery.dataEditor)
• Usuário de jobs do BigQuery (roles/bigquery.jobUser)
• Exportar resultados da avaliação como pacotes ZIP: Administrador de objetos do Storage (roles/bigquery.objectAdmin)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Executar a avaliação em um sandbox dinâmico

Para avaliar seu pipeline de dados no modo sandbox dinâmico, faça o seguinte:

1. Siga as etapas para clonar o repositório, configurar o ambiente virtual e instalar as dependências do EvalBench. Para mais informações, consulte Como começar.

2. No diretório datasets/dea-tools/, verifique se o arquivo de configuração de exemplo de execução (example_run_config.yaml) inclui as seguintes linhas:

   set_up_script: datasets/dea-tools/scripts/setup_dataform.sh
   tear_down_script: datasets/dea-tools/scripts/teardown_dataform.sh

3. Execute o EvalBench com o seguinte comando:

   EVAL_GCP_PROJECT_ID=PROJECT_ID \
   EVAL_GCP_PROJECT_REGION=REGION \
   .venv/bin/python3 evalbench/evalbench.py --experiment_config=datasets/dea-tools/example_run_config.yaml

   Substitua:

   • PROJECT_ID: o ID do projeto Google Cloud.
   • REGION: a região do projeto Google Cloud.

Executar a avaliação em um espaço de trabalho de avaliação estática

Para avaliar seu pipeline de dados no modo de espaço de trabalho estático, faça o seguinte:

1. Siga as etapas para clonar o repositório, configurar o ambiente virtual e instalar as dependências. Para mais informações, consulte Como começar.

2. No diretório datasets/dea-tools/, edite o arquivo de configuração de execução de exemplo (example_run_config.yaml) para comentar as linhas set_up_script e tear_down_script e adicione as configurações dataform_repository e dataform_workspace:

   ...
   # set_up_script: datasets/dea-tools/scripts/setup_dataform.sh
   # tear_down_script: datasets/dea-tools/scripts/teardown_dataform.sh
   dataform_repository: !ENV ${EVAL_DEA_REPOSITORY_ID}
   dataform_workspace: !ENV ${EVAL_DEA_WORKSPACE_ID}
   ...

3. Execute o EvalBench com o seguinte comando:

   EVAL_GCP_PROJECT_ID=PROJECT_ID \
   EVAL_GCP_PROJECT_REGION=REGION \
     EVAL_DEA_REPOSITORY_ID=REPOSITORY_ID \
     EVAL_DEA_WORKSPACE_ID=WORKSPACE_ID \
     .venv/bin/python3 evalbench/evalbench.py --experiment_config=datasets/dea-tools/example_run_config.yaml

   Substitua:

   • PROJECT_ID: o ID do projeto Google Cloud.
   • REGION: a região do projeto Google Cloud.
   • REPOSITORY_ID: o ID do repositório que contém o pipeline de dados.
   • WORKSPACE_ID: o ID do espaço de trabalho que contém o pipeline de dados.

4. Opcional: também é possível executar o EvalBench com core_10_cases_suite.yaml para testar o pipeline de dados em relação a 10 casos de avaliação principais em sequência com isolamento de ambiente criando um novo repositório para cada caso de teste. Para fazer isso, execute o seguinte comando:

   EVAL_GCP_PROJECT_ID=PROJECT_ID \
   EVAL_GCP_PROJECT_REGION=REGION \
   .venv/bin/python3 evalbench/evalbench.py --suite_config=datasets/dea-tools/core_10_cases_suite.yaml

Práticas recomendadas para avaliação de pipelines de dados

Para melhorar o desempenho e a acurácia das avaliações do pipeline de dados usando o EvalBench, recomendamos que você faça o seguinte:

• Procure a invocação do fluxo de trabalho do Dataform e os IDs dos jobs do BigQuery nos registros de avaliação. Use esses IDs para fazer referências cruzadas e inspecionar artefatos de execução gerados, resultados de compilação e registros de consultas no console do Google Cloud .
• Sempre execute o conjunto de avaliação principal (--suite_config) antes de lançar mudanças no modelo ou no comando para garantir a cobertura completa da regressão em diversos cenários de engenharia de dados.
• Use EVAL_DATAFORM_SETUP_ENV_FILES_DIR para pré-carregar arquivos de configuração de ambiente, como workflow_settings.yaml e definições de esquema de base, no espaço de trabalho de teste. Esses arquivos de configuração garantem que o agente seja criado em ambientes realistas em vez de espaços de trabalho vazios.
• Ao resolver problemas de casos de avaliação com falha no modo sandbox dinâmico, comente tear_down_script na configuração de execução para manter o espaço de trabalho de destino para análise post-mortem.
• Sempre combine verificadores de compilação e execução na nuvem (dataform_cloud_compile, dataform_cloud_run) com rubricas binárias baseadas em LLM para identificar erros de sintaxe ou de tempo de execução e falhas de lógica de alto nível.
• Ative os relatórios do BigQuery (<PROJECT_ID>.evalbench.results) e use os links gerados do Data Studio para acompanhar as taxas de aprovação, a precisão do uso da ferramenta e a eficiência dos comandos ao longo do tempo.