# graph_rag

**Repository Path**: mood6666/graph_rag

## Basic Information

- **Project Name**: graph_rag
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-19
- **Last Updated**: 2026-05-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GraphRAG 上手教程

> 一份**从 0 到 1 讲清楚 GraphRAG**的中文教程，面向有 RAG 基础、想搞懂 GraphRAG 的开发者。
> 不堆术语、不抄论文，全部围绕"**为什么、是什么、怎么做、跑给你看**"。

---

## 教程定位

- **读者画像**：懂 chunk / embedding / 向量检索 / LLM prompt，没接触过 GraphRAG
- **学完能得到**：
  - 说得清 GraphRAG 和 RAG 的本质区别
  - 看得懂主流方案在干啥、怎么选
  - 自己手撸一个最小 GraphRAG，并用 LightRAG 跑通生产可用的版本
- **风格**：**极简**。每个 demo 用最短的语料、最少的代码、最直白的输出，把思路讲清楚就停。不堆功能、不秀技巧。

---

## 技术选型一览

| 维度 | 选型 | 理由 |
|---|---|---|
| Python | 3.10+ | 主流 GraphRAG 生态最低要求 |
| **包管理 / 虚拟环境** | **`uv`** | 比 pip 快 10~100 倍，自动管理虚拟环境，新项目首选 |
| LLM | **豆包 doubao-1.5-pro-32k** | 性价比高、OpenAI 兼容、国内访问稳定 |
| Embedding | **豆包 doubao-embedding-text** | 与 LLM 同平台，一份 Key 搞定 |
| 向量库 | `nano-vectordb` / `chromadb` | 本地、零运维 |
| 图库 | `networkx` + `python-igraph` | 内存图，无需外部服务 |
| 社区发现 | Leiden 算法 | 业界主流图聚类算法 |
| 可视化 | `pyvis` | 纯 Python，输出 HTML，零依赖 |
| 文档 | 纯原生 Markdown（含 ASCII 流程图） | 任何 markdown 渲染器都能看 |

> **全程零外部服务**：不装 Docker、不装 Neo4j、不装数据库。装好 `uv` + 一把豆包 API Key 就够。

---

## 目录结构

```
GraphRag/
├── README.md                       # 本文件（教程总览 + 大纲）
├── pyproject.toml                  # uv 项目定义 + 依赖列表
├── uv.lock                         # uv 自动生成的锁文件（保证可复现）
├── .python-version                 # uv 自动生成，指定 Python 版本
├── .env.example                    # 环境变量模板
│
├── docs/                           # 教程正文
│   ├── 01-why-graphrag.md          # 为什么需要 GraphRAG
│   ├── 02-setup.md                 # 环境与豆包配置
│   ├── 03-demo1-from-scratch.md    # 手撸最小 GraphRAG
│   ├── 04-lightrag.md              # LightRAG 实战
│   ├── 05-engineering.md           # 工程化与选型建议
│   └── assets/                     # 图片、可视化产物
│
└── demos/                          # 全部可运行代码
    ├── common/                     # 共用模块（LLM/Embedding 客户端）
    ├── corpus/                     # 测试语料：手写 300 字三国微型故事
    ├── demo1_scratch/              # 手撸版
    └── demo3_lightrag/             # LightRAG
```

> **关于语料**：所有 demo 共用同一份 ~300 字的微型三国故事，包含 10 个左右人物、清晰的几条关系线。
> 为什么这么短？因为**目标是讲清思路，不是测试规模**。短语料的好处：跑得快、token 便宜、图小到一眼能看懂、便于横向对比方案。

---

## 详细章节大纲

### 第 1 章 为什么需要 GraphRAG（理论篇）

> 不写代码，把"为什么 + 是什么 + 怎么选"讲清楚就停。

- **1.1 一个翻车案例**：传统 RAG 回答"刘关张是什么关系"为啥经常答不准
- **1.2 RAG 的核心缺陷**：chunk 切碎了关系、多跳问题答不上、全局问题没法答
- **1.3 GraphRAG 是什么**：索引时建图 + 查询时走图（一张对比图说清）
- **1.4 主流方案简介**：LightRAG 等轻量方案的定位与适用场景

