本文档介绍了如何创建和优化上下文集,以帮助 Spanner Graph 数据智能体应用实现高 QueryData 准确率。上下文工程智能体可自动创建和优化图查询语言 (GQL) 上下文集,帮助您构建、评估和改进这些上下文集。
如需了解 Spanner Graph 的上下文集和 QueryData,请参阅上下文集概览和 QueryData 概览。
为了构建企业图数据应用,自然语言到 GQL 的转换准确率通常需要达到近乎 100% 的质量。图遍历模式不正确或缺少边缘过滤器会影响应用可用性和用户体验。若要获得可解释、与业务相关且高度准确的回答,需要进行上下文工程,即创建和迭代优化上下文集的过程。
通过为 QueryData 提供针对 Spanner Graph 架构和业务应用的上下文,您可以提供系统所需的精确图遍历规则和网域定义,以解析细微的用户意图。
本文档中的示例使用 FinGraph 属性图架构和示例数据集(通过 Owns 和 Transfers 边连接的 Person 和 Account 节点)。如需创建 FinGraph 架构并插入示例数据,请参阅设置和查询 Spanner Graph。
上下文工程智能体
上下文工程智能体可自动执行上下文工程工作流:它会生成评估数据集、引导上下文集,并以迭代方式改进上下文集。
以下列表提供了用于指示智能体的自然语言提示示例,以及智能体如何响应的说明:
- 符合情境的建议提示示例:“阅读我的 Spanner 数据库中
FinGraph属性图的应用文档,并建议要添加的 GQL 上下文项。”该智能体会解析您提供的数据集应用文档,将业务规则映射到FinGraph节点和边缘标签,并建议 GQL 模板和分面。 - 当用户问题未返回预期结果时,用于差距分析的示例提示:“当用户询问‘从应急账户转账’时,QueryData 会过滤
nick_name = 'rainy day account',不返回任何结果。请更新我的 Spanner 数据库中FinGraph属性图表的上下文,以便正确回答此问题。”代理会检查架构,确定昵称存储为Rainy Day Fund,并建议对Account.nick_name进行值搜索(如果问题在于模式,则建议使用模板或构面)。 批量处理提示示例:“以下是我的 Spanner 数据库中
FinGraph属性图的自然语言问题和 GQL 查询。将它们转换为模板:- 查找 Dana 向其转账的所有人以及转账金额:
GRAPH FinGraph MATCH (:Person {name: 'Dana'})-[:Owns]->(:Account)-[transfer:Transfers]->(:Account)<-[:Owns]-(to_person:Person) RETURN to_person.name AS recipient, transfer.amount AS amount - Alex 进行了哪些高风险转移?
GRAPH FinGraph MATCH (:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount"
代理会批量处理您的输入,将字面量值替换为
?占位符,并更新上下文集文件。- 查找 Dana 向其转账的所有人以及转账金额:
黄金数据集的重要性
为了优化上下文,您必须首先创建一个与应用的自然语言输入相匹配的黄金数据集。该智能体可以帮助您构建此黄金数据集,其中包含用户问题及其预期的 GQL 查询。借助黄金数据集,您可以执行以下操作:
- 为自然语言到 GQL 查询的性能建立基准。
- 根据标准答案 GQL 查询验证上下文更新。
- 衡量各优化迭代的准确率提升情况。
系统化的爬山过程
在系统化爬山算法中,智能体会通过评估黄金数据集、进行差距分析以及有针对性地更新 GQL 上下文,以迭代方式改进上下文集,从而将准确率提升至接近 100%:
- 自动生成基准上下文:根据 Spanner Graph 属性图架构和应用工件,创建初始 GQL 上下文集。
- 爬山优化工作流:让智能体使用配置的
graph_ids评估 QueryData 准确率,对失败的 GQL 查询执行差距分析,并自动提出改进建议,以提高准确率。
下图展示了系统化爬山工作流:
准备工作
在使用上下文工程代理之前,请完成以下前提条件:
启用必需服务
为您的项目启用以下服务:准备 Spanner 实例
- 确保有可用的 Spanner 实例。如需了解详情,请参阅创建实例。
- 确保在实例中创建数据库,以便在其中创建表。如需了解详情,请参阅在 Spanner 实例上创建数据库。
所需的角色和权限
- 将 IAM 用户或服务账号添加到实例。如需了解详情,请参阅应用 IAM 角色。
- 在项目级向 IAM 用户授予
roles/spanner.databaseReader、roles/serviceusage.serviceUsageConsumer和roles/geminidataanalytics.queryDataUser角色。如需了解详情,请参阅为项目添加 IAM 政策绑定。 - 如需创建、上传和管理上下文集,请在项目级层向 IAM 用户授予 Dataplex Catalog Editor (
roles/dataplex.catalogEditor) 或 Dataplex Catalog Admin (roles/dataplex.catalogAdmin) 角色。如需了解详情,请参阅上下文集权限。 - 在项目级层向 IAM 用户授予所需数据库的角色和权限。
如需设置 FinGraph 属性图表架构并插入本指南中使用的示例图表数据,请按照设置和查询 Spanner Graph 中的步骤操作。
准备环境
您可以在任何本地开发环境或 IDE 中构建上下文集文件。要准备环境,请完成以下步骤:
- 安装上下文工程智能体。
- 设置与 Spanner Graph 的数据库连接。
安装上下文工程代理
上下文工程代理运行 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 使用入门。
- 安装上下文工程智能体插件,其中包含用于生成上下文的工作流:
agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin
- 启动 Antigravity CLI:
agy
- 更新插件:
agy plugin uninstall google-cloud-db-context-engineering agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin
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 mcp-db-context-enrichment
设置数据库连接
智能体需要数据库连接来提取属性图架构 (spanner-list-graphs)、检查底层表 (spanner-list-tables),以及验证生成的 GQL 和 SQL 查询的语法 (spanner-execute-sql)。如需让智能体与 Spanner 数据库中的属性图进行交互,请配置身份验证凭证并定义数据库连接配置。
配置应用默认凭证
配置应用默认凭证 (ADC),以提供用于从上下文工程代理访问 Google Cloud 资源的用户凭证:
- Toolbox MCP 服务器:使用凭据连接到 Spanner 数据库、提取属性图架构,并运行 GQL 查询进行验证。
- Evalbench:使用凭证通过
graph_ids调用QueryDataREST API,并在评估期间在 Vertex AI 上运行 LLM 评分器。
在终端中运行以下命令进行身份验证:
gcloud auth application-default login配置数据库连接文件
智能体需要数据库连接来生成上下文,MCP Toolbox 支持并在配置文件 (autoctx/tools.yaml) 中定义了该连接,同时还定义了一个状态跟踪器 (autoctx/state.md),用于记录活跃的属性图名称(例如 FinGraph)。
- 启动代理环境。
让智能体为您的 Spanner 数据库设置数据库连接,并指定属性图名称。例如,输入以下提示:
Help me set up the database connection for my Spanner database with the FinGraph property graph.按照智能体的说明提供您的项目 ID、Spanner 实例 ID、数据库 ID 和属性图名称 (
FinGraph)。智能体会创建autoctx/tools.yaml(包含spanner-list-graphs、spanner-list-tables和spanner-execute-sql工具)和autoctx/state.md。打开
autoctx/state.md,并验证## Active Database部分是否按以下格式列出了您的属性图:- **Graph Ids**: ["FinGraph"]评估工作流仅从此行读取属性图 ID。如果该行缺失、为空 (
[]) 或格式不正确,评估会调用不带graph_ids的 QueryData,并且 QueryData 会生成关系型 SQL 而不是 GQL。如需应用新的
tools.yaml配置,请重新加载连接:- 在 Antigravity CLI 中,运行
/mcp并选择toolbox以重启。 - 在 Gemini CLI 中,运行
/mcp reload。 - 在 Claude Code 中,运行
/mcp,选择toolbox,然后选择Reconnect。
- 在 Antigravity CLI 中,运行
如需详细了解如何手动配置数据库配置文件,请参阅 MCP Toolbox 配置。
生成和优化上下文
上下文工程智能体提供了一组智能体技能和 MCP 工具,用于生成基准 GQL 上下文集、根据优质 GQL 数据集衡量有效性,并以迭代方式应用改进。您可以从工作流的任何阶段开始:
- 如果您已设置上下文,则可以直接进行评估。
- 如果您有想要修复的失败 GQL 查询,可以直接进行差距分析。
在任何阶段,请提醒智能体,目标是 Spanner 数据库中的属性图,并为该图命名(例如 FinGraph),以便其保持在 GQL 专属工作流中。
构建和扩展评估数据集
若要提升性能,您必须先对其进行衡量。黄金数据集是一组用户问题及其预期 GQL 查询。如果没有基准,上下文工程就缺乏系统性的验证;有了基准,每一次上下文更改都是可衡量的改进,您可以根据标准答案进行验证。
手动创建具有代表性的黄金数据集非常耗时,而且小型数据集可能会遗漏用户措辞的变化。智能体通过以下方式解决此问题:
- 根据您的属性图架构生成候选自然语言问题和 GQL 查询对。
- 使用过滤条件变体、同义词和多跳路径改写来扩展种子数据集。
- 针对 Spanner 数据库执行生成的 GQL 查询,以确认每个查询都能顺利运行并返回有效结果。
根据Spanner Graph 查询概览中的 FinGraph 查询,黄金数据集 (autoctx/golden.json) 是一个 JSON 文件,其中包含自然语言问题和 GQL 对,例如:
[
{
"id": "fingraph_001",
"database": "example-db",
"nlq": "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts.",
"golden_sql": "GRAPH FinGraph MATCH (from_person:Person {name: 'Dana'})-[:Owns]->(from_account:Account)-[transfer:Transfers]->(to_account:Account)<-[:Owns]-(to_person:Person) RETURN to_person.name AS to_account_owner, to_account.id AS to_account_id, transfer.amount AS amount;"
},
{
"id": "fingraph_002",
"database": "example-db",
"nlq": "Find all money transfers involving a blocked account.",
"golden_sql": "GRAPH FinGraph MATCH (account:Account)-[transfer:Transfers]-(:Account {is_blocked: true}) RETURN transfer.order_number, transfer.amount;"
},
{
"id": "fingraph_003",
"database": "example-db",
"nlq": "Find destination accounts that are 1 to 3 transfers away from account 7, and show the path length.",
"golden_sql": "GRAPH FinGraph MATCH (src:Account {id: 7})-[e:Transfers]->{1, 3}(dst:Account) WHERE src != dst RETURN dst.id AS dst_account_id, ARRAY_LENGTH(e) AS path_length;"
},
{
"id": "fingraph_004",
"database": "example-db",
"nlq": "Find all high-risk transfers initiated by Alex.",
"golden_sql": "GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;"
}
]
获批的配对会填充到工作区中的 autoctx/golden.json 文件中,以供评估。在每个条目中,database 必须与您的 Spanner 数据库 ID(例如 example-db)匹配。
您可以使用以下示例提示来指示智能体,指定 FinGraph 是 Spanner 数据库中的属性图:
- “根据 Spanner 数据库中的
FinGraph属性图生成 GQL 评估数据集。” - “以下是我的 Spanner 数据库中
FinGraph属性图的种子问题和 GQL 查询。将其扩展为更广泛的 GQL 评估数据集,并验证查询是否运行。
生成基准上下文集
为避免从头开始创建上下文,您可以让智能体从属性图架构和应用工件(例如业务规则、示例 GQL 查询或设计文档)中派生初始 GQL 上下文集 (bootstrap_context.json)。由于您的数据集是 Spanner 数据库中的属性图,因此在生成模板和分面时,智能体会优先使用 GQL 模式 (GRAPH FinGraph MATCH ...),而不是关系型 SQL 联接。
您可以使用以下示例提示来指示智能体:
- “从 Spanner 数据库中的
FinGraph属性图生成基准 GQL 上下文集。” - “使用属性图架构和
requirements.md中的业务规则,为 Spanner 数据库中的FinGraph属性图生成初始 GQL 上下文。”
代理会提示您为实验命名(例如 fingraph_tuning),这会将生成的工件整理到 autoctx/experiments/fingraph_tuning/ 下。智能体生成 bootstrap_context.json 后,请按照在 Spanner Studio 中管理上下文集中的说明上传上下文集文件。
评估上下文有效性
建立上下文集和黄金数据集后,您可以让代理使用每个黄金问题查询 QueryData API,从而衡量上下文性能。智能体使用 Evalbench 将生成的 GQL 和执行结果与预期的黄金答案进行比较。
对于 Spanner Graph,评估会直接调用 QueryData REST API,以便每个请求都可以包含 graph_ids。
当 autoctx/state.md 包含 - **Graph Ids**: ["FinGraph"] 时,智能体会生成一个 Evalbench 模型配置文件 (autoctx/experiments/fingraph_tuning/eval_configs/model_config.yaml),该文件使用 REST API 并在 spanner_reference.database_reference 中包含 graph_ids,如下所示:
generator: query_data_api
project_id: PROJECT_ID
location: global
use_rest_api: true
context:
datasource_references:
spanner_reference:
database_reference:
engine: GOOGLE_SQL
project_id: PROJECT_ID
instance_id: INSTANCE_ID
database_id: DATABASE_ID
graph_ids:
- FinGraph
agent_context_reference:
context_set_id: projects/PROJECT_ID/locations/REGION/contextSets/CONTEXT_SET_ID
在运行评估之前,请打开 model_config.yaml 并验证 use_rest_api 是否为 true,以及 graph_ids 是否列出了您的属性图。
运行评估可提供以下信息:
- 定量指标(例如通过和失败结果以及汇总分数),用于跟踪 GQL 上下文迭代的进度。
- 内嵌对话摘要和详细的 CSV 报告,这些内容会写入实验文件夹中的
eval_reports/目录。
如需开始评估,请提供黄金数据集路径 (autoctx/golden.json) 和上下文集 ID。如需了解如何查找上下文集 ID,请参阅查找上下文集 ID。
您可以使用以下示例提示来指示智能体:
- “根据
autoctx/golden.json评估我的 Spanner 数据库中 FinGraph 属性图的上下文。调用 QueryData REST API,并将graph_ids设置为FinGraph。 - “使用上次实验的配置,重新运行 Spanner 数据库中 FinGraph 属性图的评估。”
如需直接从工作区根目录重新运行之前生成的评估配置,请运行以下命令:
uvx google-evalbench --experiment_config=autoctx/experiments/fingraph_tuning/eval_configs/run_config.yaml如需详细了解评估配置架构以及如何自定义评估运行,请参阅 Evalbench 文档。
执行差距分析并提出改进建议
如需解决 GQL 查询失败问题,请找出其根本原因,例如:
- 反向边缘方向(
-[:Owns]->与<-[:Owns]-) - 缺少量化路径边界 (
->{1, 3}) - 未映射的业务定义(例如
high-risk transfers) - 未解析的属性值
如需了解查询语法,请参阅 Spanner Graph 查询概览和 GQL 参考文档。
该智能体可自动执行此分析和更正循环,以优化 Spanner 数据库中的属性图:
- 差距分析:智能体读取评估结果和您设置的上下文,对类似的 GQL 失败进行分组,并推荐有针对性的补充内容,例如 GQL 模板、分面或针对节点和边属性的
GRAPH_TABLE值搜索。 - 建议的修复方案:智能体会提出具体的 GQL 上下文修改建议,并使用
spanner-execute-sql针对您的 Spanner 数据库测试生成的 GQL,以验证解决方案。 - 保留基准:智能体会将改进内容写入新的 JSON 文件 (
improved_context_v1.json) 以及基准上下文,从而保留原始文件。
您可以使用以下示例提示来指示代理,指定数据集是 Spanner 数据库中的属性图,以触发特定于 GQL 的上下文工程工作流:
- “针对 Spanner 数据库中 FinGraph 属性图的上次评估运行差距分析,并提出 GQL 上下文修复建议。”
- “针对
autoctx/golden.json优化我的 Spanner 数据库中 FinGraph 属性图的此上下文集。”
如需为下一次迭代做好准备,请按照修改上下文集中的说明,将改进后的上下文集文件 (improved_context_v1.json) 上传到 Spanner Studio 中的目标上下文集。
根据需要编写特定上下文项
如果您已经知道所需的上下文项(例如,用于特定图遍历的 GQL 模板、用于重复边过滤器的分面,或对节点或边属性的 GRAPH_TABLE 值搜索),智能体可以按需生成正确参数化的 JSON 对象,而无需运行完整评估。
您可以使用以下示例提示来指示代理在 Spanner 数据库中创建属性图:
- “对于 Spanner 数据库中的 FinGraph 属性图,请使用 GQL 查询
GRAPH FinGraph MATCH (p:Person {name: 'Alex'})-[:Owns]->(src:Account)-[t:Transfers]->(dst:Account {is_blocked: true}) WHERE t.amount >= 200 RETURN dst.id AS destination_account_id, t.amount AS transfer_amount ORDER BY t.amount DESC;为‘查找 Alex 发起的所有高风险转账’创建一个模板。” - “对于 Spanner 数据库中的 FinGraph 属性图,请为 GQL 子句
MATCH (account:Account)-[transfer:Transfers]-(:Account {is_blocked: true})创建一个标记为‘涉及已冻结账号的转账’的分面。” - “对于 Spanner 数据库中的 FinGraph 属性图,请针对概念类型为‘账号昵称’的
Account节点的nick_name属性创建GRAPH_TABLE值搜索,该搜索会不区分大小写地匹配昵称。”
关于上下文类型选择的推理
选择适当的上下文类型(GQL 模板、分面或值搜索)有助于防止上下文膨胀和查询回归。您可以提示智能体根据您的查询句式推荐合适的上下文类型:
- “在 Spanner 数据库的 FinGraph 属性图中,我一直在多个 GQL 查询中过滤涉及被冻结账号(
MATCH (account:Account)-[transfer:Transfers]-(:Account {is_blocked: true}))的转账。如何才能最好地捕捉到这一瞬间?” - “用户通过‘度假基金’或‘应急基金’等昵称来引用我的 Spanner 数据库中 FinGraph 属性图中的账号。我应该在
Account.nick_name上设置哪种GRAPH_TABLE值搜索?” - “Spanner Graph 的上下文集中的 GQL 模板和 facet 有何区别?我应该在什么情况下使用它们?”
对上下文集应用批量操作
该代理支持批量更新,以便一致地管理大型 GQL 上下文集,例如在多个模板和方面更新属性图标签或更改业务阈值时:
- “读取 Spanner 数据库中 FinGraph 属性图的
golden.json,并将所有问题-GQL 对转换为模板。” - “在 Spanner 数据库中 FinGraph 属性图的
context_set.json中,将引用‘高风险转账’的任何 GQL 项中的t.amount >= 200替换为t.amount >= 300。不要管不相关的商品。”
后续步骤
- 详细了解情境集。
- 了解如何在 Spanner Studio 中创建或删除上下文集。
- 了解如何测试 Spanner Graph 的 QueryData。
- 按照端到端教程将 QueryData 与应用集成。