一、项目定位与设计目标

nano-graphrag 是一个轻量级、易于二次开发的 GraphRAG 参考实现，旨在为开发者提供一个比微软官方 GraphRAG 实现更简洁、更易读的代码库。根据 readme.md 的描述，除去测试代码与提示词模板外，整个项目的核心代码体量仅约 1100 行，强调小巧、便携、异步、全类型化四个工程属性。

项目的主要设计取舍可以归纳为以下几点：

• 小而完整：保留 GraphRAG 核心功能（实体抽取、关系建模、社区聚类、局部/全局搜索），移除了官方实现中较为繁重的工程抽象。
• 可插拔架构：LLM、Embedding、KV 存储、向量库、图存储全部以接口方式暴露，详见 nano_graphrag/base.py。
• 持久化友好：通过 working_dir 目录将中间产物（文本块、图、社区报告、向量索引、KV 缓存）落到磁盘，下次启动可自动恢复。

二、安装与环境准备

nano-graphrag 提供两种安装方式，二者皆在 readme.md 的 Install 章节给出。

重要前置条件：默认 LLM 与 Embedding 均依赖 OpenAI，因此需设置环境变量 export OPENAI_API_KEY="sk-..."。如使用 Azure OpenAI，则需参考 .env.example 配置并传入 using_azure_openai=True；使用 Amazon Bedrock 时需 aws configure 后配置 using_amazon_bedrock=True（参见 readme.md）。

常见问题：在 Windows 系统上 pip install 可能因默认编码（cp1252）报错，issue #125 跟踪了该问题，建议在安装前设置 PYTHONIOENCODING=utf-8。

三、快速上手：从零运行一个 GraphRAG

完整的快速入门示例同样定义在 readme.md 的 Quick Start 章节，核心调用由 nano_graphrag/__init__.py 暴露的 GraphRAG、QueryParam 入口组成。

from nano_graphrag import GraphRAG, QueryParam

# 1. 初始化，指定持久化目录
graph_func = GraphRAG(working_dir="./dickens")

# 2. 插入语料
with open("./book.txt") as f:
    graph_func.insert(f.read())

# 3. 全局检索（社区报告层面）
print(graph_func.query("What are the top themes in this story?"))

# 4. 局部检索（实体子图层面，作者认为更可扩展）
print(graph_func.query(
    "What are the top themes in this story?",
    param=QueryParam(mode="local"),
))

3.1 三种检索模式

QueryParam.mode 控制检索策略，依据 readme.md 的描述可总结为：

• global：基于社区报告（community report）的全局总结式回答；
• local：基于实体-关系子图的局部精确回答，是 readme.md 推荐的可扩展方案；
• naive：朴素向量检索模式，需要在 GraphRAG(..., enable_naive_rag=True) 时启用。

3.2 异步与增量插入

每个同步方法都对应一个 a 前缀的异步方法（如 ainsert、aquery），实现位于 nano_graphrag/graphrag.py。此外 readme.md 指出 nano-graphrag 使用文本的 md5 哈希作为去重键，因此支持增量插入而不会产生重复数据块，但每次插入都会重新计算社区与社区报告。

四、组件生态

nano-graphrag 的可替换组件由 nano_graphrag/base.py 中的 BaseKVStorage、BaseVectorStorage、BaseGraphStorage 三大基类定义，结合 readme.md 中的组件表，可得下表：

社区 issue #2（"Add more Storages and LLMs?"）正在征集更多 MongoDB、Ollama 等接入方案，相关 PR 与示例收录在 examples/ 目录。

五、典型数据流（High-level Pipeline）

下图概括了 GraphRAG.insert 与 GraphRAG.query 在一次生命周期内的主要阶段，步骤名称与 readme.md 的 Quick Start / Naive RAG 章节保持一致。

flowchart LR
    A[原始文本] --> B[chunk_func 文本分块]
    B --> C[best_model 抽取实体/关系]
    C --> D[BaseGraphStorage 写入图]
    C --> E[BaseVectorStorage 写入向量]
    D --> F[社区检测与社区报告生成]
    F --> G[(working_dir 持久化)]
    H[用户查询] --> I{QueryParam.mode}
    I -- local --> J[向量召回 + 实体子图]
    I -- global --> K[社区报告筛选与映射]
    I -- naive --> L[纯向量相似度检索]
    J --> M[best_model 答案合成]
    K --> M
    L --> M
    M --> N[最终回答]

六、已知差异与社区关注点

