Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

データエンジニアリングエージェントの概要

Data Engineering Agent を使用すると、自然言語プロンプトを使用して BigQuery でデータパイプラインを構築、変更、トラブルシューティングできます。Data Engineering Agent には、BigQuery にデータを取り込むためのデータエンジニアリングワークフローを効率化する次の機能が用意されています。

Dataform の統合: エージェントは、Dataform リポジトリとワークスペース内でデータパイプラインコードを直接生成して整理します。
プランの生成: エージェントは、思考を要約してプランを生成できます。これにより、続行する前にエージェントのプランを確認して検証できます。
コードの検証: エージェントは、生成されたコードのコンパイルエラーを自動的に検証して修正し、データパイプラインが機能していることを確認します。
自動データラングリング: エージェントはデータラングリングを実行し、手動介入なしで元データを構造化テーブルに変換します。
カスタム指示: エージェントは、特定のルールと再利用可能なガイドラインを自然言語で定義できるカスタムエージェント指示をサポートしています。
外部コンテキスト: エージェントは、追加のコンテキストのために Knowledge Catalog と統合されています。
パイプライン制御: 生成されたエージェントプランを確認してカスタマイズしてから、アクションを実行できます。
最適化: エージェントはデータパイプラインのパフォーマンスを最適化できます。
トラブルシューティングと修復: エージェントは、パイプラインの失敗のトラブルシューティングとコードの修正を行うことができます。
インタラクティブな推奨事項: エージェントは、セッションの開始時とセッション全体を通じて、インタラクティブでコンテキストを考慮した推奨事項を提供します。
Knowledge Catalog メタデータの拡充: エージェントは、テーブル構成から Knowledge Catalog メタデータを自動的に生成し、パイプラインの実行中にメタデータを Knowledge Catalog に送信できます。

Data Engineering Agent を使用できる場所

Data Engineering Agent は、次の方法で使用できます。

BigQuery パイプラインインターフェースまたは Dataform でデータパイプラインを構築する。
Visual Studio Code に Google Cloud Data Agent Kit 拡張機能をインストールして、統合開発環境（IDE）からデータパイプラインを構築します。
Data Engineering Agent API を使用する。

Data Engineering Agent によるデータの使用方法

Data Engineering Agent は、より高品質なエージェントレスポンスを生成するために、BigQuery テーブルのサンプル行や Knowledge Catalog で生成されたデータスキャンプロファイルなど、BigQuery と Knowledge Catalog から追加のデータとメタデータを取得できます。エージェントはこのデータをトレーニングに使用しません。エージェントの会話中にのみ、回答を通知するための追加のコンテキストとして使用します。

Data Engineering Agent がデータを処理する場所

Data Engineering Agent がデータを処理するロケーションの詳細については、Gemini in BigQuery がデータを処理する場所をご覧ください。

制限事項

Data Engineering Agent には次の制限があります。

Data Engineering Agent は、次のファイル形式の自然言語コマンドをサポートしていません。
- ノートブック
- データの準備
Data Engineering Agent はパイプラインを実行できません。パイプラインを確認して実行するか、スケジュールを設定する必要があります。
Data Engineering Agent は、手順や直接プロンプトで提供されたウェブリンクや URL を検索できません。
エージェント指示ファイルでファイルをインポートする場合、@ インポート構文は、./、/、または文字で始まるパスのみをサポートします。
データプレビュー機能は、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 をカスタマイズするその他の方法について説明します。

エージェントへの指示

エージェントへの指示は、Data Engineering Agent に対する自然言語の指示です。この指示を使用すると、永続的な指示を保存して、エージェントがカスタムの事前定義された一連のルールに従うようにできます。組織全体でエージェントの結果を統一したい場合（命名規則やスタイルガイドの適用など）は、エージェントへの指示を使用します。

Data Engineering Agent のエージェント指示を作成するには、エージェント指示ファイルとして GEMINI.MD コンテキストファイルを作成します。

エージェント指示ファイルに関するベストプラクティス

エージェントへの指示を使用する場合は、次のことをおすすめします。

