Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

数据工程智能体概览

借助 Data Engineering Agent，您可以使用自然语言提示在 BigQuery 中构建、修改和排查数据流水线问题。数据工程代理提供以下功能，可简化数据工程工作流，以便将数据注入到 BigQuery 中：

Dataform 集成：智能体直接在 Dataform 代码库和工作区中生成和整理数据流水线代码
方案生成：智能体可以总结其思路并生成方案，以便您在继续操作之前查看和验证智能体的方案
代码验证：代理会自动验证并修复任何生成的代码的编译错误，以确保数据流水线正常运行
自动数据整理：代理会执行数据整理，并将原始数据转换为结构化表格，无需人工干预。
自定义指令：智能体支持自定义智能体指令，让您可以使用自然语言定义特定规则和可重复使用的准则
外部上下文：智能体与 Knowledge Catalog 集成，可提供更多上下文
流水线控制：您可以在执行任何操作之前查看和自定义生成的代理计划。
优化：该代理可以优化数据流水线的性能
排查和修复：代理可以排查流水线故障并修复其代码。
互动式建议：智能体在会话开始时和整个会话期间提供互动式、可感知情境的建议。
Knowledge Catalog 元数据扩充：该代理可以根据您的表配置自动生成 Knowledge Catalog 元数据，并在流水线执行期间将元数据发送到 Knowledge Catalog。

数据工程代理的适用范围

您可以通过以下方法使用数据工程代理：

通过 BigQuery 流水线界面或在 Dataform 中构建数据流水线。
在 Visual Studio Code 中安装 Google Cloud Data Agent Kit 扩展程序，以便从集成开发环境 (IDE) 构建数据流水线。
使用 Data Engineering Agent API。

Data Engineering Agent 如何使用您的数据

为了生成更高质量的智能体回答，数据工程智能体可以从 BigQuery 和 Knowledge Catalog 中检索其他数据和元数据，包括 BigQuery 表中的示例行以及在 Knowledge Catalog 中生成的数据扫描配置文件。智能体不会使用这些数据进行训练；它仅在智能体对话期间将这些数据用作额外的上下文信息，以便生成更贴切的回答。

数据工程代理处理您的数据的位置

如需详细了解 Data Engineering Agent 处理数据的位置，请参阅 Gemini in BigQuery 在何处处理数据。

限制

Data Engineering Agent 具有以下限制：

Data Engineering Agent 不支持针对以下文件类型的自然语言命令：
- 笔记本
- 数据准备
数据工程代理无法执行流水线。您必须查看并运行或安排流水线。
数据工程代理无法搜索通过指令或直接提示提供的任何网页链接或网址。
在代理指令文件中导入文件时，@ 导入语法仅支持以 ./、/ 或字母开头的路径。
数据预览功能仅适用于将 hasOutput 标志设置为 true 的表、声明或查询。
数据工程智能体受 AI 技术的一般限制的约束。
在由 Lakehouse 运行时目录（原 BigLake metastore）管理的 Apache Iceberg 外部表上创建流水线时，所有 Lakehouse 运行时目录限制均适用。最值得注意的是，该代理无法在 Iceberg 表上生成写入变更（例如 INSERT、UPDATE、DELETE 或 MERGE）或 DDL 语句（例如 CREATE TABLE 或 DROP TABLE）。如需了解详情，请参阅 Apache Iceberg REST Catalog 端点概念。

智能体功能和自定义设置

以下部分介绍了其他代理功能以及自定义数据工程代理的其他方法。

代理指令

代理指令是针对数据工程代理的自然语言指令，可让您存储持久性指令，以便代理遵循一组自定义的预定义规则。如果您希望代理的回答在整个组织中保持一致，例如在命名惯例方面或为了强制执行样式指南，请使用代理指令。

如需为数据工程智能体创建智能体指令，请创建 GEMINI.MD 上下文文件作为智能体指令文件。

代理指令文件的最佳实践

使用代理指令时，我们建议您执行以下操作：

