Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

使用上下文工程代理构建上下文集

本文档介绍了如何创建和优化上下文集，以帮助在数据智能体应用中实现较高的 QueryData 查询准确率。上下文工程智能体可自动创建和优化上下文集，帮助您构建、评估和改进上下文集。

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

为了构建企业级数据应用，文本到查询模型的准确率通常需要达到接近 100% 的质量。生成的 SQL 不正确会影响应用的整体可用性和用户体验。若要获得可解释、与业务相关且准确度高的答案，需要进行上下文工程，即创建和迭代优化上下文以实现最佳准确度的过程。

通过为 QueryData 提供针对您的业务应用的上下文，您可以提供系统解析细微用户意图所需的精确业务规则。

上下文工程智能体

上下文工程智能体可自动执行此优化工作流。您可以与代理对话，以处理临时任务，从而优化上下文。以下列表提供了可用于指示智能体的自然语言提示示例，以及智能体如何响应的说明。请参考以下示例来构建和优化上下文：

失败分析提示示例：“更新上下文，以便我们正确识别‘迪士尼世界航班’等查询的机场。”代理会分析失败原因，推断差距，并建议添加适当的上下文项，例如值搜索查询。
符合情境的建议的提示示例：“阅读我的应用代码，并建议添加一些符合情境的建议。”智能体会解析代码，推断应用的领域，并建议哪些上下文项会相关。
批量处理的示例提示：“以下是 10 个问题和 SQL 查询示例。将它们转换为模板。”智能体会批量处理您的输入并更新上下文集。

黄金数据集的重要性

为了优化上下文，您必须首先创建一个与应用的自然语言输入相匹配的数据集。该代理可以帮助您构建此黄金数据集，其中包含用户问题及其预期的数据库查询。黄金数据集可让您：

建立查询性能基准。
根据标准答案数据库查询验证更新。
衡量各次迭代的准确率提升情况。

系统化的爬山过程

在系统化爬山法中，智能体通过评估黄金数据集、进行差距分析和更新，以迭代方式改进上下文集，从而将准确率提升至接近 100%。

自动生成基准上下文：创建从数据库架构和应用工件派生的起始上下文集。
爬山优化工作流：让智能体评估 QueryData 的准确率，对失败情况执行差距分析，并自动提出改进建议，以提高准确率。

下图展示了系统化爬山工作流：

迭代构建上下文的工作流。

准备工作

在使用上下文工程代理之前，请完成以下前提条件。

启用必需服务

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

准备 Cloud SQL 实例

确保您有权访问现有 Cloud SQL 实例或创建一个新实例。如需了解详情，请参阅为 Cloud SQL 创建实例。
确保在实例中创建数据库，以便在其中创建表。如需了解详情，请参阅在 Cloud SQL 实例上创建数据库。

所需的角色和权限

在实例级层添加 IAM 用户或服务账号。如需了解详情，请参阅向用户、服务账号或群组添加 IAM 政策绑定。
在项目级向 IAM 用户或服务账号授予 cloudsql.studioUser、cloudsql.instanceUser 和 geminidataanalytics.queryDataUser 角色。如需了解详情，请参阅为项目添加 IAM 政策绑定。
如需创建、上传和管理上下文集，请在项目级向 IAM 用户或服务账号授予 Dataplex Catalog Editor (roles/dataplex.catalogEditor) 或 Dataplex Catalog Admin (roles/dataplex.catalogAdmin) 角色。如需了解详情，请参阅上下文集权限。
您必须让特权用户向 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 实例执行三元组值搜索，请按照以下步骤操作：

启用 ngram_token_size 标志。

gcloud sql instances patch INSTANCE_NAME --database-flags=ngram_token_size=3

为机场名称的三元组匹配创建 FULLTEXT 索引：

CREATE FULLTEXT INDEX `idx_ngram_airports_name`
ON `airports`(`name`) 
WITH PARSER ngram;

准备环境

您可以在任何本地开发环境或 IDE 中构建上下文集文件。要准备环境，请完成以下步骤：

安装上下文工程代理
设置数据库连接

安装上下文工程代理

上下文工程代理运行 Model Context Protocol (MCP) 服务器，该服务器需要 uv 来管理底层 Python 软件包。

按照安装 uv 中的说明安装 uv。
验证 uv 是否已安装，并且可以从命令行访问：
```
uv --version
```

如需准备环境，请在所选智能体框架（例如 Antigravity CLI、Claude Code 或 Gemini CLI）中安装上下文工程智能体。

根据您选择的智能体 Harness，按照相应的安装步骤操作：

Antigravity CLI

如需在 Antigravity CLI 中安装上下文工程代理，请按以下步骤操作：

安装 Antigravity CLI。请参阅 Antigravity CLI 使用入门。
安装内容相关引擎智能体插件，其中包含用于生成上下文的工作流。将 VERSION 替换为所需的发布版本：
```
agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/VERSION
```
启动 Antigravity CLI：
```
agy
```

如需将插件更新到最新版本，请运行以下命令。将 VERSION 替换为所需的发布版本：

