如果你正准备在自己的知识库里跑 GraphRAG，我劝你先别急着看查询效果，而要把索引流水线当成第一战场。我拿一份 wiki 技术文档集做过完整实测，前前后后跑了 8 轮，换来了两个非常深刻的教训：第一，索引阶段的每个参数，最终都会变成查询结果里的正确率和缺陷；第二，失败最狡猾的形态不是运行时报红，而是那种退出码为 0、日志几乎全绿、但产出数据全是坏的“不报错的失败”。标题里的“静默失败”说的就是这种东西。这篇文章是“彻底搞懂 GraphRAG”系列的第一篇，我会把 GraphRAG 索引流水线的 10 个产出步骤完整拆开，再复盘 8 轮实测里动过的参数、看到的趋势、以及踩过的坑。适合两种人：一种是刚把 GraphRAG 跑通、还不知道每一步到底产出了什么的初学者；另一种是索引跑完后发现问答结果离谱，但日志看起来一切正常、正在怀疑人生的同学。
1. 先搞明白：GraphRAG 为什么把赌注压在“图”上
1.1 传统 RAG 的短板：文本块是孤岛
传统 RAG 的链路其实非常简洁：文档切块、向量化、检索 top-k、拼进 prompt、LLM 作答。这套流程在处理“某文档里关于某件事的说明”这类局部问题时很顺手，但一旦问题需要跨越多个文档才能回答，比如“从这批 wiki 里统计一下最常用的技术栈组合有哪些”，向量检索就很难凑齐完整的证据链。
原因在于文本块之间天然是相互独立的。检索时拿回来的 k 个块，可能都来自同一篇文档、甚至同一段落，彼此之间没有关联线索；想要从两百篇文档里归纳出共性结构，等于让 LLM 自己脑补一个全局图谱，这超出了原始语义检索的能力半径。
我习惯用一个图书馆类比来解释这个差距：传统 RAG 是文件夹式的资料室，里面几百个文件夹各装内容，你提问时它只能随机抽几页给你看；GraphRAG 是先给所有文件建一套互相引用的索引卡，你提问时先看索引卡之间的关联，再回到具体页面对照细节，还能跨文件夹做总结。这张“索引卡系统”就是知识图谱。
1.2 实体、关系、社区：GraphRAG 的核心三件套
GraphRAG 的核心思路可以概括为：在索引阶段让 LLM 先通读一遍所有文档，把文档里出现的实体（人名、组织、技术名、概念等）和关系（谁依赖谁、谁属于谁、谁导致谁）抽出来，组成一张知识图谱；然后用社区发现算法把图谱切成不同规模的社区，对每个社区生成摘要；查询时，local search 沿着实体和关系邻域去找证据链，global search 则把社区摘要当材料做 map-reduce 式汇总，回答跨文档的综合问题。
这一套设计本质上是把“知识组织”前置了。传统 RAG 把知识组织的任务留给查询时的向量召回，GraphRAG 则在索引期就用 LLM 帮你把文档结构化成显式图。这里顺带聊一下热词里的“本体 RAG”：本体是某个领域里已经定义好的概念和关系约束，比如“软件开发项目一定有代码仓库、人员、技术栈，代码仓库归属于项目”。如果你手里已经有这类本体，完全可以在抽取提示词里要求 LLM 先把文本里的实体映射到本体实例上再抽关系，抽取准确率会明显提升；没有本体时，LLM 抽出来的关系也天然形成一张轻量本体，只是需要你事后做归一化。
1.3 索引流水线的地位：一次错误，全程污染
GraphRAG 的模型开销主要发生在索引期，查询期的成本反而低。索引阶段产出的不只是向量，还包括实体表、关系表、社区表、文本块表等一系列中间结构。查询质量几乎完全被这些结构的干净程度决定。
如果索引期的实体抽错了、关系重复了、社区摘要截断了，查询端怎么调 prompt 都救不回来。我在实际项目中见过太多人反复优化 query 侧，最后发现根因在索引侧。所以如果你想真正掌握 GraphRAG，第一站必须是索引流水线，而不是查询效果。
2. 索引流水线 10 步拆解：每一步产出什么、为什么不能省
2.1 文档加载与清洗：决定下游命运的脏活
第一步是把你手里的 Markdown、PDF、HTML、wiki 导出 XML 等不同格式统一转成纯文本。这一步看着基础，实际上对下游影响最大。我跑 wiki 语料时最大的坑是“把导航、页脚、目录当成正文”抽进了图谱。wiki 页面里的“编辑本页”“相关链接”“参见条目”这些模板内容如果不清理，实体抽取会把它们当作正常句子，抽出大量无关节点。
清洗阶段不要只靠肉眼扫两遍就算了。跑完清洗后我会随机抽 30 条文本样本人工确认，必要时写正则和模板专门打掉常见噪声。文本编码问题也值得留意，尤其是中文语料里偶尔混入的不可见字符，轻则多出一堆“�”实体，重则导致 JSON 解析失败但被静默吞掉。
2.2 文本分块：切太碎会切断关系，切太大模型会漏
GraphRAG 的分块参数和传统 RAG 不太一样，它更偏大。我自己实测时用官方默认配置，chunk_size 大约 1200 token、overlap 100，不同版本会略有差异。分块直接决定了后续 LLM 抽取实体时的上下文边界：块太小会把一个完整的“A 依赖 B 且因为 C”关系链从中间切断；块太大则会让模型在长文本里读着读着就漏掉尾部实体。
我建议把 chunk_size 放在 800–2000 token 的区间里搜索，根据文体微调：wiki 型碎片化页面用 1200 足够，长文档、技术手册这类密集说明文本可以调到 1600–2000。overlap 的作用是弥补切割边界的损失，50–200 token 都可以，我常用 100。这里有个容易忽略的点：你设置了 chunk 大小，但文档加载器真正按字符切分后得到的 token 数并不精确。跑完分块后要看实际 chunk 的平均 token 分布，不要只看理论值。
2.3 实体抽取与描述生成：整个流水线的质量地基
这是整个索引流水线里最烧 LLM 预算的环节，也是质量地基。做法是把每个 chunk 丢给 LLM，要求只输出结构化 JSON 数组，包含实体名、类型、描述。我踩过的最典型的一个坑是：提示词里没写“没有实体时请输出空数组”，结果模型在空文本块上输出一句“本文没有实体，因为这是一个导航页面”，然后 JSON 解析直接失败。更糟的是有些解析失败不会被标记为任务失败，而是把 null 写进表里，静默失败就这么出现了。
所有抽取类 prompt 我都建议把 temperature 锁到 0。温度一旦高起来，同一个实体在不同 chunk 里会生成不同变体，比如“GraphRAG”可能变成“Graph RAG 框架”，去重阶段会非常痛苦。抽取时如果项目里有领域本体，可以在 prompt 中附一份实体类型清单，让模型优先把实体名映射到清单内，这一步对图谱可用性的提升非常明显。
2.4 关系抽取与去重合并：图结构能否成立的关键
关系抽取一般和实体抽取在同一个 prompt 里完成，要求模型同时输出 relationships，字段包括 source、target、description、weight。抽取完成后你会发现一个普遍现象：同一个实体在多个 chunk 里被反复抽到，关系也被重复生成。GraphRAG 官方流水线里有实体合并机制，但不能完全依赖它。
我自己会额外补一层归一化：实体名先做 strip、小写、去引号处理，再叠加同义词映射和别名表，最后合并同实体对上的重复关系。关系合并的常见策略是保留 weight 最高的一条，或者把多条描述做 concat 汇总，再给 weight 做归一化。这一步如果做得糙，查询时节点之间会出现大量重复路径，local search 拿到的证据冗余到崩。
2.5 图谱构建与存储：把抽取结果变成真正的图
实体表、关系表、文本块表出来后，就可以构建真正的图结构了。GraphRAG 默认会用内存里的图结构完成后续社区检测，中间产物以 parquet 或 graphml 形式落盘。你需要重点检查的是图的基本统计量：节点数、边数、平均度、孤立节点比例。
一组健康的数据大概长这样：节点数在几千的量级，边数至少是节点数的 1.5 到 2 倍以上，孤立节点占比小于 5%。如果你跑完发现节点三千、边才八百，那基本可以断定关系抽取出了严重问题，后面社区检测根本不会形成有意义的社区。先跑小样本验证统计量，再放大数据，这是我给自己定的规矩。
2.6 社区检测：Leiden 算法怎么把图切成情报小组
图建好以后，下一步是切成社区。GraphRAG 默认用 Leiden 算法，它是 Louvain 的升级版，核心改进是保证发现出来的社区内部是连通的，不会出现 Louvain 里“一个社区被切成两块还硬说是一块”的问题。算法跑完后会形成一棵层级树：第一层是细粒度小社区，第二层把每个社区当新节点再聚一次，直到达到 max_level 上限。
社区级的质量直接决定 global search 能拿到什么样的“全局材料”。社区切得过碎，摘要数量爆炸、成本飙升；切得过粗，摘要过于笼统、信息量低。max_level 在 2–5 之间是常见选择，我实测下来 3 到 4 对大多数语料性价比最高。如果你语料本身就偏聚合，比如 20 篇 wiki 页面都在讲同一套技术栈，那 2 到 3 层就够用了。
2.7 社区总结：把一堆节点浓缩成一段情报
对每个社区，GraphRAG 会把社区内所有实体描述和关系描述拼进 prompt，让 LLM 输出一段社区摘要。这一步是索引期 token 消耗的第二波冲击。社区数量多时，摘要 prompt 的输入往往非常长，成本会超线性上涨。
我的经验是：摘要的 prompt 里要求模型除了输出一段散文之外，还要单列“关键实体”和“关键关系”两个字段，方便下游快速拼接或过滤。社区报告的 token 上限也要控制，我常用 1200–2000。如果摘要输出被截断，导致段落结尾不完整，但整体格式仍然正常，这就属于典型的静默失败，后面 QA 阶段读到的是一条信息残缺的“证据”。
2.8 向量化与向量存储：不止给文本块打向量
GraphRAG 不是只给文本块做 embedding。实体描述、社区摘要、关系描述都需要向量化，这样才能让 local search 从任意入口出发召回相关内容。向量存储可以接入多种后端，官方默认支持 lancedb、azure blob 等，二次开发也能接 qdrant 或 faiss。
这里最重要的一条纪律是：所有内容必须用同一套 embedding 模型和同一向量维度。混合使用两个模型会导致局部检索区间完全不可比，而且这种问题几乎不会在日志里暴露。向量化之后还建议做一次全零行检查，我后面会详细讲这个坑。
2.9 索引持久化与增量更新：静默失败的高发区
索引完成后，实体表、关系表、社区表、文本块表会分别落盘。如果你的语料要持续增长，增量更新就是绕不开的话题。官方有增量方案，但实际在自定义 pipeline 里，增量更新需要自己设计“文档级分片重建”：找出受影响的文本块，重建实体抽取，再对图做全量社区重检。
为什么不建议简单追加？因为新增实体很可能改变既有社区的边界，不重跑社区检测会导致新旧描述不一致，查询时同一个概念出现两份互相矛盾的定义。增量更新是我实测中静默失败的最高发区，至少一半异常发生在这个阶段，后面 8 轮实测我会重点讲一次翻车现场。
2.10 查询端装配：索引做了这么多，到底服务谁
索引产出的所有表，最终服务于两类查询。local search 从问题里做实体匹配，挑出相关节点，沿拓扑取邻居、社区摘要和文本块；global search 按 map-reduce 的方式把多层社区摘要汇总后拼进上下文。这两类查询的效果 80% 由索引期的社区总结质量决定，prompt 本身只占一小部分。
所以当你发现 local search 答得支离破碎、global search 答得泛泛而谈时，不要只调查询 prompt，先回来检查索引期的实体去重和社区摘要是否完整。理解了这 10 步，你才算真正看懂了 GraphRAG 的索引侧。
3. 8 轮实测实录：参数每动一次，结果都在变
3.1 测试环境和基线设定
实测的语料是我本地 wiki 导出的技术文档集，清洗后约 20 篇文章、40 万 token。模型用的是 GPT-4o 系列，embedding 用 text-embedding-3-small。第一轮基线配置基本接近官方默认：chunk_size 1200、overlap 100、并行度 8、max_level 3、温度 0。第一轮的意义在于建立“诚实基线”，任何调参后的变化都能跟它对照。
这里说一句实话，第一轮跑通后我的第一反应是高兴，但随后随机抽查样本就发现约 9% 的实体名里带着多余引号和空格。这个比例虽然不高，但在文档量放大到几十倍以后，就会变成几千个噪声节点。跑通不等于正确，这是我给自己刻在桌面上的第一条 GraphRAG 经验。
3.2 八轮实测数据一览
我把 8 轮测试汇总成一张表，方便对照：
| 轮次 | 改动变量 | 实测现象 | 结论 |
|---|---|---|---|
| 第 1 轮 | 默认配置基线 | 全流程跑通，实体约 2400 个、关系约 6100 条；局部问答可用，跨文档归纳一般 | 建立基准线 |
| 第 2 轮 | chunk_size 1200 加到 2000 | 实体数升到 3100，漏抽明显减少；但关系重复对数量暴增，去重耗时变长 | 大 chunk 覆盖更好，必须加重后处理 |
| 第 3 轮 | 并行度 8 加到 16 | 索引时间缩短近一半；出现超时重试，部分请求被重复写入 | 并发提速有代价，下游必须幂等 |
| 第 4 轮 | 文档量 20 篇扩到 200 篇 | 成本翻约 8 倍；社区检测单步内存接近阈值，时间明显变慢 | 大数据量需要分片与分级配置 |
| 第 5 轮 | embedding 换成 BGE-zh | 向量化正常、维度 1024；中文语料整体召回略降但可用 | 开源模型可行，维度必须完全一致 |
| 第 6 轮 | max_level 从 3 调到 5 | 全局摘要数量增加 3 倍，跨文档综合问答准确率提升；延迟和 token 消耗同步上涨 | 层级数是一个典型的性价比杠杆 |
| 第 7 轮 | 抽取温度从 0 调到 0.7 | 实体名出现“脑补”扩展，比如 GraphRAG 变成 GraphRAG（一种图检索增强技术），重复率大增 | 抽取 prompt 必须锁 0 温度 |
| 第 8 轮 | 增量更新 10 篇文章 | 旧实体被重复重写、实体 ID 变化，同一个概念出现两套描述，问答结果冲突 | 增量更新必须用稳定实体 ID，不能反复重建 |
3.3 几轮关键测试的详细复盘
第 2 轮让我意识到一个规律：chunk 变大后，实体抽取完整性上去了，但同一个实体对在不同 chunk 里被重复抽取的概率也同步上升。原来 1200 token 块里一个关系可能只被抽到一次，改成 2000 token 后，A 和 B 之间的关系可能被三个 chunk 各自抽一遍。这不是模型变笨了，而是覆盖重叠变多、去重逻辑没跟上。我在关系表写入前加了“实体对 + 关系类型”的聚合，把多条描述做 concat 并归一化 weight，冗余才降下来。
第 3 轮的陷阱在“重试补齐”。并行度调高后，个别 LLM 调用会超时，客户端自动重试并成功。但从超时到重试成功之间，第一次调用的尾部响应还在内存里，下游任务不知道这次调用实际是“半成功”还是“全失败”，于是同一 text_unit 被重复写入。排查时索引时间看起来正常，数据量却莫名膨胀。后来我在写表前对 chunk_id + task_id 做了去重，问题消失。
第 6 轮是我愿意推荐大家多花时间尝试的方向。max_level 收到 5 以后，global search 能从更细的社区摘要里取内容，回答“这些技术栈之间有哪些共性依赖”这类问题明显更稳。代价是 prompt 变长、延迟上去了。如果你成本敏感，可以先在 3 和 4 之间做对比，而不是直接一步跳到 5。
第 8 轮是增量更新的翻车现场。我在旧索引上补了 10 篇文章，结果大部分旧实体被重新抽取了一遍，实体哈希 ID 变化导致同一概念在图上出现了两个节点。查询时模型读到两边摘要，给出“GraphRAG 有两种定义”这种自言自语式答案。后来我把实体 ID 改成“规范化实体名 + 哈希”，而不是“按批次生成的序号”，才让增量更新真正稳定下来。
4. 静默失败全档案：那些不报错的失败，怎么发现、怎么修
4.1 静默失败的三种典型面目
静默失败最麻烦的地方在于，它不会在你面前摔跤。我总结出三个反复出现的特征：第一，进程正常退出、退出码 0、日志里几乎没有 error 级别记录，但结果表里缺少关键字段或者字段内容为空；第二，数据本身明显不干净，比如实体名里混着“�”字符、纯标点实体、重复率超过 30%，但统计报表不主动提示你；第三，查询阶段模型回答得语气流畅、内容却完全错误——“一本正经地胡说八道”是静默失败最典型的出口。
为什么“不报错”比“报错”更可怕？因为报错会逼你处理，不报错只会在后续环节累积灾难。索引期的错误可能会污染实体表、关系表、社区摘要，每一步都消化一部分错误信号，最后到查询端导出的是连续推理出来的错误答案，而你已经无从追溯是哪个环节造成的。
4.2 我踩过的八类静默失败
做一张速查表，把我实测中遇到的高频静默失败列出来：
| 静默失败类型 | 典型现象 | 为什么难发现 | 修复方向 |
|---|---|---|---|
| 空实体数组 | 实体表为空或近乎为空 | 日志显示“已处理 N 个 chunk”，但过滤后全空 | 跑完统计实体数，设最小阈值告警 |
| 分块截断实体 | 同一实体被切成两个残体节点 | 单个 chunk 内看着正常，图里却出现两个残缺节点 | overlap 调大，抽查 chunk 边界样本 |
| 去重失效 | 实体数虚高，重复率超过 30% | 实体数量可观，统计上看不出毛病 | 统一 prompt 温度，额外做名称归一化 |
| 描述字段为 NULL | 实体摘要全部丢失 | 表格能正常加载，列存在但值为空 | 每个落盘表做 schema 非空校验 |
| schema 版本错位 | 字段改名后下游读旧字段 | 代码引用旧列名只是拿到 None，不抛异常 | 每个 step 打印新表 schema 并对齐 |
| embedding 全零向量 | 部分文档永远召不回 | 索引正常跑完，查询时那几篇却永远不出现 | 校验向量矩阵的非零行比例 |
| 超时重试写重复 | 同一文本块被重复处理 | 索引时间正常，去重后数据量对半砍 | 写表时按 chunk_id + task_id 去重 |
| 社区摘要被截断 | 摘要结尾在句子中途断掉 | 文本长度看起来正常，标点却不对 | 检查 summary token 上限和结尾标点 |
4.3 静默失败的三种定位手段
第一种是数据体检。索引每次跑完后，我至少会确认实体数、关系数、社区数、平均度是否在合理区间。如果 20 篇文档只有 12 个实体，那不管日志多绿，都说明抽取环节基本失效。
第二种是抽样人工检查。随机抽取 20 条实体描述、10 条关系记录，逐条读一遍。这个习惯帮我发现过“空实体数组”和“摘要被截断”两类问题。人工检查成本不高，但收益极大。人造数据可以糊弄统计量，却糊弄不了阅读。
第三种是反查测试。准备 5 个已知答案的问题，直接在图谱里查能否形成证据链。比如我知道第 3 篇文档里写过“系统 A 依赖 B 组件”，那就问 local search“A 的依赖有哪些”，看证据路径是否能够从问题一路走到原文。如果路径断在某个社区摘要上，说明社区总结环节出了问题。
4.4 一次典型排查现场：空实体数组
有次我在小语料上跑完索引，实体数只有十几个，但日志显示每个文本块都由模型处理过。我一度以为是提示词写得不够清楚，后来发现真凶是 prompt 里的一个词：我在“没有实体时输出 none”这句里写了 none，结果 LLM 非常听话，80% 的 chunk 都输出了字符串“none”。在模型眼里 none 是一个合法实体名，于是图谱里长了一堆名叫 none 的光杆节点。
这类问题完全不会触发任何报错，因为 LLM 的回复格式是正确的 JSON，只是内容语义错了。修复方式是提示词改成“如果没有实体，请输出空数组，不要解释”，并且在下游把“none”“null”“N/A”等字符串显式过滤掉。从那以后，所有抽取 prompt 都会加一句“必须输出 JSON 数组，空结果为 []”。
4.5 一次典型排查现场：全零向量
还有一次我遇到某几篇文档在查询时永远召不回。索引跑得正常、向量表能加载，但仔细检查向量矩阵后发现那几行全是 0。原因是这几篇文档经过预处理后文本非常长，embedding 接口对超长输入做截断时报了空向量，而客户端代码里写了个 fallback 用零向量填充。日志没有 error，因为把空向量替换成零向量是“设计好的逻辑”，不是异常。
修复方法是在向量化步骤之后做一个清洗：统计全零行比例，超过阈值直接重跑 embedding。单条文本超长的问题也要在分块阶段处理，比如按 token 上限强制截断或跳过异常文本。现在我每次跑完索引都会打印向量矩阵 shape、维度、全零比例这三项，任何一项异常都能在 10 秒内发现。
5. 参数配置与成本调优：让索引流水线跑得又快又稳
5.1 核心参数矩阵
| 参数 | 推荐范围 | 影响范围 | 我的常用值 |
|---|---|---|---|
| chunk_size | 800–2000 token | 实体抽取完整性与关系重复度 | 中文语料 1600 |
| chunk_overlap | 50–200 token | 跨块实体截断问题 | 100 |
| 并行度 parallelism | 4–32 | 建索引速度与超时风险 | 8–16 |
| 抽取模型 | 长上下文模型或 OpenAI 4o | 抽取质量与成本 | 4o |
| temperature | 必须 0 | 防止实体名随机变体 | 0 |
| max_level | 2–5 | 社区摘要粒度与 token 消耗 | 3–4 |
| 社区报告摘要 token 上限 | 800–2000 | 摘要完整性 | 1200–1500 |
| embedding 模型 | 领域匹配即可 | 检索一致性 | BGE-zh 或 OpenAI |
5.2 成本估算：先算清楚再开工
GraphRAG 索引期的 token 消耗不是一个可以忽略的小数字。我实测的经验是：原始文本 100 万 token，全流程消耗通常要达到 1000 万 token 以上，差距主要在实体抽取、关系抽取和社区总结这三道关卡。
可以按下面的简式粗算：
- 实体抽取输入 ≈ chunk 数 ×（chunk token 数 + 500）
- 实体抽取输出 ≈ chunk 数 × 400
- 关系抽取输入输出与实体抽取同级，合计再乘 2
- 社区报告输入 ≈ 社区总数 × 平均社区描述 token
- 社区报告输出 ≈ 社区总数 × 400
比如 1000 个 chunk、每个 1600 token，实体+关系抽取的输入就接近 420 万 token，输出约 80 万 token。社区部分还会因为层级数增加而翻倍。省成本的有效手段包括锁定 temperature 减少重试、控制 max_level、限制社区摘要长度、在增量更新时只重建受影响分片。千万别在大语料上直接默认配置全量跑，先拿小样本把参数锁定。
5.3 推荐配置参考
小型项目（文档量 100 篇以内）的 settings.yaml 参考配置：
chunks: size: 1200 overlap: 100 llm: model: gpt-4o temperature: 0 embeddings: llm: model: text-embedding-3-small parallelism: num_threads: 8 community_reports: max_level: 3 max_length: 1200注意不同版本 GraphRAG 的配置项名可能存在差异。动手前先跑graphrag init生成默认配置文件，再按上面的思路覆盖。中大型项目建议把 embedding 服务和 LLM 服务拆开，用独立的 GPU embedding 服务跑向量化，并开启增量更新；社区 max_level 先设 3，跑完一批后看社区摘要质量再决定是否加层。增量更新阶段，实体 ID 请务必使用规范化实体名哈希，而不是按批次生成的序号，这条建议值回你踩的坑。
6. 写在最后：索引跑稳了，GraphRAG 才算真正落地
跑完这 8 轮，我最大的体会是：GraphRAG 不是“多了一个 RAG 变体”，而是把索引从“可省略的预处理”提升成了“决定系统上限的核心资产”。静默失败比运行失败更值得你花时间盯，因为运行失败是在逼你处理问题，而静默失败是让错误数据悄悄流进下游，你还在错误的结果上继续调优。我现在给自己定了一条规矩：任何一次索引参数改动，都要用同一份语料跑两次，对比中间产物的哈希和统计量。这个习惯至少帮我找回了三回即将上线前才发现的数据事故。第二篇我打算写 GraphRAG 查询端本地搜索和全局搜索的选型对比与常见坑，等把 query 侧也聊完，这套 GraphRAG 才算真正走通整条链路。
