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

Knowledge Catalog メタデータを使用してデータ基盤を構築する

1. はじめに

生成 AI モデルは強力な推論エンジンですが、組織のコンテキストがありません。経営幹部が AI エージェントに「第 1 四半期の収益はいくらですか？」と尋ねると、エージェントはデータレイク全体で「収益」という名前のテーブルを数十個見つける可能性があります。厳密な財務報告書もあれば、リアルタイムのマーケティング予測もあり、廃止されたサンドボックスも多くあります。

明示的なグラウンディングがない場合、AI エージェントは単純な名前の類似性に基づいてテーブルを選択し、検証されていないデータから「説得力のある誤った」回答を生成します。

この Codelab は、ガバナンス対応の AI エージェントを構築する方法について説明する 2 部構成のシリーズの一部です。

この最初のパートでは、データ基盤を構築します。BigQuery で現実的な「雑然とした」データレイクを設定し、厳密なメタデータタグ（Knowledge Catalog アスペクト）を適用して有効なデータとノイズを区別します。また、Antigravity（AGY）CLI を使用して、エージェントがデータガバナンスルールを厳守しているかどうかをローカルでテストします。

このシリーズの第 2 部では、Model Context Protocol（MCP）と Cloud Run を使用して、ローカルエージェントのプロトタイプを安全なエンタープライズグレードのウェブアプリケーションにデプロイする方法について説明します。👉 第 2 部を読む

学習内容

セットアップスクリプトを使用して、現実的な多層データレイクをデプロイする。
Knowledge Catalog でカスタムメタデータテンプレート（アスペクトタイプ）を設計して登録し、公式データプロダクトと未加工のサンドボックステーブルを区別する。
アプリケーションコードを記述する前に、 AGY CLI を使用してデータガバナンスルールをローカルで検証する。

必要なもの

課金を有効にした Google Cloud プロジェクト
Google Cloud Shell へのアクセス（AGY CLI は Cloud Shell にプリインストールされています）。
BigQuery と Knowledge Catalog の基本的な知識と操作スキル。

主なコンセプト

Knowledge Catalog: 統合メタデータ管理サービス。これを使用して、技術メタデータ（スキーマ）をビジネスコンテキスト（ガバナンス）で拡充します。
アスペクトタイプ: 構造化されたメタデータテンプレート。フリーテキストタグとは異なり、アスペクトは厳密な型指定（列挙型、ブール値）を適用するため、マシンによる評価の信頼性が高くなります。

2. 設定と要件

Cloud Shell の起動

Google Cloud はノートパソコンからリモートで操作できますが、この Codelab では、Google Cloud Shell（Cloud 上で動作するコマンドライン環境）を使用します。

Google Cloud コンソールで、右上のツールバーにある Cloud Shell アイコンをクリックします。

Cloud Shell をアクティブにする

プロビジョニングと環境への接続にはそれほど時間はかかりません。完了すると、次のように表示されます。

環境が接続されていることを示す Google Cloud Shell ターミナルのスクリーンショット

この仮想マシンには、必要な開発ツールがすべて用意されています。永続的なホームディレクトリが 5 GB 用意されており、Google Cloud で稼働します。そのため、ネットワークのパフォーマンスと認証機能が大幅に向上しています。この Codelab での作業はすべて、ブラウザ内から実行できます。インストールは不要です。

環境を初期化する

Cloud Shell を開き、プロジェクト変数を設定して、すべてのコマンドが正しいインフラストラクチャをターゲットにしていることを確認します。

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

API を有効にする

次の手順を実行するには、必要な Google Cloud サービスを有効にします。

gcloud services enable \
  bigquery.googleapis.com \
  dataplex.googleapis.com

リポジトリのクローンを作成する

GitHub リポジトリからインフラストラクチャコードと自動化スクリプトを取得します。Cloud Shell のディスク容量を節約するため、このラボに必要な特定のフォルダのみをダウンロードします。

# 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 we need for this lab
git sparse-checkout set data-analytics/governance-context
cd data-analytics/governance-context

「雑然とした」データレイクを構築する

実際のデータ環境は、クリーンな状態であることはほとんどありません。現実をシミュレートするには、「公式」データマートと信頼できない「サンドボックス」テーブルを混在させる必要があります。

セットアップスクリプトを使用して、BigQuery データセットとテーブルをデプロイします。

セットアップスクリプトを実行可能にして実行します。これにより、3 つの BigQuery データセット（finance_mart、marketing_prod、analyst_sandbox）が作成され、そのテーブルにサンプルデータが入力されます。

chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh

