Descripción general del Agente de ingeniería de datos

El agente de ingeniería de datos te permite compilar, modificar y solucionar problemas de canalizaciones de datos en BigQuery con instrucciones en lenguaje natural. El agente de ingeniería de datos ofrece las siguientes capacidades para optimizar tus flujos de trabajo de ingeniería de datos y transferir datos a BigQuery:

  • Integración de Dataform: El agente genera y organiza el código de la canalización de datos directamente en los repositorios y espacios de trabajo de Dataform.
  • Generación de planes: El agente puede resumir su razonamiento y generar un plan que te permita revisar y verificar el plan del agente antes de continuar.
  • Validación de código: El agente valida y corrige automáticamente los errores de compilación de cualquier código generado para garantizar que la canalización de datos funcione correctamente.
  • Tratamiento automático de datos: El agente realiza el tratamiento de datos y transforma los datos sin procesar en tablas estructuradas sin intervención manual.
  • Instrucciones personalizadas: El agente admite instrucciones personalizadas que te permiten definir reglas específicas y lineamientos reutilizables en lenguaje natural.
  • Contexto externo: El agente se integra con Knowledge Catalog para obtener contexto adicional.
  • Control de la canalización: Puedes revisar y personalizar los planes del agente generados antes de que se ejecute cualquier acción.
  • Optimización: El agente puede optimizar el rendimiento de tu canalización de datos.
  • Solución de problemas y reparación: El agente puede solucionar problemas de fallas en la canalización y corregir su código.
  • Recomendaciones interactivas: El agente proporciona recomendaciones interactivas y adaptadas al contexto al principio y durante toda la sesión.
  • Enriquecimiento de metadatos de Knowledge Catalog: El agente puede generar automáticamente metadatos de Knowledge Catalog a partir de la configuración de tu tabla y enviarlos a Knowledge Catalog durante la ejecución de la canalización.

Dónde puedes usar el agente de ingeniería de datos

Puedes usar el Agente de ingeniería de datos con los siguientes métodos:

Cómo usa tus datos el agente de ingeniería de datos

Para producir respuestas de mayor calidad, el agente de ingeniería de datos puede recuperar datos y metadatos adicionales de BigQuery y Knowledge Catalog, incluidas filas de muestra de tablas de BigQuery y perfiles de análisis de datos generados en Knowledge Catalog. El agente no usa estos datos para el entrenamiento, sino solo como contexto adicional durante las conversaciones para fundamentar sus respuestas.

Dónde procesa tus datos el agente de ingeniería de datos

Para obtener más información sobre las ubicaciones en las que el Agente de Ingeniería de Datos procesa tus datos, consulta Dónde Gemini en BigQuery procesa tus datos.

Limitaciones

El Agente de Ingeniería de Datos tiene las siguientes limitaciones:

  • El agente de ingeniería de datos no admite comandos en lenguaje natural para los siguientes tipos de archivos:
    • Notebooks
    • Preparación de datos
  • El agente de ingeniería de datos no puede ejecutar canalizaciones. Debes revisar y ejecutar o programar canalizaciones.
  • El agente de ingeniería de datos no puede buscar vínculos web ni URLs proporcionados a través de instrucciones o mensajes directos.
  • Cuando importas archivos en un archivo de instrucciones del agente, la sintaxis de importación @ solo admite rutas de acceso que comienzan con ./, / o una letra.
  • La función de vista previa de datos solo se admite para tablas, declaraciones o consultas con la marca hasOutput establecida en true.
  • El Agente de ingeniería de datos está sujeto a las limitaciones generales de la tecnología de IA.
  • Cuando creas canalizaciones sobre tablas externas de Apache Iceberg administradas por el catálogo de entornos de ejecución de Lakehouse (antes metastore de BigLake), se aplican todas las limitaciones del catálogo de entornos de ejecución de Lakehouse. En particular, el agente no puede generar mutaciones de escritura (como INSERT, UPDATE, DELETE o MERGE) ni declaraciones DDL (como CREATE TABLE o DROP TABLE) en tablas de Iceberg. Para obtener más información, consulta Conceptos sobre los extremos del catálogo de REST de Apache Iceberg.

Funciones y personalizaciones del agente

En las siguientes secciones, se describen las capacidades adicionales del agente y otros métodos para personalizar el Agente de Ingeniería de Datos.

Instrucciones del agente

