使用 Gemini CLI 构建上下文集

MySQL | PostgreSQL | SQL Server

本文档介绍了如何创建和优化上下文，以便您提高 QueryData 的准确性，从而构建数据代理应用。通过在 Gemini CLI 中使用数据库上下文扩充扩展程序，您可以访问一套可自动创建和优化上下文集的开发者工具。

如需了解上下文集，请参阅上下文集概览。

该扩展程序可自动创建和优化上下文集，具体顺序如下：

了解应用：提取数据库架构、应用代码和业务需求等制品，为数据智能体建立基础业务逻辑。
创建数据集：整理一个包含代表性自然语言问题及其预期 SQL 答案的评估数据集。建立此基准数据集对于衡量性能和跟踪随时间推移的改进至关重要。
生成初始上下文：自动生成直接从数据库架构和可选应用制品派生的基准上下文集，以便快速开始。
以迭代方式优化上下文：评估数据集，找出特定查询失败的原因。Gemini 会使用自动推理功能来建议有针对性的上下文更新，从而逐步提高准确性。

虽然该扩展程序提供了强大的自动化工作流程，但它可根据您的需求进行调整。您可以绕过自动化功能，以更精细的级别创作和插入上下文。通过使用专门的生成命令，您可以控制高质量模板、分面和值搜索查询的创建。

准备工作

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

启用必需服务

为您的项目启用以下服务：

准备 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` 权限

如需向 Cloud SQL 实例授予 executesql 权限并启用 Cloud SQL Data API，请运行以下命令：

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

替换以下内容：

PROJECT_ID：您的 Google Cloud 项目的 ID。
INSTANCE_ID：Cloud SQL 实例的 ID。

如需执行本教程中的步骤，请登录 Google Cloud，然后使用 IAM 身份验证对数据库进行身份验证。

为值搜索准备数据库

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

如需使 Cloud SQL for MySQL 实例能够执行语义值搜索，请启用以下标志。

启用 cloudsql_vector 标志。

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

启用 enable-google-ml-integration 标志，以允许 Cloud SQL for MySQL 实例与 Vertex AI 集成。
```
gcloud sql instances patch INSTANCE_NAME --enable-google-ml-integration
```

创建用于存储城市嵌入的向量列

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

为城市名称生成和存储向量嵌入

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

如需使 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
安装“数据库上下文丰富化”扩展程序
设置数据库连接

安装 Gemini CLI

如需安装 Gemini CLI，请参阅开始使用 Gemini CLI。

安装“数据库上下文丰富化”扩展程序

DB 上下文丰富扩展程序提供了一个引导式交互式工作流，用于生成结构化上下文集并对其进行迭代。

如需详细了解如何安装“数据库上下文丰富化”扩展程序，请参阅“数据库上下文丰富化”扩展程序。

如需安装“数据库上下文丰富化”扩展程序，请完成以下步骤：

安装“数据库上下文丰富化”Gemini CLI 扩展程序：
```
gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment
```
注意：扩展程序在安装时需要 Gemini API 密钥，以便通过 Gemini API 进行身份验证并启用上下文生成功能。如需详细了解如何查找 API 密钥，请参阅使用 Gemini API 密钥。
（可选）更新“DB Context Enrichment”扩展程序。

如需验证已安装的扩展程序版本，请运行以下命令：
```
gemini extensions list
```
确保版本为 0.5.0 或更高版本。如需更新“数据库上下文丰富化”扩展程序，请运行以下命令：
```
  gemini extensions update mcp-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

配置数据库连接文件

该扩展程序需要数据库连接才能生成上下文，而 MCP Toolbox 支持此功能，并在配置文件中定义了数据库连接。

配置文件用于指定数据库来源以及提取架构或执行 SQL 所需的工具。数据库上下文丰富化扩展程序随附预安装的代理技能，可帮助您生成配置。

启动 Gemini CLI：
```
gemini
```
在 Gemini CLI 中输入以下内容，验证技能是否处于有效状态：
```
/skills
```
输入提示，例如 help me set up the database connection。该技能会引导您在当前工作目录中创建名为 autoctx/tools.yaml 的配置文件。
在 Gemini CLI 中运行以下命令，将 tools.yaml 配置应用于 Toolbox MCP 服务器。
```
/mcp reload
```

如需详细了解如何手动配置数据库配置文件，请参阅 MCP Toolbox 配置。

通过自动化工作流生成上下文