Dataform 中的所有文件路径都相对于代码库的根目录。使用任何 @file.md 语法的相对路径，以便将指令正确导入到 GEMINI.md。
在 GEMINI.md 中导入的文件本身可以包含导入，从而创建嵌套结构。为防止无限递归，GEMINI.md 的最大导入深度为 5 级。
如需在多个数据流水线之间共享指令，请将指令存储在中央 Dataform 代码库中，并将其关联到工作 Dataform 代码库。您可以使用本地指令来替换流水线特定行为的中央规则。
为确保项目中的一致性，您可以链接到命名惯例文件或样式指南，并指示代理在处理数据流水线时遵循这些指南。
您可以在指令文件中建议数据层，以便将不同类型的数据分组在一起。
在代理指令文件中使用标题和列表有助于整理和明确 Data Engineering Agent 的指令。
提供有意义的文件名，并将类似说明归为一组。使用 Markdown 标题按类别、功能或功能逻辑地整理规则。
为避免指令冲突，请明确定义每条指令适用的具体条件。
迭代并优化提示和工作流程。随着代理推出和模型升级，代理行为会随时间发生变化，因此我们建议您使用不同的提示迭代规则，以确定可能需要改进的方面。确保规则文件与数据流水线的任何更改保持同步。

以下示例展示了一个名为 GEMINI.md 的代理指令文件，该文件利用了我们的最佳实践来有效使用数据工程代理：

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

将其他本地文件作为代理指令导入

您还可以使用 @file.md 语法将其他数据工程代理指令文件导入到 GEMINI.md 文件中。如需了解详情，请参阅内存导入处理器。

自动数据整理

您可以使用 Data Engineering Agent 将未经处理的原始数据转换为适合数据分析的结构化表格。在收到请求后，代理会先从每个标准表或外部表中抽样最多 100 万条记录。然后，代理会通过对该样本运行分析查询来执行深度数据分析。生成数据转换后，代理会重复此抽样和分析流程，以评估转换的质量。这些数据整理转换可能包括修正数据不一致、离群值或类型不匹配的问题。然后，数据工程智能体将创建一个计划，其中概述了建议的数据整理步骤，供您在执行任何操作之前查看和完善。

每当您添加原始表（例如基于 CSV 的外部表）时，Data Engineering Agent 也会启动数据整理分析。您可以查看数据整理方案，并使用对话式命令对其进行调整。

数据抽样和分析会使用 BigQuery 资源，并受 BigQuery 价格的约束。

Data Engineering Agent 支持以下数据整理转换：

数据清理。该代理可以分析原始数据并建议清理机会，例如移除离群值、填充缺失值或不一致的值（数据插补）、修正重复数据或标准化数据格式（例如手机号码或地址）
结构性转换。如果提供了目标架构，代理可以从 JSON、ARRAY 或 STRUCT 类型中取消嵌套或提取值；将多个列合并为一个列；或将一个列拆分为多个列
数据类型检测和转换。代理可以分析数据，以确定合适的字段类型。然后，代理可以执行安全类型转换，以解决日期、时间、日期时间或时间戳字段中的任何格式不一致问题。
单位换算。该智能体可自动将字段中的各种单位转换为一个统一的单位，以实现数据标准化。

为确保准确性，代理会使用具有代表性的数据样本来检测问题并验证其转换逻辑。

生成并查看代理计划

数据工程代理可以生成代理方案，其中包含摘要以及完成请求所需的目标和步骤的概览。当您向智能体发出需要进行多项更改的复杂请求时，建议您要求智能体提供智能体计划，以便您在智能体采取任何行动之前查看其意图。数据工程代理方案通常包含以下内容：

代理针对特定请求的目标
代理计划采取的步骤的简要概览
智能体做出的任何假设
代理计划修改的文件
计划执行的任何优化或清理步骤
分阶段执行计划

在提示中，您可以要求代理在执行任何操作之前，必须先征得您的明确批准，以确保您能够审核并批准方案。例如：

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.

智能体还可能会自动生成智能体计划并请求您的批准。如果提示过于模糊不清，或者代理需要更清晰的提示才能满足您的要求，就可能会出现此结果。

如需了解有关使用代理方案的最佳实践，请参阅最佳实践。

从 Knowledge Catalog 添加上下文

数据工程智能体通过将术语表中的术语附加到 BigQuery 表和列并生成数据分析扫描，来使用 Knowledge Catalog。词汇表术语可以标记需要额外上下文信息的列，例如包含个人身份信息 (PII) 且需要特殊处理说明的列，或者用于标识不同表中名称不同的匹配列。

Knowledge Catalog 还利用数据分析，让代理更好地了解表格列中的数据分布，并帮助代理创建更具体的数据质量断言。

代理还可以使用 Knowledge Catalog 发现和查询 Apache Iceberg 表。如需了解详情，请参阅基于 Apache Iceberg 表创建流水线。

