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

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

代理會直接在 Dataform 存放區中生成及整理資料管道程式碼，並在 Dataform 工作區中運作，因此代理會自動取得 Dataform 管道。您也可以使用 Data Engineering Agent API 與代理互動，該 API 採用 A2A 通訊協定。如需可用的提示範例，請參閱「提示範例」。

資料工程代理採用 Gemini forGoogle Cloud，並支援 BigQuery AI 和機器學習函式，可在 Dataform 中建構批次 AI 擴充、語意搜尋和機器學習管道。詳情請參閱「BigQuery AI 和機器學習支援」。

限制

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

• 資料工程代理不支援下列檔案類型的自然語言指令：
  • 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. 按一下「儲存」。

BigQuery AI 和機器學習支援

資料工程代理支援許多 BigQuery AI、機器學習和物件函式，以及陳述式，包括在生成的 Dataform SQLX 管道和您建立的代理指令檔案 (GEMINI.MD) 中，包括：

• AI.FORECAST
• AI.DETECT_ANOMALIES
• AI.CAUSAL_EFFECT
• AI.EVALUATE
• AI.KEY_DRIVERS
• AI.GENERATE
• AI.GENERATE_TABLE
• AI.GENERATE_EMBEDDING
• AI.IF
• AI.SCORE
• AI.CLASSIFY
• AI.SEARCH
• AI.SIMILARITY
• AI.AGG
• CREATE MODEL (包括 LOGISTIC_REG、 KMEANS、 CONTRIBUTION_ANALYSIS、 遠端模型 (REMOTE WITH CONNECTION) 和 TRANSFORM 子句)
• CREATE TABLE 搭配自主嵌入生成功能 (AI.EMBED)
• ML.PREDICT
• ML.EVALUATE
• ML.CORRELATION
• ML.DETECT_CHANGE_POINTS
• ML.GET_INSIGHTS
• ML.SEASONALITY
• ML.TREND
• ML.VALIDATE_DATA_DRIFT
• VECTOR_SEARCH
• OBJ.GET_ACCESS_URL

如要執行含有生成式 AI 函式或遠端模型的 Dataform 管道，執行管道的服務帳戶或使用者必須具備執行生成式 AI 查詢所需的權限。資料工程代理會產生 DDL 陳述式，例如 CREATE MODEL 或 CREATE TABLE，並自動生成嵌入。接著，代理會將這些陳述式設為 Dataform operations 動作 (type: "operations")，並使用 hasOutput: true，讓下游管道節點能透過 ${ref("RESOURCE_NAME")} 參照這些陳述式。代理只會在已啟用自主嵌入生成功能的資料表上，使用 AI.SEARCH 函式。

使用 ObjectRef 函式時，使用者也必須具備基礎 Cloud Storage bucket 的委派存取權。詳情請參閱「委派存取權」。

如要進一步瞭解 BigQuery 的 AI 和機器學習函式，請參閱「BigQuery AI 簡介」。

用途

如要在資料管道中啟用支援的 AI 和機器學習函式，請按照下列方式使用：

• 提示資料工程代理建構或修改管道。舉例來說，如果您是資料工程師，正在建構排定的 ELT 管道，用於充實原始文字、從非結構化文件中擷取結構化欄位，或為新記錄評分，代理就會生成適當的 Dataform SQLX 檔案和依附元件圖。

• 在代理程式指令檔案 (GEMINI.MD) 中定義永久管道規則，例如在組織的管道中標準化模型端點、連線 ID 或預設異常門檻。

下表列出一些提示範例，可啟用 AI 或機器學習功能，用於批次資料管道：