为了让新接入的开发者形成合理预期，文档需明确 nano-graphrag 与微软原版 GraphRAG 的两点实现差异，内容来自 readme.md 的 Issues 章节：

1. 未实现 covariates：协变量（与实体相关的时序/事件数据）特性在当前版本中缺失，参见 docs/ROADMAP.md。
2. 全局检索策略简化：原版采用 map-reduce 形式遍历所有社区报告；nano-graphrag 仅取最重要的 Top-K 中心社区（由 QueryParam.global_max_consider_community 控制，默认 512 个）。

另外，社区 issue #99 提出了对微软 DRIFT 搜索模式的接入请求，issue #56 讨论了 local_rag_response 提示词中"Goal"与"Target response length and format"重复出现的问题——这两点都是潜在改进方向（参见 docs/FAQ.md）。

七、See Also

• docs/ROADMAP.md：项目路线图与未来特性规划。
• docs/FAQ.md：常见问题解答。
• docs/benchmark-en.md / docs/benchmark-zh.md：英文/中文基准测试结果。
• examples/benchmarks/eval_naive_graphrag_on_multi_hop.ipynb：在 MultiHop-RAG 任务上的评估 notebook。
• docs/use_neo4j_for_graphrag.md：将图存储切换为 Neo4j 的教程。

一、定位与设计目标

nano-graphrag 是一个面向研究者和二次开发者的轻量级 GraphRAG 实现，主仓库宣称"在剔除 tests 与 prompt 后仅约 1100 行代码"（readme.md）。其官方定位是：相对于微软官方 GraphRAG 仓库难以阅读与改动的痛点，提供一个更小、更快、更整洁，且保留核心能力（实体抽取、关系构建、社区摘要、local/global 检索）的替代实现。GraphRAG 主体以 dataclass 形式暴露在 nano_graphrag/graphrag.py 中，使用者只需 GraphRAG(working_dir=...).insert(...) 与 graph_func.query(...) 即可完成端到端流程。

社区中 #2 议题"Add more Storages and LLMs"反映了该项目的另一关键定位：可插拔，即把存储、向量库、LLM、Embedding 全部抽象为可替换组件。Issue #125 反馈的 Windows 安装编码错误也表明该项目主要面向具备一定 Python 调试能力的开发者。

nano-graphrag 将"插入"与"查询"过程中的所有中间产物抽象为三类可插拔的存储组件：键值存储（KV）、向量存储（Vector）、图存储（Graph）。在 _storage 目录下，每个具体实现都以独立模块的形式存在，并对外提供统一的 BaseKVStorage / BaseVectorStorage / BaseGraphStorage 抽象接口。用户可以按需替换实现，从而把磁盘文件、nano-vectordb、Milvus、Neo4j 等不同后端组合起来。资料来源：nano_graphrag/_storage/__init__.py:1-30

存储后端分类与默认实现

GraphRAG 在初始化时会根据传入的 *_storage_cls 决定使用哪一套实现，文件 nano_graphrag/_storage/__init__.py 把它们聚合导出。社区 Issue #2 长期呼吁增加 MongoDB、PostgreSQL 等 KV 后端，说明该层在扩展性上仍有较大需求。资料来源：readme.md:Components

数据流：从原始文本到可查询图谱

nano-graphrag 在 insert 阶段把数据按"分块 → 抽取实体关系 → 写入向量库/图存储 → 社区聚类"四条路径并行推进，状态会同时落到 KV、Vector、Graph 三类存储里。query 阶段依据 QueryParam.mode 选择 local / global / naive / mix 中的一种，从相应存储中取回上下文。aquery / ainsert 是同语义的异步版本。资料来源：readme.md:Quick Start

flowchart LR
    A[原始文档] --> B[chunking_by_token_size<br/>或 chunking_by_seperators]
    B --> C{Entity & Relation<br/>Extraction}
    C -->|JSON 解析| D[BaseGraphStorage<br/>networkx / Neo4j]
    C -->|embedding| E[BaseVectorStorage<br/>nano-vectordb / hnswlib]
    D --> F[Community Detection<br/>聚类]
    F --> G[Community Report<br/>cheap LLM 总结]
    D --> H[(BaseKVStorage<br/>磁盘 JSON)]
    E --> H
    G --> H
    H --> I[query / aquery<br/>local | global | naive]
    I --> J[LLM 生成最终答案]

可视化：GraphML 导出

