使用資料工程代理建構及修改資料管道

本文說明如何在 BigQuery 和 Dataform 中，使用資料工程代理建立及修改資料管道。

資料工程代理可協助您建構、修改及管理資料管道，在 BigQuery 載入及處理資料。有了資料工程代理，您可以使用自然語言提示，從各種資料來源生成資料管道，或調整現有資料管道，滿足資料工程需求。

代理會直接在 Dataform 存放區中生成及整理資料管道程式碼。代理會在 Dataform 工作區中運作，因此會自動提供 Dataform 管道。

如要查看更多可與 Data Engineering Agent 搭配使用的提示範例，請參閱「提示範例」。

您也可以使用 Data Engineering Agent API (採用 A2A 通訊協定) 與代理互動。

限制

資料工程代理有下列限制：

• 資料工程代理不支援下列檔案類型的自然語言指令：
  • Notebooks
  • 準備資料
• 資料工程代理無法執行管道。您必須查看並執行或排定管道。
• 資料工程代理無法搜尋透過指令或直接提示提供的任何網頁連結或網址。
• 在代理指令檔案中匯入檔案時，@ 匯入語法僅支援以 ./、/ 或字母開頭的路徑。
• 資料預覽功能僅支援 hasOutput 旗標設為 true 的資料表、宣告或查詢。
• Data Engineering Agent 受到 AI 技術的一般限制。
• 如果透過 Lakehouse 執行階段目錄 (原 BigLake Metastore) 管理的 Apache Iceberg 外部資料表建立管道，則適用所有 Lakehouse 執行階段目錄限制。最重要的是，代理無法在 Iceberg 資料表上產生寫入異動 (例如 INSERT、UPDATE、DELETE 或 MERGE) 或 DDL 陳述式 (例如 CREATE TABLE 或 DROP TABLE)。詳情請參閱「Apache Iceberg REST 目錄端點概念」。

事前準備

使用 Data Engineering Agent 前，請先完成本節中的步驟。

啟用 Gemini in BigQuery

確認Google Cloud 專案已啟用 Gemini in BigQuery。詳情請參閱「設定 Gemini in BigQuery」。

啟用必要 API

注意： 如果您沒有啟用 API 的權限，請要求專案管理員透過「API 和服務」資訊主頁為您啟用 API。或者，專案管理員可以授予您 Service Usage 管理員 (roles/serviceusage.serviceUsageAdmin) 角色，讓您管理目前專案的 API。

主控台

在 Google Cloud 控制台中，為與 Conversational Analytics API 搭配使用的 Google Cloud 專案啟用下列 API (如果尚未 啟用)。

啟用 Gemini 資料分析 API

啟用 Gemini for Google Cloud API

啟用 BigQuery API

提示： 啟用 API 後，請重新整理 Google Cloud 控制台頁面，確認 API 已啟用。

gcloud

如要啟用 Gemini 資料分析 API、Gemini for Google CloudAPI 和 BigQuery API (如果尚未啟用)，請使用 Google Cloud CLI 並執行下列 gcloud services enable 指令：

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

將 PROJECT_ID 替換為 Google Cloud 專案 ID。

必要的角色

如要取得使用 Data Engineering Agent 所需的權限，請要求管理員授予您專案的下列 IAM 角色：

• Dataform 程式碼編輯器 (roles/dataform.codeEditor)
• BigQuery 工作使用者 (roles/bigquery.jobUser)
• Gemini 資料分析無狀態對話使用者 (roles/geminidataanalytics.dataAgentStatelessUser)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這個預先定義的角色具備 geminidataanalytics.locations.useDataEngineeringAgent 權限，可使用 Data Engineering Agent。

您或許還可透過自訂角色或其他預先定義的角色取得這項權限。

如要瞭解查詢 Apache Iceberg 資料表所需的角色，請參閱「Lakehouse Apache Iceberg 支援所需的角色」。

Knowledge Catalog 整合功能必要條件

如要取得將資料工程代理與 Knowledge Catalog 整合所需的權限，請要求管理員授予您專案的 Dataplex Catalog 編輯者 (roles/dataplex.catalogEditor) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這個預先定義的角色具備 geminidataanalytics.locations.useDataEngineeringAgent 權限，可將資料工程代理與 Knowledge Catalog 整合。

您或許還可透過自訂角色或其他預先定義的角色取得這項權限。

如果您使用自訂服務帳戶執行管道，則必須在專案或 @bigquery 項目群組中，授予Dataplex Catalog 編輯者 (roles/dataplex.catalogEditor) 角色。此外，您必須啟用 Dataplex API。

使用 Cloud Key Management Service 金鑰加密資料

您可以使用 BigQuery 中預設的客戶自行管理 Cloud Key Management Service 金鑰，在資料集或專案層級加密資料。詳情請參閱「設定資料集預設金鑰」和「設定專案預設金鑰」。

您可以設定預設 Dataform Cloud Key Management Service 金鑰，在專案層級加密管道程式碼。

設定 VPC Service Controls perimeter

如果使用 VPC Service Controls，請務必設定 perimeter，保護 Dataform、BigQuery 和 Conversational Analytics API。詳情請參閱 Dataform、BigQuery 和 Conversational Analytics API。

使用資料工程代理生成資料管道

如要在 BigQuery 中使用 Data Engineering Agent，請選取下列其中一個選項：

BigQuery 管道

如要在 BigQuery 管道介面使用資料工程代理，請按照下列步驟操作：

1. 前往「BigQuery」頁面

   前往「BigQuery」

