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

本文档介绍了如何创建和优化上下文集,以帮助 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"

    代理会批量处理您的输入,将字面量值替换为 ? 占位符,并更新上下文集文件。

黄金数据集的重要性

为了优化上下文,您必须首先创建一个与应用的自然语言输入相匹配的黄金数据集。该智能体可以帮助您构建此黄金数据集,其中包含用户问题及其预期的 GQL 查询。借助黄金数据集,您可以执行以下操作:

  • 为自然语言到 GQL 查询的性能建立基准。
  • 根据标准答案 GQL 查询验证上下文更新。
  • 衡量各优化迭代的准确率提升情况。

系统化的爬山过程

在系统化爬山算法中,智能体会通过评估黄金数据集、进行差距分析以及有针对性地更新 GQL 上下文,以迭代方式改进上下文集,从而将准确率提升至接近 100%:

  • 自动生成基准上下文:根据 Spanner Graph 属性图架构和应用工件,创建初始 GQL 上下文集。
  • 爬山优化工作流:让智能体使用配置的 graph_ids 评估 QueryData 准确率,对失败的 GQL 查询执行差距分析,并自动提出改进建议,以提高准确率。

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

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

准备工作

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

启用必需服务

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

准备 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 软件包。

  1. 按照安装 uv中的说明安装 uv。
  2. 验证 uv 是否已安装并可从命令行访问:

    uv --version

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

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

Antigravity CLI

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

  1. 安装 Antigravity CLI。请参阅 Antigravity CLI 使用入门。
  2. 安装上下文工程智能体插件,其中包含用于生成上下文的工作流:
    agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin
  3. 启动 Antigravity CLI:
    agy
  4. 更新插件:
    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 中安装上下文工程代理,请按以下步骤操作:

  1. 添加插件市场:
    /plugin marketplace add https://github.com/GoogleCloudPlatform/db-context-enrichment.git
  2. 安装插件:
    /plugin install db-context-engineering@db-context-enrichment-marketplace
  3. 重新加载插件以启用更改:
    /reload-plugins
  4. 更新插件:
    /plugin update db-context-engineering@db-context-enrichment-marketplace

Gemini CLI(已弃用)

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

  1. 安装 Gemini CLI。请参阅 Gemini CLI 使用入门。
  2. 安装扩展程序:
    gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment
  3. 更新扩展程序:
    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 调用 QueryData REST API,并在评估期间在 Vertex AI 上运行 LLM 评分器。

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

gcloud auth application-default login

配置数据库连接文件

智能体需要数据库连接来生成上下文,MCP Toolbox 支持并在配置文件 (autoctx/tools.yaml) 中定义了该连接,同时还定义了一个状态跟踪器 (autoctx/state.md),用于记录活跃的属性图名称(例如 FinGraph)。

  1. 启动代理环境。
  2. 让智能体为您的 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。

  3. 打开 autoctx/state.md,并验证 ## Active Database 部分是否按以下格式列出了您的属性图:

    - **Graph Ids**: ["FinGraph"]
    

    评估工作流仅从此行读取属性图 ID。如果该行缺失、为空 ([]) 或格式不正确,评估会调用不带 graph_ids 的 QueryData,并且 QueryData 会生成关系型 SQL 而不是 GQL。

  4. 如需应用新的 tools.yaml 配置,请重新加载连接:

    • 在 Antigravity CLI 中,运行 /mcp 并选择 toolbox 以重启。
    • 在 Gemini CLI 中,运行 /mcp reload。
    • 在 Claude Code 中,运行 /mcp,选择 toolbox,然后选择 Reconnect。

如需详细了解如何手动配置数据库配置文件,请参阅 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。不要管不相关的商品。”

后续步骤