使用 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 政策绑定。
• 在项目级向 IAM 用户或服务帐号授予 cloudsql.studioUser、cloudsql.instanceUser 和 geminidataanalytics.queryDataUser 角色。如需了解详情，请参阅添加 项目的 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。

为值搜索准备数据库

如需使用语义和三元语法值搜索，您必须将 Cloud SQL for MySQL 实例配置为支持向量嵌入和 n-gram 索引。

1. 如需让 Cloud SQL for MySQL 实例执行语义值搜索，您必须启用以下标志。

   1. 启用 cloudsql_vector 标志。

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

   2. 启用 enable-google-ml-integration 标志，以允许 Cloud SQL for MySQL 实例与 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. 如需让 Cloud SQL for MySQL 实例执行三元语法值搜索，请执行以下步骤。

   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 进行验证。
• DB Context Enrichment 扩展程序：使用凭据进行身份验证并调用 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-gram 索引。
     • 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 中创建或删除上下文集
• 了解如何测试上下文集