用途	用法示範	公開資料集
批次文字摘要 (AI.GENERATE)	「從 bigquery-public-data.bbc_news.fulltext 建立『體育』文章的暫存資料表，並新增一個資料欄，用 1 到 2 句話總結內文欄。」	bigquery-public-data.bbc_news.fulltext
結構化結構定義擷取 (AI.GENERATE_TABLE)	「建立管道資料表，從 bigquery-public-data.bbc_news.fulltext 中商業文章的 body 欄擷取結構化結構定義 (company_name STRING、key_topic STRING、is_earnings_related BOOL)。」	bigquery-public-data.bbc_news.fulltext
多模態物件充實 (OBJ.GET_ACCESS_URL)	「在 Cloud Storage 產品圖片 bucket 建立外部物件資料表，並建構下游資料表，使用 OBJ.GET_ACCESS_URL 為每張圖片生成 image_description 和實體陣列。」	Cloud Storage 物件資料表 (例如 gs://cloud-samples-data/bigquery/tutorials/cymbal-pets/images/*.png)
語意資料篩選 (AI.IF)	「建立一份整理過的表格，列出 bigquery-public-data.bbc_news.fulltext 的科技文章，並篩選出討論人工智慧突破的資料列。」	bigquery-public-data.bbc_news.fulltext
批次情緒評分 (AI.SCORE)	「請根據 bigquery-public-data.bbc_news.fulltext 建立娛樂類別的擴充表格，並加入數值 sentiment_score 欄，評估正面情緒的程度。」	bigquery-public-data.bbc_news.fulltext
自動分類 (AI.CLASSIFY)	「使用 bigquery-public-data.imdb.reviews 中的電影評論，自動將每則評論分類到我們的編輯分類層級，包括敘事原型 (例如『角色研究』、『動作奇觀』、『心理驚悚』) 和觀看心情 (例如『黑暗與寫實』、『振奮人心』、『懸疑』)。將結果和電影中繼資料寫入精選資料表。」	bigquery-public-data.imdb.reviews
分組語意匯總 (AI.AGG)	「針對 bigquery-public-data.imdb.reviews 中的每部電影，彙整數百則評論中的所有觀眾意見回饋，並統整成內容提要，重點列出一致的評論、最受好評的部分，以及觀眾經常抱怨的問題。依 movie_id 和 title 將結果分組，並加入總評論數和平均評分等指標，為製片公司高階主管和行銷團隊製作統一的電影層級情報表。」	bigquery-public-data.imdb.reviews
批次生成嵌入 (AI.GENERATE_EMBEDDING)	「建立管道節點，為 bigquery-public-data.imdb.reviews 中的評論資料欄生成向量嵌入，並將其具體化為特徵資料表。」	bigquery-public-data.imdb.reviews
自主嵌入和語意搜尋 (AI.EMBED、AI.SEARCH)	建立電影評論資料表，並在評論資料欄啟用自主嵌入生成功能，然後建立下游報表表格，找出與「緊張刺激的心理驚悚片」最相符的前 10 則評論。	bigquery-public-data.imdb.reviews
排定需求預測 (AI.FORECAST)	「建立每日報表表格，預測從 bigquery-public-data.san_francisco_bikeshare.bikeshare_trips起未來 30 天內，每天的共享單車行程數量。」	bigquery-public-data.san_francisco_bikeshare.bikeshare_trips
管道異常偵測 (AI.DETECT_ANOMALIES)	「建立監控資料表，以 2017 年做為 bigquery-public-data.san_francisco_bikeshare.bikeshare_trips 的歷來基準，偵測 2018 年的每日行程量異常狀況。」	bigquery-public-data.san_francisco_bikeshare.bikeshare_trips
自動產生主要驅動因素報表 (AI.KEY_DRIVERS)	「使用 bigquery-public-data.austin_bikeshare.bikeshare_trips 建立報表表格，找出 2017 年至 2018 年間行程量變化的主要原因。」	bigquery-public-data.austin_bikeshare.bikeshare_trips
變化點偵測 (ML.DETECT_CHANGE_POINTS)	「建立表格，偵測 bigquery-public-data.san_francisco_bikeshare.bikeshare_trips 每日行程量的結構性變化點。」	bigquery-public-data.san_francisco_bikeshare.bikeshare_trips
模型訓練，包含預先處理、評估和批次評分 (CREATE MODEL、TRANSFORM、ML.EVALUATE、ML.PREDICT)	「在 bigquery-public-data.ml_datasets.census_adult_income 建立 Dataform 管道，使用 TRANSFORM 子句訓練邏輯迴歸模型來預測 income_bracket、在評估表中評估模型，並將批次預測結果輸出至評分表。」	bigquery-public-data.ml_datasets.census_adult_income
客戶區隔 (CREATE MODEL搭配KMEANS)	「建立管道，根據 bigquery-public-data.ml_datasets.penguins 的企鵝身體測量資料訓練 K-means 分群模型，並將叢集 ID 指派給分群輸出資料表。」	bigquery-public-data.ml_datasets.penguins
自動化資料偏移驗證 (ML.VALIDATE_DATA_DRIFT)	「在管道中新增監控資料表，驗證 2017 年基準行程資料表和 2018 年 bigquery-public-data.san_francisco_bikeshare.bikeshare_trips 服務行程資料表之間的特徵偏移。」	bigquery-public-data.san_francisco_bikeshare.bikeshare_trips

提示範例

下列各節提供提示範例，可與 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.

在管道中充實非結構化資料，並執行批次機器學習預測

這則提示說明如何透過鏈結的 Dataform 管道節點，結合行為特徵工程、BigQuery ML 分類模型和生成式 AI 個人化功能：

  Create a multi-step Dataform pipeline using
  bigquery-public-data.thelook_ecommerce.users and bigquery-public-data.thelook_ecommerce.orders:

  1. Create a staging table on a sample of customers to engineer retention
     features (tenure, lifetime spend, recency) and label churn based on
     inactivity over the past 90 days.
  2. Train a BigQuery ML logistic regression model on those behavioral features
     to predict churn risk.
  3. Create a final table that scores customer churn probabilities and drafts
     personalized, 3-sentence win-back emails with purchase-tailored discounts
     for the 20 customers at highest risk of churning.

最佳做法

如要提升 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).