資料工程代理總覽

資料工程代理可讓您使用自然語言提示，在 BigQuery 中建構、修改及排解資料管道問題。資料工程代理程式提供下列功能，可簡化資料工程工作流程，將資料擷取至 BigQuery：

  • Dataform 整合：代理程式會直接在 Dataform 存放區和工作區中，產生及整理資料管道程式碼
  • 生成計畫：代理程式會總結思考過程並生成計畫，供您查看及驗證，再繼續後續步驟
  • 程式碼驗證：代理程式會自動驗證並修正任何生成的程式碼編譯錯誤，確保資料管道正常運作
  • 自動資料整理：代理程式會執行資料整理作業，並將原始資料轉換為結構化表格，無須手動操作。
  • 自訂指令：代理程式支援自訂代理程式指令，可讓您以自然語言定義特定規則和可重複使用的指南
  • 外部脈絡：代理程式已與 Knowledge Catalog 整合，可提供額外脈絡
  • 管道控制：您可以先查看及自訂產生的代理計畫，再執行任何動作。
  • 最佳化：代理程式可最佳化資料管道的效能
  • 疑難排解及修復：代理程式可以排解管道故障問題，並修正程式碼。
  • 互動式建議：代理會在對話開始時和過程中，根據情境提供互動式建議。

Data Engineering Agent 的適用國家/地區

您可以透過下列方法使用資料工程代理程式：

資料工程代理程式如何使用您的資料

為生成更高品質的代理程式回覆，資料工程代理程式可以從 BigQuery 和 Knowledge Catalog 擷取額外資料和中繼資料，包括 BigQuery 資料表的樣本資料列，以及在 Knowledge Catalog 中產生的資料掃描剖析。代理不會使用這項資料進行訓練，只會在代理對話期間將這項資料做為額外脈絡資訊，以利提供回覆。

資料工程代理程式處理資料的位置

如要進一步瞭解 Data Engineering Agent 處理資料的位置，請參閱「Gemini in BigQuery 在何處處理您的資料」。

限制

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

  • 資料工程代理不支援下列檔案類型的自然語言指令：
    • 筆記本
    • 資料準備
  • 資料工程代理程式無法執行管道。您必須查看並執行或排定管道。
  • Data Engineering Agent 無法搜尋透過指令或直接提示提供的任何網頁連結或網址。
  • 在代理程式指令檔案中匯入檔案時，@ 匯入語法僅支援以 ./、/ 或字母開頭的路徑。
  • 資料預覽功能僅支援 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 目錄端點概念」。

AI 代理功能和自訂項目

以下各節說明其他代理程式功能，以及自訂資料工程代理程式的其他方法。

代理指令

代理程式指令是自然語言指令，可供資料工程代理程式儲存持續性指令，讓代理程式遵循一組自訂的預先定義規則。如要確保整個機構的代理程式結果一致 (例如命名慣例)，或強制執行樣式指南，請使用代理程式指令。

如要為資料工程代理建立代理指令，請建立GEMINI.MD內容檔案做為代理指令檔案。

代理程式指令檔案最佳做法

使用代理程式指令時，建議您採取下列做法：

  • Dataform 中的所有檔案路徑都是相對於存放區根目錄。請為所有 @file.md 語法使用相對路徑，以便將指令正確匯入 GEMINI.md。
  • 在 GEMINI.md 中匯入的檔案本身可能含有匯入項目，進而建立巢狀結構。為避免無限遞迴，GEMINI.md 的匯入深度上限為五層。
  • 如要在資料管道之間共用指令，請將指令儲存在中央 Dataform 存放區，並連結至工作 Dataform 存放區。您可以使用本機指令，覆寫管道特定行為的中央規則。
  • 為確保專案的一致性，您可以連結命名慣例檔案或樣式指南，並指示代理程式在處理資料管道時遵循這些指南。
  • 您可以在指令檔案中建議資料層，將不同類型的資料分組在一起。
  • 在代理程式指令檔案中使用標題和清單，有助於整理及釐清資料工程代理程式的指令。
  • 提供有意義的檔案名稱，並將類似的指令歸類在同一個檔案中。 使用 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 檔案。詳情請參閱「記憶體匯入處理器」。

自動資料整理

您可以運用資料工程代理程式，將未經處理的原始資料轉換為適合資料分析的結構化表格。應要求時，代理程式會先從每個標準或外部資料表取樣最多 1,000,000 筆記錄。接著，代理程式會對這個樣本執行剖析查詢，進行深入的資料分析。產生資料轉換後，代理程式會重複執行取樣和剖析程序，評估轉換品質。這些資料整理轉換作業可能包括修正資料不一致、離群值或型別不符的問題。接著，資料工程師代理程式會建立計畫，列出建議的資料整合作業步驟，供您在執行任何動作前查看及修正。

每當您新增原始表格 (例如以 CSV 為基礎的外部表格) 時，資料工程代理程式也會啟動資料整理分析。您可以查看資料重整計畫，並使用對話指令進行調整。

資料取樣和剖析會使用 BigQuery 資源，並適用 BigQuery 定價。

