使用 Antigravity CLI 測試資料脈絡

AI 代理程式可以推理，但一開始對貴公司的具體情況一無所知。假設您向代理程式詢問「我們第一季的收益是多少？」如果沒有指引，代理程式可能會從資料庫中數十個名為「收益」的表格中挑選，範圍從正式報表到雜亂的測試資料都有。如果代理程式選取名稱最接近的資料表，可能會根據未經驗證的來源，傳回看似正確的錯誤答案。

中繼資料擴充功能可解決這個脈絡問題。在本教學課程中，您將設定提供脈絡的層面，並使用 Antigravity CLI 測試資料脈絡，確認代理程式可以根據值得信賴的認證資料，準確地提供答案。

目標

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

事前準備

開始之前，請務必先執行下列工作：

如要完成本教學課程，您也應具備 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 資料集和資料表。

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

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

現在您已擁有完整填入資料的資料湖，但尚未受到管理。對 AI 代理程式而言，每個資料表看起來都完全相同。

建立資料治理範本 (切面類型)

現在，請定義資料治理規則。如要在 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",
      ...
    }
  ]
}

請注意，這個結構定義會強制執行嚴格的資料類型，例如重要性層級的 enum (GOLD_CRITICAL、SILVER_STANDARD、BRONZE_ADHOC)，以及 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 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 的層面鍵在全域中不得重複 (前置字元為專案 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)。

使用 CLI 套用層面

  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 控制台中確認指令碼已正確套用各個層面：

  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 外掛程式，並設定代理程式技能。

安裝服務外掛程式

在 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

驗證安裝

在 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。方法是將您對「已完成」和「機密」資料的要求，與您先前套用的 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。

情境 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 是否能找到某些實驗性 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. 如果正在使用 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

結論

您已建立穩固的資料基礎、使用中繼資料套用嚴格的內容，並使用 Antigravity CLI 在本機驗證一切運作正常。

後續步驟