agy plugin uninstall google-cloud-db-context-engineering
agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/VERSION

Claude Code

如需在 Claude Code 中安装上下文工程代理，请按以下步骤操作：

添加插件市场：

/plugin marketplace add https://github.com/GoogleCloudPlatform/db-context-enrichment.git

安装插件：

/plugin install db-context-engineering@db-context-enrichment-marketplace

重新加载插件以使更改生效：
```
/reload-plugins
```

更新插件：

/plugin update db-context-engineering@db-context-enrichment-marketplace

Gemini CLI（已弃用）

如需在 Gemini CLI 中安装上下文工程代理，请按以下步骤操作：

安装 Gemini CLI。请参阅 Gemini CLI 使用入门。

安装扩展程序：

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

更新扩展程序：

gemini extensions update google-cloud-db-context-engineering

设置数据库连接

智能体需要数据库连接来提取架构，并且需要能够验证生成的 SQL 上下文的语法。如需让智能体与数据库交互，请配置身份验证凭证并定义数据库连接配置。

配置应用默认凭证

配置应用默认凭证 (ADC)，以提供用户凭证，用于从情境工程代理访问 Google Cloud 资源：

Toolbox MCP 服务器：使用凭据连接到数据库、提取架构并运行 SQL 进行验证。
Evalbench：使用凭证调用 QueryData 进行评估。

在终端中运行以下命令进行身份验证：

gcloud auth application-default login

配置数据库连接文件

智能体需要数据库连接才能生成上下文，MCP Toolbox 支持此功能，并在配置文件中定义了此功能。

配置文件指定了提取架构或执行 SQL 所需的数据库来源和工具。上下文工程智能体预装了智能体技能，可帮助您生成配置。

启动代理环境。
让代理帮助设置数据库连接，例如，提示“帮我设置数据库连接”。按照代理的说明，在当前工作目录中创建配置文件 autoctx/tools.yaml。
如需应用新的 tools.yaml 配置，请重新加载连接：
- 在 Antigravity CLI 中，运行 /mcp 并选择 toolbox 以重启。
- 在 Gemini CLI 中，运行 /mcp reload。
- 在 Claude Code 中，运行 /mcp，选择 toolbox，然后选择 Reconnect。

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

生成和优化上下文

上下文工程智能体提供了一组智能体技能和 MCP 工具，可增强编程智能体的上下文工程能力。您可以结合使用这些工具来生成基准、衡量有效性并以迭代方式应用改进。不过，您可以从工作流的任何阶段开始：

如果您已设置上下文，则可以直接进行评估。
如果您有想要修复的失败查询，可以直接进行差距分析。

每项功能都描述了代理的操作、应用场景和调用命令。

示例提示展示了如何使用自然语言向代理提问。如果代理需要更多详细信息才能完成请求，则会提示您进行澄清。

构建和扩展评估数据集

若要提升性能，您必须先对其进行衡量。如果没有黄金数据集（由用户问题及其预期 SQL 组成），上下文工程就缺乏系统验证。借助黄金数据集，每项更改都是可衡量的改进，您可以根据标准答案进行验证。

手动创建具有代表性的黄金数据集非常耗时，而且小型数据集可能会遗漏用户措辞的变化。智能体通过以下方式解决此问题：

正在根据您的数据库架构生成候选问题-SQL 对。
使用过滤条件变体、同义词和改写来扩展小型种子数据集。

（可选）您可以让代理针对数据库执行生成的 SQL。此验证可确认查询在添加到数据集之前能够成功执行。

该数据集是一个包含问题-SQL 对的 JSON 文件：

json
[
  {
    "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;"
  }
]

获批的配对会填充到工作区中的 autoctx/golden.json 文件中，以便进行评估。您可以提供现有文件，也可以以内嵌方式编写一些评估示例，供代理进行扩展。

您可以使用以下示例提示来指示智能体：

“根据我的架构生成评估数据集。”
“Here's a seed question and SQL. 将其扩展为更广泛的数据集，并验证查询是否运行。”

生成基准上下文集

为避免从头开始创建上下文，您可以让智能体从数据库架构和应用工件（例如业务规则、示例查询或 README 文件）中派生初始上下文集。虽然此基准上下文并非最终版本，但它提供了一个基于数据库模型的经过验证的起点。

您可以使用以下示例提示来指示智能体：

“根据我的架构生成上下文集。”
"Generate initial context using these schemas and the business rules in requirements.md."

代理会提示您为实验命名，以便整理生成的工件，并且如果您的数据库架构很大，代理可能会要求您缩小范围。如需使用 Cloud SQL Studio 上传上下文，请在代理生成 JSON 文件后按照说明操作。

评估上下文有效性

建立上下文集和黄金数据集后，您可以让智能体使用每个黄金问题查询数据智能体的 QueryData API，从而衡量上下文性能。智能体会使用 Evalbench 将生成的 SQL 及其执行结果与预期答案进行比较。

运行评估可提供以下信息：