Las instrucciones del agente son instrucciones en lenguaje natural para el agente de ingeniería de datos que te permiten almacenar instrucciones persistentes para que el agente siga un conjunto de reglas personalizadas predefinidas. Usa instrucciones del agente si deseas que los resultados del agente sean coherentes en toda tu organización, por ejemplo, con convenciones de nomenclatura o para aplicar una guía de estilo.

Para crear instrucciones del agente de ingeniería de datos, crea un archivo de contexto GEMINI.MD como archivo de instrucciones del agente.

Prácticas recomendadas para usar archivos de instrucciones del agente

Cuando uses instrucciones del agente, te recomendamos que sigas estas indicaciones:

  • Todas las rutas de acceso a los archivos en Dataform son relativas a la raíz del repositorio. Usa rutas de acceso relativas para cualquier sintaxis de @file.md para importar correctamente las instrucciones a GEMINI.md.
  • Los archivos importados en GEMINI.md pueden contener importaciones, lo que puede crear una estructura anidada. Para evitar la recursión infinita, GEMINI.md tiene una profundidad máxima de importación de cinco niveles.
  • Para compartir instrucciones entre canalizaciones de datos, almacénalas en un repositorio central de Dataform y vincúlalas al repositorio de Dataform en funcionamiento. Puedes usar instrucciones locales para anular las reglas centrales en relación con el comportamiento específico de la canalización.
  • Para garantizar la coherencia en tu proyecto, puedes vincular archivos de convenciones de nomenclatura o guías de estilo, y darle instrucciones al agente para que siga estos lineamientos cuando trabaje con tus canalizaciones de datos.
  • Puedes sugerir capas de datos en el archivo de instrucciones para agrupar diferentes tipos de datos.
  • Usar encabezados y listas en el archivo de instrucciones del agente puede ayudar a organizar y aclarar las instrucciones para el agente de Ingeniería de datos.
  • Proporciona nombres de archivo significativos y agrupa instrucciones similares en un archivo. Organiza las reglas de forma lógica por categoría, función o funcionalidad con encabezados de Markdown.
  • Para evitar instrucciones contradictorias, define claramente las condiciones específicas en las que se aplica cada instrucción.
  • Itera y define mejor tus instrucciones y tu flujo de trabajo. El comportamiento del agente cambia con el tiempo a medida que se lanzan agentes y se actualizan los modelos, por lo que te recomendamos que iteres tus reglas con diferentes instrucciones para identificar las áreas que podrían necesitar mejoras. Mantén tu archivo de reglas sincronizado con cualquier cambio en tu canalización de datos.

En el siguiente ejemplo, se muestra un archivo de instrucciones del agente llamado GEMINI.md que utiliza nuestras prácticas recomendadas para el uso eficaz del agente de ingeniería de datos:

  ### 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

Importa archivos locales adicionales como instrucciones para el agente

También puedes importar otros archivos de instrucciones para el agente de ingeniería de datos en el archivo GEMINI.md con la sintaxis @file.md. Para obtener más información, consulta Procesador de importación de memoria.

Tratamiento automático de datos

Puedes usar el agente de ingeniería de datos para transformar datos sin procesar en tablas estructuradas aptas para el análisis de datos. Cuando se solicita, el agente primero toma muestras de hasta 1,000,000 de registros de cada tabla estándar o externa. Luego, el agente realiza un análisis de datos detallado ejecutando consultas de creación de perfiles en esta muestra. Después de generar transformaciones de datos, el agente repite este proceso de muestreo y creación de perfiles para evaluar la calidad de las transformaciones. Estas transformaciones de tratamiento de datos pueden incluir la corrección de inconsistencias, valores atípicos o discrepancias de tipos de datos. Luego, el agente de Ingeniería de datos crea un plan que describe los pasos de preparación de datos propuestos para que los revises y definas antes de que se realice cualquier acción.

El agente de ingeniería de datos también inicia el análisis de preparación de datos cada vez que agregas una tabla sin procesar, como una tabla externa basada en CSV. Puedes revisar el plan de organización de datos y ajustarlo con comandos de conversación.

El muestreo y la creación de perfiles de datos usan recursos de BigQuery y están sujetos a los precios de BigQuery.