チェックポイント: これで、完全にデータが入力された、完全に管理されていないデータレイクができました。AI にとっては、どのテーブルもまったく同じように見えます。

3. データガバナンステンプレート（アスペクトタイプ）を作成する

次に、データガバナンスルールを定義します。Knowledge Catalog では、再利用可能な厳密な型指定のメタデータテンプレートであるアスペクトタイプ を作成して行います。

このテンプレートを gcloud CLI を使用して登録し、定義方法を確認します。

アスペクトスキーマを調べる

aspect_template.json の内容を出力して、スキーマ定義を確認します。

cat aspect_template.json

次の JSON 構造が表示されます。

{
  "name": "OfficialDataProductSpec",
  "type": "record",
  "recordFields": [
    {
      "name": "product_tier",
      "type": "enum",
      "enumValues": [
        { "name": "GOLD_CRITICAL", "index": 1 },
        { "name": "SILVER_STANDARD", "index": 2 },
        { "name": "BRONZE_ADHOC", "index": 3 }
      ],
      ...
    },
    {
      "name": "is_certified",
      "type": "bool",
      ...
    }
  ]
}

このスキーマでは、重要度階層（GOLD_CRITICAL、SILVER_STANDARD、BRONZE_ADHOC）に enum、is_certified に bool など、厳密なデータ型が適用されています。これにより、メタデータの構造化とマシンでの読み取りが可能になります。

アスペクトタイプを登録する

次の gcloud コマンドを実行して、このテンプレートを Knowledge Catalog レジストリに登録します。

gcloud dataplex aspect-types create official-data-product-spec \
    --location="${REGION}" \
    --project="${PROJECT_ID}" \
    --description="Defines the comprehensive profile of a data product for governance agents." \
    --display-name="Official Data Product Spec" \
    --metadata-template-file-name="aspect_template.json"

4. ガバナンスを適用する

これは重要なエンジニアリングステップです。現在、テーブル finance_mart.fin_monthly_closing_internal と analyst_sandbox.tmp_data_dump_v2_final_real は LLM と同じように見えます。列を持つオブジェクトにすぎません。

ガバナンスエンジニアは、これらのテーブルを区別するために、アスペクト（認定メタデータラベル）をアタッチする必要があります。実際の企業では、CI/CD パイプラインを使用してこれを自動化します。スクリプトを使用してその自動化をシミュレートします。

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

Knowledge Catalog アスペクトキーは、グローバルに一意である必要があります（プロジェクト ID が接頭辞として付加されます）。./generate_payloads.sh スクリプトは、YAML メタデータファイルを動的に生成します。

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

出力:

これにより、ガバナンスシナリオ（Gold / Internal、Gold/Public、Silver/Realtime、Bronze/Sandbox）を定義する 4 つの YAML ファイルを含むフォルダ「./aspect_payloads」が作成されます。

CLI でアスペクトを適用する

スクリプトを実行する前に、プロセスを理解するために、実際に適用する内容を見てみましょう。次のコマンドを実行して、内部財務ペイロードの構造を確認します。

cat aspect_payloads/fin_internal.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

この YAML では、is_certified: true フラグの設定や GOLD_CRITICAL 階層の割り当てなど、ビジネスコンテキストが明示的に定義されています。LLM に、テーブル名に基づいて推測するのではなく、評価するための明確な構造化ルールを提供します。

次に、アプリケーションスクリプトを実行します。これにより、BigQuery テーブルが反復処理され、gcloud dataplex entries update コマンドが実行されて、この厳密なメタデータがアタッチされます。

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

検証（省略可）

続行する前に、コンソールでメタデータが正しく適用されていることを確認します。

Google Cloud コンソールで Knowledge Catalog ページを開きます。左側のナビゲーションメニューに [Knowledge Catalog] が表示されない場合は、Google Cloud コンソールウィンドウの上部にある検索バーを使用して「Knowledge Catalog」と入力し、[上位の結果] または [プロダクトとページ] の結果を選択します。
fin_monthly_closing_internal を検索します。結果に BigQuery テーブルが表示されます。テーブル名をクリックして詳細ページに移動します。

テーブルの詳細ページの下部にある [オプションのタグとアスペクト] セクションを探します。
official-data-product-spec アスペクトがあります。値が適用した [Gold Internal] シナリオと一致していることを確認します。

これで、技術的に同一の BigQuery テーブル（fin_monthly_closing_internal と tmp_data_dump_v2_final_real）が、マシンで読み取り可能なメタデータによって論理的に区別されていることを確認できました。

5. エージェントを構成してプロトタイプを作成する

