使用 Gemini CLI 建構脈絡資料集

本文說明如何使用 Gemini CLI 和 MCP 工具箱建構代理程式脈絡資料檔案。這些檔案包含範本、層面和值搜尋，可提供從自然語言生成 SQL 查詢的背景資訊。您也會使用 DB Context Enrichment 擴充功能。

如要建構代理程式結構定義檔案，請執行下列高階步驟：

• 準備環境
• 生成指定範本
• 生成目標層面
• 產生目標值搜尋
• 選用。大量生成範本

事前準備

建立代理程式前，請先完成下列先決條件。

啟用必要服務

• Data Analytics API with Gemini
• Gemini for Google Cloud API
• Dataplex Universal Catalog API

準備 Cloud SQL 執行個體

• 請確認您有權存取現有的 Cloud SQL 執行個體，或建立新的執行個體。 詳情請參閱「為 Cloud SQL 建立執行個體」。
• 請務必在執行個體中建立資料庫，並在其中建立資料表。詳情請參閱在 Cloud SQL 執行個體上建立資料庫。

必要角色和權限

• 在執行個體層級新增 IAM 使用者或服務帳戶。詳情請參閱「為使用者、服務帳戶或群組新增 IAM 政策繫結」。
• 在專案層級將 cloudsql.studioUser、cloudsql.instanceUser 和 geminidataanalytics.queryDataUser 角色授予 IAM 使用者或服務帳戶。詳情請參閱「為專案新增 IAM 政策繫結」。
• 您必須請具備權限的使用者將資料庫權限授予 IAM 使用者或服務帳戶。
  
  GRANT SELECT PRIVILEGES ON * TO "IAM_USERNAME";
  
  詳情請參閱「將資料庫權限授予個別 IAM 使用者或服務帳戶」。

授予 Cloud SQL 執行個體 executesql 權限

gcloud config set project PROJECT_ID
gcloud components update
gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API

• PROJECT_ID： Cloud de Confiance by S3NS 專案的 ID。
• INSTANCE_ID：Cloud SQL 執行個體的 ID。

準備資料庫以進行值搜尋

如要使用語意和三元值搜尋，您必須設定 MySQL 適用的 Cloud SQL 執行個體，支援向量嵌入和 n 元索引。

1. 如要讓 MySQL 適用的 Cloud SQL 執行個體執行語意值搜尋，請啟用下列標記。

   1. 啟用 cloudsql_vector 旗標。

      gcloud sql instances patch INSTANCE_NAME --database-flags=cloudsql_vector=on
      

   2. 啟用 enable-google-ml-integration 旗標，允許 MySQL 適用的 Cloud SQL 執行個體與 Vertex AI 整合。

      gcloud sql instances patch INSTANCE_NAME --enable-google-ml-integration
      

   3. 建立向量資料欄來儲存城市嵌入

      ALTER TABLE `airports` 
      ADD COLUMN `city_embedding` VECTOR(768);
      

   4. 生成及儲存城市名稱的向量嵌入

      UPDATE `airports` 
      SET `city_embedding` = mysql.ml_embedding('text-embedding-005', `city`) 
      WHERE `city` IS NOT NULL;
      

2. 如要讓 MySQL 適用的 Cloud SQL 執行個體執行三元值搜尋，請按照下列步驟操作。

   1. 啟用 ngram_token_size 旗標。

      gcloud sql instances patch INSTANCE_NAME --database-flags=ngram_token_size=3
      

   2. 為機場名稱建立三元組比對的 FULLTEXT 索引

      CREATE FULLTEXT INDEX `idx_ngram_airports_name` 
      ON `airports`(`name`) 
      WITH PARSER ngram;
      

準備環境

您可以從任何本機開發環境或 IDE 建構代理程式內容檔案。如要準備環境，請執行下列步驟：

• 安裝 Gemini CLI
• 安裝 DB Context Enrichment 擴充功能
• 設定資料庫連線

安裝 Gemini CLI

如要安裝 Gemini CLI，請參閱「開始使用 Gemini CLI」。

安裝 DB Context Enrichment MCP 擴充功能

