Gemini CLI エージェントを使用してデータ コンテキストをテストする

AI エージェントは推論できますが、特定の企業に関する知識はゼロから始まります。エージェントに「第 1 四半期の収益は？」と質問することを考えてみましょう。ガイダンスがないと、エージェントはデータベース内の「収益」という名前の数十個のテーブル（公式レポートから雑然としたテストデータまで）から選択する可能性があります。エージェントが最も近い名前のテーブルを選択した場合、未確認のソースに基づいて説得力のある誤った回答を返す可能性があります。

このコンテキストの問題を解決するのがメタデータの拡充です。このチュートリアルでは、このコンテキストを提供するアスペクトを設定し、Gemini CLI を使用してデータ コンテキストをテストし、エージェントが信頼できる認定データに基づいて回答を正確にグラウンディングできることを確認します。

目標

  • テスト用の現実的なデータレイクを作成する。
  • Knowledge Catalog のアスペクトを使用して、「ゴールド」データにラベルを付け、テストデータと区別します。
  • Gemini CLI を使用してデータ コンテキストをローカルでテストします。

始める前に

始める前に、次の操作を行ってください。

このチュートリアルを完了するには、BigQuery、ナレッジ カタログ、Terraform の基本的な知識も必要です。

環境を準備する

このチュートリアルでは、クラウドで実行されるコマンドライン環境である Google Cloud Shell を使用します。

  1. Google Cloud コンソールで、右上のツールバーにある [Cloud Shell をアクティブにする] をクリックします。環境がプロビジョニングされ、接続されるまでしばらく待ちます。

  2. Cloud Shell で PROJECT_ID 変数と REGION 変数を設定して、以降のすべてのコマンドが特定の Google Cloud プロジェクトをターゲットとするようにします。

    export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export REGION="us-central1"

  3. 必要な Google Cloud サービスを有効にします。

    gcloud services enable \
  artifactregistry.googleapis.com \
  bigqueryunified.googleapis.com \
  cloudaicompanion.googleapis.com \
  cloudbuild.googleapis.com \
  cloudresourcemanager.googleapis.com \
  datacatalog.googleapis.com \
  run.googleapis.com

  4. Google Cloud DevRel Demos リポジトリのクローンを作成します。

    GitHub からインフラストラクチャ コードとスクリプトをダウンロードします。スパース チェックアウトを使用して、このチュートリアルに必要な特定のフォルダのみを pull します。

    # Perform a shallow clone to get only the latest repository structure without the full history
git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git
cd devrel-demos

# Specify and download only the folder you need for this tutorial
git sparse-checkout set data-analytics/governance-context
cd data-analytics/governance-context

データレイクを構築する

現実的な状況を再現するには、公式データと信頼できない雑然としたデータを混在させる必要があります。この設定をすばやく行うには、Terraform とチュートリアル リポジトリの事前構成済み Terraform 構成ファイルを使用します。

Terraform 構成は、次の 2 つのタスクを処理します。

  • Knowledge Catalog のアスペクト タイプ（メタデータ テンプレート）、BigQuery データセット、テーブル（finance_mart.fin_monthly_closing_internal と analyst_sandbox.tmp_data_dump_v2_final_real を含む）を設定します。
  • テーブルにサンプルデータを読み込みます。

  1. terraform ディレクトリを開いて初期化します。

    cd terraform
terraform init

  2. 構成を適用します。これには 1 分ほどかかることがあります。

    terraform apply -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve

これで、管理対象外のデータレイクが作成されました。AI エージェントから見ると、データレイク内のテーブルは列を含むオブジェクトにすぎないため、まったく同じように見えます。この問題を解決するには、次の手順でガバナンスを適用する必要があります。

ガバナンスを適用する