アプリケーションを構築する前に（パート 2 で行います）、データガバナンスロジックをローカルで検証します。Knowledge Catalog プラグインをインストールし、Agent Skill を構成する必要があります。

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

Cloud Shell で、Knowledge Catalog プラグインをインストールします。確認と設定の詳細が求められます。

export DATAPLEX_PROJECT="${PROJECT_ID}"

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

エージェントスキルを調べる

エージェントスキルは、.agents/skills/knowledge_catalog_governance/SKILL.md にある静的な再利用可能な定義ファイルです。これには、抽象的な人間のルール（「安全なデータが必要」など）を厳密な技術的なルックアップに変換するロジックが含まれています。

ファイルを調べて、AI に教えるアルゴリズムを理解します。

cat .agents/skills/knowledge_catalog_governance/SKILL.md

モデルに厳密なフェーズ 1（メタデータの検証）とフェーズ 2（クエリの実行）ループに従うように明示的に指示します。モデルは、SQL を構築する前にメタデータを検出して検証する必要があります。

エージェントを起動してシナリオをテストする

AGY CLI セッションを開始します。.agents/skills ディレクトリからスキルが自動的に検出されて読み込まれます。

agy

注: 複数のコンテキストファイルが読み込まれることがあります。これは正常な動作です。CLI は、このプロジェクトの特定のルールに対するローカルスキルと、Knowledge Catalog プラグイン自体のデフォルトの手順を読み込みます。

インストールを確認する

/mcp と入力して、Knowledge Catalog プラグインが有効になっていることを確認します。knowledge-catalog が、使用可能なツールとともに有効なプラグインとして表示されます。

/mcp

想定される出力:

MCP Servers
...
>  ✓ knowledge-catalog  Tools: search_entries, lookup_context, lookup_entry

テストシナリオ（プロトタイピング）

次のプロンプトを実行中のエージェントセッションに 1 つずつ貼り付けて、ルールに準拠していることを確認します。

シナリオ A（CFO のデータを認定する）:

"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?"

想定: エージェントは、ツールからアクティブなプロジェクトとリージョンを自動的に検出し、アスペクトで GOLD_CRITICAL（正確）と INTERNAL_ONLY（取締役会）に意味的に一致するため、fin_monthly_closing_internal をクエリして推奨します。

シナリオ B（一般公開）:

"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?"

想定: エージェントは、月次の内部テーブルをバイパスし、EXTERNAL_READY タグが付いている唯一のアセットである fin_quarterly_public_report を厳密に選択する必要があります。

シナリオ C（運用上のニーズ）:

"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?"

想定: エージェントは、REALTIME_STREAMING 更新の頻度を識別し、財務データの GOLD_CRITICAL 階層よりも優先するため、mkt_realtime_campaign_performance を選択します。

シナリオ D（サンドボックスでの実験）:

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

想定: エージェントは、アスペクトで BRONZE_ADHOC（未加工データ）と is_certified: false（サンドボックス環境）に意味的に一致するため、tmp_data_dump_v2_final_real を選択します。

（AGY セッションを終了するには、/exit または /quit と入力します）

6. おめでとうございます！次のステップ

管理されたデータ基盤を構築し、ローカル CLI プロトタイプを使用して AI がメタデータルールを厳守できることを証明しました。

これでチェックポイントに到達しました。次のステップを選択してください。

オプション A: 今すぐパート 2 に進みたい

Model Context Protocol（MCP）と Cloud Run を使用して、このローカルプロトタイプを安全な本番環境グレードのウェブアプリケーションに変換する準備ができている場合:

👉 パート 2 の Codelab へのリンク

オプション B: パート 2 は後で行うか、パート 1 のみを完了したい

今日で停止してクラウド費用を抑えたい場合は、リソースをクリーンアップする必要があります。

ご安心ください。パート 2 では、「ファストトラックスクリプト」を提供します。このスクリプトを使用すると、パート 1 の環境を 2 分で完全に再構築できるため、中断したところから再開できます。

👉 クリーンアップセクションに進みます。

7. クリーンアップ（オプション B のみ）

ここで停止する場合は、料金が発生しないようにリソースを破棄してください。

データレイクを破棄する

現在 AGY CLI セッションを使用している場合は、Ctrl+C キーを 2 回押すか、/quit と入力してセッションを終了します。次に、次のコマンドを実行します。

chmod +x ./cleanup_data_lake.sh
./cleanup_data_lake.sh

AGY CLI プラグインをアンインストールしてローカルファイルを削除する

agy plugin uninstall dataplex
cd ~
rm -rf ~/devrel-demos