# LightRAG 技术架构文档

## 1. 项目概述

LightRAG 是一个基于图知识表示的检索增强生成（Retrieval-Augmented Generation, RAG）框架。它通过从文档中提取实体和关系构建知识图谱，结合多模态检索策略（本地、全局、混合、朴素、混合增强）来增强信息检索与问答能力。

- **项目地址**: https://github.com/HKUDS/LightRAG
- **Python 版本要求**: >= 3.10
- **许可证**: MIT

---

## 2. 整体架构

LightRAG 采用分层架构设计，主要由以下层次组成：

```
┌─────────────────────────────────────────────────────────────┐
│                    用户交互层 (Presentation)                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │  WebUI       │  │  REST API    │  │  Ollama API      │  │
│  │  (React 19)  │  │  (FastAPI)   │  │  (兼容接口)       │  │
│  └──────┬───────┘  └──────┬───────┘  └────────┬─────────┘  │
└─────────┼─────────────────┼───────────────────┼────────────┘
          │                 │                   │
┌─────────▼─────────────────▼───────────────────▼────────────┐
│                    API 服务层 (API Server)                   │
│         lightrag/api/lightrag_server.py                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │ 文档路由      │  │ 查询路由      │  │ 图谱路由          │  │
│  │ document_    │  │ query_routes │  │ graph_routes     │  │
│  │ routes       │  │              │  │                  │  │
│  └──────────────┘  └──────────────┘  └──────────────────┘  │
└────────────────────────────┬─────────────────────────────────┘
                             │
┌────────────────────────────▼─────────────────────────────────┐
│                  核心引擎层 (Core Engine)                     │
│                   lightrag/lightrag.py                        │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  LightRAG 主类 (协调器)                                  │ │
│  │  - 文档插入 (ainsert)                                    │ │
│  │  - 查询处理 (aquery)                                     │ │
│  │  - 存储管理 (initialize_storages / finalize_storages)    │ │
│  └────────────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────────────┐ │
│  │  核心操作逻辑 (operate.py)                                │ │
│  │  - 实体/关系提取 (extract_entities)                      │ │
│  │  - 文本分块 (chunking_by_token_size)                     │ │
│  │  - 知识图谱查询 (kg_query)                               │ │
│  │  - 朴素查询 (naive_query)                                │ │
│  │  - 节点边合并 (merge_nodes_and_edges)                    │ │
│  └────────────────────────────────────────────────────────┘ │
└────────────────────────────┬─────────────────────────────────┘
                             │
┌────────────────────────────▼─────────────────────────────────┐
│                   存储抽象层 (Storage Abstraction)            │
│                     lightrag/base.py                          │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────┐ ┌─────────┐ │
│  │ BaseKVStorage│ │BaseVectorStorage│ │BaseGraph│ │BaseDoc  │ │
│  │              │ │              │ │Storage  │ │Status   │ │
│  └──────┬───────┘ └──────┬───────┘ └────┬─────┘ └────┬────┘ │
└─────────┼────────────────┼──────────────┼────────────┼──────┘
          │                │              │            │
┌─────────▼────────────────▼──────────────▼────────────▼──────┐
│                  存储实现层 (Storage Implementations)         │
│                        lightrag/kg/                           │
│  ┌─────────────┐ ┌─────────────┐ ┌────────────────────────┐ │
│  │ KV 存储      │ │ 向量存储     │ │ 图存储                  │ │
│  │ JsonKVStorage│ │NanoVectorDB │ │NetworkXStorage         │ │
│  │ RedisKVStorage│ │MilvusVector │ │Neo4JStorage            │ │
│  │ PGKVStorage  │ │PGVector     │ │PGGraphStorage          │ │
│  │ MongoKVStorage│ │FaissVector  │ │MongoGraphStorage       │ │
│  │ OpenSearchKV │ │QdrantVector │ │MemgraphStorage         │ │
│  │              │ │OpenSearchVec│ │OpenSearchGraph         │ │
│  └─────────────┘ └─────────────┘ └────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────┐
│                 LLM 提供商层 (LLM Providers)                 │
│                       lightrag/llm/                           │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────────────┐ │
│  │ OpenAI   │ │ Ollama   │ │ Azure    │ │ Anthropic       │ │
│  │ Gemini   │ │ Bedrock  │ │ Zhipu    │ │ HuggingFace     │ │
│  │ Jina     │ │ vLLM     │ │ LMDeploy │ │ LlamaIndex      │ │
│  └──────────┘ └──────────┘ └──────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```