El agente de Data Engineering admite las siguientes transformaciones de tratamiento de datos:

  • Limpieza de datos El agente puede analizar datos sin procesar y sugerir oportunidades de limpieza, como quitar valores atípicos, completar valores faltantes o incoherentes (imputación de datos), corregir datos duplicados o estandarizar formatos de datos (por ejemplo, números de teléfono o direcciones).
  • Transformaciones estructurales Cuando se proporciona un esquema de destino, el agente puede anular el anidamiento o extraer valores de los tipos JSON, ARRAY o STRUCT, combinar varias columnas en una o dividir una columna en varias.
  • Detección y conversión de tipos de datos El agente puede analizar los datos para determinar los tipos de campos adecuados. Luego, el agente puede realizar una conversión de tipo segura para resolver cualquier inconsistencia de formato en los campos de fecha, hora, fecha y hora o marca de tiempo.
  • Conversión de unidades El agente puede convertir automáticamente varias unidades dentro de un campo en una unidad coherente para estandarizar tus datos.

Para garantizar la precisión, el agente usa muestras representativas de tus datos para detectar problemas y validar su lógica de transformación.

Genera y revisa planes de agentes

El agente de ingeniería de datos puede generar planes de agentes que proporcionan un resumen y una descripción general de los objetivos y los pasos que se deben seguir para completar una solicitud. Cuando le pidas al agente que realice solicitudes complejas que requieran muchos cambios, te recomendamos que le pidas que te proporcione un plan para que puedas revisar sus intenciones antes de que realice cualquier acción. En general, un plan del Agente de ingeniería de datos consta de lo siguiente:

  • Objetivo del agente para una solicitud en particular
  • Una descripción general de alto nivel de los pasos que el agente planea seguir
  • Las suposiciones que hace el agente
  • Archivos que el agente planea modificar
  • Los pasos de optimización o limpieza que planea realizar
  • Un plan de ejecución por fases

En tu instrucción, puedes incluir la necesidad de revisar y aprobar el plan para que el agente no realice ninguna acción sin tu aprobación explícita. Por ejemplo:

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.

El agente también podría generar un plan automáticamente y solicitar tu aprobación. Este resultado puede ocurrir cuando una instrucción es demasiado ambigua o si el agente necesita más claridad para cumplir con tu solicitud.

Para conocer las prácticas recomendadas sobre el uso de planes de agentes, consulta Prácticas recomendadas.

Cómo agregar contexto desde Knowledge Catalog

El agente de ingeniería de datos usa Knowledge Catalog adjuntando términos del glosario a las tablas y columnas de BigQuery, y generando análisis de perfiles de datos. Los términos del glosario pueden etiquetar columnas que requieren contexto adicional, como las que contienen información de identificación personal (PII) que requieren instrucciones de manejo especiales, o bien identificar columnas coincidentes con nombres diferentes en las distintas tablas.

Knowledge Catalog también utiliza el perfilado de datos, que le proporciona al agente una mejor comprensión de la distribución de los datos dentro de las columnas de la tabla y lo ayuda a crear aserciones de calidad de los datos más específicas.

El agente también puede usar Knowledge Catalog para descubrir y consultar tablas de Apache Iceberg. Para obtener más información, consulta Crea canalizaciones sobre tablas de Apache Iceberg.

Agrega verificaciones de calidad de los datos a una tabla existente

Cuando le indicas al agente que agregue verificaciones de calidad, este infiere verificaciones razonables para la tabla en función del esquema y las muestras. También puedes agregar aserciones basadas en opiniones como parte de la instrucción. Por ejemplo:

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

Durante la ejecución de la canalización, los resultados de las aserciones de Dataform se publican automáticamente en Knowledge Catalog (vista previa). Estos resultados completan el cuadro de evaluación de la calidad de los datos de Knowledge Catalog con un estado de aprobado o reprobado. Cada ejecución reemplaza los cuadros de evaluación de la calidad de los datos existentes que publicaron las ejecuciones anteriores de Dataform, pero no afecta los cuadros de evaluación creados por los análisis de datos de Knowledge Catalog.

Enriquecimiento automático de datos

Los metadatos estándar de BigQuery (por ejemplo, conjuntos de datos, tablas y vistas) están disponibles automáticamente en Knowledge Catalog.

También puedes definir metadatos personalizados para tus tablas y vistas directamente en el bloque de configuración de tus archivos .sqlx. Cuando se completa correctamente una acción, Dataform inicia automáticamente una sincronización de metadatos con Knowledge Catalog. Este proceso de enriquecimiento actualiza Knowledge Catalog con los metadatos semánticos definidos en tu configuración de SQLX.

