agentic_huge_data_base / wiki
页面 LightRAG · 3.6 基于文件的存储选项·DeepWiki 中文全文译文
DeepWiki 中文译文 / LightRAG / 3.6

3.6 · 基于文件的存储选项（File-Based Storage Options）

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

项目LightRAG 章节3.6 状态全文译文 模块存储与持久化、图谱与关系、检索、召回与索引、界面与交互
项目要点页2.5 参考项目 项目章节目录LightRAG DeepWiki 原始章节File-Based Storage Options 上一章3.5 下一章3.7
源码线索
  • lightrag/kg/json_doc_status_impl.py
  • lightrag/kg/json_kv_impl.py
  • lightrag/kg/mongo_impl.py
  • lightrag/kg/postgres_impl.py
  • lightrag/kg/redis_impl.py
模块标签
  • 存储与持久化
  • 图谱与关系
  • 检索、召回与索引
  • 界面与交互
  • 系统架构

章节正文

基于文件的存储选项

原始 DeepWiki 页面https://deepwiki.com/HKUDS/LightRAG/3.6-file-based-storage-options
此页面内容来自 DeepWiki 重组后的对应页面（来源：4-3.zh.md）

KV 与文档状态存储

相关源文件

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

  • lightrag/kg/factory.py
  • lightrag/kg/json_doc_status_impl.py
  • lightrag/kg/json_kv_impl.py
  • lightrag/kg/mongo_impl.py
  • lightrag/kg/neo4j_impl.py
  • lightrag/kg/postgres_impl.py
  • lightrag/kg/redis_impl.py
  • lightrag/llm_roles.py
  • lightrag/storage_migrations.py
  • tests/test_batch_graph_operations.py
  • tests/test_doc_status_chunk_preservation.py
  • tests/test_document_file_path_normalization.py
  • tests/test_json_doc_status_storage.py
  • tests/test_postgres_doc_status_lookup.py
  • tests/test_postgres_upsert.py

LightRAG 中的键值（KV）存储和文档状态存储系统为元数据、文本片段、大语言模型（LLM）响应缓存以及文档入库状态机提供了基础持久化层。这些系统采用可插拔架构设计，用户可以根据需要选择基于文件的 JSON 存储（适用于简单场景）或 PostgreSQL、MongoDB、Redis 等健壮的数据库（适用于生产环境扩展）。

可插拔存储架构

所有 KV 和文档状态存储实现均继承自 BaseKVStorage 或 DocStatusStorage lightrag/base.py:31-36。get_storage_class 工厂方法会根据配置在运行时解析具体的实现 lightrag/kg/factory.py:17-42。

核心存储接口
类职责关键方法
BaseKVStorage通用键值持久化，用于文本片段、元数据和缓存。get_by_id, get_by_ids, upsert, filter_keys
DocStatusStorage专用存储，用于跟踪文档生命周期和处理状态。get_status_counts, get_docs_by_statuses, index_done_callback

来源：lightrag/base.py:29-36, lightrag/kg/factory.py:1-43

基于文件的实现（默认）

默认实现使用 JsonKVStorage 和 JsonDocStatusStorage。这些类将数据以 JSON 文件形式存储在工作目录中 lightrag/kg/json_kv_impl.py:40-45。

共享内存与锁机制

为支持多进程并发，这些实现采用共享内存模式：

  1. 命名空间锁：每个命名空间（例如 text_chunks、llm_response_cache）都有一个专用的 NamespaceLock，用于防止写入时的竞态条件 lightrag/kg/json_kv_impl.py:47-49。
  2. 共享数据：数据被加载到由 get_namespace_data 管理的共享字典中 lightrag/kg/json_kv_impl.py:63-65。
  3. 持久化：内存中的变更不会立即写入磁盘。相反，index_done_callback 函数仅在 storage_updated 标志被设置时，才会将内存状态刷新到 .json 文件中 lightrag/kg/json_kv_impl.py:77-82。
扁平化键方案

LightRAG 已迁移到扁平化键方案以提升性能。旧的缓存结构会在 initialize 阶段通过 _migrate_legacy_cache_structure 自动迁移 lightrag/kg/json_kv_impl.py:65-68。

