使用 Gemini CLI 建構脈絡資料集

預覽

這項功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》，以及《生成式 AI 預先發布版產品附加條款》。正式發布前功能是依「原樣」提供，支援服務可能受限。 詳情請參閱推出階段說明。

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

如要瞭解內容集，請參閱「內容集總覽」。

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

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

事前準備

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

啟用必要服務

為專案啟用下列服務：

• Data Analytics API with Gemini
• Gemini for Google Cloud API
• 知識目錄 API

準備 AlloyDB for PostgreSQL 叢集、執行個體和資料庫

請確認您有權存取現有的 AlloyDB 叢集和執行個體，或建立新的叢集和執行個體。
如要完成本教學課程，您必須在 AlloyDB 執行個體中建立資料庫。 詳情請參閱「建立資料庫」。

必要角色和權限

• 在資料庫層級將 Identity and Access Management (IAM) 使用者或服務帳戶新增至叢集。詳情請參閱「管理資料庫使用者」。
• 在專案層級將 alloydb.databaseUser、serviceusage.serviceUsageConsumer 和 geminidataanalytics.queryDataUser 角色授予 IAM 使用者。詳情請參閱「為專案新增 IAM 政策繫結」。

授予 AlloyDB for PostgreSQL 執行個體 executesql 權限

如要將 executesql 權限授予 AlloyDB for PostgreSQL 執行個體，並將 data_api_access 執行個體設定設為 ALLOW_DATA_API 值，請使用下列 curl 指令：

   curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     https://alloydb.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/clusters/CLUSTER_ID/instances/INSTANCE_ID?updateMask=dataApiAccess \
     -d '{
       "dataApiAccess": "ENABLED",
     }'

取代下列項目：

• PROJECT_ID： Google Cloud 專案的 ID。
• LOCATION：AlloyDB 叢集所在的區域。
• CLUSTER_ID：AlloyDB 叢集的 ID。
• INSTANCE_ID：AlloyDB 執行個體的 ID。

如要執行本教學課程中的步驟，請登入 Google Cloud，然後使用 IAM 驗證功能驗證資料庫。

準備環境

您可以在任何本機開發環境或 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. 安裝 DB Context Enrichment Gemini CLI 擴充功能：

   gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment

   注意： 安裝擴充功能時，必須提供 Gemini API 金鑰，才能向 Gemini API 進行驗證，並啟用內容生成功能。如要進一步瞭解如何找出 API 金鑰，請參閱「使用 Gemini API 金鑰」。

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 時所需的工具。擴充功能已預先安裝代理程式技能，可協助您產生設定。

注意： 如果未建立連線，擴充功能會傳回錯誤訊息，例如「Error Discovering tools from mcp_toolbox」，且無法產生內容。

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 檔案的形式撰寫脈絡資料。

注意： Gemini CLI 可以存取本機檔案，減少指定本機目錄中檔案確切位置等額外負擔。舉例來說，如果 Gemini CLI 工作流程中的某個步驟要求您提供 tools.yaml 檔案中的資訊，您可以問問 Gemini CLI use tools.yaml 或使用 look it up 等提示詞回覆。

生成指定範本

如要將特定查詢配對新增為查詢範本至內容集，可以使用 /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. 輸入 postgresql，選取 AlloyDB 做為資料庫引擎。

2. 輸入要使用的 PostgreSQL 版本。選取 default 即可選取 PostgreSQL 16。

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，必須啟用 pg_trgm 擴充功能。
     • SEMANTIC_SIMILARITY_MATCH：針對字串值進行語意搜尋。最適合跨語言和同義字搜尋。如需支援的型號清單，請參閱「支援的 Google 型號」。如要使用 SEMANTIC_SIMILARITY_MATCH，請務必啟用 vector 和 google_ml_integration 擴充功能。

   • 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 類似的內容集檔案會儲存在您執行指令的目錄中。

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

後續步驟

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