nano-graphrag 从入门到理解 一份写给初学者的教程

假设你手里有一批公司内部文档，你想让 AI 帮你回答问题。会遇到两类麻烦：

RAG（Retrieval-Augmented Generation，检索增强生成）的思路一句话就能说完：

完整流程分两个阶段：

被切成的每一小块叫一个 分块（chunk）。为什么按块存，而不是整篇存？因为检索时"粒度"要小——一篇 5000 字的文章里可能只有 200 字和你的问题相关，返回整篇既浪费又会淹没重点。

那么"找出最相关的几块"具体怎么实现？这就引出下一课的向量检索。

怎么判断"哪几块和问题相关"？最朴素的办法是关键词匹配——搜"奶茶"就找含"奶茶"的块。但"开奶茶店"和"经营饮品连锁"没有共同关键词，语义上却是近义的。

Embedding（向量化）解决这个问题：用一个专门的模型把文字变成一串数字（一个坐标点），规则是——意思越接近的文字，坐标离得越近。

存这些坐标的地方叫向量数据库（向量库）。查询时：把问题也转成坐标 → 计算距离 → 返回最近的 top-k 块。距离常用余弦相似度衡量。

普通 RAG（切块 → 向量检索）很好用，但有三个天然短板，正好对应第一课的两个问题：

知识图谱（Knowledge Graph）就是上一课说的那张"网"：

• 节点（Node）= 实体：人、公司、地点、事件…… 如「小李」「茶百道」「杭州」
• 边（Edge）= 关系：两个实体之间有联系。如 小李 —就职于→ 茶百道
• 每个节点/边上还可以挂一段描述文字和一个权重（关系多强）

用例子画出来是这样：

[小李] ──就职于(权重8)──▶ [茶百道] ──成立于2008──▶ [成都]
  │                         │
  └──位于──[杭州]        ──总部位于──[成都]

问题「小李的公司成立于哪年？」在图上就是走两步：
   小李 ──就职于──▶ 茶百道 ──成立于──▶ 2008   ✔ 两个块的信息被边"串"起来了

GraphRAG 的完整思路（微软 2024 年提出，nano-graphrag 是它的极简实现）分两个阶段：

三个短板与解法一一对应：

使用这个库只有两个动作，这是第一个。你写代码时它长这样：

from nano_graphrag import GraphRAG

graph = GraphRAG(working_dir="./my_kg")
graph.insert("小李在杭州的茶百道工作……")   # 把文档喂进去

这一行 insert 背后发生了 6 件事，每件都在磁盘 ./my_kg/ 留下产物：

第二个动作是提问，通过 QueryParam(mode=...) 选三种模式之一：

from nano_graphrag import QueryParam

graph.query("小李的公司成立于哪一年？", QueryParam(mode="local"))   # 问细节
graph.query("这批公司整体发展如何？",     QueryParam(mode="global"))  # 问全局
graph.query("茶百道总部在哪？",           QueryParam(mode="naive"))   # 翻原文

clone 下来的项目长这样（只看核心目录 nano_graphrag/）：

做什么

把文档切成小块（chunk）。默认策略是按 token 数滑动窗口硬切：每块最多 1200 个 token，相邻块重叠 100 个 token。

为什么要 MD5 编号？

MD5 是把任意内容压缩成固定长度指纹的函数：内容相同 → 指纹必然相同；内容差一个字 → 指纹完全不同。用指纹当主键，去重、增量更新、"只处理新内容"全都免费获得了。

两种切法

对应源码

_op.py:31 chunking_by_token_size · _op.py:94 get_chunks · _utils.py:186 compute_mdhash_id

# _op.py 滑动窗口，就 3 行核心逻辑：
for start in range(0, len(tokens), max_token_size - overlap_token_size):
    chunk_token.append(tokens[start : start + max_token_size])   # 每次前进 1100，取 1200

做什么

把每个块发给 LLM，让它按照固定话术，输出这段文字里的实体（是什么）和关系（谁和谁怎么样）。这是整个系统最花钱的一步，所有块并发进行（同时发很多请求）。

