使用 Gemini CLI 代理測試資料脈絡

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

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

目標

建立用於測試的真實資料湖泊。
使用 Knowledge Catalog 層面標記「黃金」資料，並與測試資料區分。
使用 Gemini CLI 在本機測試資料情境。

事前準備

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

為本教學課程挑選Google Cloud 專案。
確認專案已啟用計費功能。

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

準備環境

本教學課程使用 Google Cloud Shell，這是可在雲端執行的指令列環境。

在 Google Cloud 控制台右上方的工具列中，按一下「啟用 Cloud Shell」。佈建並連至環境預計只需要幾分鐘，

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

啟用必要的 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

複製 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

建構資料湖泊

為了模擬真實情況，您需要混合使用官方資料和不可靠的雜亂資料。使用 Terraform 和教學課程存放區中預先設定的 Terraform 設定檔，即可快速完成設定。

Terraform 設定會處理兩項工作：

設定 Knowledge Catalog 切面類型 (中繼資料範本)、BigQuery 資料集和資料表，包括 finance_mart.fin_monthly_closing_internal 和 analyst_sandbox.tmp_data_dump_v2_final_real。
將範例資料載入資料表。

開啟 terraform 目錄並初始化。
```
cd terraform
terraform init
```

套用設定。這項作業最多可能需要一分鐘。

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

您現在擁有未受管理的資料湖泊！對 AI 代理程式而言，資料湖泊中的資料表看起來完全相同，因為它們只是含有資料欄的物件。如要修正這個問題，請在下一個步驟中套用控管規則。

套用管理原則

這是設定程序中最重要的部分。目前，這兩個表格對 AI 代理程式來說完全相同。如要區分兩者，請套用「切面」，這類切面就像經過認證的中繼資料標籤，可為代理提供所需脈絡。在本節中，您會使用兩個指令碼：一個用於產生中繼資料，另一個則用於將中繼資料套用至資料表。

產生管理酬載

Terraform 已設定切面類型，因此您現在需要產生資料來填入這些類型。

執行 ./generate_payloads.sh 指令碼，建立 aspect_payloads/ 目錄。這個目錄包含四個 YAML 檔案，分別定義不同的控管情境，您會在下一個步驟中套用這些檔案。

返回教學課程目錄的根目錄，然後執行 ./generate_payloads.sh 指令碼：

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

套用切面

執行 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 代理提供明確的結構化規則。
執行 apply_governance.sh 指令碼。這項指令碼會逐一檢查 BigQuery 資料表，並使用 gcloud CLI 將 YAML 酬載中的中繼資料「蓋印」到每個資料表上。
```
chmod +x ./apply_governance.sh
./apply_governance.sh
```

驗證中繼資料

繼續操作前，請確認指令碼已正確套用各個層面。

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

您已成功使用中繼資料區分這些資料表，並為 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設定檔具有邏輯，可將「我需要安全資料」等宣告式規則轉換為精確的搜尋查詢，只傳回具有正確治理標籤的資料表。

目前設定檔只是範本，您需要在規則中加入特定 Google Cloud 專案 ID，這樣執行 CLI 時，系統才能正確指定受管理資料。

將 PROJECT_ID 新增至設定檔。

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

如要查看變更並瞭解資料環境的運作方式，請快速瀏覽 GEMINI.md 檔案：
```
cat GEMINI.md
```
請注意，檔案會將規則分成第 1 階段和第 2 階段。這會強制執行嚴格的作業順序。服務專員必須先尋找正確的控管標籤 (第 1 階段)，才能存取資料本身 (第 2 階段)。這種「先搜尋」的邏輯可避免代理程式猜測表格名稱，或從未經查證的來源生成錯誤答案。

請確認第 2 階段包含實際 Google Cloud 專案 ID。如果這項資訊有誤，代理程式就不知道該從何處尋找資料。

啟動 Gemini CLI 並測試情境

開始新的 Gemini 工作階段。由於您位於專案資料夾中，CLI 會自動偵測並載入本機 GEMINI.md 做為系統環境。

gemini

驗證安裝

確認 Knowledge Catalog 擴充功能已啟用。dataplex 應該會顯示在已設定的 MCP 伺服器工具清單中。

/mcp desc

立即體驗

現在來看看資料環境的實際運作情形。逐一將這些提示貼到 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。

情境 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 能否找到一些實驗性機器學習工作的原始沙箱資料。

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

清除所用資源

如要避免產生週期性費用，請按照下列步驟操作：

刪除 Terraform 資源。

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

解除安裝 Knowledge Catalog 擴充功能，並移除本機的試用檔案。
```
gemini extensions uninstall dataplex
cd ~
rm -rf ~/devrel-demos
```

結論

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