定量指标（例如通过和失败结果以及汇总分数），用于跟踪上下文迭代的进度。
内嵌对话摘要和详细的 CSV 报告，这些报告会写入实验文件夹中的 eval_reports/ 目录。

如需开始评估，请提供黄金数据集路径和上下文集 ID。如需了解如何查找上下文集 ID，请参阅查找智能体上下文 ID。

您可以使用以下示例提示来指示智能体：

“根据 golden.json 评估我的上下文。”
“使用我上次实验中的配置重新运行评估。”

如需重新运行之前生成的评估配置，而无需再次设置，请直接询问代理或调用 CLI：

uvx google-evalbench --experiment_config=autoctx/experiments/my-experiment/eval_configs/run_config.yaml

如需详细了解评估配置架构以及如何自定义评估运行，请参阅 Evalbench 文档。

执行差距分析并提出改进建议

如需解决查询失败问题，您必须找出其根本原因，例如列不正确、缺少表联接或模糊字词未解析。手动识别这些问题需要对评估报告进行大量分析。

智能体可自动执行以下分析和更正循环：

差距分析：智能体会读取评估结果和您设置的上下文，对类似的失败进行分组，并推荐有针对性的上下文添加内容，例如模板、分面或值搜索。
建议的修复：代理会提出具体的修改建议，并可选择针对您的数据库测试 SQL 以验证解决方案。
保留基准：智能体会将改进内容写入新的 JSON 文件，同时保留基准上下文，从而保留原始文件。

您可以使用以下示例提示来指示智能体：

“Run gap analysis on my last evaluation and propose fixes.”
“针对 golden.json 优化此上下文集。”

如需为下一次迭代做准备，请使用 Cloud SQL Studio 将改进后的上下文上传到目标上下文集，并按照说明操作。

根据需要编写特定上下文项

如果您已经知道所需的上下文（例如特定问题的模板、重复过滤器的分面或特定列的值搜索），则手动编写上下文 JSON 可能会在参数名称、类型元数据或片段语法中引入序列化错误。智能体负责处理 JSON 格式设置，让您可以专注于业务意图。

您还可以使用此功能进行临时更新，例如，当您需要支持新的查询句式或解决缺失的架构细节时。如需获取 JSON，请向智能体描述所需的上下文，而无需运行评估或设置实验。

当您接到一次性任务时，此功能也非常适用：例如，利益相关方给您提供了一对新的问题-SQL 组合，希望您能支持；或者您在代码审核期间发现缺少某个方面。您无需设置实验或运行评估即可解决此问题，只需描述您想要的内容，智能体就会生成 JSON。

您可以使用以下示例提示来指示智能体：

“为‘加利福尼亚州有哪些机场？’创建一个模板，并使用 SQL：SELECT name FROM airports WHERE country = 'United States' AND state = 'CA'。”
“为标签为‘红眼’的滤镜 departure_time BETWEEN '00:00:00' AND '06:00:00' 创建一个分面。”
“为airports.iata创建值搜索。”

关于选择哪种上下文类型的理由

无论搜索的是模板、分面还是值，选择正确的上下文类型都有助于防止上下文膨胀和数据库查询回归。例如，使用模板而非分面可能会导致规则重复，而在模板已足够的情况下引入值搜索则可能会增加查询延迟。如需找到正确的架构格式，请在创建上下文项之前，提示代理根据查询结构或数据库列推荐类型。代理会解释其推理过程，帮助您了解上下文选项。

您可以使用以下示例提示来指示智能体：

“我一直在许多查询中编写过滤条件 departure_time BETWEEN '00:00:00' AND '06:00:00'。如何才能最好地捕捉到这一瞬间？”
“用户使用自由文本描述航班状态，我想将这些描述与 flights.status 匹配。我应该设置哪种类型的价值搜索？”
“模板和分面有什么区别？我应该在什么情况下使用它们？”

对上下文集应用批量操作

该智能体支持批量更新，以便一致地管理大型上下文集。如果您需要同时更新多个上下文项（例如，当数据库列被重命名、代码值更改格式或模板引用已弃用的表时），代理可以对每个受影响的项应用更改，而不会更改不相关的条目。

您可以使用以下示例提示来指示智能体：

“阅读 golden.txt，并将所有配对转换为模板。”
“在 context_set.json 中，将引用‘United’的所有项中的 airline = 'UA' 替换为 airline = 'United Airlines'。不要管不相关的商品。”

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

上下文工程智能体

黄金数据集的重要性

系统化的爬山过程

准备工作

启用必需服务

准备 Cloud SQL 实例

所需的角色和权限

向 Cloud SQL 实例授予 executesql 权限

为值搜索准备数据库

准备环境

安装上下文工程代理

Antigravity CLI

Claude Code

Gemini CLI（已弃用）

设置数据库连接

配置应用默认凭证

配置数据库连接文件

生成和优化上下文

构建和扩展评估数据集

生成基准上下文集

评估上下文有效性

执行差距分析并提出改进建议

根据需要编写特定上下文项

关于选择哪种上下文类型的理由

对上下文集应用批量操作

后续步骤

使用上下文工程代理构建上下文集

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