发给 LLM 的提示词长什么样

提示词存在 prompt.py，简化后核心是这样：

识别文中所有实体，格式：("entity" <|> 实体名 <|> 类型 <|> 描述)
识别实体间关系，格式：("relationship" <|> 源 <|> 目标 <|> 描述 <|> 强度)
用 ## 分隔每条记录，全部完成后输出 <|COMPLETE|>

--- 示例（few-shot）---
("entity" <|> "Alex" <|> "person" <|> "Alex 是个观察力敏锐的角色……")##
("relationship" <|> "Alex" <|> "Taylor" <|> "Alex 受 Taylor 影响" <|> 7)

--- 真实数据 ---
Text: {你切好的那个块}

Gleaning：追问"还有漏的吗？"

第一次抽取后，系统会再发一句 "MANY entities were missed in the last extraction. Add them below…"（上次漏了很多，补上），让模型补充；再问一句"还有吗？YES/NO"决定是否继续。这叫 gleaning（打谷扬场式的复查），就像写完作文后再检查一遍错别字。entity_extract_max_gleaning 控制最多复查几轮（默认 1 轮）。

做什么

每个块各自抽出了实体，现在要把全库结果汇成一张图。核心问题是：10 个块都提到了"茶百道"，图里应该有 10 个节点还是 1 个？——1 个。同名实体合并为同一节点。

合并时三个字段怎么处理

边（关系）合并同理，两点差异：

• 权重累加：两个实体在不同块里反复共同出现 → weight 相加，说明关系越铁
• 图是无向的：(A,B) 和 (B,A) 是同一条边，聚合前统一按字母序排好

合并完成后，每个实体（名称＋描述）会被向量化存进实体向量库——这就是第 6 课流程里的最后一步⑥，local 查询正是靠它找回相关实体的。

_op.py:182 _merge_nodes_then_upsert · _op.py:230 _merge_edges_then_upsert · _op.py:111 描述超长摘要

做什么

图建好后，可能有成千上万个节点。把互相连接紧密的一簇节点划成一组，一个组就叫一个社区（community）。这一步由聚类算法完成，nano-graphrag 用的是 Leiden 算法。

为什么要"层级"？

圈子可以套圈子：「茶百道-研发圈」内部又分「小李-小王-小张」小组。Leiden 输出的就是多层结果（level 0、1、2……）：层数字越小圈越大（level 0 ≈ 全公司大部门，level 2 ≈ 项目小组）。同一节点可以同时属于多个层的社区。

level 0:  [====== 一个大社区（100 人）======]
level 1:     [== 社区A（30人）==]   [== 社区B（40人）==]
level 2:        [小组A1] [小组A2]      [小组B1] [小组B2]

代码里每个节点存一份归属记录：
"clusters": [{"level":0,"cluster":5}, {"level":1,"cluster":12}, ...]

occurrence（出现度）是什么？

每个社区会算一个 0~1 的值：该社区覆盖的文本块数 ÷ 全库最大社区的文本块数。直觉上，覆盖原文越多的社区，越"有料"——后面查询排序时会用到它。

_storage/gdb_networkx.py:230 _leiden_clustering · _storage/gdb_networkx.py:170 community_schema

做什么 & 为什么

对每个社区，把它内部的实体、关系打包，让 LLM 写一份结构化摘要报告。这一步是在为"全局问题"预存答案：

报告里有什么

LLM 被要求返回一个 JSON（提示词在 prompt.py 的 community_report）：

{
  "title": "茶百道研发与成都总部社区",
  "summary": "该社区围绕茶百道展开，包含其成都总部、杭州研发中心及人员……",
  "rating": 6.5,                    // 0~10 分：这个圈子的重要程度
  "rating_explanation": "涉及核心业务实体，影响中等偏上",
  "findings": [                       // 5~10 条要点，每条=标题+展开
    {"summary":"茶百道的双城布局", "explanation":"成都总部与杭州研发……"},
    ...
  ]
}