Dataform のすべてのファイルパスは、リポジトリのルートからの相対パスです。@file.md 構文には相対パスを使用して、GEMINI.md に指示を正しくインポートします。
GEMINI.md でインポートされたファイル自体にインポートを含めることができ、ネストされた構造を作成できます。無限再帰を防ぐため、GEMINI.md の最大インポート深度は 5 レベルになっています。
データパイプライン間で指示を共有するには、指示を一元的な Dataform リポジトリに保存し、作業用の Dataform リポジトリにリンクします。ローカル指示を使用すると、パイプライン固有の動作に対して中央のルールをオーバーライドできます。
プロジェクトの一貫性を確保するには、命名規則ファイルやスタイルガイドにリンクし、データパイプラインを操作する際にこれらのガイドラインに従うようエージェントに指示します。
指示ファイルでデータレイヤを提案して、さまざまな種類のデータをグループ化できます。
エージェントの指示ファイルで見出しとリストを使用すると、Data Engineering Agent に対して指示を整理し、明確にすることができます。
わかりやすいファイル名を付け、類似した手順を 1 つのファイルにまとめます。Markdown の見出しを使用して、カテゴリや機能ごとにルールを論理的に整理します。
指示の競合を避けるため、各指示が適用される特定の条件を明確に定義します。
プロンプトとワークフローを繰り返し調整します。エージェントの動作は、エージェントのロールアウトとモデルのアップグレードによって時間の経過とともに変化するため、さまざまなプロンプトを使用してルールを繰り返しテストし、改善が必要な領域を特定することをおすすめします。ルールファイルは、データパイプラインの変更と同期させてください。

次の例は、Data Engineering Agent を効果的に使用するためのベストプラクティスを活用する、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 構文を使用して、Data Engineering Agent の他の指示ファイルを GEMINI.md ファイルにインポートすることもできます。詳細については、メモリインポートプロセッサをご覧ください。

自動データラングリング

Data Engineering エージェントを使用すると、未加工の未処理データをデータ分析に適した構造化テーブルに変換できます。リクエストされると、エージェントはまず、各標準テーブルまたは外部テーブルから最大 1,000,000 件のレコードをサンプリングします。エージェントは、このサンプルに対してプロファイリングクエリを実行して、詳細なデータ分析を行います。データ変換を生成した後、エージェントはこのサンプリングとプロファイリングのプロセスを繰り返して、変換の品質を評価します。これらのデータラングリング変換には、データの不整合、外れ値、型の不一致の修正などが含まれます。Data Engineering Agent は、提案されたラングリングステップの概要を示す計画を作成します。この計画は、アクションが実行される前に確認して調整できます。

Data Engineering Agent は、CSV ベースの外部テーブルなどの未加工テーブルを追加するたびに、データラングリング分析を開始します。データラングリングプランを確認し、会話型コマンドで調整できます。

データサンプリングとプロファイリングでは BigQuery リソースが使用され、BigQuery の料金が適用されます。

Data Engineering Agent は、次のデータラングリング変換をサポートしています。

データクリーニング。エージェントは、元データを分析して、外れ値の削除、欠損値や不整合値の補完（データの補完）、重複データの修正、データ形式（電話番号や住所など）の標準化など、クリーンアップの機会を提案できます。
構造変換。ターゲットスキーマが指定されている場合、エージェントは JSON、ARRAY、STRUCT 型の値のネスト解除や抽出、複数の列の 1 つへの結合、1 つの列の複数の列への分割を行うことができます。
データ型の検出と変換。エージェントはデータを分析して、適切なフィールドタイプを決定できます。エージェントは、安全な型キャストを実行して、日付、時刻、日時、タイムスタンプフィールド内の形式の不整合を解決できます。
単位の変換。エージェントは、フィールド内のさまざまな単位を 1 つの一貫した単位に自動的に変換して、データを標準化できます。

精度を確保するため、エージェントはデータの代表サンプルを使用して問題を検出し、変換ロジックを検証します。

エージェントプランを生成して確認する

Data Engineering Agent は、リクエストを完了するために必要な目標と手順の概要を提供するエージェントプランを生成できます。多くの変更を必要とする複雑なリクエストをエージェントにプロンプトする場合は、エージェントにエージェントプランを提供するように依頼することをおすすめします。これにより、エージェントがアクションを実行する前にエージェントの意図を確認できます。Data Engineering Agent プランは、通常、次の要素で構成されます。

