graph-rag agent

你已经跑通过普通 RAG，现在发现答案要跨好几份文档串关系，单靠向量召回总是缺一环，于是想上图谱加智能体。这篇不讲概念，只讲落地：哪类问题值得上图、检索工具怎么挂进循环、超时并发降级日志评测分别怎么设。看完能判断自己这套值不值得改造，也知道第一步先动哪。

你已经把普通 RAG 跑通了，然后发现有些问题老是答不全：答案横跨好几份文档，得把人和人、组件和组件之间的关系串起来，光靠向量召回只能捞到零散片段。于是你想上图谱，再套一个智能体让它自己去查。这个方向本身没问题，但落地时要处理的坑比概念多得多：什么时候值得上图、图查询挂在循环的哪一步、超时并发怎么设、断链了往哪退、日志和评测盯哪几个数。这篇就按这几个问题往下拆。

先说结论性质的东西：图检索不是替换向量检索，是加在它旁边的一条新召回路径；智能体的价值在于让它自己决定走哪条路，而不是你在主流程里硬写顺序。下面每一节都给你判断标准和可执行动作，具体数字一律去站内页面核对当时的口径。

先判断：你这类问题到底要不要上图

上图谱最怕的情况是「问题其实很简单，但团队觉得图谱听起来更高级」。判断成本很高，所以先用信号筛一遍：如果下面几条大部分不成立，那你的问题大概率还在普通 RAG 的射程内，改造只是徒增维护负担。

• 信号一：答案依赖实体之间的多跳关系，比如谁和谁有合作、哪个组件依赖哪个模块；向量召回容易只捞到单篇片段，拼不出完整链路。反例是答案就集中在一两份文档里，那加图只是白花钱。
• 信号二：问题里频繁出现「哪些」「一共」「跨部门」这类需要聚合的提问，纯相似度检索给不了完整集合。如果提问基本都是单点事实查询，先别动。
• 信号三：数据本身有稳定结构，工单、组织、依赖、供应链这些能持续抽出实体和边。如果文档天天改版、实体抽取一直抽不准，图谱会先变成负担。
• 落地前置：先确认你已经有一条不带图谱也能跑通的检索链路。图检索是加在它旁边的一条召回，不是替换。

典型结构：图检索在智能体循环里站哪个位置

一种常见做法是在主流程里写死「先查图再查向量」，这看起来稳定，实际很脆：问题类型一变，顺序就成了瓶颈。更实用的做法是把图查询做成一个和向量检索并列的工具，交给模型自己选。它选错了你也能从日志里看出来，然后针对性调提示词或工具描述。

并列工具

把「向量检索」和「图查询」注册成两个可选工具，让模型按问题类型选路，而不是主流程硬编码顺序。

两种分工

一是向量先定位实体、再拿实体去图里扩邻居；二是模型直接生成图查询语句、拿回子图后再回向量库补原文细节。前者稳、后者灵活。

终止条件

步数上限、连续两轮召回无新增、需要人工确认，这三种都要显式写出来，否则跨跳查询会一路扩下去。

子图瘦身

不要整块塞进上下文，先摘要成「实体—关系—出处」的短行，原文片段按需二次召回，不然上下文预算会被图结构吃光。

1. 第一步：把图查询包成工具输入是实体或查询语句，输出是结构化的关系行加出处 ID，不要直接返回大段文本。
2. 第二步：写清工具描述在工具描述里写明什么类型的问题适合走图，模型才会在合适的时机调用，也方便你之后复盘。
3. 第三步：设终止条件把步数上限和「连续两轮无新增」写进循环控制里，跑通后观察实际跳数分布再调。
4. 第四步：验证闭环取一批多跳问题，看模型是否真的走了图路径，以及最终答案有没有引用到出处片段。

超时、并发与降级：跨跳查询最容易炸的地方

跨跳查询最直观的特征是耗时不稳定：跳数一多，数据库往返次数就叠上去。很多线上事故不是模型答错，而是图查询把整条链路拖到超时，用户看到的是「转圈然后报错」。所以超时、并发、降级这三件事要在上线前就设计好，而不是等出事再补。

• 图查询单独设超时，一般比向量检索更短，因为一次跨跳会叠加多次数据库往返。超时后返回「检索不完整」的标记，而不是空结果——空结果会被模型理解成「这件事不存在」。
• 并发按「一次用户提问 = 一条检索链」计数，链内的图查询和向量查询不要各自开并发池，否则限流时两边会成倍撞上去。批量任务要分批跑并留重投窗口。
• 降级顺序排好：图库挂退到纯向量，向量挂退到关键词，两路都挂就明确告诉模型「没有外部资料」，让它拒答而不是硬编。
• 缓存分两层：实体解析结果可以长缓存，子图查询结果按数据更新频率短缓存。缓存键要把查询语句和跳数带上，不然换了深度还在读旧子图。

日志与评测：怎么知道改动是变好还是变贵

图加智能体之后，你会同时面对两个变化：效果可能变好，成本和延迟可能变差。只盯最终答案准确率，很容易把「多花了一倍时间换来的微小提升」当成成功。所以日志字段和评测分层要一起设计，让每次改动都能被拆开看。

• 每次问答至少记：走了哪条检索路径、实际跳了几跳、召回片段数、耗时分段（解析／查图／向量／生成）、是否发生降级。缺了路径和跳数，后面根本没法复盘。
• 评测集按问题类型分层：单点事实、多跳关系、聚合统计各留一批，分别看准确率和平均跳数。总量提升但多跳这批掉了，多半是路径选择出了问题，不是检索质量。
• 做小规模对照：固定同一批问题，跑「只用向量」和「向量加图」两版，比准确率、延迟、单次成本三个数，别只看其中一个。
• 数字口径以站内 AI 测评榜单（/benchmarks） 和 真实用量榜（/usage） 的当期页面为准，不要拿旧数当基线。

如果要做跨服务商的对照，把中转或直连的稳定性也一起纳入观察，站内 中转站目录（/sites） 和 可信度排行（/rankings） 提供了现成的观察维度，但最终结论要回到你自己的业务问题上。

上线检查清单与常见坑

最后给一份可以照着打勾的清单。它的目的不是保证成功，而是保证你在铺开之前已经看过那些最容易翻车的地方。任何一条过不了，就先别扩大流量。

1. 小流量灰度先抽一类多跳问题做灰度，观察跳数分布和超时率，再决定要不要铺开。
2. 实体抽取单独评测抽错实体比不抽还糟，会把噪声边带进子图，上线前先在一批样本上过一遍准确率。
3. 准备重建流程数据更新后子图和向量要能一起刷，不能只刷一半，否则两边对不上。
4. 明确不适用场景实时性要求极高、数据每天大改、或问题几乎都是单跳事实查询时，普通 RAG 更划算；图规模很小时，结构化过滤可能就够了。
5. 接入鉴权与重试口径按 把 API 接进已有系统：网关、鉴权与灰度上线清单（/guides/api-gateway-auth-rollout） 过一遍，图库连接和模型连接要分开管。