coco
503 lines
22 KiB
Markdown
503 lines
22 KiB
Markdown
# 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 主分支代码分析*
|