特定のリクエストに対するエージェントの目標
エージェントが実行する予定のステップの概要
エージェントが行う前提
エージェントが変更を予定しているファイル
実行予定の最適化またはクリーニングの手順
段階的な実行プラン

プロンプトに、プランの確認と承認が必要であることを含めることで、エージェントが明示的な承認なしにアクションを実行しないようにできます。次に例を示します。

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 データスキャンによって作成されたスコアカードには影響しません。

スキーママッピングを生成する

Data Engineering Agent に、ソーススキーマとターゲットスキーマ間のスキーママッピングを生成するように指示できます。

  Create a Dataform pipeline to map the tables from schema
  SOURCE_SCHEMA to schema TARGET_SCHEMA. Give me the plan.

次のように置き換えます。

SOURCE_SCHEMA: ソーステーブルのスキーマの名前。
TARGET_SCHEMA: ターゲットテーブルのスキーマの名前。

エージェントは、次の処理を行ってプランを生成します。

アンカーテーブルの選択: 各ターゲットテーブルのプライマリソーステーブルを決定します。
結合グラフの最適化: プロパティグラフのエッジ定義に直接沿った結合パスをマッピングし、デカルト爆発と型の不一致を回避します。
フィールドレベルのギャップ分析: すべてのマッピングをマッピングタイプ（Direct、Derived、Joined、Aggregated）に分類し、NOT NULL と REQUIRED の制約の整合性を検証します。

プランを確認してマッピングロジックを確認したら、そのスキーママッピングに基づいてパイプラインを作成するようエージェントに指示できます。

BigQuery Graph でのスキーママッピング

プロジェクトに BigQuery Graph がある場合、エージェントは自動的にそれを検出して読み取り、追加のコンテキストを提供してスキーママッピングの精度を向上させます。エージェントは BigQuery Graph を読み取って、ソーステーブルとターゲットテーブル間のセマンティック関係を理解できます。これにより、より正確なマッピングを生成し、複雑なデータセットの移行や変換時にユーザーの手動介入を減らすことができます。スキーママッピングを生成するようにエージェントに指示すると、エージェントはデータセットを自動的にスキャンし、関連するグラフが存在する場合は BigQuery Graph を使用します。

BigQuery Graph の機能、エディション、料金の詳細については、BigQuery Graph の概要をご覧ください。アクセス制御と BigQuery Graph の作成の詳細については、BigQuery Graph を作成してクエリを実行するをご覧ください。

Google ドライブの統合

データエンジニアリングエージェントは、Google ドライブからファイルを読み取って読み込み、データパイプラインに含めることができます。エージェントにプロンプトを入力するときに、ドライブ上のファイルへのリンクを指定し、リクエストされたときにドライブへの OAuth アクセスをエージェントに提供します。エージェントは、提供されたファイルを読み取り、ライブドライブファイルから読み取る外部テーブルを作成し、Dataform パイプラインクエリを介してファイルを読み込むことができます。外部テーブルのドライブアクセスを有効にするには、ドライブアクセスを認証して有効にするをご覧ください。

エージェントは、ドライブ上の次のファイル形式をサポートしています。

CSV
Google スプレッドシート
JSONL（改行区切り JSON）

自動データ拡充

BigQuery の標準メタデータ（データセット、テーブル、ビューなど）は、Knowledge Catalog で自動的に使用できます。

テーブルとビューのカスタムメタデータを、.sqlx ファイルの構成ブロックで直接定義することもできます。アクションが正常に完了すると、Dataform は自動的に Knowledge Catalog へのメタデータ同期を開始します。この拡充プロセスにより、SQLX 構成で定義されたセマンティックメタデータで Knowledge Catalog が更新されます。

メタデータキーを使用して、Knowledge Catalog の情報を指定します。拡充プロセスでは、次のメタデータ構造がサポートされています。