nano-graphrag 自身不内置交互式可视化，但内置的 networkx 后端可以把图直接导出为 GraphML，从而接入 Gephi、yEd、 Cytoscape 等工具。README 提到，当数据量较大时曾出现 graphml_visualize.py 解析失败的问题，v0.0.8 已通过 PR 修复（#27 中的同类修复）。对于 Neo4j 用户，官方文档 docs/use_neo4j_for_graphrag.md 建议直接使用 Neo4j Browser 进行可视化。资料来源：readme.md:Components

配置注入与社区常见问题

通过 GraphRAG 的 dataclass 字段即可注入自定义存储：

• GraphRAG(key_string_value_json_storage_cls=YOURS, ...) 替换 KV；
• GraphRAG(vector_db_storage_cls=YOURS, ...) 替换向量库；
• GraphRAG(graph_storage_cls=YOURS, ...) 替换图存储。

当所有存储都不是文件型时，建议设置 always_create_working_dir=False 以跳过目录创建。资料来源：readme.md:Advances

社区方面有几点需要留意：

1. Windows 编码问题（Issue #125）：在 Windows 上首次安装运行可能因 cp1252 编码失败，需要在源码读取处显式指定 encoding="utf-8"。这是安装层的常见故障点。资料来源：readme.md:Install
2. 重复 prompt 片段（Issue #56）：PROMPTS["local_rag_response"] 中确实存在 "Goal" 与 "Target response length and format" 的内容重复，目前属于模板原文的有意保留，可在自定义 prompt 时手动清理。
3. DRIFT 搜索（Issue #99）：社区已提出希望参考微软 GraphRAG 新增的 DRIFT 搜索模式，该模式依赖额外的图遍历与社区筛选逻辑，可能需要扩展 BaseGraphStorage 的查询能力。资料来源：readme.md:Issues

See Also

• 进阶特性：LLM、Embedding 与 Prompt 定制
• Neo4j 集成指南
• 异步与批量插入用法
• 返回纯检索上下文的查询模式

LLM 函数扩展

双模型抽象

nano-graphrag 在内部使用两类 LLM：「高级模型」负责规划与生成答案，「廉价模型」负责摘要与社区报告等批量任务。默认情况下前者为 gpt-4o，后者为 gpt-4o-mini。资料来源：readme.md:80-120。用户可通过 GraphRAG 数据类的 best_model_func 与 cheap_model_func 注入自定义函数，并通过 best_model_max_token_size、best_model_max_async、cheap_model_max_token_size、cheap_model_max_async 控制并发与上下文上限。资料来源：readme.md:120-150。

自定义函数签名

参考 nano_graphrag/_llm.py 中的 gpt_4o_complete，用户自定义的 LLM 函数应满足如下异步签名：

async def my_llm_complete(
    prompt, system_prompt=None, history_messages=[], **kwargs
) -> str:
    hashing_kv: BaseKVStorage = kwargs.pop("hashing_kv", None)
    response = await call_your_LLM(messages, **kwargs)
    return response

其中 hashing_kv 会被框架用于 LLM 调用级缓存，剩余 **kwargs 透传给具体模型（如 max_tokens）。

多后端示例

仓库在 examples/ 目录中提供了多种后端的参考实现：

社区中长期存在「增加更多 LLM 与存储后端」的需求，issue #2 跟踪了 MongoDB、Ollama 等后端的支持进度。资料来源：Issue #2。

嵌入函数扩展

默认嵌入函数使用 text-embedding-3-small，输出维度 1536，最大 token 数 8192。资料来源：nano_graphrag/_utils.py 中的 openai_embedding。替换方式与 LLM 类似，通过 embedding_func 注入，并通过 wrap_embedding_func_with_attrs 装饰器声明 embedding_dim 与 max_token_size。资料来源：readme.md:150-200。

仓库提供两类本地嵌入示例：

• using_ollama_as_llm_and_embedding.py：在无 OpenAI Key 时同时替换 LLM 与嵌入。
• using_local_embedding_model.py：使用 sentence-transformers 在本地计算向量。

替换时需保证新函数的 embedding_dim 与目标向量库一致，否则会触发向量库初始化错误。

提示词体系

关键 Prompt

所有提示词集中在 nano_graphrag.prompt.PROMPTS 字典中，可在运行时直接覆写。资料来源：nano_graphrag/prompt.py。其中最关键的四个 prompt 及其用途如下：

