agentic_huge_data_base / wiki
页面 LightRAG · 4 接口服务端·DeepWiki 中文全文译文
DeepWiki 中文译文 / LightRAG / 4

4 · 接口服务端（API Server）

轻量图谱增强检索 · 聚焦本章的模块关系、源码依据与实现要点。

项目LightRAG 章节4 状态全文译文 模块接口与服务契约、界面与交互、检索、召回与索引、系统架构
项目要点页2.5 参考项目 项目章节目录LightRAG DeepWiki 原始章节API Server 上一章3.9 下一章4.1
源码线索
  • env.example
  • lightrag/__init__.py
  • lightrag/api/__init__.py
  • lightrag/api/config.py
  • lightrag/api/lightrag_server.py
  • lightrag/api/routers/document_routes.py
  • lightrag/api/utils_api.py
  • lightrag/constants.py
  • lightrag/kg/shared_storage.py
模块标签
  • 接口与服务契约
  • 界面与交互
  • 检索、召回与索引
  • 系统架构
  • 测试、发布与运维

章节正文

存储后端

原始 DeepWiki 页面https://deepwiki.com/HKUDS/LightRAG/4-storage-backends

存储后端

相关源文件

以下文件为本维基页面的生成提供了上下文：

  • lightrag/base.py
  • lightrag/kg/__init__.py
  • lightrag/lightrag.py
  • lightrag/operate.py
  • lightrag/prompt.py
  • lightrag/utils.py

LightRAG 采用可插拔的存储架构，旨在满足双层知识图谱（KG）和向量检索增强生成（RAG）系统对多样化数据的需求。系统将数据持久化抽象为四大类别：键值（KV）存储、向量存储、图存储和文档状态存储。这种模块化设计使得 LightRAG 能够从基于本地文件的 JSON 存储（用于开发环境）扩展到分布式数据库（如 Neo4j、Milvus 和 PostgreSQL），以适应生产环境。

架构总览

存储层基于 StorageNameSpace 基类构建 lightrag/base.py:181-184，该基类提供了通用的生命周期方法，如 initialize、finalize 和 index_done_callback lightrag/base.py:186-198。LightRAG 类通过工厂模式编排这些后端 lightrag/lightrag.py:135，允许用户通过配置或环境变量指定偏好的实现。

存储抽象示意图

下图展示了 LightRAG 核心如何与抽象的存储接口交互，以执行 RAG 操作。

LightRAG · 存储抽象示意图 · 图 1
LightRAG · 存储抽象示意图 · 图 1

来源：lightrag/lightrag.py:171-182、lightrag/base.py:90-95、lightrag/operate.py:105-109

图存储后端

图存储负责持久化提取的实体及其关系。它支持复杂的遍历和子图检索，这对于"本地"和"全局"查询模式至关重要。

  • 默认实现：NetworkXStorage（内存存储，附带 GraphML 文件持久化）。
  • 生产环境后端：Neo4j（通过 Neo4JStorage）、带 Apache AGE 的 PostgreSQL、MongoDB 和 Memgraph。
  • 主要职责：管理节点（实体）和边（关系），处理工作空间隔离，并在适用时支持类似 Cypher 的查询。

详情请参见图存储后端。

来源：lightrag/kg/__init__.py:12-22、lightrag/lightrag.py:177-178

向量存储后端

向量存储处理文本片段、实体和关系的嵌入向量。它是"朴素"和"混合"查询模式下基于相似性检索的主要引擎。

  • 默认实现：NanoVectorDBStorage（基于文件的向量数据库）。
  • 生产环境后端：Milvus、Qdrant、FAISS、PostgreSQL（pgvector）和 MongoDB Atlas。
  • 主要职责：向量的 upsert（插入或更新）操作及元数据管理，以及使用余弦相似度阈值执行 query 操作 lightrag/base.py:34。

详情请参见向量存储后端。

来源：lightrag/kg/__init__.py:23-35、lightrag/lightrag.py:174-175

键值存储与文档状态存储

这些后端管理非结构化或半结构化数据，以及入库管线的内部状态。

  • 键值存储：存储大语言模型（LLM）响应缓存和映射数据。实现包括 JsonKVStorage、Redis 和 MongoDB。
  • 文档状态存储：跟踪文档的生命周期（例如 PENDING、PROCESSING、PROCESSED）。
  • 主要职责：提供高速的 get_by_id 和 upsert 操作 lightrag/kg/__init__.py:10。

详情请参见键值存储与文档状态存储。

来源：lightrag/kg/__init__.py:2-11、lightrag/kg/__init__.py:36-46

共享存储与并发

LightRAG 实现了一套复杂的锁定和同步机制，以确保多进程环境下的数据一致性，尤其是在使用基于文件的后端时。

  • 统一锁定：使用 KeyedUnifiedLock 和 NamespaceLock 防止并发文档入库期间的竞态条件 lightrag/kg/shared_storage.py。
  • 工作空间隔离：数据通过 workspace 标识符进行分区 lightrag/lightrag.py:186-187，允许多个逻辑 RAG 实例共享同一个物理存储后端。

详情请参见共享存储与多进程并发。

来源：lightrag/lightrag.py:82-87、lightrag/operate.py:75

实现映射

下表总结了存储工厂中定义的每种存储类型的可用实现 lightrag/kg/__init__.py:114-140。

存储类型实现必需方法
键值JsonKVStorage、RedisKVStorage、PGKVStorage、MongoKVStorage、OpenSearchKVStorageget_by_id、upsert
图NetworkXStorage、Neo4JStorage、PGGraphStorage、MongoGraphStorage、MemgraphStorageupsert_node、upsert_edge
向量NanoVectorDBStorage、MilvusVectorDBStorage、PGVectorStorage、FaissVectorDBStorage、QdrantVectorDBStoragequery、upsert
文档状态JsonDocStatusStorage、RedisDocStatusStorage、PGDocStatusStorage、MongoDocStatusStorageget_docs_by_status

来源：lightrag/kg/__init__.py:1-46