# https://github.com/gusye1234/nano-graphrag 项目说明书

生成时间：2026-06-23 23:29:46 UTC

## 目录

- [项目概览与快速入门](#page-1)
- [系统架构、核心模块与查询流程](#page-2)
- [存储后端、可视化与数据流](#page-3)
- [LLM/嵌入扩展、提示词与故障排查](#page-4)

<a id='page-1'></a>

## 项目概览与快速入门

### 相关页面

相关主题：[系统架构、核心模块与查询流程](#page-2), [LLM/嵌入扩展、提示词与故障排查](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [readme.md](https://github.com/gusye1234/nano-graphrag/blob/main/readme.md)
- [nano_graphrag/__init__.py](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/__init__.py)
- [nano_graphrag/graphrag.py](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/graphrag.py)
- [nano_graphrag/_llm.py](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/_llm.py)
- [nano_graphrag/_op.py](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/_op.py)
- [nano_graphrag/base.py](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/base.py)
- [setup.py](https://github.com/gusye1234/nano-graphrag/blob/main/setup.py)
- [requirements.txt](https://github.com/gusye1234/nano-graphrag/blob/main/requirements.txt)
- [docs/ROADMAP.md](https://github.com/gusye1234/nano-graphrag/blob/main/docs/ROADMAP.md)
- [docs/FAQ.md](https://github.com/gusye1234/nano-graphrag/blob/main/docs/FAQ.md)
</details>

# 项目概览与快速入门

## 一、项目定位与设计目标

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

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

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

## 二、安装与环境准备

`nano-graphrag` 提供两种安装方式，二者皆在 [readme.md](https://github.com/gusye1234/nano-graphrag/blob/main/readme.md) 的 `Install` 章节给出。

| 安装方式 | 命令 | 适用场景 |
| :--- | :--- | :--- |
| 源码安装（推荐） | `git clone` + `pip install -e .` | 需要修改源码、阅读实现或参与贡献 |
| PyPI 安装 | `pip install nano-graphrag` | 仅作为依赖库使用 |

> **重要前置条件**：默认 LLM 与 Embedding 均依赖 OpenAI，因此需设置环境变量 `export OPENAI_API_KEY="sk-..."`。如使用 Azure OpenAI，则需参考 [.env.example](https://github.com/gusye1234/nano-graphrag/blob/main/.env.example.azure) 配置并传入 `using_azure_openai=True`；使用 Amazon Bedrock 时需 `aws configure` 后配置 `using_amazon_bedrock=True`（参见 [readme.md](https://github.com/gusye1234/nano-graphrag/blob/main/readme.md)）。

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

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

完整的快速入门示例同样定义在 [readme.md](https://github.com/gusye1234/nano-graphrag/blob/main/readme.md) 的 `Quick Start` 章节，核心调用由 [nano_graphrag/__init__.py](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/__init__.py) 暴露的 `GraphRAG`、`QueryParam` 入口组成。

```python
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](https://github.com/gusye1234/nano-graphrag/blob/main/readme.md) 的描述可总结为：

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

### 3.2 异步与增量插入

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

## 四、组件生态

`nano-graphrag` 的可替换组件由 [nano_graphrag/base.py](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/base.py) 中的 `BaseKVStorage`、`BaseVectorStorage`、`BaseGraphStorage` 三大基类定义，结合 [readme.md](https://github.com/gusye1234/nano-graphrag/blob/main/readme.md) 中的组件表，可得下表：

| 组件类型 | 内置实现 | 扩展示例/文档 |
| :--- | :--- | :--- |
| LLM | OpenAI、Amazon Bedrock | DeepSeek、Ollama（[`examples/`](https://github.com/gusye1234/nano-graphrag/tree/main/examples)） |
| Embedding | OpenAI、Amazon Bedrock | sentence-transformers（本地推理） |
| 向量数据库 | `nano-vectordb`、hnswlib | milvus-lite、faiss |
| 图存储 | networkx | Neo4j（[`docs/use_neo4j_for_graphrag.md`](https://github.com/gusye1234/nano-graphrag/blob/main/docs/use_neo4j_for_graphrag.md)） |
| 可视化 | graphml 导出 | `examples/` 中提供脚本 |
| 文本分块 | 按 token 切分、按分隔符切分（[`chunking_by_seperators`](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/_op.py)） | 自定义 `chunk_func` |

社区 issue #2（"Add more Storages and LLMs?"）正在征集更多 MongoDB、Ollama 等接入方案，相关 PR 与示例收录在 [`examples/`](https://github.com/gusye1234/nano-graphrag/tree/main/examples) 目录。

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

下图概括了 `GraphRAG.insert` 与 `GraphRAG.query` 在一次生命周期内的主要阶段，步骤名称与 [readme.md](https://github.com/gusye1234/nano-graphrag/blob/main/readme.md) 的 `Quick Start` / `Naive RAG` 章节保持一致。

```mermaid
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](https://github.com/gusye1234/nano-graphrag/blob/main/readme.md) 的 `Issues` 章节：

1. **未实现 `covariates`**：协变量（与实体相关的时序/事件数据）特性在当前版本中缺失，参见 [docs/ROADMAP.md](https://github.com/gusye1234/nano-graphrag/blob/main/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](https://github.com/gusye1234/nano-graphrag/blob/main/docs/FAQ.md)）。

## 七、See Also

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

---

<a id='page-2'></a>

## 系统架构、核心模块与查询流程

### 相关页面

相关主题：[项目概览与快速入门](#page-1), [存储后端、可视化与数据流](#page-3), [LLM/嵌入扩展、提示词与故障排查](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [nano_graphrag/graphrag.py](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/graphrag.py)
- [nano_graphrag/base.py](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/base.py)
- [nano_graphrag/_op.py](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/_op.py)
- [nano_graphrag/_splitter.py](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/_splitter.py)
- [nano_graphrag/_utils.py](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/_utils.py)
- [nano_graphrag/prompt.py](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/prompt.py)
- [readme.md](https://github.com/gusye1234/nano-graphrag/blob/main/readme.md)
</details>

# 系统架构、核心模块与查询流程

## 一、定位与设计目标

`nano-graphrag` 是一个面向研究者和二次开发者的轻量级 GraphRAG 实现，主仓库宣称"在剔除 `tests` 与 `prompt` 后仅约 1100 行代码"（[readme.md](https://github.com/gusye1234/nano-graphrag/blob/main/readme.md)）。其官方定位是：相对于微软官方 [GraphRAG](https://arxiv.org/pdf/2404.16130) 仓库难以阅读与改动的痛点，提供一个**更小、更快、更整洁**，且保留核心能力（实体抽取、关系构建、社区摘要、local/global 检索）的替代实现。`GraphRAG` 主体以 `dataclass` 形式暴露在 [nano_graphrag/graphrag.py](https://github.com/gusye1234/nano-graphrag/blob/main/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/` 包内，模块职责如下表所示：

| 模块 | 主要职责 | 关键类 / 函数 |
| :--- | :--- | :--- |
| `graphrag.py` | 顶层入口，编排插入、查询、增量更新、社区检测等流程 | `GraphRAG`、`QueryParam` |
| `base.py` | 定义所有可替换组件的抽象基类 | `BaseKVStorage`、`BaseVectorStorage`、`BaseGraphStorage` |
| `_op.py` | 通用算子：分块、合并、排序等无状态操作 | `chunking_by_token_size`、`chunking_by_seperators` |
| `_splitter.py` | 文本分割算法的具体实现 | `SeparatorSplitter` |
| `_utils.py` | 工具与装饰器，例如 Embedding 函数包装、Hash 缓存 | `wrap_embedding_func_with_attrs` |
| `prompt.py` | 集中存放 LLM 提示词模板 | `PROMPTS` 字典（`entity_extraction`、`community_report`、`local_rag_response`、`global_reduce_rag_response`、`fail_response` 等） |

资料来源：[readme.md](https://github.com/gusye1234/nano-graphrag/blob/main/readme.md)、[nano_graphrag/base.py](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/base.py)。

### 2.1 三类存储抽象

`base.py` 明确把存储层分为三类，并允许通过构造参数替换：

- `BaseKVStorage`：以 md5-hash 为键的键值存储，默认落盘到 `working_dir`；用于缓存 chunk hash、LLM 调用结果、文本片段等。
- `BaseVectorStorage`：向量索引，默认使用 [`nano-vectordb`](https://github.com/gusye1234/nano-vectordb)，社区/Examples 中还演示了 `hnswlib` 与 `milvus-lite`。
- `BaseGraphStorage`：图存储，默认 `networkx`，内置了 `Neo4jStorage`（参见 [use_neo4j_for_graphrag.md](https://github.com/gusye1234/nano-graphrag/blob/main/docs/use_neo4j_for_graphrag.md)）。

这种分层让 `GraphRAG` 主体逻辑与持久化细节解耦。

### 2.2 双 LLM 角色

`readme.md` 指出系统区分"强模型"与"弱模型"两种 LLM 角色：前者（默认 `gpt-4o`）负责实体抽取、规划与回答；后者（默认 `gpt-4o-mini`）负责摘要与社区报告等"廉价"任务。用户可通过 `best_model_func` / `cheap_model_func` 替换为任意兼容 `_llm.gpt_4o_complete` 签名的 `async def`，示例包括 `deepseek`、`ollama` 等。

---

## 三、索引构建（Insert）流程

`GraphRAG.insert` 是异步编排的入口，内部串联了**分块 → 实体/关系抽取 → 图合并 → 社区检测 → 社区报告**五个阶段：

```mermaid
flowchart LR
    A[原始文本 / 文档列表] --> B[chunking_by_token_size / chunking_by_seperators]
    B --> C[基于 md5 的去重与缓存写入 KV]
    C --> D[PROMPTS entity_extraction 调用 best_model_func]
    D --> E[合并实体/关系到 BaseGraphStorage]
    E --> F[社区检测<br/>社区报告 PROMPTS community_report]
    F --> G[写入向量索引 BaseVectorStorage]
```

资料来源：[nano_graphrag/_op.py](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/_op.py)、[nano_graphrag/prompt.py](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/prompt.py)、[readme.md](https://github.com/gusye1234/nano-graphrag/blob/main/readme.md)。

关键点：

1. **分块可插拔**。`_op.py` 提供了基于 token 的 `chunking_by_token_size` 与基于分隔符的 `chunking_by_seperators` 两种内置实现，并允许通过 `GraphRAG(..., chunk_func=...)` 替换（[examples/using_custom_chunking_method.py](https://github.com/gusye1234/nano-graphrag/blob/main/examples/using_custom_chunking_method.py)）。
2. **增量插入无重复**。每个 chunk 用 md5 做去重键，但 `readme.md` 明确指出"每次 insert 都会重新计算社区并重生成报告"，这与官方 GraphRAG 的行为不同，使用时需要注意成本。
3. **Embedding 与 LLM 解耦**。`_utils.py` 中的 `wrap_embedding_func_with_attrs` 装饰器用于声明 `embedding_dim` 与 `max_token_size`，保证向量索引与下游相似度计算的兼容性。

---

## 四、查询流程

`GraphRAG.query` 与异步版本 `aquery` 通过 `QueryParam.mode` 决定走哪条检索路径，目前支持 `local`、`global`、`naive` 三种模式（`QueryParam` 的具体参数可通过 `help()` 查看）。`readme.md` 还提供了 `only_need_context=True` 的"仅取上下文"模式，便于将检索结果接入自定义 prompt。

### 4.1 Local 模式

从用户问题出发做向量检索，召回相关实体，再沿图扩散到一跳/两跳邻居，组装局部子图与文本片段，最终交由 `PROMPTS["local_rag_response"]` 模板生成回答。Issue #56 反馈该提示词中"Goal"与"Target response length and format"出现重复，这是 `prompt.py` 模板书写的实际状况——并非 bug，而是模板本身的设计选择，使用者可自由覆盖 `PROMPTS[...]` 来修复。

### 4.2 Global 模式

与官方 GraphRAG 的 map-reduce 思路不同，`nano-graphrag` 只挑选**最重要的 Top-K 社区**（由 `QueryParam.global_max_consider_community` 控制，默认 512 个），再让 `cheap_model_func` 基于社区报告生成答案，因此更节省 token。

### 4.3 Naive 模式

开启 `enable_naive_rag=True` 后可走朴素向量检索，不依赖图结构，适合做 baseline 对比。社区中 #99 提出的"DRIFT search"（微软在 local/global 之后新引入的检索范式）当前尚未在源码中体现，是 ROADMAP 上的潜在方向。

---

## 五、可替换组件与可观测性

`GraphRAG` 构造器暴露了 `key_string_value_json_storage_cls`、`vector_db_storage_cls`、`graph_storage_cls`、`best_model_func`、`cheap_model_func`、`embedding_func`、`convert_response_to_json_func` 等参数。当所有存储都改为非文件后端时，建议同时传入 `always_create_working_dir=False` 以跳过目录创建逻辑。`readme.md` 的"Components"小节给出了当前可用的实现矩阵，并明确欢迎社区贡献新存储或新 LLM——这也是 Issue #2 的核心诉求。

对于希望进一步观察内部行为的开发者，可以在 `query(..., only_need_context=True)` 下直接打印 local 模式返回的 `Reports` CSV 与 global 模式返回的 `Analyst` 报告，再按需拼装到自己的 prompt 中。

---

## See Also

- [Quick Start 与 Quick Start 代码示例](https://github.com/gusye1234/nano-graphrag/blob/main/readme.md)
- [Neo4j 后端使用指南](https://github.com/gusye1234/nano-graphrag/blob/main/docs/use_neo4j_for_graphrag.md)
- [项目 ROADMAP](https://github.com/gusye1234/nano-graphrag/blob/main/docs/ROADMAP.md)
- [FQA 常见问题](https://github.com/gusye1234/nano-graphrag/blob/main/docs/FAQ.md)
- [中文基准测试](https://github.com/gusye1234/nano-graphrag/blob/main/docs/benchmark-zh.md)

---

<a id='page-3'></a>

## 存储后端、可视化与数据流

### 相关页面

相关主题：[系统架构、核心模块与查询流程](#page-2), [LLM/嵌入扩展、提示词与故障排查](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [nano_graphrag/_storage/__init__.py](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/_storage/__init__.py)
- [nano_graphrag/_storage/kv_json.py](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/_storage/kv_json.py)
- [nano_graphrag/_storage/vdb_nanovectordb.py](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/_storage/vdb_nanovectordb.py)
- [nano_graphrag/_storage/vdb_hnswlib.py](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/_storage/vdb_hnswlib.py)
- [nano_graphrag/_storage/gdb_networkx.py](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/_storage/gdb_networkx.py)
- [nano_graphrag/_storage/gdb_neo4j.py](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/_storage/gdb_neo4j.py)
- [nano_graphrag/base.py](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/base.py)
- [readme.md](https://github.com/gusye1234/nano-graphrag/blob/main/readme.md)
- [docs/use_neo4j_for_graphrag.md](https://github.com/gusye1234/nano-graphrag/blob/main/docs/use_neo4j_for_graphrag.md)
</details>

# 存储后端、可视化与数据流

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

## 存储后端分类与默认实现

| 存储类型 | 抽象基类 | 默认实现 | 可选实现 | 注入参数 |
| :--- | :--- | :--- | :--- | :--- |
| 键值对 (KV) | `BaseKVStorage` | 磁盘 JSON 文件（`kv_json.py`） | 自定义类（参考社区对 MongoDB 的诉求） | `key_string_value_json_storage_cls` |
| 向量库 (Vector) | `BaseVectorStorage` | `nano-vectordb`（`vdb_nanovectordb.py`） | `hnswlib`、`milvus-lite`、`faiss` | `vector_db_storage_cls` |
| 图存储 (Graph) | `BaseGraphStorage` | `networkx`（`gdb_networkx.py`） | `Neo4j`（`gdb_neo4j.py`） | `graph_storage_cls` |

`GraphRAG` 在初始化时会根据传入的 `*_storage_cls` 决定使用哪一套实现，文件 [nano_graphrag/_storage/__init__.py](https://github.com/gusye1234/nano-graphrag/blob/main/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]()

```mermaid
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](https://github.com/gusye1234/nano-graphrag/pull/27) 中的同类修复）。对于 Neo4j 用户，官方文档 [docs/use_neo4j_for_graphrag.md](https://github.com/gusye1234/nano-graphrag/blob/main/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 定制](LLM_Embedding_Prompt.md)
- [Neo4j 集成指南](use_neo4j_for_graphrag.md)
- [异步与批量插入用法](Async_Insert.md)
- [返回纯检索上下文的查询模式](QueryParam.md)

---

<a id='page-4'></a>

## LLM/嵌入扩展、提示词与故障排查

### 相关页面

相关主题：[项目概览与快速入门](#page-1), [系统架构、核心模块与查询流程](#page-2), [存储后端、可视化与数据流](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [nano_graphrag/_llm.py](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/_llm.py)
- [nano_graphrag/prompt.py](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/prompt.py)
- [nano_graphrag/_op.py](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/_op.py)
- [nano_graphrag/_utils.py](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/_utils.py)
- [readme.md](https://github.com/gusye1234/nano-graphrag/blob/main/readme.md)
- [examples/using_ollama_as_llm.py](https://github.com/gusye1234/nano-graphrag/blob/main/examples/using_ollama_as_llm.py)
- [examples/using_ollama_as_llm_and_embedding.py](https://github.com/gusye1234/nano-graphrag/blob/main/examples/using_ollama_as_llm_and_embedding.py)
- [examples/using_deepseek_as_llm.py](https://github.com/gusye1234/nano-graphrag/blob/main/examples/using_deepseek_as_llm.py)
- [examples/using_local_embedding_model.py](https://github.com/gusye1234/nano-graphrag/blob/main/examples/using_local_embedding_model.py)
- [examples/using_custom_chunking_method.py](https://github.com/gusye1234/nano-graphrag/blob/main/examples/using_custom_chunking_method.py)
</details>

# LLM/嵌入扩展、提示词与故障排查

`nano-graphrag` 在保持核心代码仅约 1100 行的同时，提供了高度可插拔的 LLM、嵌入函数与提示词体系。资料来源：[readme.md:1-50]()。本页聚焦三件事：如何替换默认的 LLM 与嵌入实现、如何定制提示词、以及社区中常见的问题与排查思路。

## 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](https://github.com/gusye1234/nano-graphrag/blob/main/nano_graphrag/_llm.py) 中的 `gpt_4o_complete`，用户自定义的 LLM 函数应满足如下异步签名：

```python
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/](https://github.com/gusye1234/nano-graphrag/tree/main/examples) 目录中提供了多种后端的参考实现：

| 后端 | 入口示例 | 关键参数 |
| :--- | :--- | :--- |
| OpenAI | 内置 `_llm.py` | `OPENAI_API_KEY` |
| Azure OpenAI | 内置 `_llm.py` | `using_azure_openai=True`，参考 `.env.example.azure` |
| Amazon Bedrock | [using_amazon_bedrock.py](https://github.com/gusye1234/nano-graphrag/blob/main/examples/using_amazon_bedrock.py) | `using_amazon_bedrock=True`、`best_model_id`、`cheap_model_id` |
| DeepSeek | [using_deepseek_as_llm.py](https://github.com/gusye1234/nano-graphrag/blob/main/examples/using_deepseek_as_llm.py) | 自定义 `my_llm_complete` |
| Ollama | [using_ollama_as_llm.py](https://github.com/gusye1234/nano-graphrag/blob/main/examples/using_ollama_as_llm.py) | 自定义 `my_llm_complete` |

社区中长期存在「增加更多 LLM 与存储后端」的需求，issue #2 跟踪了 MongoDB、Ollama 等后端的支持进度。资料来源：[Issue #2](https://github.com/gusye1234/nano-graphrag/issues/2)。

## 嵌入函数扩展

默认嵌入函数使用 `text-embedding-3-small`，输出维度 1536，最大 token 数 8192。资料来源：[nano_graphrag/_utils.py](https://github.com/gusye1234/nano-graphrag/blob/main/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](https://github.com/gusye1234/nano-graphrag/blob/main/examples/using_ollama_as_llm_and_embedding.py)：在无 OpenAI Key 时同时替换 LLM 与嵌入。
- [using_local_embedding_model.py](https://github.com/gusye1234/nano-graphrag/blob/main/examples/using_local_embedding_model.py)：使用 `sentence-transformers` 在本地计算向量。

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

## 提示词体系

### 关键 Prompt

所有提示词集中在 `nano_graphrag.prompt.PROMPTS` 字典中，可在运行时直接覆写。资料来源：[nano_graphrag/prompt.py](https://github.com/gusye1234/nano-graphrag/blob/main/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](https://github.com/mangiucugna/json_repair) 等库做容错。

### 分块策略 Prompt 联动

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

## 常见故障与排查

### Windows 编码问题

Issue #125 报告在 Windows 平台 `pip install` 时触发 `cp1252` 解码错误。资料来源：[Issue #125](https://github.com/gusye1234/nano-graphrag/issues/125)。建议在执行前设置：

```shell
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](https://github.com/gusye1234/nano-graphrag/issues/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](https://github.com/gusye1234/nano-graphrag/issues/99)。目前可通过自定义 `aquery` 调用并复用 `nan

## See Also

- [架构总览](architecture.md)
- [存储后端扩展](storage-backends.md)
- [查询模式（local / global / naive）](query-modes.md)
- [Roadmap](https://github.com/gusye1234/nano-graphrag/blob/main/docs/ROADMAP.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: gusye1234/nano-graphrag; human_manual_source: deepwiki_human_wiki -->