• PROMPTS["entity_extraction"]：从文本块中抽取实体与关系。
• PROMPTS["community_report"]：对图谱聚类（社区）进行结构化总结。
• PROMPTS["local_rag_response"]：本地搜索的系统提示模板。
• PROMPTS["global_reduce_rag_response"]：全局搜索的系统提示模板。
• PROMPTS["fail_response"]：当检索结果为空时的兜底回答。

资料来源：readme.md:30-80。

JSON 输出的稳定性

框架在调用 best_model_func 时会附带 "response_format": {"type": "json_object"}，以约束实体抽取输出为合法 JSON。资料来源：readme.md:180-210。部分开源模型（如 Ollama 系列）可能输出不稳定 JSON，框架提供 convert_response_to_json_func 钩子，推荐使用 json_repair 等库做容错。

分块策略 Prompt 联动

PROMPTS["entity_extraction"] 默认期望一段连续的文本块输入，因此分块粒度直接影响实体召回。可通过 chunk_func 切换为 chunking_by_seperators（基于分隔符的文本切分）。资料来源：nano_graphrag/_op.py 与 using_custom_chunking_method.py。

常见故障与排查

Windows 编码问题

Issue #125 报告在 Windows 平台 pip install 时触发 cp1252 解码错误。资料来源：Issue #125。建议在执行前设置：

set PYTHONIOENCODING=utf-8
chcp 65001

或使用 pip install --user 避免系统级 site-packages 写入冲突。

Prompt 中重复字段

Issue #56 指出 PROMPTS["local_rag_response"] 中 "Goal" 与 "Target response length and format" 存在重复段落。资料来源：Issue #56。该重复是模板中的有意冗余，用于强化 LLM 遵循格式；但若影响 token 预算，可直接在 PROMPTS 中覆写该字符串以去除冗余。

重复插入与社区重建

每次调用 insert 后，框架会重新计算图谱社区并重生成 community report。资料来源：readme.md:200-260。如需增量插入且避免重建，可结合 working_dir 持久化机制，仅追加新文本块。

全局搜索差异

官方 GraphRAG 在全局搜索中采用 map-reduce 风格，将所有社区填入上下文；nano-graphrag 仅选择 top-K 重要社区（默认 512 个，由 QueryParam.global_max_consider_community 控制）。资料来源：readme.md:280-300。如需更接近官方行为，可调大该参数，但需权衡上下文长度。

DRIFT 搜索缺失

社区已在 issue #99 中请求添加 Microsoft 新增的 DRIFT 搜索模式。资料来源：Issue #99。目前可通过自定义 aquery 调用并复用 `nan

See Also

• 架构总览
• 存储后端扩展
• 查询模式（local / global / naive）
• Roadmap

Pitfall Log / 踩坑日志

项目：gusye1234/nano-graphrag

摘要：发现 13 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：配置坑 - 来源证据：JSONDecodeError using no_openai_key_at_all.py。

1. 配置坑 · 来源证据：JSONDecodeError using no_openai_key_at_all.py

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：JSONDecodeError using no_openai_key_at_all.py
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/gusye1234/nano-graphrag/issues/75 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据："'charmap' codec can't decode" error encountered when installing on windows from source

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题："'charmap' codec can't decode" error encountered when installing on windows from source
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/gusye1234/nano-graphrag/issues/163 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

3. 安装坑 · 来源证据：docker部署

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：docker部署
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/gusye1234/nano-graphrag/issues/166 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

4. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/gusye1234/nano-graphrag | host_targets=claude, chatgpt

5. 配置坑 · 来源证据：Writing graph with 0 edges triggers leiden error

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Writing graph with 0 edges triggers leiden error
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/gusye1234/nano-graphrag/issues/167 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

6. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/gusye1234/nano-graphrag | README/documentation is current enough for a first validation pass.

7. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/gusye1234/nano-graphrag | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/gusye1234/nano-graphrag | no_demo; severity=medium

9. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/gusye1234/nano-graphrag | no_demo; severity=medium

10. 安全/权限坑 · 来源证据：Installation issue on Windows machine related to encoding

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Installation issue on Windows machine related to encoding
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/gusye1234/nano-graphrag/issues/125 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

11. 安全/权限坑 · 来源证据：[Feature] Add ArcadeDB as graph storage backend

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature] Add ArcadeDB as graph storage backend
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/gusye1234/nano-graphrag/issues/173 | 来源类型 github_issue 暴露的待验证使用条件。

12. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/gusye1234/nano-graphrag | issue_or_pr_quality=unknown

13. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/gusye1234/nano-graphrag | release_recency=unknown