Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

資料工程代理總覽

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

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

Data Engineering Agent 的適用國家/地區

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

從 BigQuery 管道介面或 Dataform 建立資料管道。
在 Visual Studio Code 中安裝 Google Cloud Data Agent Kit 擴充功能，即可從整合式開發環境 (IDE) 建構資料管道。
使用 Data Engineering Agent API。

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

為生成更高品質的代理程式回覆，資料工程代理程式可以從 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

匯入其他本機檔案做為代理程式指令

您也可以將其他資料工程師代理程式的指令檔案匯入 GEMINI.md 檔案，並使用 @file.md 語法。詳情請參閱「記憶體匯入處理器」。

自動資料整理

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

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

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

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

資料清理。代理程式可以分析原始資料，並建議清理機會，例如移除離群值、填補遺漏或不一致的值 (資料插補)、修正重複資料，或標準化資料格式 (例如電話號碼或地址)
結構轉換。提供目標結構定義後，代理程式可以取消巢狀結構或從 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 Core 3.0.37 以上版本。
一般切面：語意詳細資料，例如資料表系統和類型資訊。必須使用 Dataform Core 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 中搜尋資產。詳情請參閱「搜尋資源」。

最佳化資料 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).

評估資料管道

如要評估資料工程代理生成的資料管道成效，請使用 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 管理員 (roles/dataform.admin)
BigQuery 資料編輯者 (roles/bigquery.dataEditor)
BigQuery 工作使用者 (roles/bigquery.jobUser)
將評估結果匯出為 ZIP 封裝檔： Storage 物件管理員 (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：專案的 ID。 Google Cloud
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}
...