coco
22 KiB
22 KiB
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：
@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. 关键设计决策
- 异步优先: 所有 I/O 操作（LLM 调用、存储访问）均采用 async/await 模式
- 存储可插拔: 通过抽象基类实现不同存储后端的无缝切换
- 多查询模式: 针对不同场景提供 local/global/hybrid/mix 等多种检索策略
- 工作空间隔离: 支持多租户场景下的数据隔离
- LLM 缓存: 对 LLM 响应进行缓存以降低成本与延迟
- Token 预算管理: 查询阶段精确控制上下文 Token 使用量
- Ollama 兼容: 通过兼容接口降低接入成本
文档生成日期: 2026/04/28 基于 LightRAG 主分支代码分析