これは設定の最も重要な部分です。現時点では、2 つのテーブルは AI エージェントから見ると同じように見えます。これらを区別するには、アスペクトを適用します。これは、エージェントに必要なコンテキストを提供する認定メタデータ ラベルのようなものです。このセクションでは、メタデータを生成するスクリプトと、テーブルに適用するスクリプトの 2 つを使用します。

ガバナンス ペイロードを生成する

Terraform でアスペクト タイプがすでに設定されているため、アスペクト タイプに入力するデータを生成する必要があります。

./generate_payloads.sh スクリプトを実行して aspect_payloads/ ディレクトリを作成します。このディレクトリには、さまざまなガバナンス シナリオを定義する 4 つの YAML ファイルが含まれています。これらのファイルは次のステップで適用します。

チュートリアル ディレクトリのルートに戻り、./generate_payloads.sh スクリプトを実行します。

cd ..
chmod +x ./generate_payloads.sh
./generate_payloads.sh

アスペクトを適用する

  1. apply_governance.sh スクリプトを実行する前に、テーブルに添付されるデータを確認します。次のコマンドを実行して、内部財務データに定義されているメタデータを表示します。

    cat aspect_payloads/fin_internal.yaml

    YAML ファイルは、テーブルのビジネス コンテキストを定義します。

    your-project-id.us-central1.official-data-product-spec:
  data:
    product_tier: GOLD_CRITICAL
    data_domain: FINANCE
    usage_scope: INTERNAL_ONLY
    update_frequency: DAILY_BATCH
    is_certified: true

    この例では、データを is_certified: true として明示的にマークし、GOLD_CRITICAL 階層を割り当てています。これにより、AI エージェントは明確で構造化されたルールに従うことができます。

  2. apply_governance.sh スクリプトを実行します。このスクリプトは、BigQuery テーブルを反復処理し、gcloud CLI を使用して、YAML ペイロードのメタデータを各テーブルに「スタンプ」します。

    chmod +x ./apply_governance.sh
./apply_governance.sh

メタデータを確認する

次に進む前に、スクリプトがアスペクトを正しく適用したことを確認してください。

  1. Google Cloud コンソールで [Knowledge Catalog] ページを開きます。上部にある検索バーを使って拡張機能を探すことができます。
  2. fin_monthly_closing_internal を検索します。結果でテーブル名を選択して、詳細ページを開きます。
  3. [オプションのタグとアスペクト] セクションで、official-data-product-spec アスペクトを見つけます。値が適用した「Gold Internal」シナリオと一致していることを確認します。

これで、メタデータを使用してこれらのテーブルを区別し、AI エージェントが同じことを行う方法を AI エージェントに提供できました。

Gemini CLI でデータ コンテキストをテストする

完全なウェブ アプリケーションを構築する前に、Model Context Protocol（MCP）環境を使用してガバナンス ロジックをローカルでテストできます。この設定では、Gemini CLI がクライアント（ユーザーが対話するインターフェース）として機能し、Knowledge Catalog 拡張機能がローカル サーバーとして機能します。

Knowledge Catalog 拡張機能をインストールする

Cloud Shell で、Knowledge Catalog 拡張機能をインストールします。

export DATAPLEX_PROJECT="${PROJECT_ID}"

gemini extensions install https://github.com/gemini-cli-extensions/dataplex

ルールを定義

GEMINI.md 構成ファイルには、「安全なデータが必要」などの宣言型ルールを、正しいガバナンスラベルを持つテーブルのみを返す正確な検索に変換するロジックが含まれています。