Usa la clave de metadatos para especificar información para Knowledge Catalog. El proceso de enriquecimiento admite las siguientes construcciones de metadatos:

  • Descripción general: Documentación y texto de resumen de la entrada. Requiere la versión 3.0.37 o una posterior de Dataform Core.
  • Aspectos genéricos: Detalles semánticos, como información del sistema y el tipo de tabla. Se requiere la versión 3.0.52 o una posterior de Dataform Core.

En el siguiente ejemplo de configuración, se muestra cómo agregar una descripción general y aspectos de metadatos genéricos a una configuración de tabla para Knowledge Catalog:

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

Para verificar el estado de una actualización de metadatos, consulta Cómo inspeccionar los registros de ejecución del espacio de trabajo para los flujos de trabajo de Dataform o Cómo ver ejecuciones manuales anteriores para las canalizaciones de BigQuery.

Para verificar los metadatos sincronizados, puedes buscar el activo en Knowledge Catalog. Para obtener más información, consulta Cómo buscar recursos.

Optimiza las canalizaciones de datos

Puedes solicitarle al agente que optimice tus canalizaciones de datos. Cuando se genera DDL para tablas nuevas, el agente de ingeniería de datos recomienda la partición y la agrupación en clústeres según los patrones de uso de datos analizados. Además, el agente puede aplicar automáticamente otras optimizaciones de la canalización. Estos son algunos ejemplos de posibles optimizaciones:

  • Eliminación de columnas para reducir la lectura de datos del almacenamiento y actuar como un factor principal de costos y rendimiento.
  • Envío de predicados para filtrar los datos en una etapa temprana del plan de ejecución y reducir significativamente el volumen procesado por las operaciones posteriores
  • Eliminación de subexpresiones comunes para mejorar la eficiencia, ya que identifica y calcula la lógica de transformación compartida solo una vez, lo que evita prácticas ineficientes, como analizar y unir tablas grandes varias veces.
  • Modelos incrementales para procesar solo los datos nuevos o modificados desde la última ejecución, en lugar de volver a generar tablas completas con cada ejecución.

Crea canalizaciones en tablas de Apache Iceberg

El agente de ingeniería de datos admite la generación y compilación de canalizaciones de Dataform en tablas de Apache Iceberg administradas por el catálogo de entornos de ejecución de Lakehouse (antes metastore de BigLake). Esta función te permite consultar y unir tablas de formato de código abierto regionales (almacenadas en Cloud Storage) directamente junto con tus tablas de BigQuery. Para obtener más información, consulta Conceptos sobre los extremos del catálogo de REST de Apache Iceberg.

Por ejemplo, puedes indicarle al agente que consulte una tabla de Apache Iceberg en el catálogo de entornos de ejecución de Lakehouse:

Include the stackoverflow_post_history_iceberg table in this pipeline.

En tus instrucciones, no es necesario que especifiques rutas de acceso de cuatro partes completamente calificadas, por ejemplo, project.catalog.dataset.table. Puedes hacer referencia a las tablas de Apache Iceberg con nombres estándar en lenguaje natural o identificadores lógicos, por ejemplo, the StackOverflow post history table o post_history. El agente invoca automáticamente búsquedas semánticas en el catálogo con Knowledge Catalog para resolver y vincular las tablas correctas de Apache Iceberg a tu espacio de trabajo de canalización.

Para usar esta función, tu repositorio de Dataform debe usar la versión 3.0.33 o posterior de Dataform Core.

Recomendaciones interactivas

El agente de ingeniería de datos analiza el estado de compilación de tu espacio de trabajo, el historial de ejecución y el estado de conversación activo para proporcionar recomendaciones prácticas directamente en la interfaz de chat. Estas sugerencias aparecen automáticamente cuando abres un espacio de trabajo y durante toda la sesión para brindarte recomendaciones sobre la configuración, la solución de problemas y las optimizaciones que guiarán tu flujo de trabajo.

Para usar una recomendación, haz clic en una de las sugerencias que se encuentran en Recomendaciones de IA. Esto cargará la instrucción en la barra de entrada del chat, que puedes editar o personalizar antes de enviarla al agente. También puedes colocar el cursor sobre una sugerencia para ver la instrucción exacta.

Prácticas recomendadas

Para mejorar los resultados cuando trabajes con Data Engineering Agent y Dataform, te recomendamos que hagas lo siguiente:

Usa instrucciones del agente para solicitudes comunes. Si sueles aplicar ciertas técnicas o si con frecuencia realizas las mismas correcciones al agente, usa las instrucciones del agente como una ubicación centralizada para almacenar instrucciones y solicitudes comunes.

