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

利用上下文工程智能体构建和优化上下文集

为了在数据智能体应用中实现高 QueryData 查询准确率和低在线延迟时间，您可以使用上下文工程智能体来构建、评估和优化上下文集。通过自动执行上下文创建、上传和优化，该智能体可帮助您的应用针对自然语言问题返回快速、确定且可解释的答案。

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

通过为 QueryData 提供针对您的业务应用量身定制的上下文，您可以提供系统所需的精确业务规则，以解析细微的用户意图并提供接近 100% 的查询质量。当您在 CLI 或 IDE 中工作时，上下文工程代理会自动将上下文集上传到 Google Cloud ，同时在工作区中保存本地文件以进行版本控制。

上下文工程智能体

上下文工程代理可直接在 CLI 或 IDE 中充当设计时助理。手动编写上下文需要手动编写详细的查询句式、预测每种措辞变化，并在迭代过程中手动诊断查询失败。上下文工程智能体通过以下方式消除了这些开销：引导基准上下文、精选标准答案评估数据集、迭代式爬山算法来修复准确率差距，以及证明您的上下文可以泛化到新问题。

您可以使用自然语言与代理对话，以推动优化工作流。首先输入提示，例如“根据我的应用要求优化上下文集。”

准备工作

在使用上下文工程代理之前，请先完成以下部分中的前提条件。即使您的数据库实例位于其他区域，您也可以在 us-central1、us-east1、europe-west4 和 asia-southeast1 区域中创建和存储上下文集。

启用必需服务

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

准备数据库

准备 Cloud SQL for MySQL 实例并为代理配置访问权限：

创建 Cloud SQL for MySQL 实例，并在 Cloud SQL for MySQL 实例上创建数据库，或使用现有实例和数据库。
在 Cloud SQL for MySQL 实例上启用 Data API 访问权限。在实例上将 Data API 访问权限 (data_api_access) 设置为 ALLOW_DATA_API，以便代理可以检查架构并验证查询。对于在未启用 Data API 访问权限的情况下创建的实例，请参阅启用 Data API 访问权限或在 Google Cloud 控制台中进行配置。

所需的角色和权限

如需获得使用上下文工程代理和管理上下文集所需的权限，请配置以下 Identity and Access Management (IAM) 角色和数据库权限：

将 IAM 用户或服务账号添加到实例。如需了解详情，请参阅将单个 IAM 用户或服务账号添加到 Cloud SQL 实例。
在项目级层向 IAM 用户或服务账号授予 roles/cloudsql.instanceUser（如果您还在 Cloud SQL Studio 中测试查询，则授予 roles/cloudsql.studioUser）、roles/serviceusage.serviceUsageConsumer、roles/geminidataanalytics.queryDataUser 和 roles/mcp.toolUser 角色。如需了解详情，请参阅为项目添加 IAM 政策绑定。
如需创建、上传和管理上下文集，请在项目级向 IAM 用户或服务账号授予 Dataplex Catalog Editor (roles/dataplex.catalogEditor) 或 Dataplex Catalog Admin (roles/dataplex.catalogAdmin) 角色。如需了解详情，请参阅上下文集权限。
让特权用户向 IAM 用户或服务账号授予只读数据库权限（如果您使用语义值搜索，则授予对 mysql.ml_embedding 的执行权限）：
```
GRANT SELECT ON *.* TO "IAM_USERNAME";
GRANT EXECUTE ON FUNCTION mysql.ml_embedding TO "IAM_USERNAME";
```
将 IAM_USERNAME 替换为 IAM 用户或服务账号的数据库用户名（不含 @ 和域名的邮箱）。如需了解详情，请参阅向单个 IAM 用户或服务账号授予数据库权限。

为值搜索准备数据库

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

启用 Vertex AI API 和 Compute Engine API，并向 Cloud SQL for MySQL 实例的服务账号授予 roles/aiplatform.user 角色。如需了解详情，请参阅启用 Vertex AI 集成。
在 Cloud SQL for MySQL 实例上启用 cloudsql_vector 和 ngram_token_size 数据库标志以及 Vertex AI 集成：
```
gcloud sql instances patch INSTANCE_NAME \
    --enable-google-ml-integration \
    --database-flags=cloudsql_iam_authentication=on,cloudsql_vector=on,ngram_token_size=3
```
将 INSTANCE_NAME 替换为您的 Cloud SQL for MySQL 实例的名称。

--database-flags 标志会替换实例上的所有现有数据库标志，并重启实例。如果您的实例配置了其他标志，请将其包含在英文逗号分隔列表中。

如需让 Cloud SQL for MySQL 实例执行语义值搜索，请执行以下操作：

创建一个向量列来存储嵌入（例如，properties 表上的 city 嵌入）：

ALTER TABLE `properties`
ADD COLUMN `city_embedding` VECTOR(768) USING VARBINARY;

为列值生成并存储向量嵌入：

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

如需让 Cloud SQL for MySQL 实例执行三元组值搜索，请在目标文本列（例如 properties 表上的 address）上使用 ngram 解析器创建 FULLTEXT 索引：
```
CREATE FULLTEXT INDEX `idx_ngram_properties_address`
ON `properties`(`address`)
WITH PARSER ngram;
```

