使用 Antigravity CLI 測試資料脈絡

Knowledge Catalog (舊稱 Dataplex Universal Catalog) 的中繼資料擴充功能可讓您提供結構化資料背景資訊，讓 AI 代理根據可信、經過認證的來源提供答案。在本教學課程中，您會將自訂切面附加至範例 BigQuery 資料表，並使用 Antigravity CLI 測試 AI 代理如何套用管理規則。

目標

  • 在 BigQuery 部署實際的多層資料湖泊，用於測試。
  • 在 Knowledge Catalog 中設計及註冊自訂中繼資料範本 (切面類型)，區分正式資料產品和原始沙箱資料表。
  • 使用 Antigravity CLI (agy) 驗證資料治理規則和 AI 代理基準。

事前準備

開始前，請務必完成下列操作：

如要完成本教學課程，您也應具備 BigQuery 和 Knowledge Catalog 的基本知識。

準備環境

本教學課程會使用 Google Cloud Shell，這是在雲端執行的指令列環境。Antigravity CLI (agy) 已預先安裝在 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 \
  bigquery.googleapis.com \
  dataplex.googleapis.com \
  aiplatform.googleapis.com \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  iam.googleapis.com

  4. 複製 Google Cloud DevRel Demos 存放區。

    從 GitHub 下載基礎架構程式碼和指令碼。使用稀疏檢出功能，只提取本教學課程所需的特定資料夾。

    # 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

在 BigQuery 中部署範例資料湖泊

現實世界的資料環境很少是乾淨的。AI 代理可以推論，但一開始對貴公司一無所知。假設您詢問代理：「我們第 1 季的收益是多少？」如果沒有指引，代理可能會從資料庫中挑選數十個名為「revenue」的資料表，從官方報表到原始測試資料都有。如果代理選取名稱最接近的資料表，可能會根據未經驗證的來源，傳回看似正確但實際上錯誤的答案。

如要模擬這個情境，您需要混合使用「官方」資料市集和不受信任的「沙箱」資料表。您將使用設定指令碼部署 BigQuery 資料集和資料表。

將設定指令碼設為可執行狀態，然後執行指令碼。這會建立三個 BigQuery 資料集 (finance_mart、marketing_prod、analyst_sandbox)，並在資料表中填入樣本資料：

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

現在，您已擁有一個資料完整的資料湖泊，但尚未受到管理。對 AI 代理來說，每個資料表看起來都一樣。

在 Knowledge Catalog 定義自訂切面類型

現在，請定義資料治理規則。如要在 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。這可確保中繼資料維持結構化且機器可讀。

在 Knowledge Catalog 註冊切面類型

執行下列 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 data governance agents." \
    --display-name="Official Data Product Spec" \
    --metadata-template-file-name="aspect_template.json"

將治理切面附加至資料湖泊資料表

這是關鍵的工程步驟。目前，資料表 finance_mart.fin_monthly_closing_internal 和 analyst_sandbox.tmp_data_dump_v2_final_real 對 AI 代理來說看起來完全相同。只是含有資料欄的物件。

為了區分這些資料表，您套用切面，將認證的中繼資料標籤附加至這些資料表。在實際的企業環境中，您會使用 CI/CD 管道自動執行這項作業。在本教學課程中，您將使用指令碼模擬自動化作業。

產生面向中繼資料酬載

Knowledge Catalog aspect 鍵在全域內不得重複 (前置字串為專案 ID)。./generate_payloads.sh 指令碼會動態產生 YAML 中繼資料檔案：

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

這會建立 aspect_payloads/ 目錄，其中包含 4 個 YAML 檔案，定義不同的資料治理情境 (fin_internal.yaml、fin_public.yaml、mkt_realtime.yaml、sandbox.yaml)。

將切面附加至 BigQuery 資料表

  1. 執行指令碼前，請先查看要附加至資料表的資料。執行下列指令，查看內部財務資料的中繼資料：

    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. 執行應用程式指令碼。這個指令碼會疊代 BigQuery 資料表，並使用 gcloud dataplex entries update 指令將中繼資料酬載附加至各個資料表：

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

在 Google Cloud 控制台中驗證套用的切面

繼續操作前，請先在 Google Cloud 控制台確認指令碼是否正確套用切面：

  1. 在 Google Cloud 控制台開啟「Knowledge Catalog」頁面。您可以使用頂端的搜尋列找出該擴充功能。
  2. 搜尋 fin_monthly_closing_internal。在結果中選取 BigQuery 資料表名稱，開啟詳細資料頁面。
  3. 在底部的「Optional tags and aspects」(選用標記和切面) 部分，找到 official-data-product-spec 切面。確認這些值與您套用的「Gold Internal」情境相符。

您已確認技術上相同的 BigQuery 資料表 (fin_monthly_closing_internal 和 tmp_data_dump_v2_final_real)，在邏輯上會依機器可讀的中繼資料區分。

使用 Antigravity CLI 測試資料情境

建構應用程式前，您可以使用 Antigravity CLI 在本機驗證資料治理邏輯。為此，您需要安裝 Knowledge Catalog 外掛程式，並設定代理技能。

安裝 Knowledge Catalog 外掛程式

在 Cloud Shell 中安裝服務外掛程式：

export DATAPLEX_PROJECT="${PROJECT_ID}"

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

檢查代理技能定義

代理技能是靜態、可重複使用的定義檔案，位於 .agents/skills/knowledge-catalog-governance/SKILL.md。其中包含邏輯，可將抽象的人類規則 (例如「我需要安全的資料」) 轉譯為結構化技術查詢。

如要檢查技能設定並瞭解資料情境的運作方式，請檢查 SKILL.md 檔案：

cat .agents/skills/knowledge-catalog-governance/SKILL.md

請注意，系統會指示模型嚴格遵循第 1 階段 (中繼資料驗證) 和第 2 階段 (查詢執行) 迴圈。模型必須先探索及驗證中繼資料，才能建構任何 SQL 陳述式。這種搜尋優先邏輯可防止代理猜測資料表名稱，或根據未經驗證的來源產生幻覺答案。

啟動 Antigravity CLI 工作階段

啟動 Antigravity CLI 工作階段。由於您位於專案資料夾中，CLI 會自動從 .agents/skills 目錄中探索並載入技能：

agy

在 CLI 中驗證外掛程式安裝作業

在 Antigravity CLI 提示中，確認外掛程式已啟用。輸入 /mcp，列出已設定的工具和外掛程式：

/mcp

輸出內容應顯示 knowledge-catalog 為有效外掛程式，並列出可用工具：

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

執行資料內容驗證情境

現在來看看資料情境的實際運作方式。將這些提示詞逐一貼到 Antigravity CLI 工作階段。

情境 1：擷取經認證的黃金級資料

看看 Antigravity 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。做法是將您對「finalized」和「confidential」資料的要求，與先前套用的 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 必須略過。系統應該會指向 fin_quarterly_public_report，因為這是唯一標記為 EXTERNAL_READY 的資料表。

情境 3：擷取即時串流資料

資料科學家通常需要絕對最新的資訊。看看 Antigravity 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：探索未認證的沙箱資料

有時「夠好」比「完美」更重要。看看 Antigravity CLI 能否找到一些實驗性機器學習工作的原始沙箱資料：

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. 如果您正在使用 Antigravity CLI 工作階段，請連按兩次 Ctrl+C 或輸入 /quit，即可退出工作階段。

  2. 執行清除指令碼，刪除在本教學課程中建立的 BigQuery 資料表、資料集和 Knowledge Catalog 切面類型：

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

  3. 解除安裝服務外掛程式，並移除本機示範檔案：

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

後續步驟