現時点では、構成ファイルはテンプレートにすぎません。CLI を実行したときに管理対象データが正しくターゲット設定されるように、特定の Google Cloud プロジェクト ID をルールに追加する必要があります。

  1. 構成ファイルに PROJECT_ID を追加します。

    envsubst < GEMINI.md > GEMINI.md.tmp && mv GEMINI.md.tmp GEMINI.md

  2. 変更を確認し、データ コンテキストの仕組みを理解するには、GEMINI.md ファイルを簡単に確認します。

    cat GEMINI.md

    ファイルでは、ルールがフェーズ 1 とフェーズ 2 に分割されています。これにより、オペレーションの厳密な順序が適用されます。エージェントは、データ自体にアクセスする（フェーズ 2）前に、まず正しいガバナンス ラベルを探す（フェーズ 1）必要があります。この「検索優先」ロジックにより、エージェントがテーブル名を推測したり、未確認の情報源から回答を生成したりすることを防ぐことができます。

    フェーズ 2 に実際の Google Cloud プロジェクト ID が含まれていることを確認します。これが正しくないと、エージェントはデータの検索場所を特定できません。

Gemini CLI を起動してテスト シナリオを実行する

新しい Gemini セッションを開始します。プロジェクト フォルダにいるため、CLI はローカル GEMINI.md をシステム コンテキストとして自動的に検出して読み込みます。

gemini

インストールを確認する

Knowledge Catalog 拡張機能が有効になっていることを確認します。構成済みの MCP サーバーツールのリストに dataplex が表示されます。

/mcp desc

試してみる

それでは、データ コンテキストの動作を確認しましょう。これらのプロンプトを 1 つずつ CLI に貼り付けます。

シナリオ 1: 「ゴールド」標準データを見つける

Gemini CLI が重要な取締役会で最も信頼できるデータを見つけられるかどうかを確認します。

We are preparing the deck for an internal Board of Directors meeting next week. I need the numbers to be absolutely finalized, trustworthy, and kept strictly confidential. Which table is safe to use?

CLI は生データをスキップして fin_monthly_closing_internal を見つけます。これは、リクエストされた「確定」データと「機密」データを、以前に適用した GOLD_CRITICAL タグと INTERNAL_ONLY タグと照合することで実現されます。

シナリオ 2: 一般公開

データを外部で共有したいとします。CLI から内部シークレットが漏洩しないようにする必要があります。

I need to share our quarterly financial summary with an external consulting firm. It is critical that we do not leak any raw or internal metrics. Which dataset is officially scrubbed and explicitly approved for external sharing?

内部テーブルには最も詳細な情報が含まれていますが、CLI はこのテーブルをバイパスする必要があります。EXTERNAL_READY というタグが付いているテーブルは fin_quarterly_public_report だけなので、fin_quarterly_public_report が返されます。

シナリオ 3: リアルタイムの運用ニーズ

データ サイエンティストは最新の情報を必要とすることがよくあります。Gemini CLI が日次バッチとライブストリームの違いを理解しているかどうかを確認します。

My dashboard needs to show what's happening right now with our ad spend. I can't wait for the overnight load. What do you recommend?

CLI は mkt_realtime_campaign_performance を検出します。メタデータ内の REALTIME_STREAMING の更新の頻度を識別します。

シナリオ 4: サンドボックスの探索

「完璧」よりも「十分」な方が良い場合もあります。Gemini CLI が試験運用版の ML 作業の未加工のサンドボックス データを見つけられるかどうかを確認します。

I'm just playing around with some new ML models and need a lot of raw data. It doesn't need to be perfect, just a sandbox environment.

CLI は tmp_data_dump_v2_final_real を検出します。この選択が正しいのは、BRONZE_ADHOC 階層と一致し、is_certified: false で明示的にマークされているためです。

テストが完了したら、CLI セッションを終了できます。

/quit

クリーンアップ

定期購入料金が発生しないようにするには、次の手順を行います。

  1. Terraform リソースを破棄します。

    cd ~/devrel-demos/data-analytics/governance-context/terraform
terraform destroy -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve

  2. Knowledge Catalog 拡張機能をアンインストールし、ローカルのデモファイルを削除します。

    gemini extensions uninstall dataplex
cd ~
rm -rf ~/devrel-demos

まとめ

堅牢なデータ基盤を構築し、メタデータを使用して厳格なコンテキストを適用し、Gemini CLI を使用してすべてがローカルで機能することを確認しました。