准备环境

您可以在本地开发环境或 IDE 中构建和优化上下文集。

安装 uv

上下文工程代理需要 uv 来管理底层 Python 软件包：

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

安装上下文工程代理

在您首选的开发环境中安装上下文工程代理插件：

Antigravity CLI

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

安装上下文工程代理插件：

agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin

启动 Antigravity CLI：
```
agy
```

如需稍后更新插件，请运行 agy plugin uninstall db-context-engineering，然后运行 agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin。

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 extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment

如需稍后更新扩展程序，请运行 gemini extensions update google-cloud-db-context-engineering。

使用 Google Cloud进行身份验证

配置应用默认凭证 (ADC)，以对您的开发环境进行身份验证：
```
gcloud auth application-default login
```
为您的凭证设置配额项目，以便 Model Context Protocol (MCP) 工具可以使用您的 Google Cloud 项目：
```
gcloud auth application-default set-quota-project PROJECT_ID
```
请将 PROJECT_ID 替换为您的 Google Cloud 项目 ID。

连接到您的数据库

启动智能体环境，并让智能体建立数据库连接（例如，“帮我设置数据库连接”）。代理会引导您创建 .context-engineering/tools.yaml 配置文件，以便读取架构并验证 SQL。（在创建 .context-engineering/tools.yaml 之前，启动时预计会出现初始 toolbox MCP 服务器连接警告。）
重新加载 MCP 服务器连接以应用 .context-engineering/tools.yaml 配置：
- Antigravity CLI：运行 /mcp 并选择 toolbox（或 db-context-engineering_toolbox）以重启。
- Claude Code：运行 /mcp，选择 toolbox，然后选择 Reconnect。
- Gemini CLI：运行 /mcp refresh（或 /mcp reload）。

构建和优化上下文

上下文工程代理会引导上下文集完成端到端生命周期，从初始引导到经过验证的通用性。

引导基准上下文集

为了避免从空白页面创建上下文，智能体会检查您的数据库架构以及任何可用的应用工件，例如业务需求、文档或示例 SQL 查询。智能体会推导出一个初始基准上下文集，其中包含基于数据库模型的基础查询模板和查询方面。

生成并验证基准上下文后，智能体会将其直接上传到 Google Cloud ，并返回上下文集资源名称。

根据应用工件创建评估数据集和留存数据集

如需系统地提高准确率，您需要将标准答案问题与经过验证的 SQL 查询配对。如果您还没有评估基准，该智能体可以通过从应用代码、历史查询和数据库架构中提取业务场景来生成一个评估基准。

在数据集生成过程中，智能体将创建两个不同的集合：

训练基准：在迭代优化过程中使用的一组具有代表性的问题-SQL 对。
留出数据集：一组与训练基准领域相似的独立问题，专门用于测试泛化能力。

通过爬山算法优化准确率

在爬山法优化中，智能体会以迭代方式优化上下文集，从而将 QueryData 准确率提升至近乎 100%：

评估：智能体使用 QueryData API 根据训练基准测试当前的上下文集，并对准确率进行评分。
诊断差距：智能体分析查询失败，找出其根本原因（例如缺少表联接、未关联的私有实体或复杂的过滤条件），并制定有针对性的修复措施。
优化和上传：代理会添加或改进查询模板、查询分面和值搜索，以解决差距，并自动将更新后的上下文集从 CLI 上传到 Google Cloud 。
迭代：智能体在多轮迭代中重复此循环，直到准确率收敛到最佳分数。

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

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

使用留出数据集证明泛化能力

在训练基准上实现高精确度是必要的，但生产流量包含开发期间从未见过的措辞变化和复杂的复合问题。

在爬山优化收敛后，智能体会根据留存数据集测试生成的上下文集。此步骤可验证设置的上下文是否能很好地泛化到新的用户输入，而不会过度拟合初始基准。智能体会生成一份泛化能力报告，展示其在处理未见过的问题变体和复合过滤条件（例如“帮我找找德尔马地区靠近好学校、适合年轻家庭且有海景的房源”）时的准确率。

按需创作和推理

除了完整的优化运行之外，您还可以与代理对话，以便在业务需求发生变化时进行有针对性的更新：

有针对性的编写：用自然语言描述具体的业务需求，智能体会设置上下文项的格式，并直接从 CLI 上传，无需手动修改：
- “为‘帮我查找德尔马好学校附近的房源’创建模板，SQL 为：SELECT p.property_id, p.address FROM properties AS p JOIN schools AS s ON p.school_id = s.school_id WHERE p.city = 'Del Mar' AND s.rating >= 7。”
- “为标签为‘适合初创家庭’的过滤条件 properties.bedrooms BETWEEN 3 AND 4 AND properties.square_feet BETWEEN 1500 AND 2500 创建一个分面。”
- “为properties.city创建值搜索。”
跨上下文集批量更新：如果数据库列被重命名或表结构发生变化，代理可以同时更新所有受影响的上下文项，而无需修改不相关的条目：
- “在我的上下文集中，将任何引用单户住宅的项中的 properties.property_type = 'SFR' 替换为 properties.property_type = 'Single Family Residential'。不要管不相关的商品。”