DB Context Enrichment 擴充功能提供引導式互動工作流程，可從資料庫結構定義產生結構化 NL2SQL 內容。

如要進一步瞭解如何安裝 DB Context Enrichment 擴充功能，請參閱「DB Context Enrichment 擴充功能」。

如要安裝 DB Context Enrichment 擴充功能，請按照下列步驟操作：

1. 安裝 MCP Toolbox Gemini CLI 擴充功能：

   gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox

2. (選用) 更新 DB Context Enrichment 擴充功能。

   如要確認已安裝的擴充功能版本，請執行下列指令：

   gemini extensions list

   確認版本為 0.4.2 以上。如要更新 DB Context Enrichment 擴充功能，請執行下列指令：

     gemini extensions update mcp-db-context-enrichment

   如要更新 DB Context Enrichment 擴充功能或取代 GEMINI_API_KEY，請執行下列指令：

   gemini extensions config mcp-db-context-enrichment GEMINI_API_KEY

   將 GEMINI_API_KEY 替換成您的 Gemini API 金鑰。

設定資料庫連線

擴充功能需要資料庫連線，才能產生用於擷取結構定義和執行 SQL 陳述式的內容。如要讓擴充功能與資料庫互動，請設定驗證憑證，並定義資料庫來源和工具。

設定應用程式預設憑證

您必須設定應用程式預設憑證 (ADC)，為兩個主要元件提供使用者憑證：

• Toolbox MCP 伺服器：使用憑證連線至資料庫、擷取結構定義，並執行 SQL 進行驗證。
• 資料庫內容擴充功能：使用憑證驗證並呼叫 Gemini API。

在終端機中執行下列指令來驗證身分：

gcloud auth application-default login

設定 tools.yaml 檔案

擴充功能需要資料庫連線才能生成脈絡，這項功能由 MCP Toolbox 支援，並定義在 tools.yaml 設定檔中。

tools.yaml 檔案會指定資料庫來源，以及擷取結構定義或執行 SQL 時所需的工具。擴充功能已預先安裝代理程式技能，可協助您產生設定。

1. 啟動 Gemini CLI：

   gemini

2. 在 Gemini CLI 中輸入以下內容，確認技能已啟用：

   /skills

3. 輸入提示，例如「help me setup the database connection」。這項技能會引導您在目前的工作目錄中建立 tools.yaml 檔案。

4. 在 Gemini CLI 中執行下列指令，將 tools.yaml 設定套用至 Toolbox MCP 伺服器。

   /mcp reload

如要進一步瞭解如何手動設定 tools.yaml 檔案，請參閱「MCP Toolbox 設定」。

生成背景資訊

先前安裝的擴充功能可讓 Gemini CLI 協助您以 JSON 檔案的形式撰寫脈絡資料。

生成指定範本

如要將特定查詢配對新增為查詢範本至內容集，可以使用 /generate_targeted_templates 指令。如要進一步瞭解範本，請參閱「情境集總覽」

如要將查詢範本新增至內容集，請按照下列步驟操作：

1. 在相同目錄中啟動 Gemini CLI：

   gemini

2. 完成 Gemini CLI 驗證設定。

3. 確認 MCP 工具箱和資料庫擴充功能已可供使用：

   /mcp reload

4. 執行 /generate_targeted_templates 指令：

   /generate_targeted_templates

5. 輸入要新增至查詢範本的自然語言查詢。

6. 在查詢範本中輸入對應的 SQL 查詢。

7. 查看生成的查詢範本。您可以將查詢範本儲存為內容集檔案，或附加至現有的內容集檔案。

與 my-cluster-psc-primary_postgres_templates_20251104111122.json 類似的內容集檔案會儲存在您執行指令的目錄中。

如要進一步瞭解內容集檔案和查詢範本，請參閱「內容集總覽」。

生成目標層面

如要將特定查詢配對新增為內容集檔案的構面，可以使用 /generate_targeted_facets 指令。

如要將構面新增至內容集檔案，請按照下列步驟操作：

1. 執行 /generate_targeted_facets 指令：

   /generate_targeted_facets

2. 輸入要新增至查詢範本的自然語言查詢。