Utiliza planes de agentes. Los planes de agentes pueden ser útiles para desglosar tareas complejas de la canalización. Los planes del agente también pueden mostrarte las suposiciones y las intenciones del agente, por lo que te recomendamos que revises esos planes para asegurarte de que se le proporcione el contexto correcto.

Después de revisar un plan, puedes editarlo proporcionándole comentarios y cambios al agente de Ingeniería de datos. Por ejemplo:

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

En algunos casos, puede ser útil pedirle al agente que genere un plan que no necesite tu aprobación explícita. El hecho de hacer que el agente planifique obliga al agente de ingeniería de datos a desglosar sus acciones, lo que a menudo genera mejores resultados. Puedes obligar al agente a generar un plan y ejecutarlo automáticamente. Por ejemplo:

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.

Escribe con claridad. Expresa tu solicitud con claridad y evita ser impreciso. Cuando sea posible, proporciona fuentes de datos de origen y destino cuando realices la solicitud, como se muestra en el siguiente ejemplo:

  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.

Proporciona solicitudes directas y con alcance. Haz una pregunta a la vez y mantén las instrucciones concisas. En el caso de las instrucciones con más de una pregunta, enumera cada parte distinta de la pregunta para mejorar la claridad, como se muestra en el siguiente ejemplo:

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

Proporciona instrucciones explícitas y enfatiza los términos clave. Puedes agregar énfasis a los términos o conceptos clave en tus instrucciones y etiquetar ciertos requisitos como importantes, como se muestra en el siguiente ejemplo:

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

Especifica el orden de las operaciones. En el caso de las tareas ordenadas, estructura tu instrucción en listas, en las que los elementos enumerados se dividan en pasos pequeños y enfocados, como se muestra en el siguiente ejemplo:

  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.

Define mejor e itera. Sigue probando diferentes frases y enfoques para ver cuál genera los mejores resultados. Si el agente genera código SQL no válido o comete otros errores, guíalo con ejemplos o documentación pública.

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

Evalúa las canalizaciones de datos

Para evaluar la eficacia de una canalización de datos generada por el agente de ingeniería de datos, usa la herramienta EvalBench. EvalBench es un framework de código abierto que admite evaluaciones de agentes de varios turnos. EvalBench actúa como un paquete de pruebas unitarias automatizadas, lo que te permite configurar situaciones de varios turnos, agregar evaluadores determinísticos y respaldados por LLM, y administrar el ciclo de vida de tus canalizaciones de Dataform.

Al simular instrucciones en lenguaje natural en un entorno de pruebas aislado, EvalBench mide la eficacia con la que el agente comprende las instrucciones, llama a las herramientas adecuadas y genera el código de canalización correcto. EvalBench puede verificar tus canalizaciones de datos de la siguiente manera:

  • Validación de reglas personalizadas: Verifica que el agente siga estrictamente los lineamientos de programación, las convenciones de nomenclatura y las prácticas recomendadas específicos de tu organización.
  • Prevención de regresiones de código: Prueba los cambios en la canalización antes de la implementación para asegurarte de que las actualizaciones del agente o las modificaciones del esquema no interrumpan la funcionalidad existente.
  • Generación de comparativas de calidad: Obtén puntuaciones objetivas y automatizadas para la corrección de SQL, la precisión de la ejecución de herramientas y la confiabilidad de la canalización.

Ejecuta una evaluación de canalización de datos

Puedes ejecutar EvalBench en los siguientes dos modos:

  • Zona de pruebas dinámica: EvalBench aprovisiona un repositorio y un espacio de trabajo de Dataform nuevos y temporales al comienzo de una ejecución de evaluación, ejecuta los casos de prueba y desmantela automáticamente todos los recursos creados una vez que se completa la ejecución. Este modo no modifica ningún código de producción, repositorios de producción ni conjuntos de datos de BigQuery, y no deja ningún artefacto residual en tu proyecto de Google Cloud . El modo de zona de pruebas dinámico es adecuado para las canalizaciones de CI/CD automatizadas, las pruebas de regresión nocturnas y la puntuación de comparativas objetivas en las que se requiere un aislamiento estricto del entorno.

  • Espacio de trabajo estático: EvalBench se conecta a un repositorio y a un espacio de trabajo de Dataform preexistentes y administrados por el usuario, y omite los scripts de creación y eliminación automatizados. Este modo permite que el agente en evaluación modifique y cree archivos SQLX nuevos dentro del espacio de trabajo existente a medida que procesa los casos de evaluación. El modo de espacio de trabajo estático es adecuado para la ingeniería de instrucciones activa, la iteración de rúbricas y la depuración local en la que necesitas inspeccionar los archivos SQLX generados directamente en tu espacio de trabajo de Dataform después de la ejecución.

