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

透過資料工程代理程式，您可以使用 Gemini in BigQuery 建構、修改及管理資料管道，以便在 BigQuery 中載入及處理資料。透過資料工程代理，您可以使用自然語言提示，從各種資料來源產生資料管道，或調整現有資料管道，以符合資料工程需求。資料工程代理程式提供下列功能：

  • 使用自然語言建立管道：代理程式會運用 Gemini 瞭解您的資料，並解讀您的簡單指令。您可以使用簡單易懂的指令，讓 Data Engineering Agent 建構或編輯資料管道。

  • 整合 Dataform：代理程式會生成必要的管道程式碼，並整理到 Dataform 存放區的 SQLX 檔案中。代理程式會在 Dataform 工作區中運作，因此代理程式會自動提供 Dataform 管道。

  • 自訂代理指令：以簡單易懂的語言建立代理指令，為 Data Engineering Agent 定義自訂規則。代理程式指令會在整個機構中持續生效，有助於強制執行全機構規則，例如命名慣例或樣式指南。

  • 管道驗證：代理程式會驗證所有產生的程式碼，確保資料管道正常運作。

您可以搭配使用自然語言提示和 Data Engineering Agent，建立資料表、檢視區塊、判斷提示、宣告和作業 SQLX 檔案。舉例來說，您可以使用資料工程代理程式執行下列操作：

  • 從外部資料來源 (例如 Cloud Storage) 載入各種格式的資料，例如 CSV、AVRO 或 PARQUET。
  • 建立或使用現有的 BigQuery 常式 (使用者定義函式)，對資料執行自訂分析和轉換。
  • 以自然語言為代理程式定義可重複使用的規範。

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

限制

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

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

支援的地區

Gemini in BigQuery 使用 Google Cloud負載平衡，因此可在全球運作。由於 BigQuery 中的 Gemini 是全球服務，因此無法選擇要使用的區域。

所有 Dataform 和 BigQuery 要求都會傳送至各自的區域端點，因此所有資料和程式碼都會保留在所屬區域。

Gemini in BigQuery 服務的提供區域如下：

美洲

  • 愛荷華州 (us-central1)

歐洲

  • 芬蘭 (europe-north1)
  • 法蘭克福 (europe-west3)

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

為生成更高品質的代理程式回覆，資料工程代理程式可以從 BigQuery 和 Dataplex Universal Catalog 擷取額外資料和中繼資料，包括 BigQuery 資料表的樣本資料列，以及在 Dataplex Universal Catalog 中產生的資料掃描設定檔。這類資料不會用於訓練資料工程代理程式，只會在代理程式對話期間做為額外背景資訊，協助代理程式生成回覆。

事前準備

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

您也必須啟用 Gemini Data Analytics API。

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

必要的角色

如要取得使用資料工程代理程式所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

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

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

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

如要在 BigQuery 中使用資料工程代理程式，請選取下列任一選項：

BigQuery 管道

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

  1. 前往「BigQuery」頁面

    前往「BigQuery」

  2. 在查詢編輯器中，依序點選「arrow_drop_down」arrow_drop_down>「建立新項目」>「管線」。

  3. 選取執行憑證的選項，然後按一下「開始使用」。這些憑證不會由代理程式使用，但您必須提供這些憑證，才能執行產生的資料 pipeline。

  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.

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

  6. 資料工程代理程式會根據提示生成資料管道。

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

對資料管道套用資料工程代理建議的變更。

Dataform

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

  1. 前往「Dataform」頁面。

    前往 Dataform

  2. 選取存放區。

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

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

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

      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.

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

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

查看資料管道

在 Data Engineering Agent 生成的資料管道中，您可以點選管道節點進行檢查。

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

編輯資料管道

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

按一下「Ask Agent」，在資料管道上使用資料工程代理程式。

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

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

為資料工程師代理建立代理程式指令

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

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

請按照下列步驟建立代理程式指令：

  1. 在「詢問服務專員」下方，按一下「管道操作說明」。
  2. 在「管道操作說明」窗格中，按一下「建立操作說明檔案」。

  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. 在管道或開發工作區中，按一下「執行」分頁標籤。

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

    在管道的狀態欄中，找出執行失敗的作業。

  3. 將滑鼠游標懸停在圖示上，然後按一下「調查」。資料工程師虛擬服務專員會分析資料管道執行作業，找出任何錯誤。

    提示資料工程代理診斷管道錯誤。

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

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

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

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

提示範例

以下各節會顯示一些範例提示，您可以使用這些提示搭配資料工程代理程式，開發資料管道。

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

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

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

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

有了這項提示，代理程式會根據結構定義和樣本，推斷出合理的資料表品質檢查。您也可以在提示中加入一些主觀的斷言。

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

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

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

  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.

最佳做法

以下各節將說明使用 Data Engineering Agent 和 Dataform 的最佳做法。

使用資料工程代理程式的最佳做法

針對常見要求使用代理程式指令。如果您經常使用某些技巧，或是經常對代理程式進行相同的修正，請將代理程式指令做為集中儲存常見指令和要求的中心位置。

提供更多背景資訊給服務專員。您可以將詞彙表字詞附加至 BigQuery 資料表和資料欄，並產生資料剖析掃描作業，為代理程式提供 Dataplex Universal Catalog 的額外背景資訊。詞彙表中的字詞可用於標記需要額外脈絡的資料欄，例如含有個人識別資訊 (PII) 的資料欄需要特殊處理指示，或是識別不同資料表中的相符資料欄。資料剖析掃描作業可讓代理更瞭解資料表資料欄中的資料分布情形，並協助代理建立更明確的資料品質斷言。詳情請參閱「關於資料剖析」。

清楚撰寫內容。清楚說明要求，避免含糊不清。盡可能在提示中提供來源和目的地資料來源，如下例所示：

  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