---

## 3. 核心模块详解

### 3.1 主协调器 (lightrag.py)

`LightRAG` 类是整个框架的核心入口，主要职责包括：

- **生命周期管理**: 实例化后必须调用 `await rag.initialize_storages()` 初始化存储后端
- **文档插入**: `ainsert()` 支持单文档、批量文档、自定义 ID、文件路径引用
- **查询处理**: `aquery()` 支持多种查询模式与参数配置
- **存储清理**: `finalize_storages()` 用于优雅关闭与资源释放

关键配置参数：
- `working_dir`: 工作目录
- `workspace`: 工作空间隔离
- `max_parallel_insert`: 最大并行插入数（默认 2，建议最大 10）
- `kv_storage` / `vector_storage` / `graph_storage` / `doc_status_storage`: 存储后端选择

### 3.2 核心操作逻辑 (operate.py)

包含所有索引与查询的核心算法：

| 函数 | 职责 |
|------|------|
| `chunking_by_token_size` | 基于 Token 大小的文本分块 |
| `extract_entities` | 使用 LLM 从文本中提取实体和关系 |
| `kg_query` | 基于知识图谱的查询（local/global/hybrid） |
| `naive_query` | 纯向量检索查询（不依赖知识图谱） |
| `merge_nodes_and_edges` | 合并节点与边，处理冲突与重复 |
| `rebuild_knowledge_from_chunks` | 从文本块重建知识 |

### 3.3 提示词模板 (prompt.py)

集中管理所有 LLM 提示词：
- `entity_extraction_system_prompt`: 实体与关系提取的系统提示
- `entity_extraction_user_prompt`: 用户提示模板
- 支持多语言输出与自定义分隔符

### 3.4 类型定义 (types.py)

Pydantic 模型定义：
- `KnowledgeGraph`: 知识图谱结构（节点 + 边）
- `KnowledgeGraphNode` / `KnowledgeGraphEdge`: 节点与边模型
- `GPTKeywordExtractionFormat`: 关键词提取格式

---

## 4. 存储层架构

LightRAG 使用 **4 种存储类型**，每种都有多种可插拔实现：

### 4.1 存储类型说明

| 存储类型 | 用途 | 抽象基类 |
|---------|------|---------|
| **KV_STORAGE** | LLM 响应缓存、文本块、文档信息 | `BaseKVStorage` |
| **VECTOR_STORAGE** | 实体/关系/文本块的嵌入向量 | `BaseVectorStorage` |
| **GRAPH_STORAGE** | 实体-关系图结构 | `BaseGraphStorage` |
| **DOC_STATUS_STORAGE** | 文档处理状态跟踪 | `DocStatusStorage` |

### 4.2 存储实现矩阵

| 后端 | KV | Vector | Graph | DocStatus | 环境变量要求 |
|------|----|--------|-------|-----------|-------------|
| **JSON (文件)** | ✅ | - | - | ✅ | 无 |
| **NanoVectorDB** | - | ✅ | - | - | 无 |
| **NetworkX** | - | - | ✅ | - | 无 |
| **PostgreSQL + pgvector** | ✅ | ✅ | ✅ | ✅ | POSTGRES_* |
| **Neo4j** | - | - | ✅ | - | NEO4J_* |
| **MongoDB** | ✅ | ✅ | ✅ | ✅ | MONGO_* |
| **Redis** | ✅ | - | - | ✅ | REDIS_URI |
| **Milvus** | - | ✅ | - | - | MILVUS_* |
| **Qdrant** | - | ✅ | - | - | QDRANT_URL |
| **Faiss** | - | ✅ | - | - | 无 |
| **Memgraph** | - | - | ✅ | - | MEMGRAPH_URI |
| **OpenSearch** | ✅ | ✅ | ✅ | ✅ | OPENSEARCH_HOSTS |