概要: エントリのドキュメントと概要テキスト。Dataform コアバージョン 3.0.37 以降が必要です。
一般的なアスペクト: テーブルシステムやタイプ情報などのセマンティックの詳細。Dataform コアバージョン 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 でアセットを検索します。詳しくは、リソースを検索するをご覧ください。

データパイプラインの最適化

エージェントにプロンプトを入力して、データパイプラインを最適化できます。新しいテーブルの DDL を生成するときに、Data Engineering Agent は、分析されたデータ使用パターンに基づいてパーティショニングとクラスタリングを推奨します。また、エージェントは他のパイプライン最適化を自動的に適用することもできます。可能な最適化の例を次に示します。

列のプルーニング。ストレージから読み取られるデータを削減し、主な費用とパフォーマンスの要因として機能します。
述語のプッシュダウン。実行プランの早い段階でデータをフィルタリングして、後続のオペレーションで処理される量を大幅に削減します。
共通部分式の排除。共有変換ロジックを 1 回だけ識別して計算することで、効率を向上させます。これにより、大規模なテーブルを複数回スキャンして結合するなどの非効率な処理を回避できます。
実行ごとにテーブル全体を再構築するのではなく、前回の実行以降に新規または変更されたデータのみを処理する増分モデル。

Apache Iceberg テーブルにパイプラインを作成する

データエンジニアリングエージェントは、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.

プロンプトで、完全修飾された 4 つの部分からなるパス（project.catalog.dataset.table など）を指定する必要はありません。Apache Iceberg テーブルは、標準の自然言語名または論理識別子（the StackOverflow post history table や post_history など）を使用して参照できます。エージェントは、Knowledge Catalog を使用してセマンティックカタログ検索を自動的に呼び出し、正しい Apache Iceberg テーブルを解決してパイプラインワークスペースにバインドします。

この機能を使用するには、Dataform リポジトリで Dataform Core バージョン 3.0.33 以降を使用する必要があります。

インタラクティブな最適化案

データエンジニアリングエージェントは、ワークスペースのコンパイルステータス、実行履歴、アクティブな会話の状態を分析し、チャットインターフェースで直接、実用的な推奨事項を提供します。これらの提案は、ワークスペースを開いたときとセッション全体で自動的に表示され、ワークフローをガイドするための設定、トラブルシューティング、最適化に関する推奨事項を提供します。

推奨事項を使用するには、[AI の推奨事項] の下の候補のいずれかをクリックします。これにより、プロンプトがチャット入力バーに読み込まれます。エージェントに送信する前に、プロンプトを編集またはカスタマイズできます。候補にカーソルを合わせると、正確なプロンプトが表示されます。

ベストプラクティス

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 つにして、プロンプトを簡潔にします。複数の質問を含むプロンプトの場合は、次の例に示すように、質問の各部分を個別に列挙して、明確さを高めます。

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

データパイプラインを評価する

Data Engineering Agent によって生成されたデータパイプラインの有効性を評価するには、EvalBench ツールを使用します。EvalBench は、マルチターンのエージェント評価をサポートするオープンソースフレームワークです。EvalBench は自動化された単体テストスイートとして機能し、マルチターンシナリオの設定、LLM を活用した決定的スコアラーの追加、Dataform パイプラインのライフサイクルの管理を行うことができます。

EvalBench は、分離されたサンドボックスで自然言語プロンプトをシミュレートすることで、エージェントが指示を理解し、適切なツールを呼び出し、正しいパイプラインコードを生成する効果を測定します。EvalBench は、次の方法でデータパイプラインをチェックできます。

カスタムルールの検証: エージェントが組織固有のコーディングガイドライン、命名規則、ベストプラクティスに厳密に従っていることを確認します。
コードの回帰を防ぐ: デプロイ前にパイプラインの変更をテストして、エージェントの更新やスキーマの変更によって既存の機能が破損しないことを確認します。
品質ベンチマークの生成: SQL の正確性、ツール実行の精度、パイプラインの信頼性に関する客観的な自動スコアを取得します。

データパイプライン評価を実行する

EvalBench は、次の 2 つのモードで実行できます。