3. 在查詢範本中輸入對應的 SQL 查詢。

4. 查看生成的構面。您可以將構面儲存至內容集檔案，或附加至現有的內容集檔案。

與 my-cluster-psc-primary_postgres_templates_20251104111122.json 類似的內容集檔案會儲存在您執行指令的目錄中。

如要進一步瞭解內容集檔案和構面，請參閱「內容集總覽」

生成值搜尋查詢

如要產生值搜尋，指定系統應如何搜尋及比對概念類型中的特定值，可以使用 /generate_targeted_value_searches 指令。

請務必完成「準備資料庫以進行值搜尋」中的步驟。

如要產生價值指數，請按照下列步驟操作：

1. 執行 /generate_targeted_value_searches 指令：

   /generate_targeted_value_searches

1. 輸入 mysql，選取 MySQL 做為資料庫引擎。選取「預設」即可選取 MySQL 8.0。

1. 輸入值搜尋設定，如下所示：

   Table name: TABLE_NAME
   Column name: COLUMN_NAME
   Concept type: CONCEPT_TYPE
   Match function: MATCH_FUNCTION
   Description: DESCRIPTION
   

   更改下列內容：

   • TABLE_NAME：與概念類型相關聯的資料欄所在資料表。
   • COLUMN_NAME：與概念類型相關聯的資料欄名稱。
   • CONCEPT_TYPE：要定義的概念類型，例如 City name。

   • MATCH_FUNCTION：用於搜尋值的比對函式。你可以使用下列其中一個函式：

     • EXACT_STRING_MATCH：用於完全比對兩個字串值。最適合用於不重複 ID、代碼和主鍵。
     • TRIGRAM_STRING_MATCH：用於計算正規化三連字距離的模糊比對。最適合使用者搜尋和更正名稱。如要使用 TRIGRAM_STRING_MATCH，您必須準備資料庫，以支援 n 元索引。
     • SEMANTIC_SIMILARITY_MATCH：用於字串值的語意搜尋。最適合跨語言和同義字搜尋。如需支援的機型清單，請參閱「支援的 Google 機型」。如要使用 SEMANTIC_SIMILARITY_MATCH，請先準備資料庫，支援向量嵌入。

   • DESCRIPTION：(選用) 值搜尋查詢的說明。

2. 視需要新增其他值搜尋。如果略過新增額外值索引，系統會直接進入下一個步驟，根據範本產生 SQL。

3. 查看生成的價值搜尋。您可以將內容集另存為內容集檔案，或附加至現有的內容集檔案。

與 my-cluster-psc-primary_postgres_templates_20251104111122.json 類似的內容集檔案會儲存在您執行指令的目錄中。

如要進一步瞭解值索引，請參閱「內容集總覽」

選用：產生大量範本

如要根據資料庫結構定義和資料自動產生內容集檔案，可以使用 /generate_bulk_templates 指令。

如要自動產生大量範本，請按照下列步驟操作：

1. 執行 /generate_bulk_templates 指令：

   /generate_bulk_templates

2. 根據資料庫結構定義，以範本為基礎的 SQL 生成功能會引導您完成一系列問題，驗證資料庫資訊並授予存取資料庫結構定義的權限。

3. 查看生成的查詢範本。您可以核准範本，或更新要修訂的查詢配對。

4. 輸入要新增至查詢範本的自然語言查詢。

5. 在查詢範本中輸入對應的 SQL 查詢。

6. 查看生成的查詢範本。您可以將查詢範本儲存為結構定義檔案，或附加至現有結構定義檔案。

7. 核准查詢範本後，您可以建立新的範本檔案，或將查詢配對附加到現有範本檔案。查詢範本會以 JSON 檔案格式儲存在本機目錄中。

與 my-cluster-psc-primary_postgres_templates_20251104111122.json 類似的內容集檔案會儲存在您執行指令的目錄中。

如要進一步瞭解內容集檔案，請參閱「內容集總覽」。

後續步驟

• 進一步瞭解情境集。
• 瞭解如何在 Cloud SQL Studio 中建立或刪除內容集
• 瞭解如何測試內容集