Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

運用 Knowledge Catalog 中繼資料建立資料基礎

1. 簡介

生成式 AI 模型擅長推理，但缺乏機構脈絡。如果高階主管詢問 AI 代理「我們第一季的收益是多少？」，代理可能會在資料湖泊中找到數十個名為「收益」的資料表。有些是嚴謹的財務報表，有些是即時行銷估算值，許多可能是已淘汰的沙箱。

如果沒有明確的基礎，AI 代理程式會根據簡單的名稱相似度選取資料表，導致從未經驗證的資料得出「令人信服的錯誤」答案。

本程式碼研究室是系列課程的第二部分，探討如何建構具備治理意識的 AI 代理程式。

在第一部分中，您將建構資料基礎。您將在 BigQuery 中設定實際的「雜亂」資料湖泊，套用嚴格的中繼資料標記 (Knowledge Catalog 方面)，區分有效資料和雜訊，並使用 Antigravity (AGY) CLI 在本機測試代理程式是否嚴格遵守資料治理規則。

您可以閱讀本系列的第二部分，瞭解如何使用 Model Context Protocol (MCP) 和 Cloud Run，將本機代理原型部署至安全無虞的企業級 Web 應用程式。👉 閱讀第 2 部分

課程內容

使用設定指令碼部署真實的多層資料湖泊。
在 Knowledge Catalog 中設計及註冊自訂中繼資料範本 (切面類型)，以區分正式資料產品和原始沙箱資料表。
在編寫任何應用程式程式碼之前，請先使用 AGY CLI 在本機驗證資料治理規則。

軟硬體需求

已啟用計費功能的 Google Cloud 專案。
存取 Google Cloud Shell (AGY CLI 已預先安裝在 Cloud Shell 中)。
對 BigQuery 和 Knowledge Catalog 有基本瞭解。

核心概念

Knowledge Catalog：整合式中繼資料管理服務。我們使用這項功能，以業務脈絡 (治理) 充實技術中繼資料 (結構定義)。
切面類型：結構化中繼資料範本。與任意文字標記不同，Aspect 會強制執行嚴格型別 (列舉、布林值)，因此機器評估時可信度較高。

2. 設定和需求條件

啟動 Cloud Shell

雖然可以透過筆電遠端操作 Google Cloud，但在本程式碼研究室中，您將使用 Google Cloud Shell，這是可在雲端執行的指令列環境。

在 Google Cloud 控制台中，點選右上角工具列的 Cloud Shell 圖示：

啟用 Cloud Shell

佈建並連線至環境的作業需要一些時間才能完成。完成後，您應該會看到如下的內容：

Google Cloud Shell 終端機的螢幕截圖，顯示環境已連線

這部虛擬機器搭載各種您需要的開發工具，並提供永久的 5GB 主目錄，而且可在 Google Cloud 運作，大幅提升網路效能並強化驗證功能。您可以在瀏覽器中完成本程式碼研究室的所有作業。您不需要安裝任何軟體。

初始化環境

開啟 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 資料集和資料表。

將設定指令碼設為可執行狀態並執行。這會建立三個 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",
      ...
    }
  ]
}

請注意，這個結構定義會強制執行嚴格的資料類型，例如重要性層級的 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 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

輸出內容：

這會建立「./aspect_payloads」資料夾，內含 4 個 YAML 檔案，定義控管情境 (Gold/Internal、Gold/Public、Silver/Realtime、Bronze/Sandbox)。

使用 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」，請使用 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

測試情境 (原型設計)

將下列提示逐一貼到執行中的代理程式工作階段，確認代理程式遵守規則。

情境 A (認證財務長的資料)：

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

預期：代理程式會從工具中自動探索您目前使用的專案和區域，因為 fin_monthly_closing_internal 在「Aspect」中與 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?"

預期結果：代理程式必須略過每月內部資料表，並嚴格選取 fin_quarterly_public_report，因為這是唯一標記 EXTERNAL_READY 的資產。

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

預期結果：代理程式會選取 mkt_realtime_campaign_performance，因為代理程式會識別 REALTIME_STREAMING 更新頻率，並優先處理該頻率，而非財務資料的 GOLD_CRITICAL 層級。

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

預期結果：代理會選取 tmp_data_dump_v2_final_real，因為這在語意上與其 Aspect 中的 BRONZE_ADHOC (原始資料) 和 is_certified: false (沙箱環境) 相符。

(如要結束 AGY 工作階段，請輸入 /exit 或 /quit)

6. 恭喜！接下來要做什麼？

您已成功建構受控資料基礎，並證明 AI 可以使用本機 CLI 原型嚴格遵守中繼資料規則！

您現在已達到查核點。請選擇後續行動：

選項 A：我現在想繼續進行第 2 部分！

如要使用 Model Context Protocol (MCP) 和 Cloud Run，將這個本機原型變成安全的正式版網頁應用程式，請按照下列步驟操作：

👉 第 2 部分程式碼研究室的連結

選項 B：我稍後會完成第 2 部分，或我只想完成第 1 部分。

如要暫時停止作業並避免產生雲端費用，請清理資源。

別擔心！在第 2 部分中，我們會提供「快速入門指令碼」，讓您在短短 2 分鐘內完全重建第 1 部分的環境，以便從上次中斷的地方繼續。

👉 前往清理部分。

7. 清理 (僅適用於選項 B)

如果您的課程就此停住，請刪除資源，以免產生費用。

刪除資料湖泊

如果目前在 AGY CLI 工作階段中，請按兩次 Ctrl+C 或輸入 /quit 結束工作階段。然後執行下列指令：

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

解除安裝 AGY CLI 外掛程式並移除本機檔案

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