---

### 第 2 章 环境与豆包配置（5 分钟搞定）

- **2.1 安装 uv**（一行命令、跨平台）

  ```bash
  # Windows (PowerShell)
  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

  # macOS / Linux
  curl -LsSf https://astral.sh/uv/install.sh | sh
  ```

- **2.2 申请豆包 API Key**（火山方舟控制台路径截图）
- **2.3 一键拉起项目**

  ```bash
  uv sync                  # 自动建虚拟环境 + 装全部依赖（读 pyproject.toml）
  cp .env.example .env     # 填入豆包 Key
  uv run python demos/common/test_connection.py   # 验证 LLM + Embedding 都通
  ```

- **2.4 uv 常用命令速查**
  - `uv add <pkg>` 加依赖
  - `uv run python xxx.py` 在虚拟环境里跑脚本（不用手动 activate）
  - `uv lock --upgrade` 升级所有依赖
- **2.5 通用客户端封装介绍**：`common/llm.py`、`common/embed.py`
- **2.6 模型切换说明**：如何把豆包换成 OpenAI / DeepSeek

---

### 第 3 章 Demo 1 —— 从零手撸最小 GraphRAG（核心章）

> **全教程灵魂**。不用任何 GraphRAG 框架，100% 自己写。每一步都看得见摸得着。

5 步流程，每步 1 个 py 文件、几十行代码：

1. **抽实体关系**：LLM 把文本变成 `(实体A, 关系, 实体B)` 三元组
2. **建图**：networkx 把三元组建成知识图
3. **社区发现**：igraph 跑 Leiden，把图分成几个"小团体"
4. **检索**：根据问题找相关实体 / 社区
5. **生成**：把检索结果 + 问题塞给 LLM 出答案

跑完输出：一个 HTML 图（pyvis）+ 3 个示例问题的答案 + 对比传统 RAG 的答案。

**Demo 文件清单**：

```
demos/demo1_scratch/
├── main.py              # 一键跑全流程，约 50 行
├── step1_extract.py     # 实体关系抽取
├── step2_graph.py       # 建图
├── step3_community.py   # 社区发现
├── step4_query.py       # 检索 + 生成
├── visualize.py         # pyvis 输出 HTML
└── output/              # 生成的图 + 答案
```

---

### 第 4 章 Demo 2 —— LightRAG 实战

- **4.1 最小代码跑通**：30 行搞定
- **4.2 4 种检索模式**：naive / local / global / hybrid 各跑一遍同一个问题
- **4.3 增量更新**：再加一段语料看图怎么长大
- **4.4 与手撸版横向 PK**：同语料、同问题，看索引时间 / token 消耗 / 答案质量

---

### 第 5 章 选型建议（收尾）

- **5.1 两方案成本对比表**
- **5.2 什么时候该上 GraphRAG、什么时候别上**
- **5.3 推荐继续学习的资源**

---

## 教程产出节奏（渐进式）

每章独立、按顺序推进，每完成一章你都可以单独 review：

- [x] **Step 0** 大纲（本文件）
- [x] **Step 1** 项目骨架（pyproject.toml + .env.example + common 模块 + 语料）
- [x] **Step 2** 文档 [01 为什么需要 GraphRAG](docs/01-why-graphrag.md)
- [x] **Step 3** 文档 [02 环境配置](docs/02-setup.md)
- [x] **Step 4** Demo 1 手撸版 + 文档 [03 手撸最小 GraphRAG](docs/03-demo1-from-scratch.md)
- [x] **Step 5** Demo 2 LightRAG + 文档 [04 LightRAG 实战](docs/04-lightrag.md)
- [x] **Step 6** 文档 [05 工程化与选型](docs/05-engineering.md)

---

## 学习路径建议

- **完全小白**：按顺序 1 → 5 通读
- **赶时间**：1 → 2 → 3（手撸版）→ 4（LightRAG）

---

## License

MIT