動的サンドボックス: EvalBench は、評価実行の開始時に新しい一時的な Dataform リポジトリとワークスペースをプロビジョニングし、テストシナリオを実行して、完了時に作成されたすべてのリソースを自動的に破棄します。このモードでは、本番環境のコード、本番環境のリポジトリ、BigQuery データセットは変更されません。また、 Google Cloud プロジェクトにアーティファクトが残ることもありません。動的サンドボックスモードは、自動化された CI / CD パイプライン、夜間の回帰テスト、厳格な環境分離が必要な客観的なベンチマークスコアリングに適しています。
静的ワークスペース: EvalBench は、ユーザーが管理する既存の Dataform リポジトリとワークスペースに接続し、自動作成スクリプトと削除スクリプトをスキップします。このモードでは、評価対象のエージェントが評価ケースを処理する際に、既存のワークスペース内で新しい SQLX ファイルを変更して作成できます。静的ワークスペースモードは、アクティブなプロンプトエンジニアリング、ルーブリックのイテレーション、ローカルデバッグに適しています。これらの作業では、実行後に Dataform ワークスペースで生成された SQLX ファイルを直接検査する必要があります。

始める前に

EvalBench の実行に必要な権限を取得するには、EvalBench を実行するサービスアカウントまたはユーザー ID に対する次の 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: Google Cloudプロジェクトの ID。
- 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}
...
```
次のコマンドを使用して EvalBench を実行します。
```
EVAL_GCP_PROJECT_ID=PROJECT_ID \
EVAL_GCP_PROJECT_REGION=REGION \
  EVAL_DEA_REPOSITORY_ID=REPOSITORY_ID \
  EVAL_DEA_WORKSPACE_ID=WORKSPACE_ID \
  .venv/bin/python3 evalbench/evalbench.py --experiment_config=datasets/dea-tools/example_run_config.yaml
```
次のように置き換えます。
- PROJECT_ID: Google Cloudプロジェクトの ID。
- REGION: Google Cloudプロジェクトのリージョン。
- REPOSITORY_ID: データパイプラインを含むリポジトリの ID。
- WORKSPACE_ID: データパイプラインを含むワークスペースの ID。
省略可: core_10_cases_suite.yaml を使用して EvalBench を実行し、各テストケースに新しいリポジトリを作成して環境を分離し、10 個のコア評価ケースに対してデータパイプラインを順次テストすることもできます。これを行うには、次のコマンドを実行します。
```
EVAL_GCP_PROJECT_ID=PROJECT_ID \
EVAL_GCP_PROJECT_REGION=REGION \
.venv/bin/python3 evalbench/evalbench.py --suite_config=datasets/dea-tools/core_10_cases_suite.yaml
```

データパイプライン評価のベストプラクティス

EvalBench を使用したデータパイプライン評価のパフォーマンスと精度を向上させるには、次のことをおすすめします。

評価ログで Dataform ワークフローの呼び出しと BigQuery ジョブ ID を探します。これらの ID を使用して、生成された実行アーティファクト、コンパイル結果、クエリログを Google Cloud コンソールで相互参照して検査します。
モデルまたはプロンプトの変更をリリースする前に、必ずコア評価スイート（--suite_config）を実行して、さまざまなデータエンジニアリングシナリオで回帰を完全にカバーします。
EVAL_DATAFORM_SETUP_ENV_FILES_DIR を使用して、workflow_settings.yaml やベーススキーマ定義などの環境設定ファイルをテストワークスペースにプリロードします。これらの設定ファイルにより、エージェントは空のワークスペースではなく、現実的な既存の環境に基づいてビルドされます。
動的サンドボックスモードで失敗した評価ケースのトラブルシューティングを行う場合は、実行構成で tear_down_script をコメントアウトして、事後分析のためにターゲットワークスペースを保持します。
クラウドコンパイルと実行検証ツール（dataform_cloud_compile、dataform_cloud_run）を LLM ベースのバイナリルーブリックと常に組み合わせて、構文エラーやランタイムエラーと高レベルのロジックエラーの両方を特定します。
BigQuery レポート（<PROJECT_ID>.evalbench.results）を有効にし、生成されたデータポータルのリンクを使用して、合格率、ツールの使用精度、プロンプトの効率を時系列で追跡します。

データ エンジニアリング エージェントの概要 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。