### 4.3 工作空间隔离

不同存储类型实现工作空间隔离的方式：
- **文件型存储**: 子目录隔离
- **集合型存储**: 集合名前缀
- **关系型数据库**: workspace 字段过滤
- **Qdrant**: payload 分区

---

## 5. 查询模式

LightRAG 支持 6 种查询模式：

| 模式 | 说明 | 适用场景 |
|------|------|---------|
| **local** | 基于特定实体的上下文相关检索 | 精准事实查询 |
| **global** | 基于社区摘要的广度知识检索 | 概述性、总结性问题 |
| **hybrid** | 结合 local 与 global | 平衡精度与广度 |
| **naive** | 纯向量搜索，不依赖知识图谱 | 快速简单查询 |
| **mix** | 整合知识图谱与向量检索（默认） | 推荐配合 Reranker 使用 |
| **bypass** | 直接透传，不走 RAG | 特殊调试场景 |

查询参数 `QueryParam` 关键字段：
- `top_k`: 检索的实体/关系数量
- `chunk_top_k`: 文本块检索数量
- `max_entity_tokens` / `max_relation_tokens` / `max_total_tokens`: Token 预算控制
- `enable_rerank`: 启用重排序
- `stream`: 流式输出

---

## 6. API 服务架构

### 6.1 FastAPI 服务 (lightrag/api/)

```
lightrag/api/
├── lightrag_server.py      # FastAPI 应用主入口
├── run_with_gunicorn.py    # Gunicorn 多进程启动
├── auth.py                 # JWT/OAuth2 认证
├── passwords.py            # 密码哈希
├── config.py               # 全局配置与参数解析
├── utils_api.py            # API 工具函数
├── runtime_validation.py   # 运行时校验
├── gunicorn_config.py      # Gunicorn 配置
└── routers/
    ├── document_routes.py  # 文档上传、管理、删除
    ├── query_routes.py     # 查询接口
    ├── graph_routes.py     # 图谱操作
    └── ollama_api.py       # Ollama 兼容 API
```

### 6.2 认证机制

- **JWT Token**: 基于 PyJWT / python-jose
- **OAuth2 Password Flow**: 用户名密码登录
- **API Key**: `LIGHTRAG_API_KEY` 头部验证
- **多账户支持**: `AUTH_ACCOUNTS` 环境变量配置

### 6.3 Ollama 兼容 API

模拟 Ollama 聊天模型接口，使 AI 聊天机器人（如 Open WebUI）可以直接调用 LightRAG。

---

## 7. WebUI 前端架构

### 7.1 技术栈

- **框架**: React 19 + TypeScript
- **构建工具**: Vite 7
- **包管理器**: Bun
- **样式**: Tailwind CSS 4
- **路由**: React Router DOM 7
- **状态管理**: Zustand 5
- **国际化**: i18next + react-i18next（支持 11 种语言）
- **图可视化**: Sigma.js + Graphology + @react-sigma
- **UI 组件**: Radix UI + shadcn/ui 风格
- **Markdown 渲染**: react-markdown + KaTeX

### 7.2 目录结构