通过上下文工程提高准确性通常是一个手动试错的过程。开发者通常会猜测查询失败的原因，然后编写修复程序并手动进行测试。Gemini CLI 中的“数据库上下文丰富”扩展程序可自动执行此改进流程。它使用评估数据集（包含问题及其正确的 SQL 答案）来衡量性能，并确定某些查询失败的原因。然后，Gemini 会自动建议进行特定的上下文更新，以提高准确性。完成以下步骤，系统性地提高数据代理的准确性。

初始化工作区

初始化命令会设置本地工作区，包括数据库连接配置和实验目录。此专用工作区可确保所有配置、实验和生成的文件都集中在一个位置，从而更轻松地管理和跟踪情境优化工作。

创建一个新目录，用作迭代优化流程的工作区，然后导航到该目录。
在新目录中启动 Gemini CLI：
```
gemini
```

运行初始化命令：

/autoctx:init

如果尚未设置数据库连接，该代理会引导您创建 tools.yaml 文件，还会初始化本地 state.md 文件和 experiments 目录。

初始化后，您的工作区应如下所示：

my-workspace/
└── autoctx/
    ├── tools.yaml          # Database connection and tools configuration
    ├── state.md            # Local file to track the experiment progress
    └── experiments/        # Dedicated directory for future experiment-specific files

准备和扩充数据集

为了让 Gemini 能够系统地对您的上下文集进行优化，请准备一个包含代表性自然语言问题及其预期 SQL 答案（“黄金答案”）的评估数据集，以评估您的上下文集。高质量的评估数据集对于衡量性能、识别查询失败情况以及跟踪随时间推移而取得的改进至关重要。数据集应为 JSON 文件，其中包含自然语言问题 (NLQ) 和涵盖数据应用中目标用例的标准 SQL。

正确格式的示例如下：

[
  {
    "id": "example_001",
    "nlq": "What is the total revenue for the top 5 products?",
    "golden_sql": "SELECT product_id, sum(net_revenue) FROM sales GROUP BY product_id ORDER BY sum(net_revenue) DESC LIMIT 5;"
  }
]

Gemini CLI 扩展程序包含一个提供的命令，该命令可创建并扩缩一小部分基准问题，以用于评估。

前往您的工作区文件夹。
在新目录中启动 Gemini CLI：
```
gemini
```
在 Gemini CLI 中运行 /autoctx:generate-dataset 命令：
```
/autoctx:generate-dataset
```
当代理提示您时，请提供一个种子，即一个初始示例或一小组示例，用于指导生成更大的数据集。种子可以是以下任一值：
- 一个小型黄金标准数据集文件
- 特定的自然语言到 SQL (NL2SQL) 黄金对
例如，您可以提供以下 NL2SQL 标准答案对作为种子：
```
Question: "What are the names of all airports in California?"
SQL: "SELECT name FROM airports WHERE state = 'CA';"
```
代理会提示用户授予权限，以便使用 execute_sql 工具验证语法和执行有效性。这是可选步骤。
代理会询问是否要使用种子数据中的变体（应用不同的过滤条件、同义词等）来扩充数据集。这是可选步骤。

代理使用 execute_sql 工具针对数据库运行新生成的 SQL 查询，以验证语法和执行有效性，然后再向您显示这些查询。

有选择地接受、修改或拒绝建议。获批的配对会自动保存到本地，可随时用于评估。

my-workspace/
└── autoctx/
    ├── tools.yaml
    ├── state.md
    ├── golden.json  # Generated dataset
    └── experiments/

创建初始上下文集

生成初始上下文集可为评估和迭代改进提供基准。此步骤使用数据库架构和应用制品来创建反映业务逻辑的基础上下文。

Gemini CLI 扩展程序包含一个预构建的命令，可根据数据库架构和有关数据代理应用的信息（例如应用代码或包含业务需求信息的文件）生成一组初始模板和分面。如需从头开始生成基准上下文集，请执行以下操作：

前往您的工作区文件夹。
在新目录中启动 Gemini CLI：
```
gemini
```
在 Gemini CLI 中运行 /autoctx:bootstrap 命令：
```
/autoctx:bootstrap
```
一般来说，代理会提供以下帮助。
- 代理会提示您指定实验名称。实验是一个专用工作区文件夹，用于封装数据库上下文配置的完整生命周期，跟踪其基准状态、评估测试结果以及后续的迭代爬山改进。此名称用于整理工作区中实验文件夹下的所有生成的文件；请选择一个具有描述性且易于记忆的名称。
- 代理会从目标数据库中提取并列出架构，并提示您视需要提供其他资源或文件。如果架构很复杂，智能体还会提示您选择特定的架构或表作为初始上下文集。如果您未指定任何表，系统会假定当前数据库架构中的所有表。

