使用 Gemini CLI 建構環境

本文說明如何使用 Gemini CLI 和 MCP 工具箱建構代理程式環境定義檔案。這些檔案包含範本和層面，可提供從自然語言生成 SQL 查詢的背景資訊。您也會使用 DB Context Enrichment MCP 伺服器。

如要瞭解資料代理程式，請參閱「資料代理程式總覽」。

如要建構代理程式環境，請執行下列高階步驟：

  • 準備環境
  • 生成目標範本
  • 生成目標層面
  • 選用。產生大量範本

事前準備

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

準備 Spanner 執行個體

  • 請確認 Spanner 執行個體是否可用。詳情請參閱「建立執行個體」。
  • 在資料庫中填入使用者想存取的資料和結構定義。

必要角色和權限

準備環境

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

  • 安裝 Gemini CLI
  • 安裝及設定 MCP Toolbox
  • 安裝及設定 DB Context Enrichment MCP 伺服器

安裝 Gemini CLI

如要安裝 Gemini CLI，請參閱「開始使用 Gemini CLI」。請務必在獨立目錄中安裝 Gemini CLI，這個目錄也會用於安裝 MCP 工具箱和 DB Context Enrichment MCP 伺服器。

安裝及設定 MCP Toolbox

  1. 在安裝 Gemini CLI 的相同目錄中，安裝 MCP Toolbox Gemini CLI 擴充功能：

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

  2. 在安裝 MCP Toolbox 的相同目錄中，建立 tools.yaml 設定檔，以設定資料庫連線：

      sources:
    my-spanner-source:
      kind: spanner
      project: PROJECT_ID
      instance: INSTANCE_ID
      database: DATABASE_ID

    更改下列內容：

    • PROJECT_ID： Google Cloud 專案 ID。
    • INSTANCE_ID：Spanner 執行個體的 ID。
    • DATABASE_ID：要連線的資料庫名稱。

  3. 確認 tools.yaml 檔案設定正確無誤：

    ./toolbox --tools-file "tools.yaml"

安裝 DB Context Enrichment MCP 伺服器

DB Context Enrichment MCP 伺服器提供引導式互動工作流程，可從資料庫結構定義產生結構化 NL2SQL 範本。這項工具依賴 MCP Toolbox 擴充功能來連線至資料庫。如要進一步瞭解如何安裝 DB Context Enrichment MCP 伺服器，請參閱「DB Context Enrichment MCP 伺服器」。

如要安裝 DB Context Enrichment MCP 伺服器，請按照下列步驟操作：

  1. 在安裝 Gemini CLI 的相同目錄中，安裝 uv Python 套件安裝程式。

      pip install --user pipx
  pipx ensurepath
  pipx install uv

  2. 安裝 DB Context Enrichment MCP 伺服器。

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

伺服器會使用 Gemini API 生成內容。請務必將 API 金鑰匯出為環境變數。如要進一步瞭解如何找出 API 金鑰，請參閱「使用 Gemini API 金鑰」。

如要匯出 Gemini API 金鑰，請執行下列指令：

export GEMINI_API_KEY="YOUR_API_KEY"

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

生成目標範本

如要將特定查詢配對新增為代理程式環境的查詢範本，可以使用 /generate_targeted_templates 指令。如要進一步瞭解範本，請參閱「資料代理程式總覽」。

如要將查詢範本新增至代理程式環境，請執行下列步驟：

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

    gemini

  2. 完成 Gemini CLI 驗證設定。

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

    /mcp list

  4. 執行 /generate_targeted_templates 指令：

    /generate_targeted_templates

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

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

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

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

如要進一步瞭解內容檔案和查詢範本，請參閱「代理程式內容」。

生成目標層面

如要將特定查詢配對新增為代理程式內容檔案的構面，可以使用 /generate_targeted_fragments 指令。如要進一步瞭解層面，請參閱「資料代理程式總覽」。

如要將構面新增至代理程式內容，請執行下列步驟：

  1. 執行 /generate_targeted_fragments 指令：

    /generate_targeted_fragments

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

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

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

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

如要進一步瞭解代理程式結構定義檔案，請參閱「代理程式結構定義」。

後續步驟