```
lightrag_webui/src/
├── App.tsx                 # 根组件
├── AppRouter.tsx           # 路由配置
├── main.tsx                # 入口
├── index.css               # 全局样式
├── api/
│   └── lightrag.ts         # API 客户端
├── components/             # 通用组件
│   ├── AppSettings.tsx
│   ├── ThemeProvider.tsx
│   └── LanguageToggle.tsx
├── contexts/               # React Context
├── features/               # 页面级功能模块
│   ├── LoginPage.tsx
│   ├── DocumentManager.tsx
│   ├── GraphViewer.tsx
│   ├── RetrievalTesting.tsx
│   └── ApiSite.tsx
├── hooks/                  # 自定义 Hooks
│   ├── useLightragGraph.tsx
│   └── useRandomGraph.tsx
├── locales/                # 翻译文件 (en, zh, ja, de, fr, ...)
├── stores/                 # Zustand 状态存储
│   ├── graph.ts
│   ├── settings.ts
│   └── state.ts
└── utils/                  # 工具函数
```

### 7.3 功能模块

- **文档管理**: 上传、查看状态、删除文档
- **图谱可视化**: 交互式知识图谱浏览与搜索
- **检索测试**: 查询调试与结果查看
- **API 文档**: 内置 Swagger UI
- **设置面板**: 主题切换、语言切换、系统配置

---

## 8. LLM 提供商集成

### 8.1 支持的提供商

| 提供商 | 模块文件 | 说明 |
|--------|---------|------|
| OpenAI | `llm/openai.py` | GPT-4, GPT-4o, Embedding |
| Azure OpenAI | `llm/azure_openai.py` | 企业版 OpenAI |
| Anthropic | `llm/anthropic.py` | Claude 系列 |
| Google Gemini | `llm/gemini.py` | Gemini Pro |
| Ollama | `llm/ollama.py` | 本地开源模型 |
| AWS Bedrock | `llm/bedrock.py` | 亚马逊云模型 |
| Zhipu AI | `llm/zhipu.py` | 智谱 AI |
| HuggingFace | `llm/hf.py` | 开源模型 |
| Jina AI | `llm/jina.py` | Embedding/Rerank |
| NVIDIA | `llm/nvidia_openai.py` | NVIDIA API |
| vLLM | `llm/vllm.py` | 高性能推理 |
| LMDeploy | `llm/lmdeploy.py` | 模型部署 |

### 8.2 嵌入函数规范

使用 `@wrap_embedding_func_with_attrs` 装饰器声明维度与最大 Token：

```python
@wrap_embedding_func_with_attrs(embedding_dim=1536, max_token_size=8192)
async def custom_embed(texts: list[str]) -> np.ndarray:
    return await openai_embed.func(texts, model="text-embedding-3-large")
```

### 8.3 重排序 (Reranker)

- 显著改善检索质量
- 推荐模型: `BAAI/bge-reranker-v2-m3`, Jina Rerankers
- 在 `mix` 模式下效果最佳

---

## 9. 数据流

### 9.1 索引流程 (Document Insertion)

```
原始文档
    │
    ▼
┌─────────────┐
│ 文本分块    │  chunking_by_token_size
│ (Token 级)  │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ 实体提取    │  extract_entities (LLM)
│ 关系提取    │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ 知识合并    │  merge_nodes_and_edges
│ 去重消歧    │
└──────┬──────┘
       │
       ▼
┌─────────────────────────────────┐
│ 存储写入                        │
│ • KV: 文本块、LLM 缓存          │
│ • Vector: 实体/关系/块 Embedding│
│ • Graph: 节点与边               │
│ • DocStatus: 处理状态           │
└─────────────────────────────────┘
```

### 9.2 查询流程 (Query)

```
用户查询
    │
    ▼
┌─────────────┐     ┌─────────────┐
│ 关键词提取  │────▶│ 查询模式选择 │
│ (LLM/规则)  │     │ local/global│
└─────────────┘     │ /hybrid/mix │
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
        ┌─────────┐  ┌─────────┐  ┌─────────┐
        │ KG 检索 │  │ Vector  │  │ Rerank  │
        │ 子图    │  │ 相似度  │  │ 重排序  │
        └────┬────┘  └────┬────┘  └────┬────┘
             │            │            │
             └────────────┼────────────┘
                          ▼
                   ┌─────────────┐
                   │ 上下文组装  │
                   │ (Token 预算)│
                   └──────┬──────┘
                          ▼
                   ┌─────────────┐
                   │ LLM 生成    │
                   │ 最终回答    │
                   └─────────────┘
```