来源：lightrag/kg/json_kv_impl.py:28-105, lightrag/kg/json_doc_status_impl.py:31-73

数据库原生实现

PostgreSQL 存储

PGKVStorage 和 PGDocStatusStorage 利用 PostgreSQL 进行持久化存储。

  • 表结构：数据存储在 LIGHTRAG_KV_STORE 和 LIGHTRAG_DOC_STATUS 等表中 lightrag/kg/postgres_impl.py:2555-2560。
  • 批量优化：upsert 方法经过优化，使用 executemany 并设置默认批量大小为 200，以减少往返次数 lightrag/kg/postgres_impl.py:2618-2625。
  • 原生查找：与需要全表扫描的 JSON 存储不同，PostgreSQL 实现重写了 get_doc_by_file_basename 等方法，使用带索引的 SQL 查询 tests/test_postgres_doc_status_lookup.py:70-73。
MongoDB 存储

MongoKVStorage 使用 MongoDB 集合实现 KV 接口。

  • 数据隔离：使用由 {workspace}_{namespace} 构建的 final_namespace，确保同一数据库中不同 LightRAG 实例之间的数据隔离 lightrag/kg/mongo_impl.py:119-121。
  • 批量操作：在 bulk_write 中使用 UpdateOne 并设置 upsert=True，实现高性能数据入库 lightrag/kg/mongo_impl.py:192-205。
Redis 存储

RedisKVStorage 提供极快的内存 KV 存储，并支持可选的持久化。

  • 连接管理：使用 RedisConnectionManager 在不同存储实例之间共享单个连接池 lightrag/kg/redis_impl.py:58-63。
  • 序列化：值以 JSON 序列化后的字符串形式存储 lightrag/kg/redis_impl.py:215-220。

来源：lightrag/kg/postgres_impl.py:2550-2650, lightrag/kg/mongo_impl.py:85-210, lightrag/kg/redis_impl.py:127-180

文档状态机

DocStatusStorage 跟踪每个文档的生命周期。这对于恢复中断的入库操作和防止重复处理至关重要。

文档状态流转

DocStatus 枚举定义了以下状态 lightrag/base.py:34：

  • PENDING：文档已排队等待处理。
  • PROCESSING：文档正在被解析或分析。
  • PROCESSED：文档已成功集成到知识图谱中。
  • FAILED：处理因错误而停止。
数据流图：文档入库到存储
LightRAG · 数据流图：文档入库到存储 · 图 1
LightRAG · 数据流图：文档入库到存储 · 图 1

来源：lightrag/lightrag.py:530-550, lightrag/base.py:33-35, lightrag/kg/json_doc_status_impl.py:174-182

实现细节与持久化

通过 index_done_callback 实现持久化

LightRAG 存储的一个独特特性是 index_done_callback。在基于文件的存储中，upsert 仅更新共享内存字典。实际的磁盘写入发生在管线完成一批工作并调用此回调时 lightrag/kg/json_kv_impl.py:143-146。这最大限度地减少了大量入库期间的 I/O 开销。

命名空间锁逻辑

为防止多个进程损坏同一个 JSON 文件，系统使用 NamespaceLock lightrag/kg/json_kv_impl.py:47-49。

LightRAG · 命名空间锁逻辑 · 图 2
LightRAG · 命名空间锁逻辑 · 图 2

来源：lightrag/kg/json_kv_impl.py:45-104, lightrag/kg/shared_storage.py:13-26

关键类与函数
  • JsonKVStorage.upsert：更新共享字典并添加 create_time/update_time 时间戳 lightrag/kg/json_kv_impl.py:152-178。
  • DocStatusStorage.get_status_counts：返回入库管线的进度摘要 lightrag/kg/json_doc_status_impl.py:94-102。
  • try_initialize_namespace：确保只有第一个访问命名空间的进程执行初始的磁盘到内存加载 lightrag/kg/shared_storage.py:25。

来源：lightrag/kg/json_kv_impl.py:1-180, lightrag/kg/json_doc_status_impl.py:1-185