向现有表添加数据质量检查

当您提示代理添加质量检查时，代理会根据架构和样本为表推断合理的检查。您还可以在提示中添加主观断言。例如：

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

在流水线执行期间，任何 Dataform 断言的结果都会自动发布到 Knowledge Catalog（预览版）。这些结果会填充Knowledge Catalog 数据质量记分卡，并显示通过或未通过状态。每次执行都会覆盖之前 Dataform 运行发布的数据质量记分卡，但不会影响 Knowledge Catalog 数据扫描创建的记分卡。

自动数据丰富化

来自 BigQuery 的标准元数据（例如数据集、表和视图）会自动在 Knowledge Catalog 中提供。

您还可以在 .sqlx 文件的配置块中直接为表和视图定义自定义元数据。成功完成操作后，Dataform 会自动启动与 Knowledge Catalog 的元数据同步。此丰富过程会使用 SQLX 配置中定义的语义元数据来更新 Knowledge Catalog。

使用元数据键指定 Knowledge Catalog 的信息。丰富处理流程支持以下元数据结构：

概览：条目的文档和摘要文本。需要使用 Dataform 核心版本 3.0.37 或更高版本。
通用方面：语义细节，例如表格系统和类型信息。需要使用 Dataform 核心版本 3.0.52 或更高版本。

以下示例配置展示了如何向 Knowledge Catalog 的表配置添加概览和通用元数据方面：

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

如需查看元数据更新的状态，请参阅 Dataform 工作流的检查工作区执行日志或 BigQuery 流水线的查看过往手动运行。

如需验证同步的元数据，您可以在 Knowledge Catalog 中搜索相应资产。如需了解详情，请参阅搜索资源。

优化数据流水线

您可以提示代理优化数据流水线。在为新表生成 DDL 时，数据工程代理会根据分析的数据使用模式推荐分区和聚类。此外，该代理还可以自动应用其他流水线优化。可能的优化示例包括：

通过列剪除来减少从存储空间读取的数据，从而成为主要的成本和性能驱动因素。
谓词下推，可在执行计划中尽早过滤数据，从而显著减少后续操作处理的数据量。
通过仅识别和计算一次共享转换逻辑来消除常见子表达式，从而提高效率，防止多次扫描和联接大型表等低效做法。
增量模型，用于仅处理自上次运行以来新增或更改的数据，而不是在每次运行时重建整个表。

基于 Apache Iceberg 表创建流水线

数据工程代理支持在由 Lakehouse 运行时目录（以前称为 BigLake metastore）管理的 Apache Iceberg 表上生成和编译 Dataform 流水线。借助此功能，您可以直接查询和联接区域性开放源代码格式表（存储在 Cloud Storage 中），同时还可以查询和联接 BigQuery 表。如需了解详情，请参阅 Apache Iceberg REST Catalog 端点概念。

例如，您可以提示代理查询 Lakehouse 运行时目录中的 Apache Iceberg 表：

Include the stackoverflow_post_history_iceberg table in this pipeline.

在提示中，您无需指定完全限定的四部分路径，例如 project.catalog.dataset.table。您可以使用标准自然语言名称或逻辑标识符（例如 the StackOverflow post history table 或 post_history）引用 Apache Iceberg 表。代理会自动使用 Knowledge Catalog 调用语义目录搜索，以将正确的 Apache Iceberg 表解析并绑定到您的流水线工作区。

如需使用此功能，您的 Dataform 代码库必须使用 Dataform Core 3.0.33 版或更高版本。

互动式建议

数据工程代理会分析您的工作区编译状态、执行历史记录和活跃对话状态，以便直接在聊天界面中提供切实可行的建议。当您打开工作区时，这些建议会自动显示，并在整个会话期间提供设置、问题排查和优化建议，以指导您的工作流程。

如需使用建议，请点击 AI 建议下方的某个建议，系统会将相应提示加载到聊天输入栏中，您可以在发送给代理之前修改或自定义该提示。您还可以将鼠标悬停在建议上，查看确切的提示。

最佳做法

为了在使用 Data Engineering Agent 和 Dataform 时获得更好的结果，我们建议您执行以下操作：

针对常见请求使用代理指令。如果您经常应用某些技巧，或者经常对代理提出相同的更正，请使用代理指令作为集中存储常用指令和请求的位置。

利用代理计划。代理计划有助于分解复杂的流水线任务。代理计划还可以显示代理的假设和意图，因此我们建议您查看这些计划，确保为代理提供正确的上下文。

