GraphRAG：微软图谱RAG框架安装与使用指南

官方信息

项目背景

传统 RAG 有一个致命短板：它只能回答"局部问题"——比如"合同第三条写了什么"。但如果你问"这份 1000 页的报告整体讲了什么？""这些公司之间有什么关联？""整个行业的趋势是什么？"——基于向量相似度的检索就抓瞎了，因为答案分散在几百个片段里，没有任何一段单独包含完整答案。

微软研究院提出的 GraphRAG 就是为了解决这个问题。它的思路是：先用 LLM 从文档中抽取出实体（人、组织、地点、事件）和它们之间的关系，构建成一张知识图谱；然后对图谱做社区检测（community detection），把紧密相连的实体聚成一个个"主题社区"；再用 LLM 为每个社区生成摘要。回答全局性问题时，GraphRAG 会把所有社区摘要汇总起来让 LLM 综合回答。

GraphRAG 在"全局性问题"（global search）上效果远超传统向量 RAG，但代价是索引阶段成本高——需要用 LLM 处理每一个文档片段，构建图谱。它适合文档量大、需要做综述/分析/关联推理的场景，比如法律文书分析、新闻舆情、企业知识洞察。

核心特性

• 知识图谱构建：自动从文本抽取实体和关系，构建实体关系图。
• 社区检测与摘要：用 Leiden 算法把图谱聚类成主题社区，自动生成社区摘要。
• 全局搜索（Global Search）：回答"整体趋势""主题概览"类问题，这是传统 RAG 做不到的。
• 局部搜索（Local Search）：基于实体邻居和关联证据回答具体问题。
• 多种 LLM 支持：OpenAI、Azure OpenAI、Ollama、本地模型。
• 可视化：导出图谱为 GEXF/GraphML，用 Gephi 或 yEd 可视化。
• 批处理索引：离线建库，查询时毫秒级响应。

环境要求

详细部署步骤

第一步：环境准备

conda create -n graphrag python=3.11 -y
conda activate graphrag

第二步：安装 GraphRAG

方式一：pip 安装

pip install graphrag

# 验证
graphrag --version

方式二：源码安装

git clone https://github.com/microsoft/graphrag.git
cd graphrag
pip install -e .

第三步：初始化项目

mkdir -p my_graphrag/input
cd my_graphrag

# 初始化配置文件
graphrag init --root ./

这会在当前目录生成 settings.yaml 和 output/ 目录。

第四步：准备输入数据

把要分析的文本文件（.txt / .md）放进 input/ 目录：

# 示例：把一堆文章放进去
cp /path/to/documents/*.txt input/

# 注意：每个文件是一个独立的"文档"
# 文件编码 UTF-8，纯文本格式

第五步：配置 settings.yaml

vim settings.yaml

关键配置项：

llm:
  api_key: ${GRAPHRAG_API_KEY}
  type: openai_chat
  model: gpt-4o-mini
  # 如果用 DeepSeek（兼容 OpenAI 接口）：
  # api_base: https://api.deepseek.com/v1

embeddings:
  model: text-embedding-3-small
  # 本地 Embedding 可换 nomic-embed-text

chunks:
  size: 1200
  overlap: 100

# 报告类型
reports:
  enabled: true

设置环境变量：

export GRAPHRAG_API_KEY=sk-xxxxxxxx

第六步：构建索引（最耗时的一步）

# 全量构建索引
graphrag index --root ./

# 这个过程会：
# 1. 把文档切分成 chunk
# 2. 用 LLM 抽取实体和关系
# 3. 构建知识图谱
# 4. 社区检测
# 5. 为每个社区生成摘要
# 6. 生成全局报告

索引时间取决于文档数量和 LLM 速度。100 篇文章大约需要 30 分钟到 2 小时，会消耗一定的 API token。

第七步：全局搜索（Global Search）

全局搜索回答"综述类"问题：

graphrag query \
  --root ./ \
  --method global \
  --query "这些文档主要讨论了哪些主题？有什么共同趋势？"

第八步：局部搜索（Local Search）

局部搜索回答"具体实体相关"的问题：

graphrag query \
  --root ./ \
  --method local \
  --query "张三和李四之间是什么关系？"

第九步：用 Python API 调用

from graphrag.query.indexer_adapters import read_indexer_reports
from graphrag.query.structured_search.global_search.search import GlobalSearch

# 加载索引后的产物（在 output/ 目录下）
# 然后调用 search 方法

常见坑与解决

• 索引成本太高：先用小数据集测试（10 篇文章），确认效果后再全量；用便宜的模型（gpt-4o-mini）做实体抽取。
• API 限流：settings.yaml 中调小 async_jobs 并发数。
• 中文效果差：GraphRAG 默认 Prompt 是英文优化的，需要自定义 entity_extraction_prompt 为中文。
• 内存爆掉：文档量超过 1 万篇时，建议分片处理或换用图数据库后端。

使用方法示例

索引完成后，output/ 目录会包含：

• entities.parquet：抽取的实体列表
• relationships.parquet：实体关系
• communities.parquet：社区划分
• community_reports.parquet：每个社区的摘要报告

这些文件可以导入 Neo4j、Gephi 做可视化。全局搜索适合"总结""趋势""概览"类问题；局部搜索适合"某个具体实体相关"的问题。

常见问题 FAQ

Q1：GraphRAG 和普通 RAG 区别？
A：普通 RAG 靠向量相似度找相关片段，擅长"找具体答案"；GraphRAG 构建知识图谱并做社区摘要，擅长"总结全局趋势"。两者互补，可以组合使用。

Q2：索引成本有多高？
A：每 100 万 token 文档，实体抽取大约消耗 50-100 万 token 的 LLM 调用。用 gpt-4o-mini 大约几美元。

Q3：支持中文吗？
A：基础功能支持，但默认 Prompt 是英文的，需要自定义中文抽取 Prompt 才能达到最佳效果。

Q4：能增量更新吗？
A：官方正在支持，目前主要是全量重建。新文档加入后需要重新跑索引。

Q5：开源协议？
A：MIT 协议，可自由商用。

跳转链接

• GitHub 仓库：https://github.com/microsoft/graphrag
• 官方论文：From Local to Global: A Graph RAG Approach to Query-Focused Summarization
• 文档：https://microsoft.github.io/graphrag/