时地方

This commit is contained in:
coco
2026-07-21 14:53:24 +08:00
parent 8b94d76799
commit 1b8027e61c
308 changed files with 61360 additions and 10 deletions
+502
View File
@@ -0,0 +1,502 @@
# 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 主分支代码分析*