Antes de comenzar

Para obtener los permisos que necesitas para ejecutar EvalBench, pídele a tu administrador que te otorgue los siguientes roles de IAM en la cuenta de servicio o la identidad del usuario que ejecuta EvalBench:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Ejecuta la evaluación en una zona de pruebas dinámica

Para evaluar tu canalización de datos en el modo de zona de pruebas dinámica, haz lo siguiente:

  1. Sigue los pasos para clonar el repositorio, configurar el entorno virtual y, luego, instalar las dependencias de EvalBench. Para obtener más información, consulta Cómo comenzar.

  2. En el directorio datasets/dea-tools/, verifica que el archivo de configuración de ejecución de ejemplo (example_run_config.yaml) incluya las siguientes líneas:

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

  3. Ejecuta EvalBench con el siguiente 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

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el ID del proyecto de Google Cloud.
    • REGION: Es la región del Google Cloudproyecto.

Ejecuta la evaluación en un espacio de trabajo de evaluación estático

Para evaluar tu canalización de datos en el modo de espacio de trabajo estático, haz lo siguiente:

  1. Sigue los pasos para clonar el repositorio, configurar el entorno virtual y, luego, instalar las dependencias. Para obtener más información, consulta Cómo comenzar.

  2. En el directorio datasets/dea-tools/, edita el archivo de configuración de ejecución de ejemplo (example_run_config.yaml) para marcar como comentario las líneas set_up_script y tear_down_script, y agrega las configuraciones dataform_repository y 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. Ejecuta EvalBench con el siguiente 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

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el ID del proyecto de Google Cloud.
    • REGION: Es la región del Google Cloudproyecto.
    • REPOSITORY_ID: Es el ID del repositorio que contiene la canalización de datos.
    • WORKSPACE_ID: Es el ID del espacio de trabajo que contiene la canalización de datos.

  4. Opcional: También puedes ejecutar EvalBench con core_10_cases_suite.yaml para probar la canalización de datos en 10 casos de evaluación principales de forma secuencial con aislamiento del entorno. Para ello, crea un repositorio nuevo para cada caso de prueba. Para ello, ejecuta el siguiente 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ácticas recomendadas para la evaluación de canalizaciones de datos

Para mejorar el rendimiento y la precisión de las evaluaciones de tu canalización de datos con EvalBench, te recomendamos que hagas lo siguiente:

  • Busca la invocación del flujo de trabajo de Dataform y los IDs de los trabajos de BigQuery en los registros de evaluación. Usa estos IDs para comparar datos mediante referencia cruzada y, luego, inspeccionar los artefactos de ejecución, los resultados de compilación y los registros de consultas generados en la consola de Google Cloud .
  • Siempre ejecuta el paquete de evaluación principal (--suite_config) antes de lanzar cambios en el modelo o las instrucciones para garantizar una cobertura completa de la regresión en diversos casos de ingeniería de datos.
  • Usa EVAL_DATAFORM_SETUP_ENV_FILES_DIR para cargar previamente los archivos de configuración del entorno, como workflow_settings.yaml y las definiciones de esquema base, en el espacio de trabajo de prueba. Estos archivos de configuración garantizan que el agente se compile en entornos existentes realistas en lugar de espacios de trabajo vacíos.
  • Cuando soluciones problemas relacionados con casos de evaluación fallidos en el modo de zona de pruebas dinámica, comenta tear_down_script en tu configuración de ejecución para conservar el espacio de trabajo de destino para el análisis posterior.
  • Siempre combina los verificadores de compilación y ejecución en la nube (dataform_cloud_compile, dataform_cloud_run) con rúbricas binarias basadas en LLM para identificar errores de sintaxis o de tiempo de ejecución, y fallas lógicas de alto nivel.
  • Habilita los informes de BigQuery (<PROJECT_ID>.evalbench.results) y usa los vínculos generados de Data Studio para hacer un seguimiento de los porcentajes de aprobación, la precisión del uso de herramientas y la eficiencia de las instrucciones a lo largo del tiempo.