查看方案后，您可以向数据工程代理提供反馈和更改，从而修改方案。例如：

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

在某些情况下，让代理生成无需您明确批准的方案会很有帮助。让代理制定计划的行为会迫使数据工程代理分解其行动，这通常会带来更好的结果。您可以强制代理生成方案并自动执行。例如：

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.

文字清晰。明确说明您的要求，避免含糊不清。在提示时，尽可能提供源数据源和目标数据源，如以下示例所示：

  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.

提供直接且有范围的请求。一次只问一个问题，并使提示简洁明了。对于包含多个问题的提示，请将问题的每个不同部分列出来，以提高清晰度，如以下示例所示：

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

提供明确的说明并强调关键术语。您可以在提示中突出显示关键术语或概念，并将某些要求标记为重要，如以下示例所示：

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

指定操作顺序。对于有序任务，请以列表形式构建提示，其中列出的项分为专注的小步骤，如以下示例所示：

  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.

优化和迭代。不断尝试不同的措辞和方法，看看哪种效果最好。如果代理生成了无效的 SQL 或其他错误，请使用示例或公开文档来引导代理。

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

评估数据流水线

如需评估数据工程代理生成的数据流水线的有效性，请使用 EvalBench 工具。EvalBench 是一个开源框架，支持多轮智能体评估。EvalBench 充当自动化单元测试套件，可让您设置多轮对话场景、添加 LLM 支持的确定性评分器，以及管理 Dataform 流水线的生命周期。

通过在隔离的沙盒中模拟自然语言提示，EvalBench 可衡量代理理解指令、调用正确工具和生成正确流水线代码的有效性。EvalBench 可以通过以下方式检查数据流水线：

验证自定义规则：验证代理是否严格遵循贵组织的特定编码指南、命名惯例和最佳实践。
防止代码回归：在部署之前测试流水线更改，以确保代理更新或架构修改不会破坏现有功能。
生成质量基准：获取有关 SQL 正确性、工具执行准确性和流水线可靠性的客观自动化得分。

运行数据流水线评估

您可以通过以下两种模式运行 EvalBench：

动态沙盒：EvalBench 在评估运行开始时预配全新的临时 Dataform 代码库和工作区，执行测试场景，并在完成后自动拆除所有已创建的资源。此模式不会修改任何生产代码、生产代码库或 BigQuery 数据集，也不会在您的 Google Cloud 项目中留下任何剩余制品。动态沙盒模式适用于需要严格隔离环境的自动化 CI/CD 流水线、每晚回归测试和客观基准评分。
静态工作区：EvalBench 连接到预先存在且由用户管理的 Dataform 代码库和工作区，并跳过自动创建和删除脚本。在此模式下，受评估的代理可以在处理评估用例时修改现有工作区中的 SQLX 文件并创建新文件。静态工作区模式适用于主动提示工程、评分准则迭代和本地调试，在这些情况下，您需要在执行后直接在 Dataform 工作区中检查生成的 SQLX 文件。

准备工作

如需获得运行 EvalBench 所需的权限，请让管理员为您授予运行 EvalBench 的服务账号或用户身份的以下 IAM 角色：

Dataform Admin (roles/dataform.admin)
BigQuery Data Editor (roles/bigquery.dataEditor)
BigQuery Job User (roles/bigquery.jobUser)
将评估结果导出为 ZIP 软件包：Storage Object Admin (roles/bigquery.objectAdmin)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

在动态沙盒中运行评估

如需在动态沙盒模式下评估数据流水线，请执行以下操作：

按照相关步骤克隆代码库、设置虚拟环境并安装所有 EvalBench 依赖项。如需了解详情，请参阅使用入门。

在 datasets/dea-tools/ 目录中，验证示例运行配置 (example_run_config.yaml) 文件是否包含以下代码行：

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

使用以下命令运行 EvalBench：

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

替换以下内容：

PROJECT_ID： Google Cloud项目的 ID。
REGION： Google Cloud项目的区域。

在静态评估工作区中运行评估

如需在静态工作区模式下评估数据流水线，请执行以下操作：

按照相应步骤克隆代码库、设置虚拟环境并安装所有依赖项。如需了解详情，请参阅使用入门。

在 datasets/dea-tools/ 目录中，修改示例运行配置 (example_run_config.yaml) 文件，以注释掉 set_up_script 和 tear_down_script 行，并添加 dataform_repository 和 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}
...