查看并视需要优化生成的上下文集。优化后，代理会在工作区文件夹下的本地磁盘上直接生成 JSON 上下文的描述文件：

my-workspace/
└── autoctx/
    ├── tools.yaml
    ├── state.md
    └── experiments/
        └── my-experiment/
            └── bootstrap_context.json  # The generated initial context set file

按照相关说明从 Cloud SQL Studio 上传上下文。

评估情境效果

Gemini CLI 扩展程序包含一个内置命令，可用于使用黄金数据集评估数据代理。该扩展程序与 Evalbench 集成，通过使用黄金集中指定的问题查询代理的 QueryData API 来执行评估，然后将生成的 SQL 及其执行结果与黄金 SQL 进行比较。评估是了解当前上下文集效果的关键。通过将生成的 SQL 与黄金数据集进行比较，您可以找出失败的特定查询，并确定需要改进上下文的方面。

如需衡量当前上下文的效果与黄金数据集的对比情况，请执行以下操作：

将 Cloud SQL Studio 中的上下文上传到目标上下文集以进行评估。如果待评估的上下文未上传，则此步骤为可选步骤。
前往您的工作区文件夹。
在文件夹中启动 Gemini CLI：
```
gemini
```
在 Gemini CLI 中运行 /autoctx:evaluate 命令：
```
/autoctx:evaluate
```

提供黄金数据集的路径、用于生成评估配置和运行评估的上下文集 ID，以及指定的输出目录。

完成后，智能体会在实验文件夹中以文件的形式生成评估结果，并总结评估结果。

（可选）您可以手动检查详细评估报告中的评估结果，该报告以 CSV 文件的形式存储在实验文件夹中。

my-workspace/
└── autoctx/
    ├── tools.yaml
    ├── state.md
    ├── golden.json
    └── experiments/
        └── my-experiment/
            └── bootstrap_context.json
            └── eval_configs/
                └── <configs_for_eval_run>/
            └── eval_reports/
                └── <eval_id>/
                    └── eval_report/
                        ├── configs.csv
                        ├── evals.csv
                        ├── scores.csv
                        └── summary.csv

执行差距分析和情境优化

作为优化上下文集的重要一步，Gemini CLI 扩展程序包含一个内置命令，可用于对现有上下文集执行差距分析，并提出可改进其质量的更改。差距分析对于了解特定查询失败的原因以及可以改进上下文的方面至关重要。根据此分析，Gemini 会使用自动推理功能建议有针对性的上下文更新（例如新模板或分面），以解决这些失败问题并迭代提高查询准确率。

前往您的工作区文件夹。
在文件夹中启动 Gemini CLI：
```
gemini
```

在 Gemini CLI 中运行 /autoctx:hillclimb 命令：

/autoctx:hillclimb

智能体可自动识别最适合爬山算法的评估结果和基本背景信息，如果存在多个选项，则会请求用户确认。

如果没有可用的评估结果，代理会提示您运行评估，并设置数据集和上下文。

准备就绪后，该智能体将读取评估结果和现有上下文集，然后生成差距分析报告。

my-workspace/
└── autoctx/
    ├── tools.yaml
    ├── state.md
    ├── golden.json
    └── experiments/
        └── my-experiment/
            └── bootstrap_context.json
            └── eval_configs/
            └── eval_reports/
            └── hillclimb/
                └── gap_analysis_v1.md

代理通过提出新的规范性模板和方面来制定修复方案，还可以通过 execute_sql 针对数据库测试 SQL。

准备就绪后，系统会在本地生成新的改进版上下文 JSON 文件，同时保留基准上下文 JSON 文件。

my-workspace/
└── autoctx/
    ├── tools.yaml
    ├── state.md
    ├── golden.json
    └── experiments/
        └── my-experiment/
            └── bootstrap_context.json
            └── eval_configs/
            └── eval_reports/
            └── hillclimb/
                ├── gap_analysis_v1.md
                └── improved_context_v1.md

按照说明将上下文从 Cloud SQL Studio 上传到目标上下文集，以便开始下一轮迭代（从评估开始）。

限制

自动化工作流仅支持生成和优化模板和分面。如果您想为数据代理配置值搜索，请参阅生成值搜索查询。

生成有针对性的上下文

