本文全面解析微软开源的 GraphRAG 项目，从它是什么、怎么用、如何优化运行性能、生成哪些关键文件，到如何集成到你自己的业务中。内容深入但通俗，适合开发者、数据分析师、AI工程师学习参考。
一、什么是 GraphRAG？它解决了什么问题？
GraphRAG（Graph Retrieval-Augmented Generation）是微软研究团队发布的开源项目，它是一种“图增强的检索生成系统”。
与传统的RAG不同，GraphRAG不仅仅是“检索+生成”，它引入了图结构，使得RAG具备以下关键能力：
| 能力 | 描述 |
|---|---|
| 结构化理解 | 构建文档内的实体-关系图谱 |
| 全局洞察 | 对文档中的知识点进行社区聚类和语义总结 |
| 精确查询 | 提供局部语义搜索与全局知识总结两种方式 |
| 可解释性强 | 每个结论都可以回溯原始实体、文本、社区 |
使用GraphRAG的典型场景：
- 长文档问答（文档QA）：如法律文书、政策文件、财报等
- 结构化摘要生成：需要从海量文本中提炼结构化知识
- 知识图谱构建：不手写规则、纯靠LLM自动提取关系
- 企业数据洞察：对公司资料、项目报告进行结构建模和分析
🆚 GraphRAG vs 传统 RAG vs Embedding Search
| 特性 | 传统Embedding Search | 普通RAG | GraphRAG |
|---|---|---|---|
| 基于向量检索 | ✅ | ✅ | ✅ |
| 上下文生成 | ❌ | ✅ | ✅ |
| 知识关系建模 | ❌ | ❌ | ✅ |
| 社区聚类分析 | ❌ | ❌ | ✅ |
| 全局结构回答 | ❌ | ❌ | ✅ |
| 可解释性 | 中 | 低 | 高 |
简言之，GraphRAG是对RAG的能力升级，不仅可问，还能解释“知识是如何构成的”。
二、如何跑通 GraphRAG？从0到1完整流程
1. 安装环境（推荐使用虚拟环境）
pip install graphrag 不再需要 Poetry、源码克隆等繁琐步骤。GraphRAG 已正式发布到 PyPI。2. 初始化项目目录
使用官方命令快速初始化：
graphrag init --root ./ragtest 这一步会生成标准的目录结构： ragtest/ ├── settings.yaml # 主配置文件 ├── prompts/ # 提示词模板 ├── . env # 存放API密钥（需手动填入） └── input/ # ❗需要手动创建，用来放你要分析的文档3. 配置 API 密钥
编辑.env文件，填入你的 API Key。例如使用硅基流动 API：
GRAPHRAG_API_KEY = sk-your-siliconflow-api-key 同时，在settings.yaml中设置 API 提供方：models: default_chat_model: type: openai_chat api_base: https://api.siliconflow.cn/v1 api_key: ${GRAPHRAG_API_KEY} model: deepseek-ai/DeepSeek-V3 encoding_model: cl100k_base concurrent_requests: 3 requests_per_minute: 30 default_embedding_model: type: openai_embedding api_base: https://api.siliconflow.cn/v1 api_key: ${GRAPHRAG_API_KEY} model: BAAI/bge-large-zh-v1.5 encoding_model: cl100k_base concurrent_requests: 3 requests_per_minute: 304. 添加文档到 input 目录
将你需要处理的文档放入ragtest/input/目录中：
ragtest/ ├── settings.yaml # 配置文件 ├── prompts/ # 提示词模板 ├── input/ # 数据输入目录（需手动创建） ├── .env # 存储API密钥 └── output/ # 自动生成的索引结果 支持.txt,.pdf,.docx等多种格式。5. 运行索引构建命令
cd ragtest graphrag index --root . 该命令会自动完成以下过程：- 文本分块
- 实体识别与关系提取（调用大模型）
- 构建实体-关系图谱
- 社区检测（Leiden算法）
- 生成社区摘要（调用大模型）
- 嵌入计算 + 向量索引构建
这个过程会花费很长时间
6. 运行查询命令
# 全局查询（问结构化主题） graphrag query --root . --method global "公司的核心项目是什么？" # 局部查询（问细节语义） graphrag query --root . --method local "张三的职责是什么？" 需要在包含 settings.yaml 配置文件的目录中运行，也就是 ragtest 目录。 cd ragtest # 切换到包含settings.yaml的目录 示例： graphrag query --root . --method global --query "张飞是谁的兄弟" Missing reports for communities: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140, 141, 142, 143, 144, 145, 146, 147, 148, 149, 150, 151, 152, 153, 154, 155, 156, 157, 158, 159, 160, 161, 162, 163, 164, 165, 166, 167, 168, 169, 170, 171, 172, 173, 174, 175, 176, 177, 178, 179, 180, 181, 182, 183, 184, 185, 186, 187, 188, 189, 190, 191, 192, 193, 194, 195, 196, 197, 198, 199, 200, 201, 202, 203, 204, 205, 206, 207, 208, 209, 210, 211, 212, 213, 214, 215, 216, 217, 218, 219, 220, 221, 222, 223, 224, 225, 226, 227, 228, 229, 230, 231, 232, 233, 234, 235, 236, 237, 238, 239, 240, 241, 242, 243, 244, 245, 246, 247, 248, 249, 250, 251, 252, 253, 254, 255, 256, 257, 258, 259, 260, 261, 262, 263, 264, 265, 266, 267, 268, 269, 270, 271, 272, 273, 274, 275, 276, 277, 278, 279, 280, 281, 282, 283, 284, 285, 286, 287, 288, 289, 290, 291, 292, 293, 294, 295, 296, 297, 298, 299, 300, 301, 302, 303, 304, 305, 306, 307, 308, 309, 310, 311, 312, 313, 314, 315, 316, 317, 318, 319, 320, 321, 322, 323, 324, 325, 326, 327, 328, 329, 330, 331, 332, 333, 334, 335, 336, 337, 338, 339, 340, 341, 342, 343, 344, 345, 346, 347, 348, 349, 350, 351, 352, 353, 354, 355, 356, 357, 358, 359, 360, 361, 362, 363, 364, 365, 366, 367, 368, 369, 370, 371, 372, 373, 374, 375, 376, 377, 378, 379, 380, 381, 382, 383, 384, 385, 386, 387, 388, 389, 390, 391, 392, 393, 394, 395, 396, 397, 398, 399, 400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413, 414, 415, 416, 417, 418, 419, 420, 421, 422, 423, 424, 425, 426, 427, 428, 429, 430, 431, 432, 433, 434, 435, 436, 437, 438, 439, 440, 441, 442, 443, 444, 445, 446, 447, 448, 449, 450, 451, 452, 453, 454, 455, 456, 457, 458, 459, 460, 461, 462, 463, 464, 465, 466, 467, 468, 469, 470, 471, 472, 473, 474, 475, 476, 477, 478, 479, 480, 481, 482, 483, 484, 485, 486, 487, 488, 489, 490, 491, 492, 493, 494, 495, 496, 497, 498] SUCCESS: Global Search Response: 张飞是刘备的兄弟。在三国时期，张飞与刘备、关羽并称为‘桃园三结义’，三人结为异姓兄弟，共同参与了三国的诸多历史事件。[Data: Reports (1, 3)]三、ragtest目录结构详解
一旦运行完索引命令，目录结构如下：
ragtest/ ├── input/ # 输入数据 │ └── three_kingdomspart.txt # 我们给定的文档，比如三国演义 ├── output/ # 主要输出文件 │ ├── documents.parquet # 文档表 │ ├── text_units.parquet # 文本单元表 │ ├── entities.parquet # 实体表 │ ├── relationships.parquet # 关系表 │ ├── communities.parquet # 社区表 │ ├── community_reports.parquet # 社区报告表 │ ├── covariates.parquet # 协变量表（可选） │ └── lancedb/ # 向量数据库 │ └── default/ # 存储文本嵌入向量 ├── cache/ # 缓存文件 │ ├── base_text_units.parquet # 基础文本单元缓存 │ ├── extracted_entities.parquet # 提取的实体缓存 │ ├── extracted_relationships.parquet # 提取的关系缓存 │ └── ... (其他中间缓存文件) └── logs/ # 运行日志 └── indexing-engine.log # 索引过程日志四、GraphRAG输出文件详解
1️⃣documents.parquet（文档表）
- 存储原始文档的元信息与全文内容
- 每个文档一个条目，记录其
title、text、doc_id 就是原始文档的条目
2️⃣text_units.parquet（文本单元表）
将每个文档分块（chunk）后的切片内容
每一块对应一次LLM调用（如实体提取）
就是切分后的每一个chunk的内容
3️⃣entities.parquet（实体表）
- 所有文档中提取出的人物、组织、地点、事件
- 包含：实体名称、类型、频率、描述、出现在哪些块中
- 是知识图谱的"节点"
4️⃣relationships.parquet（关系表）
- 每对实体之间的语义关系（如“张三-管理-产品部”）
- 包含描述、关系类型、权重等
- 是知识图谱的"边"
5️⃣communities.parquet（社区表）
- 基于图谱运行社区检测算法，聚出“主题组”
- 每个社区包含一组相关的实体（如某产品线团队）
- 作用是发现"主题集群"
6️⃣community_reports.parquet（社区报告表）
- 对每个社区，调用LLM生成的结构化摘要
- 包括报告标题、摘要、主要发现
- 面向的是用户，用的是自然语言
- Qwen模型容易失败，得换个合适的模型
7️⃣lancedb/（向量数据库）
- 每个文本单元的向量表示，用于局部语义搜索
五、GraphRAG是否用到GPU？用的是API还是本地推理？
✅ GraphRAG 默认是纯CPU + API架构
- 大模型（LLM）的生成任务 → 调用远程API（如OpenAI、DeepSeek、硅基流动）
- 向量嵌入 → 调用API返回向量
- 图谱构建与聚类 → 本地CPU完成
无需安装本地大模型，也不需要GPU。只需配置好API Key，即可全流程运行。
六、如何让GraphRAG跑得更快？性能优化建议
虽然GraphRAG不依赖GPU，但它对网络和API速率非常敏感。
常见导致运行慢的原因：
- 文本分块太多（默认1200字符一块）
- 并发请求太高，API服务限速
- 提取的实体种类太多（默认4类）
- 启用了多轮提取或大社区处理
✅ 优化建议清单：
1. 减小文本块大小，降低请求量
chunks: size: 600 # 默认1200，减小可以减少每次Token量 overlap: 502. 限制实体类型
extract_graph: entity_types: [person, organization]3. 降低并发并限速（尤其用硅基流动时）
models: default_chat_model: concurrent_requests: 3 requests_per_minute: 304. 启用缓存
cache: type: file base_dir: "cache"5. 先用小文档测试，逐步扩大规模
进一步的性能优化清单
| 优化点 | 说明 | 适用场景 |
|---|---|---|
| Chunk Size & Overlap 调参 | • 若供应商按token/min计费/限速，减小 chunk可让单次 token-load↓，降低被限速概率；但请求数会增多。• 若按req/min限速，增大 chunk（1500-2000 tokens）+overlap 50→20可以显著减少调用次数。 | 大文件 / 限速严格 |
| 停用 Claim 与 Gleanings | 在settings.yaml：claim_extraction.enabled: false``extract_graph.max_gleanings: 0 | 只想要实体-关系-社区时 |
| 分阶段执行 | 先跑graphrag index --root . --method embeddings只计算嵌入，确认速度 OK 后再跑完整流水线。 | 超长语料试跑 |
| 本地嵌入模型 | 用api_base: http://localhost:11434+ Ollama embedding（nomic-embed）可把 60-70 %的 API 调用转本地，速度和成本双降。 | 有 GPU / CPU 充裕 |
| 递增批处理 | 利用parallelization.stagger（0.3-0.5）让请求批次交错，更平滑地利用限额。 | 供应商支持并发高但限速 |
| 文本预清洗 | 去除页眉页脚、模板重复段，可减少 10-30 % 无效 token。 | PDF 批量导入 |
| 重用 Prompt 模板 | 把长系统 prompt 写进prompt_template:文件并引用，可显著减小每次 token。 | 自定义 prompt 很长时 |
七、我想接入自己项目，应该怎么做？
GraphRAG是标准输出结构+自定义配置驱动的系统，你只需要：
✅ 调整配置文件settings.yaml
- 实体类型适配你业务领域
- 分块策略按文档特点调整
extract_graph: entity_types: [person, department, project] prompt: prompts/extract_business.txt chunks: size: 1000 overlap: 100✅ 修改提示词模板
在prompts/中编写自定义模板，如：
请从以下文本中提取： - PERSON: 员工、客户、合作伙伴 - DEPARTMENT: 公司内部部门 - PROJECT: 项目/产品✅ 使用GraphRAG生成结构化结果并接入你系统
你可以将生成的entities.parquet，``relationships.parquet，``community_reports.parquet作为你系统的知识结构、标签源、甚至问答基础。
✅ 总结
| 功能 | GraphRAG |
|---|---|
| 文档结构建模 | ✅ |
| 实体/关系抽取 | ✅ |
| 社区聚类分析 | ✅ |
| 多层次问答支持 | ✅ |
| 无需本地部署大模型 | ✅ |
| 支持企业定制 | ✅ |
GraphRAG 就像是一个自动化知识工厂，帮你从无结构文本中提炼出有结构的图谱和洞察。只要你配置得当，它可以无缝集成到你任何AI相关的业务系统中。
📎 项目地址：https://github.com/microsoft/graphrag
📖 官方文档：
https://github.com/microsoft/graphrag?tab=readme-ov-file
想入门 AI 大模型却找不到清晰方向？备考大厂 AI 岗还在四处搜集零散资料？别再浪费时间啦！2025 年AI 大模型全套学习资料已整理完毕，从学习路线到面试真题，从工具教程到行业报告，一站式覆盖你的所有需求，现在全部免费分享！
👇👇扫码免费领取全部内容👇👇
一、学习必备：100+本大模型电子书+26 份行业报告 + 600+ 套技术PPT，帮你看透 AI 趋势
想了解大模型的行业动态、商业落地案例？大模型电子书？这份资料帮你站在 “行业高度” 学 AI：
1. 100+本大模型方向电子书
2. 26 份行业研究报告：覆盖多领域实践与趋势
报告包含阿里、DeepSeek 等权威机构发布的核心内容，涵盖：
- 职业趋势：《AI + 职业趋势报告》《中国 AI 人才粮仓模型解析》；
- 商业落地：《生成式 AI 商业落地白皮书》《AI Agent 应用落地技术白皮书》；
- 领域细分：《AGI 在金融领域的应用报告》《AI GC 实践案例集》；
- 行业监测：《2024 年中国大模型季度监测报告》《2025 年中国技术市场发展趋势》。
3. 600+套技术大会 PPT：听行业大咖讲实战
PPT 整理自 2024-2025 年热门技术大会，包含百度、腾讯、字节等企业的一线实践：
- 安全方向：《端侧大模型的安全建设》《大模型驱动安全升级（腾讯代码安全实践）》；
- 产品与创新：《大模型产品如何创新与创收》《AI 时代的新范式：构建 AI 产品》；
- 多模态与 Agent：《Step-Video 开源模型（视频生成进展）》《Agentic RAG 的现在与未来》；
- 工程落地：《从原型到生产：AgentOps 加速字节 AI 应用落地》《智能代码助手 CodeFuse 的架构设计》。
二、求职必看：大厂 AI 岗面试 “弹药库”，300 + 真题 + 107 道面经直接抱走
想冲字节、腾讯、阿里、蔚来等大厂 AI 岗？这份面试资料帮你提前 “押题”，拒绝临场慌！
1. 107 道大厂面经：覆盖 Prompt、RAG、大模型应用工程师等热门岗位
面经整理自 2021-2025 年真实面试场景，包含 TPlink、字节、腾讯、蔚来、虾皮、中兴、科大讯飞、京东等企业的高频考题，每道题都附带思路解析：
2. 102 道 AI 大模型真题：直击大模型核心考点
针对大模型专属考题，从概念到实践全面覆盖，帮你理清底层逻辑：
3. 97 道 LLMs 真题：聚焦大型语言模型高频问题
专门拆解 LLMs 的核心痛点与解决方案，比如让很多人头疼的 “复读机问题”：
![]()
三、路线必明： AI 大模型学习路线图，1 张图理清核心内容
刚接触 AI 大模型，不知道该从哪学起？这份「AI大模型 学习路线图」直接帮你划重点，不用再盲目摸索！
路线图涵盖 5 大核心板块，从基础到进阶层层递进：一步步带你从入门到进阶，从理论到实战。
L1阶段:启航篇丨极速破界AI新时代
L1阶段：了解大模型的基础知识，以及大模型在各个行业的应用和分析，学习理解大模型的核心原理、关键技术以及大模型应用场景。
L2阶段：攻坚篇丨RAG开发实战工坊
L2阶段：AI大模型RAG应用开发工程，主要学习RAG检索增强生成：包括Naive RAG、Advanced-RAG以及RAG性能评估，还有GraphRAG在内的多个RAG热门项目的分析。
L3阶段：跃迁篇丨Agent智能体架构设计
L3阶段：大模型Agent应用架构进阶实现，主要学习LangChain、 LIamaIndex框架，也会学习到AutoGPT、 MetaGPT等多Agent系统，打造Agent智能体。
L4阶段：精进篇丨模型微调与私有化部署
L4阶段：大模型的微调和私有化部署，更加深入的探讨Transformer架构，学习大模型的微调技术，利用DeepSpeed、Lamam Factory等工具快速进行模型微调，并通过Ollama、vLLM等推理部署框架，实现模型的快速部署。
L5阶段：专题集丨特训篇 【录播课】
![]()
四、资料领取：全套内容免费抱走，学 AI 不用再找第二份
不管你是 0 基础想入门 AI 大模型，还是有基础想冲刺大厂、了解行业趋势，这份资料都能满足你！
现在只需按照提示操作，就能免费领取：
👇👇扫码免费领取全部内容👇👇
2025 年想抓住 AI 大模型的风口？别犹豫，这份免费资料就是你的 “起跑线”！
