使用 Gemini CLI 构建上下文

本文档介绍了如何使用 Gemini CLI 和 MCP Toolbox 构建代理上下文文件。这些文件包含模板和方面，可为根据自然语言生成 SQL 查询提供上下文。您还将使用 DB Context Enrichment MCP 服务器。

如需了解数据代理，请参阅数据代理概览。

如需构建代理上下文，请执行以下高级别步骤：

  • 准备环境
  • 生成有针对性的模板
  • 生成目标分面
  • 可选。生成批量模板

准备工作

在创建代理之前，请完成以下前提条件。

准备 Spanner 实例

  • 确保 Spanner 实例可用。如需了解详情，请参阅创建实例。
  • 使用最终用户想要访问的数据和架构填充数据库。

所需的角色和权限

准备环境

您可以在任何本地开发环境或 IDE 中构建代理上下文文件。如需准备环境，请执行以下步骤：

  • 安装 Gemini CLI
  • 安装和设置 MCP Toolbox
  • 安装并设置数据库上下文扩充 MCP 服务器

安装 Gemini CLI

如需安装 Gemini CLI，请参阅开始使用 Gemini CLI。请确保将 Gemini CLI 安装在单独的目录中，该目录也用于安装 MCP Toolbox 和 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 工具箱的同一目录中创建一个 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"

安装数据库上下文丰富化 MCP 服务器

DB Context Enrichment MCP Server 提供了一个引导式交互式工作流，用于根据数据库架构生成结构化 NL2SQL 模板。它依赖于 MCP Toolbox 扩展程序来实现数据库连接。如需详细了解如何安装“数据库上下文丰富化”MCP 服务器，请参阅数据库上下文丰富化 MCP 服务器。

如需安装数据库上下文丰富化 MCP 服务器，请执行以下操作：

  1. 在安装 Gemini CLI 的同一目录下，安装 uv Python 软件包安装程序。

      pip install --user pipx
  pipx ensurepath
  pipx install uv

  2. 安装数据库上下文丰富化 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 类似的代理上下文文件会保存在您运行命令的目录中。

如需详细了解代理上下文文件，请参阅代理上下文。

后续步骤