如果您希望采用更自定义的方法来创建上下文，可以使用“数据库上下文丰富”扩展程序手动生成特定的上下文元素。以下命令将引导您以 JSON 文件形式编写上下文，从而对模板、分面和值搜索查询生成进行精细控制。

生成有针对性的模板

如需将特定的查询-SQL 对作为查询模板添加到上下文集中，请使用 /generate_targeted_templates 命令。

如需详细了解上下文集文件和查询模板，请参阅上下文集概览。

如需向上下文集添加查询模板，请完成以下步骤：

在 Gemini CLI 中运行 /generate_targeted_templates 命令：
```
/generate_targeted_templates
```
输入要添加到查询模板中的自然语言查询。
为查询模板输入相应的 SQL 查询。
查看生成的查询模板。您可以将查询模板保存为上下文集文件，也可以将其附加到现有上下文集文件。

上下文集文件（例如 my-cluster-psc-primary_postgres_context_set_20251104111122.json）会保存在您运行命令的目录中。

如需将特定查询添加到 SQL 条件，作为上下文集文件的方面，请使用 /generate_targeted_facets 命令。

如需详细了解上下文集文件和方面，请参阅上下文集概览

如需向上下文集文件添加 facet，请完成以下步骤：

在 Gemini CLI 中运行 /generate_targeted_facets 命令：
```
/generate_targeted_facets
```
输入要添加到分面的自然语言 intent。
将相应的 SQL 代码段输入到分面中。
查看生成的方面。您可以将分面保存到上下文集文件，也可以将其附加到现有上下文集文件。

上下文集文件（例如 my-cluster-psc-primary_postgres_context_set_20251104111122.json）会保存在您运行命令的目录中。

生成值搜索查询

如需生成值搜索，以指定系统如何在概念类型中搜索和匹配特定值，请使用 /generate_targeted_value_searches 命令。

如需详细了解值索引，请参阅上下文集概览

完成准备数据库以进行值搜索中的步骤。

如需生成值索引，请完成以下步骤：

运行 /generate_targeted_value_searches 命令：
```
/generate_targeted_value_searches
```
输入 mysql 以选择 MySQL 作为数据库引擎。选择“默认”即可选择 MySQL 8.0。
按如下方式输入值搜索配置：
```
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 模板适用于 MySQL 8.0.36 或更高版本。
  - SEMANTIC_SIMILARITY_MATCH：用于对字符串值进行语义搜索。最适合跨语言搜索和同义词搜索。如需查看支持的型号列表，请参阅支持的 Google 型号。如需使用 SEMANTIC_SIMILARITY_MATCH，请准备数据库以支持向量嵌入。
- DESCRIPTION：（可选）值搜索查询的说明。
根据需要添加其他值搜索。如果您跳过添加其他值索引，基于模板的 SQL 生成将进入下一步。
查看生成的价值搜索。您可以将设置的上下文保存为上下文集文件，也可以将其附加到现有的上下文集文件中。

上下文集文件（例如 my-cluster-psc-primary_postgres_context_set_20251104111122.json）会保存在您运行命令的目录中。

使用 Gemini CLI 构建上下文集

准备工作

启用必需服务

准备 Cloud SQL 实例

所需的角色和权限

向 Cloud SQL 实例授予 `executesql` 权限

为值搜索准备数据库

准备环境

安装 Gemini CLI

安装“数据库上下文丰富化”扩展程序

设置数据库连接

配置应用默认凭据

配置数据库连接文件

通过自动化工作流生成上下文

初始化工作区

准备和扩充数据集

创建初始上下文集

评估情境效果

执行差距分析和情境优化

限制

生成有针对性的上下文

生成有针对性的模板

生成定向分面

生成值搜索查询

后续步骤

使用 Gemini CLI 构建上下文集 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

启用必需服务

准备 Cloud SQL 实例

所需的角色和权限

向 Cloud SQL 实例授予 executesql 权限

为值搜索准备数据库

准备环境

安装 Gemini CLI

安装“数据库上下文丰富化”扩展程序

设置数据库连接

配置应用默认凭据

配置数据库连接文件

通过自动化工作流生成上下文

初始化工作区

准备和扩充数据集

创建初始上下文集

评估情境效果

执行差距分析和情境优化

限制

生成有针对性的上下文

生成有针对性的模板

生成定向分面

生成值搜索查询

后续步骤

使用 Gemini CLI 构建上下文集

向 Cloud SQL 实例授予 `executesql` 权限