資料工程代理支援下列資料整理轉換：

  • 資料清理。代理程式可以分析原始資料，並建議清理機會，例如移除離群值、填補遺漏或不一致的值 (資料插補)、修正重複資料，或標準化資料格式 (例如電話號碼或地址)
  • 結構轉換。提供目標結構定義後，代理程式可以取消巢狀結構或從 JSON、ARRAY 或 STRUCT 型別中擷取值；將多個資料欄合併為一個；或將一個資料欄分割為多個資料欄
  • 偵測及轉換資料類型。代理程式可以分析資料，判斷適當的欄位類型。接著，代理程式可以執行安全型別轉換，解決日期、時間、日期時間或時間戳記欄位中的格式不一致問題。
  • 單位換算。代理程式可自動將欄位中的各種單位轉換為一致的單位，讓資料標準化。

為確保準確度，代理程式會使用具代表性的資料樣本來偵測問題，並驗證轉換邏輯。

生成及檢查代理程式計畫

資料工程代理程式可以生成代理程式計畫，其中會提供目標摘要和概覽，以及完成要求的步驟。如果提示代理程式執行複雜要求，需要進行許多變更，建議先要求代理程式提供代理程式計畫，以便在代理程式採取任何行動前，先審查其意圖。資料工程代理計畫通常包含下列項目：

  • 代理程式對特定要求的目標
  • 代理程式預計採取的步驟概略總覽
  • 代理做出的任何假設
  • 代理程式計畫修改的檔案
  • 計畫執行的任何最佳化或清理步驟
  • 分階段執行計畫

在提示中，您可以要求先檢查並核准計畫，這樣一來，未經您明確核准，AI 代理程式就不會採取任何行動。例如：

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 中的內容

Data Engineering Agent 會將詞彙表字詞附加至 BigQuery 資料表和資料欄，並產生資料剖析掃描作業，藉此使用 Knowledge Catalog。詞彙表字詞可標記需要額外脈絡的資料欄，例如含有個人識別資訊 (PII) 的資料欄 (需要特殊處理指示)，或識別不同資料表中的相符資料欄 (名稱不同)。

Knowledge Catalog 也會運用資料剖析，讓代理程式進一步瞭解資料表欄中的資料分布情形，並建立更具體的資料品質斷言。

此外，代理程式也可以使用 Knowledge Catalog 探索及查詢 Apache Iceberg 資料表。詳情請參閱「透過 Apache Iceberg 資料表建立管道」。

在現有資料表中新增資料品質檢查

提示代理程式新增品質檢查時，代理程式會根據結構定義和樣本，推斷出合理的表格檢查。您也可以在提示中加入主觀的斷言。例如：

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

最佳化資料 pipeline

您可以提示代理程式最佳化資料管道。產生新資料表的 DDL 時，資料工程代理程式會根據分析的數據用量模式，建議分區和叢集。此外，代理程式可以自動套用其他管道最佳化設定。可能的最佳化範例如下：

  • 減少從儲存空間讀取的資料量，以降低主要成本並提升效能。
  • 述詞下推，可在執行計畫中提早篩選資料，大幅減少後續作業處理的資料量。
  • 找出並計算共用的轉換邏輯一次，即可消除常見的子運算式，提升效率，避免多次掃描及聯結大型資料表等效率不彰的做法。
  • 增量模型，只處理上次執行後新增或變更的資料，而不是在每次執行時重建整個資料表。

透過 Apache Iceberg 資料表建立管道

Data Engineering Agent 支援透過 Lakehouse 執行階段目錄 (舊稱 BigLake metastore) 管理的 Apache Iceberg 資料表，產生及編譯 Dataform 管道。這項功能可讓您直接查詢及彙整區域開放原始碼格式資料表 (儲存在 Cloud Storage 中)，以及 BigQuery 資料表。詳情請參閱「Apache Iceberg REST 目錄端點概念」。

舉例來說，您可以提示代理程式查詢 Lakehouse 執行階段目錄中的 Apache Iceberg 資料表：

Include the stackoverflow_post_history_iceberg table in this pipeline.

在提示中，您不需要指定完整的四部分路徑，例如 project.catalog.dataset.table。您可以使用標準自然語言名稱或邏輯 ID 參照 Apache Iceberg 資料表，例如 the StackOverflow post history table 或 post_history。代理程式會使用 Knowledge Catalog 自動叫用語意目錄搜尋，將正確的 Apache Iceberg 資料表解析並繫結至管道工作區。

如要使用這項功能，Dataform 存放區必須使用 Dataform Core 3.0.33 以上版本。

互動式建議

資料工程代理會分析工作區編譯狀態、執行記錄和有效對話狀態，直接在對話介面中提供可做為行動依據的最佳化建議。開啟工作區時，系統會自動顯示這些建議，並在整個工作階段中提供設定、疑難排解和最佳化建議，引導您完成工作流程。

如要使用建議，請按一下「AI 建議」下方的其中一項建議，系統會將提示載入聊天輸入列，您可以在傳送給服務專員前編輯或自訂提示。你也可以將游標懸停在建議上，查看確切的提示。

最佳做法

為提升使用資料工程代理程式和 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).