你大概已经见过 GraphRAG 的概念图，也照着 demo 跑通了一次，但真换到自己的文档上就开始卡：实体抽取跑一半超时、图越建越慢、检索出来一堆没用的关系。这篇不讲原理，只讲落地顺序——先怎么把小批量跑通，再把并发、超时、降级和日志一件件补上，最后给出怎么判断这套图到底比普通检索值不值。
你大概率已经照着某个 demo 把 GraphRAG 跑通过一次，概念图也能画出来，但一换到自己的文档集就全是坑：实体抽取跑到一半超时，图越建越慢，检索出来一堆看不出用处的关系，最后只能退回普通检索。这篇不讲原理，只讲落地顺序——先把小批量跑通，再把并发、超时、降级和日志一件件补上，最后给你一套判断标准，看这套图到底值不值得留。
整体思路是把它当成一条流水线，而不是一个大模型调用。抽取、建图、检索三段各自有各自的失败模式，混在一起调会让你永远不知道是哪一段坏了。所以先分段打通，再谈优化。
先定顺序：抽取、建图、检索三段别混着调
推荐按「小样本抽实体 → 批量跑抽取 → 写进 Neo4j → 图检索 → 拼进回答」这个顺序推进。前一段没有稳定下来，就不要开下一段。很多人一上来就全量入图，结果 schema 定错了，返工成本极高，等于白跑一遍。
- 先定 schema把节点类型、关系名、允许的属性手写死，让本地模型只做填空。比如节点只允许「人、组织、项目」三类，关系只允许「参与、归属、依赖」三种。schema 越窄，抽取越稳，后面查询也越好写。
- 小样本打通拿十几篇文档跑通全流程即可，重点看抽取结果是否可解析、写入是否成功、检索能否命中。这一步不求数量，只求链路通。
- 批量再放开确认小样本稳定后再放大文档量。每放大一档，先看耗时和失败率，再决定要不要继续加。
本地模型这端：超时、上下文和输出格式
本地模型和云端 API 最大的差别是你自己扛资源限制。抽取任务通常比聊天慢，超时值不要沿用聊天场景的默认配置，要按单文档最长耗时上浮一档来设。设太紧，长文档直接被砍；设太松，一个卡住的任务会拖住整批。
另一个常见问题是上下文塞太满。本地模型在上下文接近上限时，容易出现漏实体却不报错的情况，你看着是成功了，其实数据已经残了。把「一次抽一整篇」改成「一次抽一小块」，虽然请求数变多，但结果更可控，也更好定位问题。
- 强制结构化输出：固定 JSON 字段，解析失败的样本单独落盘，别混进正常结果
- 解析失败攒够一批再调 prompt，不要边跑边改，否则你分不清是 prompt 变了还是数据变了
- 单文档耗时和输出条数都记下来，方便后面判断是模型慢还是文档本身太复杂
- 抽取和问答分开跑，别用同一个模型实例同时扛两件事，容易互相抢资源
Neo4j 这端：写入方式与检索姿势
写入是第一个性能分水岭。逐条写会慢到没法迭代，正确做法是批量合并，在同一次事务里成批提交。批量大小先按机器内存和 Neo4j 的承受能力试，从小的开始往上加，找到稳定值就固定下来。
另一个坑是实体归一。大小写、别名、全半角如果不统一，同一个东西在图里会散成好几个节点，检索时你就会得到一堆碎片。写入前先做一层归一，把明显的同义词合并掉，这一步做扎实，后面查询质量会明显不一样。
| 环节 | 推荐做法 | 不适用的情况 |
|---|---|---|
| 写入 | 同事务批量合并，先小批量试稳定值 | 文档量极小、只做一次性验证时可以逐条写 |
| 实体归一 | 写入前统一大小写、别名、全半角 | 实体本身就是需要区分的同名不同物时，不能强行合并 |
| 检索 | 先做实体链接，再限定跳数扩邻居 | 问题里没有明确实体、纯语义模糊查询时，图检索基本帮不上忙 |
| 排序 | 图检索结果和向量召回结果合并后再排序 | 只有单一来源结果时不用合并，直接返回即可 |
工程护栏：并发、降级、日志与评测
抽取是长任务，并发别一上来就开满。按机器能扛的档位分批跑，失败的分片单独留记录，可以重投。更关键的是要有降级路径：本地模型挂了或者抽不出东西时，能退回纯向量检索，别让整条问答链直接断掉。图是增强，不是唯一入口。
日志至少覆盖这几项：文档 id、抽取耗时、实体和关系条数、解析失败原因、本次检索走了哪条路径。没有这些，你出问题时只能靠猜。评测方面，准备一批带标准答案的问题，同时跑「图检索 + 向量」和「只用向量」两种配置，看差异落在哪类问题上——是关系型问题变好了，还是简单事实问题反而变差了。
- 并发：分批跑，失败分片可重投，不要一次开满
- 降级：模型不可用时退回纯向量检索，保证问答可用
- 日志：文档 id、耗时、条数、失败原因、检索路径五项齐
- 评测：同一批问题跑两种配置，看差异集中在哪类问题
- 成本：本地推理的时间成本也要算，别只看模型是否免费
至于这套图到底值不值，判断标准不是分数高低，而是差异结构。如果图检索只在关系型、多跳问题上带来提升，其他问题持平或略降，那它可以作为特定场景的增强保留；如果两类问题差异不明显，说明你的文档里实体关系本来就不丰富，硬上图的收益有限。具体数字和对照结果，可以到站内评测页面核对当时的记录。
下一步如果你还在选本地模型和运行方式，可以先去工具目录看各方案的适用场景，再回来决定抽取和检索这两段分别用哪套配置。→常见问题
本地模型抽实体质量差，是不是必须换更大的模型？
先别急着换。多数情况是块切太大、schema 没约束、或者输出格式没压死。把输入切小、把 JSON 字段固定下来、把解析失败的样本单独看一批，往往比换模型见效快。真要换，也先在同一批样本上对比，别全量重跑。
跑一次全量建图太慢，怎么排优先级？
先按文档来源和更新频率分层，把常问的那部分先入库，冷门资料放后面。建图本身是离线任务，可以夜间分批跑，失败分片重投。判断标准是：问答里被引用的那部分图先建完，就算合格。
怎么判断这套图的检索真的比纯向量好？
拿一批需要跨文档、多跳关系才能答的问题做对照，比如「谁负责的项目用了哪个供应商」这类。两种配置各跑一遍，看回答准确率和引用是否对得上。如果问题都是单点事实，图检索大概率帮不上忙，这时候不必硬上。
