microsoft/graphrag · 上手攻略
- 仓库：microsoft/graphrag
- 链接：https://github.com/microsoft/graphrag
- 分类：rag · llm-infra
- 作者：Tom
- 更新：2026-07-09
它是什么
GraphRAG 是微软研究院开源的模块化图结构 RAG 系统，旨在解决传统向量 RAG 无法处理的"全数据集级别的推理问题"。
传统 RAG 靠向量相似度检索，擅长"找相似片段"，但对"这本小说里最核心的主题是什么"这类需要全局理解的问题力不从心——因为答案分散在大量段落中，向量召回永远只能覆盖局部。
GraphRAG 的核心思路：先用 LLM 将文档内容提取为知识图谱（实体+关系+社区报告），再基于图谱做全局推理。发布于 2024 年，MIT 许可证，Python 实现，当前 Stars 超过 34k，是私有数据 RAG 领域最有影响力的开源项目之一。
解决什么问题
- 全局性问题：传统 RAG 答不了的"总结类"问题，GraphRAG 通过社区报告（Community Reports）在全图谱层面做 Map-Reduce 推理。
- 关系推理问题：需要跨多个实体、多个关系链条才能回答的问题，图谱结构天然支持多跳推理。
- 私有数据理解：通用 ChatGPT 无法访问的内部文档、政策、手册，GraphRAG 帮你构建专属知识图谱并提供推理能力。
快速安装
环境要求
- Python 3.10–3.12（3.13 暂不支持）
- LLM API Key（OpenAI API Key 或 Azure OpenAI）
安装步骤
mkdir graphrag_quickstart && cd graphrag_quickstart
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
python -m pip install graphrag
⚠️ 警告：GraphRAG 索引过程非常消耗 LLM token，建议先用官方提供的样例数据集熟悉流程，再用便宜模型测试，最后才上大模型跑真实数据。
初始化工作目录
graphrag init
按提示输入 chat model 和 embedding model 配置，会在当前目录生成：
- .env — 含 GRAPHRAG_API_KEY=你的密钥
- settings.yaml — pipeline 配置
- input/ — 放待处理的文本文件
下载测试文本
curl https://www.gutenberg.org/cache/epub/24022/pg24022.txt -o ./input/book.txt
配置 API Key
OpenAI 模式：直接在 .env 中替换 GRAPHRAG_API_KEY 的值。
Azure OpenAI 模式：在 settings.yaml 中修改 model_provider: azure，并填写 azure_deployment_name、api_base、api_version：
type: chat
model_provider: azure
model: gpt-4.1
azure_deployment_name: <你的部署名>
api_base: https://<instance>.openai.azure.com
api_version: 2024-02-15-preview
支持 Azure 托管身份认证（auth_method: azure_managed_identity），需提前 az login。
核心用法
索引（Index）
graphrag index
整个流程会：
1. 将 input/ 下的文本切分为 chunks
2. 用 LLM 提取实体（人名、地点、概念等）、关系（实体间联系）和社区报告（社区级别的摘要）
3. 输出 ./output/ 下的 parquet 文件（可配合可视化工具探索图谱）
注意：索引大文档集可能消耗大量 LLM 调用和资金，建议先用小数据集估算成本。
查询（Query）
全局搜索（适合宏观问题）：
graphrag query "What are the top themes in this story?"
本地搜索（适合具体实体问题）：
graphrag query \
"Who is Scrooge and what are his main relationships?" \
--method local
三种查询引擎
| 引擎 | 原理 | 适用问题类型 |
|---|---|---|
| Local Search | 融合图谱实体信息 + 原始文本 chunks | 具体实体、具体关系类问题 |
| Global Search | 对所有社区报告做 Map-Reduce | 总结性、全局性问题 |
| DRIFT Search | 在 Local 基础上引入社区层级信息，扩展检索广度 | 需要兼顾广度和深度的复杂问题 |
| Basic Search | 纯向量相似度（Rough baseline，用于对比） | 快速对比实验 |
Prompt Tuning（重要！）
官方默认 Prompt 是通用场景设计的，直接用效果可能不达预期。强烈建议跑一遍 Auto Tuning：
graphrag tune --help # 查看 auto tuning 用法
Auto Tuning 会用你的实际数据生成领域适配的 Prompt，通常能显著提升索引质量。具体见 官方 Prompt Tuning 文档。
版本升级注意
- 小版本升级（如 0.3.x → 0.4.x）：运行
graphrag init --root <path> --force重建配置。 - 大版本升级：使用官方提供的迁移 notebook（需重索引数据），迁移前务必备份原有配置和 output。
典型适用场景
| 场景 | 为什么用 GraphRAG |
|---|---|
| 企业内部知识库问答 | 私有文档（合同、手册、研究报告）的全局推理，比普通 RAG 效果更好 |
| 学术文献综述 | 从大量论文中提炼主题、方法和关系网络 |
| 法律文档分析 | 发现法律条文间的引用关系和逻辑结构 |
| 文学作品分析 | 角色关系网络、主题提炼、全文语义理解 |
| 新闻事件溯源 | 多篇报道中事件、人物、机构的关系推理 |
坑与注意
- 索引成本极高：处理一本《圣诞颂歌》就要消耗大量 LLM token。生产环境使用前，务必用小数据评估费用；建议优先尝试 GPT-4o-mini 等便宜模型调优，确认流程正确后再切生产模型。
- Python 版本严格：仅支持 3.10–3.12，3.13 会报错。
- 实体抽取质量依赖模型能力：弱模型（如 GPT-3.5-turbo）抽出的图谱质量有限，最终查询效果也会受限，建议至少 GPT-4o 级别。
- Auto Tuning 不是可选的：官方文档明确建议"strongly encouraged to run"，不做 tuning 的效果差距明显。
- 配置复杂有一定门槛：
settings.yaml涉及 LLM、embedding、chunk_size、community_level 等多个参数，理解各参数含义需要时间。 - 输出不可直接用于生产：parquet 输出是中间格式，若要做可视化或 API 化，需要额外封装。
与同类对比
| 方案 | 特点 | 对比 GraphRAG |
|---|---|---|
| 传统向量 RAG（Faiss / Milvus / Pinecone） | 纯向量检索，简单高效 | 无法处理全局性问题；GraphRAG 补足了这一环 |
| LightRAG | 更轻量的图+向量混合 RAG | 更简单更快，但全局推理能力不如 GraphRAG |
| Neo4j + 通用 RAG | 用图数据库做知识图谱存储 | 需要自己维护图谱 pipeline；GraphRAG 一体化完成抽取+存储+查询 |
| BM25 + Rerank | 传统关键词检索 + 重排 | 对长尾实体召回更好，但无推理能力 |
| GraphRAG | 微软开源，图谱 + 全局推理 | 成熟度高（34k Stars），但索引成本高，配置复杂 |
一句话推荐结论
当你需要处理的不是"找一段话"而是"理解这个文档集合的全局结构和关系"时，GraphRAG 是目前最成熟的开源方案；用它，但务必先用小数据把整个流程跑通并做好成本估算再上生产。