报告会存成两份：JSON（保留 rating 等结构化字段，供排序过滤用）和 Markdown 文本（供直接阅读/拼进提示词）。

怎么保证不超模型窗口：打包预算

一个社区可能有几百个节点，全塞进提示词会爆窗口。系统有一套打包策略（_pack_single_community_describe）：

_op.py:625 generate_community_report · _op.py:464 打包预算逻辑

它怎么回答"小李的公司成立于哪一年？"

五步走，全部发生在 _build_local_query_context 里：

_op.py:844 _build_local_query_context · _op.py:935 local_query

它完全不走实体向量，只读"年报"

问「这批文档里的公司整体发展如何？」——没有任何单个实体能回答这个问题。global 的策略是把第 13 课写好的所有社区报告拿来，走一轮 Map-Reduce：

对比 local，二者的分工非常清晰：

_op.py:1017 global_query · _op.py:970 _map_global_communities

最简单的一个模式，四步：

它与 local 的区别只有一个开关：enable_naive_rag=True 时才会额外建一个分块向量库（local 用的是实体向量库，两者是不同的库）。

先说 token

token 是 LLM 的"字数单位"：模型有上下文窗口上限（如 128k token），API 按 token 计费。项目里所有"1200"、"500"、"16384"之类的数字都是 token 数。项目用一个叫 TokenizerWrapper 的工具把文字数成 token（底层是 tiktoken），全项目数 token 只走这一个口，换成别的分词器也不影响别处。

核心矛盾

全项目的统一工具：truncate_list_by_token_size

def truncate_list_by_token_size(list_data, key, max_token_size, tokenizer):
    tokens = 0
    for i, data in enumerate(list_data):        # 按顺序累加
        tokens += len(tokenizer.encode(key(data))) + 1
        if tokens > max_token_size:
            return list_data[:i]                  # 装满就停，返回前缀
    return list_data

它在源码里出现了十几次，每次调用前列表都已经排好序，所以"返回前缀"＝"保留最重要的"。这就是前面各课反复看到的"预算 4000 tokens""按评分截断"背后的同一行代码。

LLM API 会限流、会抖动、会重复计费。_llm.py 给每次调用上了三道保险：

保险一 · 重试（摔倒了爬起来）

遇到限流错误（RateLimitError）或连接错误时，最多再试 5 次，间隔 4→10 秒指数变长。用的是 tenacity 库的 @retry 装饰器，套在每个调用函数外面，调用方无感知。

保险二 · 缓存（同一道题不答两次）

_llm.py:50 openai_complete_if_cache · _utils.py:220 compute_args_hash

保险三 · 限流（进闸门先排队）

抽取几百个块时会同时发几百个请求，API 必然报错。系统给每个 LLM/Embedding 函数外面套了一层并发闸门（limit_async_func_call）：同时最多 16 个在飞（可配），第 17 个请求必须等前面有人完成才放行。

_utils.py:276 limit_async_func_call

系统里的数据其实分三种形态

"可插拔"是怎么实现的？

base.py 只定义接口（一堆 raise NotImplementedError 的方法声明），不关心后面是谁。具体实现放在 _storage/ 里。想换零件？改一个字段：

from nano_graphrag._storage.gdb_neo4j import Neo4jStorage

graph = GraphRAG(
    graph_storage_cls=Neo4jStorage,          # 图存储从 NetworkX 换成 Neo4j，就这一行
    vector_db_storage_cls=HNSWVectorStorage, # 向量库同理
)

还有个容易忽略的设计：统一的落盘时机

所有存储都继承同一个基类，带三个钩子函数：index_start_callback（开始写入前调用）、index_done_callback（全部写完后调用）。默认实现是"整个 insert 过程都在内存里改，最后一次性把 JSON/graphml/向量库写到磁盘"——避免写一半崩了留下脏数据。

base.py:59-186 接口定义 · graphrag.py:360 _insert_done 统一落盘

建议的上手顺序（由浅入深，每步都有反馈）

可以继续学的概念（按性价比排序）