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

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

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

如要查看更多可搭配資料工程代理程式使用的提示範例，請參閱「提示範例」。

限制

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

• 資料工程代理不支援下列檔案類型的自然語言指令：
  • 筆記本
  • 資料準備
  • 任何 SQLX 中的 JavaScript
• 資料工程代理程式無法執行管道。您必須查看並執行或排定管道。
• 如果 SQL 依附於不存在的中介資源，且沒有完整管道叫用 (使用者觸發)，資料工程代理程式就無法驗證 SQL。
• Data Engineering Agent 無法搜尋透過指令或直接提示提供的任何網頁連結或網址。
• 在代理程式指令檔案中匯入檔案時，@匯入語法僅支援以 ./、/ 或字母開頭的路徑。
• 資料預覽功能僅支援 hasOutput 旗標設為 true 的資料表、宣告或查詢。
• Data Engineering Agent 須遵守一般 AI 技術限制。

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

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

Data Engineering Agent 處理資料的位置

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

事前準備

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

啟用 Gemini in BigQuery

確認已為Cloud de Confiance by S3NS 專案啟用 Gemini in BigQuery。詳情請參閱「設定 Gemini in BigQuery」。

啟用必用的 API。

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

必要的角色

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

• Dataform 程式碼編輯器 (roles/dataform.codeEditor)
• BigQuery 工作使用者 (roles/bigquery.jobuser)
• Gemini Data Analytics 無狀態對話使用者 (roles/geminidataanalytics.dataAgentStatelessUser)

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

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

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

整合 Knowledge Catalog 的先決條件

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

這個預先定義的角色具備 geminidataanalytics.locations.useDataEngineeringAgent 權限，可將 Data Engineering Agent 與 Knowledge Catalog 整合。

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

您也必須啟用 Knowledge Catalog API。

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

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

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

設定 VPC Service Controls 範圍

如果您使用 VPC Service Controls，必須設定 perimeter 來保護 Dataform、BigQuery 和對話式數據分析 API。詳情請參閱 Dataform、BigQuery 和 對話式數據分析 API。

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

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

編輯資料管道

如要編輯資料管道，請點選「詢問代理程式」，然後輸入提示，建議變更資料管道。

檢查資料工程師代理程式建議的變更，然後按一下「套用」套用變更。

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

查看資料管道

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

• 「設定」分頁會顯示與節點相關聯的產生 SQLX 查詢。
• 「資料預覽」分頁會顯示檔案的輸入和輸出資料表。您可以點選「執行工作」，執行工作 (含或不含依附元件)，透過這個節點預覽資料轉換。

排解資料管道錯誤

如果在生成資料管道時發生任何錯誤，請確認您已完成執行資料工程代理程式的所有必要條件。詳情請參閱「事前準備」一節。

執行 Gemini Cloud Assist 調查

如要進一步排解管道問題，可以使用 Data Engineering Agent 執行根本原因分析，並取得排解問題的建議。

這項功能會使用 Gemini Cloud Assist 調查 (預先發布版)，且僅適用於簽訂Premium 支援服務合約的使用者。如要進一步瞭解如何啟用 Gemini Cloud Assist 調查功能，請參閱「排解 Gemini Cloud Assist 調查功能的問題」。

您可以按照下列步驟，使用資料工程代理程式排解資料管道錯誤：

1. 在管道或開發工作區中，按一下「執行」分頁標籤。

2. 在執行作業清單中，找出失敗的資料管道執行作業。您可以在「狀態」欄中找出失敗的執行作業。

   

3. 將游標懸停在圖示上，然後按一下「調查」。資料工程代理程式會對資料管道執行錯誤的根本原因分析 (RCA)。

   

4. 分析完成後，資料工程代理會在「Observations and Hypothesis」部分產生報告。這份報表包含：

   • 從資料管道執行記錄擷取的觀察結果和資料點。
   • 可能導致失敗的原因。
   • 解決已識別問題的一系列實用步驟或建議。

您可以根據資料工程代理程式的疑難排解報告，手動實作建議。您也可以按照下列步驟，指示資料工程代理程式為您套用修正：

1. 複製疑難排解報告中的建議。
2. 返回 Data Engineering Agent：
   1. 如果您使用 BigQuery 管道，請前往管道頁面，然後按一下「詢問專員」。
   2. 如果您使用 Dataform，請按一下「詢問專員」。
3. 將建議貼到提示中，然後指示資料工程師代理程式直接修正資料管道。
4. 按一下 [傳送]。

其他 AI 專員功能和自訂選項

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

建立代理指令

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

您可以建立 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. 在「外部存放區」下方，選取「使用外部存放區中的指示」。
3. 在提供的欄位中，指定包含要與資料管道搭配使用的代理程式指令的存放區。
4. 按一下 [儲存]。

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

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

自動資料整理

您可以運用 Data Engineering Agent，將未經處理的原始資料轉換為適合資料分析的結構化表格。如果提出要求，代理程式會先從每個標準或外部資料表取樣最多 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) 的資料欄需要特殊處理指示，或是識別不同資料表中的相符資料欄。

知識目錄也會運用資料剖析，讓代理程式更瞭解資料表欄中的資料分布情形，並協助代理程式建立更明確的資料品質斷言。

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

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

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

最佳化資料 pipeline

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

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

提示範例

以下各節提供範例提示，可用於 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，建立使用者定義函式 (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 時的成效，建議您採取下列做法：

針對常見要求使用代理程式指令。如果你經常使用特定技巧，或是經常對代理程式進行相同修正，請使用代理程式指令集中儲存常見指令和要求。

善用代理計畫。代理計畫有助於分解複雜的管道工作。代理程式計畫也會顯示代理程式的假設和意圖，因此建議您檢查這些計畫，確保代理程式獲得正確的脈絡資訊。

查看企劃書後，您可以向資料工程代理程式提供意見和變更，藉此編輯企劃書。例如：

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

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

建立代理指令檔案，自訂資料工程代理，滿足您的需求。使用代理程式指令時，建議您採取下列做法：

• 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