agentic_huge_data_base / wiki
页面 LightRAG · 2.5 并发与缓存系统·DeepWiki 中文全文译文
DeepWiki 中文译文 / LightRAG / 2.5

2.5 · 并发与缓存系统（Concurrency and Caching Systems）

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

项目LightRAG 章节2.5 状态全文译文 模块系统架构、接口与服务契约、模型调用与提供方适配、配置治理
项目要点页2.5 参考项目 项目章节目录LightRAG DeepWiki 原始章节Concurrency and Caching Systems 上一章2.4 下一章3
源码线索
  • docs/LightRAG_concurrent_explain.md
  • lightrag/base.py
  • lightrag/lightrag.py
  • lightrag/operate.py
  • lightrag/prompt.py
  • lightrag/utils.py
模块标签
  • 系统架构
  • 接口与服务契约
  • 模型调用与提供方适配
  • 配置治理
  • 图谱与关系

章节正文

并发、缓存与实用工具

原始 DeepWiki 页面https://deepwiki.com/HKUDS/LightRAG/2.5-concurrency-caching-and-utilities

并发、缓存与工具

相关源文件

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

  • docs/LightRAG-API-Server-zh.md
  • docs/LightRAG-API-Server.md
  • lightrag/api/gunicorn_config.py
  • lightrag/api/run_with_gunicorn.py
  • lightrag/base.py
  • lightrag/kg/shared_storage.py
  • lightrag/lightrag.py
  • lightrag/operate.py
  • lightrag/prompt.py
  • lightrag/tools/README_CLEAN_LLM_QUERY_CACHE.md
  • lightrag/tools/README_MIGRATE_LLM_CACHE.md
  • lightrag/tools/clean_llm_query_cache.py
  • lightrag/tools/migrate_llm_cache.py
  • lightrag/utils.py
  • tests/test_api_config_bedrock.py

本节详细介绍 LightRAG 用于管理异步执行、确保跨进程数据一致性、通过缓存优化大语言模型（LLM）交互以及提供健壮数据处理工具函数的内部机制。

异步执行与并发控制

LightRAG 高度依赖 Python 的 asyncio 来实现非阻塞 I/O。为了防止压垮外部大语言模型（LLM）提供商或本地资源，它采用了复杂的限流和同步原语。

优先级限制的异步调用

priority_limit_async_func_call 装饰器是控制管线中并发的主要机制 lightrag/utils.py:120-120。它包装异步函数，确保它们遵守由 DEFAULT_MAX_ASYNC 定义的全局并发限制 lightrag/lightrag.py:56-56。

无限制信号量

与标准的 asyncio.Semaphore 不同，UnlimitedSemaphore 类提供了一个信号量接口，可以切换为无上限模式 lightrag/utils.py:1002-1025。这在并发限制根据配置动态确定或禁用的场景中使用。

协作式让出

为了在长时间运行的 CPU 密集型任务（如解析大文本块）期间保持事件循环的响应性，LightRAG 使用了 _cooperative_yield lightrag/utils.py:1028-1035。该函数调用 asyncio.sleep(0) 以允许调度器切换任务 lightrag/operate.py:46-46。

多进程同步

当通过 Gunicorn 在生产环境中运行时 lightrag/api/run_with_gunicorn.py:143-155，LightRAG 利用共享存储架构来同步各工作进程之间的数据。

类用途来源
UnifiedLock一个包装器，为 asyncio.Lock 和 multiprocessing.Lock 提供一致的 async with 接口。lightrag/kg/shared_storage.py:137-154
KeyedUnifiedLock管理一个由字符串（如实体名称）标识的锁注册表，允许对特定数据实体进行细粒度锁定。lightrag/kg/shared_storage.py:348-360
NamespaceLock高级锁，用于在索引等操作期间保护整个存储命名空间。lightrag/kg/shared_storage.py:86-87

来源： lightrag/utils.py:120-120, lightrag/lightrag.py:56-56, lightrag/utils.py:1002-1035, lightrag/kg/shared_storage.py:137-360, lightrag/api/run_with_gunicorn.py:143-155

健康检查与工作进程恢复

