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 エージェントをカスタマイズするための追加のエージェント機能とその他の方法について説明します。

エージェントへの指示

エージェントへの指示は、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 プランは次の要素で構成されます。

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

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

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.

パイプラインの実行中に、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 グラフを使用します。

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

データの自動拡充

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

.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 テーブル上にパイプラインを作成する

Data Engineering エージェントは、Lakehouse ランタイムカタログ（旧称 BigLake metastore）で管理される Apache Iceberg テーブルに対する Dataform パイプラインの生成とコンパイルをサポートしています。この機能を使用すると、BigQuery テーブルとともに、リージョンオープンソース形式のテーブル（Cloud Storage に保存）を直接クエリして結合できます。詳細については、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 以降を使用する必要があります。

インタラクティブな推奨事項

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

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

ベストプラクティス

Data Engineering Agent と Dataform を使用する際のパフォーマンスを改善するには、次の操作を行うことをおすすめします。

一般的なリクエストにはエージェントへの指示を活用する。よく使用する手法がある場合や、エージェントに同じ修正を頻繁に加える場合は、エージェントへの指示を共通の手順やリクエストを保存する一元的な場所として使用します。

エージェントプランを活用します。エージェントプランは、複雑なパイプラインタスクを分解するのに役立ちます。エージェントプランには、エージェントの想定と意図も表示されます。エージェントに正しいコンテキストが提供されていることを確認するため、これらのプランを確認することをおすすめします。

プランを確認した後、フィードバックと変更を Data Engineering エージェントにプロンプトで送信して、プランを編集できます。次に例を示します。

In the plan, ensure that all of the intermediate tables are views.

場合によっては、明示的な承認を必要としないプランをエージェントに生成してもらうと便利です。エージェントに計画を立てさせることで、Data Engineering エージェントはアクションを分解する必要があり、多くの場合、より良い結果につながります。エージェントにプランの生成と自動実行を強制できます。次に例を示します。

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）を有効にして、生成されたデータポータルリンクを使用して、合格率、ツールの使用精度、プロンプトの効率を長期にわたって追跡します。

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