2. 在查詢編輯器中，依序點選 arrow_drop_down「Create new」(新建) >「Pipeline」(管道)。

3. 在管道介面中，點選「詢問代理」。

4. 在「Ask agent」(詢問代理) 欄位中，輸入自然語言提示來生成資料管道，例如：

     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.
   

   輸入提示後，按一下「傳送」。

5. 資料工程代理會依據提示詞生成資料管道。

資料工程代理會生成資料管道草稿，您可以點選管道節點，查看生成的 SQLX 查詢。如要套用代理建議的資料管道，請按一下「套用」。

Dataform

如要在 Dataform 中使用資料工程代理，請按照下列步驟操作：

1. 前往「Dataform」。

   前往 Dataform

2. 選取存放區。

3. 選取或建立開發工作區。

4. 在工作區中，按一下「詢問代理」。

5. 在顯示的「Ask agent」(詢問代理) 提示中，輸入自然語言提示來生成資料管道，例如：

     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.
   

   輸入提示後，按一下「傳送」。

傳送提示後，資料工程代理會根據提示生成資料管道，並修改 Dataform SQLX 檔案。代理會直接將這些變更套用至工作區檔案。

編輯資料管道

如要編輯資料管道，請按一下「Ask agent」(詢問代理)，然後輸入提示，建議變更資料管道。

查看資料工程代理建議的變更，然後點選「Apply」(套用) 套用變更。

您也可以手動編輯 SQLX 查詢，方法是選取管道節點，然後按一下「Open」(開啟)。

查看資料管道

在資料工程代理生成的資料管道中，點選管道節點即可查看。

• 「Configuration」(設定) 分頁會顯示與節點相關聯的生成 SQLX 查詢。
• 「資料預覽」分頁會顯示檔案的輸入和輸出資料表。如要預覽透過這個節點進行的資料轉換，請按一下「Run task」(執行工作)，執行工作 (不論是否包含依附元件)。

排解資料管道錯誤

如果在生成資料管道時發生錯誤，請完成執行資料工程代理的所有必要條件。

管道中的錯誤會在「Executions」(執行作業) 分頁中顯示為失敗的執行作業。如要使用資料工程代理執行根本原因分析，並取得疑難排解建議，請按照下列步驟操作：

1. 在「Executions」(執行作業) 分頁中，按一下失敗執行作業執行的狀態，然後點選「Investigate」(調查)。

   

   「Ask agent」(詢問代理) 面板隨即開啟，並顯示要求代理對失敗執行作業進行根本原因分析的提示。

2. 查看代理提供的疑難排解報告。

疑難排解報表會提供更多資訊，說明管道生成程序中的錯誤。您可以提示代理依據報表修正這些管道錯誤。

建立代理指令

代理指令是以自然語言撰寫，可讓您儲存永久指令，讓資料工程代理遵循一組自訂的預先定義規則。如要讓代理在整個組織中產生一致的結果，例如使用命名慣例或強制執行樣式指南，請使用代理指令。

您可以建立 GEMINI.MD 脈絡檔案，做為資料工程代理的代理指令檔案。您可以建立代理程式指令檔案，在本機工作區中使用，也可以透過外部存放區，在多個資料管道中使用相同的指令檔案。

如要建立代理操作說明，請按照下列步驟操作：

1. 在「詢問代理」下方，點按「管道操作說明」。
2. 在「Instructions for pipeline」窗格中，點選「Create instructions file」。

3. 在顯示的 GEMINI.MD 檔案中，以自然語言輸入指令。

   以下範例顯示含有多項規則的代理指令檔案：

     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. 按一下 [儲存]。

如要瞭解如何以最佳方式建構代理指令檔案，請參閱「代理指令檔案的最佳做法」。

從外部存放區載入代理指示

如要在多個資料管道重複使用一組代理指示，請連結外部存放區：

1. 在「詢問代理」下方，點按「管道操作說明」。
2. 在「External repository」(外部存放區) 下方，選取「Use instructions from external repository」(使用外部存放區中的指示)。
3. 在提供的欄位中，指定要與資料管道搭配使用的代理程式指令存放區。
4. 按一下 [儲存]。

提示範例

下列各節提供提示範例，可與 Data Engineering Agent 搭配使用，開發資料管道。

將現有資料匯總至新資料表

收到這則提示後，資料工程代理會使用結構定義和樣本，推論如何依鍵分組資料。代理通常會設定新的資料表，並提供資料表和資料欄說明。

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

建立新的衍生資料欄，並為新資料表新增資料品質檢查

以下提示詞說明如何新增資料表和資料欄，並同時指定資料表的品質檢查：

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

在模型定義中建立 UDF

資料工程代理也能設定 DDL，建立 user-defined function (UDF)。雖然代理不會實際建立 UDF，但您可以執行資料管道來建立 UDF。這些 UDF 可用於資料管道中的模型定義。

  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.

最佳做法

如要提升 Data Engineering Agent 和 Dataform 的作業成效，建議您採取下列做法：

使用代理操作說明處理常見要求。如果您經常套用特定技術，或經常對代理進行相同的修正，請使用代理指示做為集中位置，儲存常見的指示和要求。

使用代理計畫。代理計畫有助於拆解複雜的管道工作。代理計畫也會顯示代理的假設和意圖，因此建議您查看這些計畫，確保代理取得正確的背景資訊。

查看計畫後，您可以向 Data Engineering Agent 提供意見回饋和變更，藉此編輯計畫。例如：

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