nano-graphrag
纳米级 GraphRAG 实现，1100 行代码带你搞懂知识图谱检索的核心原理
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
纳米级 GraphRAG 实现，1100 行代码带你搞懂知识图谱检索的核心原理
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
纳米级 GraphRAG，让复杂的知识图谱检索变得触手可及
想象一下：你手头有一份厚厚的用户手册，想让 AI 帮你快速回答「保修期内退换货流程是什么」这样的问题。传统 RAG（检索增强生成）会怎么工作？它把文档切成小块，去向量数据库里找最相似的几块，然后塞给大模型。这听起来没问题，但在真实场景中，问题来了——
如果手册里「退换货」分散在第3章、第7章和附录里，而用户的提问涉及多个知识点的交叉理解，传统的向量检索很可能只捞到一块「皮毛」，回答支离破碎。
微软 GraphRAG 提出了一个优雅的解法：先用大模型从文档中抽取出实体和关系，构建一个知识图谱，再在图谱层面做检索和推理。这样，即使知识点分散在各处，图谱也能把它们串联起来，给出全局性的回答。
但 GraphRAG 有一个致命问题——代码太重了。微软官方实现有几十个模块、数万行代码，普通人想看懂、想改、想借鉴，简直像在读天书。
nano-graphrag 的出现，就是为了解决这个问题。它的核心理念是：小而美、可 hack。
该项目作者在 GitHub 上坦言：「GraphRAG 很好很强大，但微软的官方实现太难读、难改了。」于是他用大约 1100 行代码（不含测试和 prompt）重新实现了一个精简版，保留了 GraphRAG 的核心功能，同时大幅降低了学习和使用门槛。
截至 2025 年，该项目已收获超过 3800 颗 GitHub Stars，413 个 Fork，84 个 open issue，社区活跃度相当可观。用户遍布全球，从 Discord 群组图标可以看出，这个项目有专门的微信群和中国开发者社区。
nano-graphrag 采用了高度模块化的设计，各核心组件都可以自由替换：
文本分块（Chunking）：默认使用 tiktoken 按 token 数量切分，默认每块 1200 tokens，支持重叠。也可以换用 HuggingFace tokenizer 或完全自定义切分函数。
实体关系抽取（Entity Extraction）：核心流程是用 LLM 从文本中抽取实体（Entity）和关系（Relationship），并生成描述。使用 Microsoft GraphRAG 同款 prompt，但支持 DSPy 优化抽取质量。
图谱存储：默认使用 NetworkX 内存图谱，也支持 Neo4j（生产级图数据库）。存储层抽象为 BaseGraphStorage 接口，可以自由插拔。
向量存储：默认 FAISS，也支持 HNSWLib、NanoVectorDB（项目自研轻量向量库）、Milvus、Qdrant 等多种选择。
KV 存储：默认 JSON 文件持久化，也支持自定义存储层。
社区检测：使用 Leiden 算法对图谱进行社区检测（默认参数最大社区规模 10），生成社区报告用于全局查询。
节点嵌入：可选 node2vec 算法对图谱节点做嵌入，提升检索精度。
nano-graphrag 提供了三种不同的检索模式，适用于不同场景：
Local Query（局部查询）：根据用户问题，先在向量库中检索相关实体，再在图谱中扩展相关子图，给出精准的局部答案。这是作者认为最推荐的方式，可扩展性强，适合大多数场景。
Global Query（全局查询）：利用社区报告进行全局推理，适合「这本小说的主题是什么」或「公司的核心价值观是什么」这类需要汇总全文档信息的问题。
Naive RAG（朴素 RAG）：不做图谱，纯粹用向量检索。适合快速对比测试或简单场景。
nano-graphrag 的 LLM 接口层设计非常灵活，开箱支持：
即使你没有 OpenAI API Key，只要有一台普通的 Linux/Mac 电脑，就能通过 Ollama 或 Transformers 本地跑起来。examples 目录下有大量参考脚本，从「零 API Key 方案」到「混合调用方案」一应俱全。
作为一个开源学习项目，nano-graphrag 的代码质量令人印象深刻：
类型安全：全面使用 Python dataclass + 类型注解，IDE 友好，静态检查无压力。
异步支持：所有核心方法都有对应的 async 版本（ainsert、aquery 等），方便集成到异步应用。
测试覆盖：有 .coveragerc 配置，GitHub Actions 集成 Codecov，测试体系完整。
版本发布：已有 v0.0.2 到 v0.0.8 多个正式版本发布，更新维护活跃。
文档完善：有 FAQ、ROADMAP、benchmark 文档，还有中文 benchmark 文档，对中文用户非常友好。
没有 Web UI：这是一款面向开发者的纯 Python 库，所有交互通过 Python 代码完成。非技术用户上手门槛较高。
增量插入的副作用：nano-graphrag 支持增量插入文档（md5 去重），但每次插入都会重新计算社区和社区报告，这是一个已知限制，大文档反复追加时需要注意。
中文支持：实测支持中文，但主要 benchmark 和示例以英文为主，中文场景的表现可能与英文有差异。
向量库依赖：默认使用 FAISS（通过 pip install nano-graphrag 安装），但如果数据量非常大（百万级向量），可能需要升级到 Milvus 等生产级向量库。
nano-graphrag 不仅仅是一个工具，更是一个优秀的GraphRAG 学习教材。作者将微软复杂的 GraphRAG 拆解成一个个可理解的模块，让任何人都能搞懂知识图谱 + LLM 检索的原理，并在其基础上进行二次开发。
从 2024 年 GraphRAG 概念诞生到 2025 年的今天，GraphRAG 已经从「微软黑科技」变成了「人人可 DIY」的开源技术。nano-graphrag 在这个过程中扮演了重要的布道者角色。
对于想要深入理解 RAG 演进路径的 AI 开发者，以及需要快速构建知识图谱问答系统的企业团队，nano-graphrag 都是一个值得关注的开源项目。