GraphRAG 详解：微软基于知识图谱的 RAG 系统
普通向量 RAG 擅长"找到相关段落"，却答不好"这批文档整体讲了什么主题、各主题之间什么关系"这类全局性问题——因为答案散落在成百上千个chunk里，检索只能捞到零星几块。microsoft/graphrag（GraphRAG）就是微软为此提出的解法：先用 LLM 从文本里抽取实体与关系、构建知识图谱，再对图做社区聚类、逐层摘要，把"全局理解"变成可检索的资产。约 35.6k Star、MIT 协议，背后是同名论文。本文从动机、原理、CLI 上手、三种检索到成本与现状，完整拆解。
1、项目概述
GraphRAG 是微软研究院开源的模块化、基于图的检索增强生成系统，定位是用 LLM 从非结构化文本中抽取有意义的结构化数据（实体、关系、声明），作为问答的目标上下文。仓库约 35.6k Star、3.7k Fork，MIT 协议，对应论文 GraphRAG: Unlocking LLM Discovery on Narrative Private Data（arXiv 2404.16130）。
两个必须先知道的现状：
- 项目目前处于维护模式（maintenance mode）：只修 bug 与依赖安全更新，不再加新特性、不收 PR
- 官方明确警告：索引是昂贵操作（大量 LLM 调用），务必从小数据集起步、先读文档
- 官方强烈建议先做提示词调优（prompt tuning），而非直接用开箱默认
- 责任 AI 说明在 RAI_TRANSPRAENCY 之外的 RAI_TRANSPARENCY.md，含用途、局限与评估指标
2、为什么需要图：向量 RAG 的全局性盲区
向量检索的机制是"拿问题找相似的块"，这决定了它天生擅长局部、弱于全局。
向量 RAG 的两类短板：
- 全局性问题：如"这批文档的主要主题是什么"——答案需要汇总整个语料，检索只能捞出少数块
- 关系性问题：如"A 和 B 怎么关联的"——跨文档的实体关系没有被显式组织，靠块相似度撞运气
GraphRAG 的思路：
1. 把非结构文本升级成"实体 + 关系 + 声明"的结构化知识图谱
2. 对图做社区检测（Leiden 算法），把关联实体聚成主题社区
3. 用 LLM 为每个社区生成摘要报告，形成分层"全局地图"
4. 问答时按问题类型选择：查细节走图邻域，问全局走社区报告
3、核心概念：索引管线与查询引擎
仓库由两大包组成：Indexing Pipeline（建图建摘要）与 Query Engine（答问）。
索引管线产物：
- 实体表与关系表：从每个文本块抽取的人、地、组织及相互关系
- 社区（communities）：Leiden 算法聚出的实体簇，分多层级
- 社区报告（community reports）：逐社区生成的主题摘要，高层社区汇总低层
- 全部产物落在 output 目录的 parquet 文件里（create_final_entities 等表）
查询引擎两种打法：
- Global Search：map-reduce 扫社区报告答全局问题
- Local Search：从问题实体出发走图邻域，答细节问题
- DRIFT Search：全局与局部结合的混合检索
4、安装与 CLI 快速上手
官方推荐在虚拟环境里装包，init 初始化工作区后配置模型，再一条命令建索引。
// 安装（建议先建 venv）
python -m pip install graphrag
// 在项目目录初始化：生成 .env、settings.yaml 与 input/ 目录
graphrag init
// .env 里只需一个变量，填 OpenAI 或 Azure 的 Key
// GRAPHRAG_API_KEY=sk-...
// 下载示例语料（一本公版书）
curl https://www.gutenberg.org/cache/epub/24022/pg24022.txt -o ./input/book.txt
// 建索引（昂贵操作，小数据集先行）
graphrag index// 全局问题：默认走社区报告
graphrag query "What are the top themes in this story?"
// 局部问题：指定 local 方法
graphrag query "Who is Scrooge and what are his main relationships?" --method local
// 升级小版本后需强制重新初始化配置（免重索引）
graphrag init --root [path] --force上手要点：
1. init 生成 .env（只放 GRAPHRAG_API_KEY）与 settings.yaml（模型配置）
2. 用 Azure 的话在 settings.yaml 的 models 块里补 deployment、api_base 等参数
3. 索引完成后查 output 目录的 parquet 表，可导入分析工具复盘图结构
4. 小版本升级用 init --force 重建配置；跨大版本走迁移 notebook 避免重索引
5、三种检索模式怎么选
索引建好后，按问题的"格局"选检索方法是使用 GraphRAG 的关键。
选择依据：
1. 问语料整体：主题、趋势、宏观比较 → Global（社区报告 map-reduce）
2. 问具体对象：某人、某组织、某事件的相关细节 → Local（图邻域扩展）
3. 既要全局脉络又要局部细节的复合问题 → DRIFT 混合检索
4. 经验法则：先 global 摸清语料地图，再 local 深挖感兴趣的主题
效果差异：
- 全局摘要类问题上，社区报告式检索显著优于向量基线（论文核心结论）
- 细节问答上图邻域检索可结合原文块，保住向量检索的局部优势
- DRIFT 用少量全局信号引导局部探索，兼顾覆盖与深度
6、成本与调优
GraphRAG 的强大是花钱买的：索引阶段的 LLM 调用量与语料规模成正比，调优因此不是可选项。
成本构成：
- 实体抽取：每个文本块至少一次 LLM 调用
- 社区报告：每个社区逐层生成摘要，社区数量随图规模增长
- 官方建议：先小语料试跑、看懂 settings.yaml 各项再放量
省钱与提质：
1. 抽取与摘要可用不同档位模型（便宜的做抽取，强的做摘要）
2. 先跑 prompt tuning，让抽取提示词贴合你的领域词汇
3. 适当调大块粒度、限制实体类型，直接减少调用量
4. 索引一次、多次查询——把成本摊到问答侧
7、生态位与同类工具
GraphRAG 是"用图增强 RAG"范式的源头，如今已长出一个工具家族。
生态位：
- 论文与官方实现定义了"知识图谱 + 社区摘要"的标准范式
- WeKnora 等知识库平台已把 GraphRAG 纳入检索策略选项
- LightRAG、nano-graphrag 等社区实现提供了更轻量的替代
- 与代码知识图谱类工具（Graphify、Code-Graph-RAG）同范式不同域：一个面向文档叙事，一个面向代码库
使用建议：
1. 想复现论文效果、吃透原理 → 用官方实现
2. 要控制成本快速落地 → 评估 LightRAG 等轻量分支或平台内置的 GraphRAG 选项
3. 注意维护模式现状：新项目选型时把"不再演进"纳入考量
8、总结
GraphRAG 是微软开源的图增强 RAG 系统（35.6k Star、MIT、论文支撑），核心是两步：索引用 LLM 抽取实体关系建知识图谱、Leiden 聚社区并逐层生成摘要报告；查询按问题格局选 Global（社区报告 map-reduce）、Local（图邻域）或 DRIFT（混合）。它补上了向量 RAG 答不了全局性与关系性问题的短板，代价是索引阶段可观 的 LLM 成本，官方要求小步试跑并先做提示词调优。
落地建议：有大量叙事型私有文档（报告、小说、访谈、工单）且需要"问全局"的团队，值得用小样本跑通官方 CLI、对比向量基线验证收益后再放量；成本敏感或要长期演进的项目，可考虑 WeKnora 内置的 GraphRAG 选项或 LightRAG 等轻量实现。把它当作对向量 RAG 的"全局补充"而非替代，是发挥其价值的正确姿势。