---

## 10. 部署架构

### 10.1 部署方式

| 方式 | 文件/命令 | 适用场景 |
|------|----------|---------|
| **Python 包** | `uv tool install "lightrag-hku[api]"` | 快速试用 |
| **源码运行** | `uv sync --extra api && lightrag-server` | 开发调试 |
| **Docker** | `docker build -t lightrag .` | 容器化部署 |
| **Docker Compose** | `docker-compose up` | 完整服务栈 |
| **Kubernetes** | `k8s-deploy/` | 生产级集群 |
| **Gunicorn** | `lightrag-gunicorn` | 多工作进程生产 |

### 10.2 Docker Compose 完整栈

包含服务：
- LightRAG Server
- PostgreSQL (可选存储)
- Neo4j (可选图数据库)
- Redis (可选缓存)
- Qdrant / Milvus (可选向量数据库)

### 10.3 环境配置

主配置文件 `.env` 关键段：
- 服务器设置 (HOST, PORT, CORS)
- 存储后端连接串
- LLM 与 Embedding 配置
- Reranker 配置
- 认证配置 (AUTH_ACCOUNTS, LIGHTRAG_API_KEY)

---

## 11. 测试体系

### 11.1 测试结构

```
tests/
├── conftest.py                    # 共享 Fixture
├── test_auth.py                   # 认证测试
├── test_chunking.py               # 分块测试
├── test_batch_embeddings.py       # Embedding 批处理
├── test_dimension_mismatch.py     # 维度兼容性
└── ...
```

### 11.2 测试标记

| 标记 | 说明 | 运行方式 |
|------|------|---------|
| `offline` | 离线单元测试（默认） | `pytest tests` |
| `integration` | 集成测试（需外部服务） | `pytest tests --run-integration` |
| `requires_db` | 需要数据库 | - |
| `requires_api` | 需要 API 密钥 | - |

---

## 12. 技术栈总结

### 后端

| 类别 | 技术 |
|------|------|
| 语言 | Python 3.10+ |
| Web 框架 | FastAPI |
| 异步 | asyncio |
| 数据验证 | Pydantic |
| 图计算 | NetworkX |
| 向量检索 | NanoVectorDB / FAISS / Milvus / Qdrant / pgvector |
| 数据库 | PostgreSQL / MongoDB / Redis / Neo4j |
| 认证 | JWT + OAuth2 + bcrypt |
| 日志 | 内置 logging |
| 包管理 | uv (推荐) / pip |

### 前端

| 类别 | 技术 |
|------|------|
| 框架 | React 19 |
| 语言 | TypeScript 5.9 |
| 构建 | Vite 7 |
| 样式 | Tailwind CSS 4 |
| 路由 | React Router DOM 7 |
| 状态 | Zustand 5 |
| 图可视化 | Sigma.js 3 + Graphology |
| 组件库 | Radix UI |
| 国际化 | i18next |
| 测试 | Bun Test |

---

## 13. 关键设计决策

1. **异步优先**: 所有 I/O 操作（LLM 调用、存储访问）均采用 async/await 模式
2. **存储可插拔**: 通过抽象基类实现不同存储后端的无缝切换
3. **多查询模式**: 针对不同场景提供 local/global/hybrid/mix 等多种检索策略
4. **工作空间隔离**: 支持多租户场景下的数据隔离
5. **LLM 缓存**: 对 LLM 响应进行缓存以降低成本与延迟
6. **Token 预算管理**: 查询阶段精确控制上下文 Token 使用量
7. **Ollama 兼容**: 通过兼容接口降低接入成本

---

*文档生成日期: 2026/04/28*
*基于 LightRAG 主分支代码分析*