LightRAG 实现了防御性编程模式，以处理外部服务（特别是在向量数据库（VDB）操作期间）的停滞问题。

卡住任务检测

safe_vdb_operation_with_exception 工具函数包装了向量数据库（VDB）调用，并带有强制超时和重试逻辑 lightrag/utils.py:136-166。它根据配置的嵌入向量超时时间计算防御性超时，通常应用 3 倍乘数并设置 120 秒的下限，以避免在慢速提供商上出现误报 lightrag/operate.py:95-109。

工作进程恢复（Gunicorn）

在多工作进程环境中，LightRAG 使用 Gunicorn 的 on_exit 和 on_starting 钩子来管理共享资源 lightrag/api/gunicorn_config.py:95-138。finalize_share_data 函数确保在主进程退出时清理共享锁和管理器代理 lightrag/kg/shared_storage.py:134-134。

来源： lightrag/utils.py:136-166, lightrag/operate.py:95-109, lightrag/api/gunicorn_config.py:95-138, lightrag/kg/shared_storage.py:134-134

大语言模型（LLM）响应缓存

为了降低延迟和成本，LightRAG 使用扁平化键方案在配置的键值（KV）存储中缓存大语言模型（LLM）响应。

扁平化键方案

缓存键通过对输入提示和模型配置进行哈希生成。这确保了更改模型或系统提示会正确地使缓存失效。

  • 身份提取： get_llm_cache_identity 创建一个唯一字符串，表示大语言模型（LLM）提供商、模型和参数 lightrag/utils.py:1255-1277。
  • 键组成： 最终键通常遵循 {命名空间}:{模式}:{哈希} 的模式 lightrag/operate.py:24-33。
缓存管理工具

LightRAG 提供了用于维护缓存的专门工具：

  • migrate_llm_cache.py：在不同的键值（KV）后端之间移动缓存数据（例如，从 Json 到 Redis），同时保持工作空间隔离 lightrag/tools/migrate_llm_cache.py:5-19。
  • clean_llm_query_cache.py：选择性地删除与查询相关的缓存条目（混合、混合、本地、全局），而不影响提取或摘要缓存 lightrag/tools/clean_llm_query_cache.py:5-19。
数据流：大语言模型（LLM）缓存交互

下图说明了 use_llm_func_with_cache 如何与键值（KV）存储交互。

LightRAG · 数据流：大语言模型（LLM）缓存交互 · 图 1
LightRAG · 数据流：大语言模型（LLM）缓存交互 · 图 1

来源： lightrag/utils.py:1255-1277, lightrag/operate.py:24-33, lightrag/tools/migrate_llm_cache.py:5-19, lightrag/tools/clean_llm_query_cache.py:5-19

工具与数据消毒

SanitizingJSONEncoder

为了处理复杂的 Python 对象并确保跨不同存储后端的 JSON 兼容性，LightRAG 使用了一个自定义编码器。

  • 代理项处理： 它会剥离无效的 Unicode 代理项和控制字符，这些字符经常导致 PostgreSQL 或 MongoDB 等数据库驱动程序失败 lightrag/utils.py:49-51。
  • 类型转换： 它会自动将 numpy 类型、set 对象和 datetime 对象转换为 JSON 可序列化格式 lightrag/utils.py:431-454。
文本规范化

在知识图谱（KG）构建期间，使用 sanitize_and_normalize_extracted_text 函数来清理大语言模型（LLM）输出，删除不需要的字符并规范化分隔符 lightrag/operate.py:21-21。

Token 化

LightRAG 使用一个集中的 Tokenizer 协议，通常通过 TiktokenTokenizer 实现 lightrag/utils.py:115-116。这确保了在片段切分、提取和查询上下文组装过程中 Token 计数的一致性。

自然语言到代码实体映射

此图将高级工具概念映射到代码库中的具体实现。

LightRAG · 自然语言到代码实体映射 · 图 2
LightRAG · 自然语言到代码实体映射 · 图 2

来源： lightrag/utils.py:49-51, lightrag/utils.py:431-454, lightrag/operate.py:21-21, lightrag/utils.py:115-116, lightrag/utils.py:120-120, lightrag/kg/shared_storage.py:348-360