agentic_huge_data_base / wiki
页面 LightRAG · 2.1 LightRAG 引擎核心·DeepWiki 中文全文译文
DeepWiki 中文译文 / LightRAG / 2.1

2.1 · LightRAG 引擎核心（LightRAG Engine Core）

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

项目LightRAG 章节2.1 状态全文译文 模块检索、召回与索引、模型调用与提供方适配、配置治理、文档对象与元数据
项目要点页2.5 参考项目 项目章节目录LightRAG DeepWiki 原始章节LightRAG Engine Core 上一章2 下一章2.2
源码线索
  • lightrag/__init__.py
  • lightrag/api/__init__.py
  • lightrag/base.py
  • lightrag/lightrag.py
  • lightrag/namespace.py
  • lightrag/operate.py
  • lightrag/prompt.py
  • lightrag/types.py
  • lightrag/utils.py
模块标签
  • 检索、召回与索引
  • 模型调用与提供方适配
  • 配置治理
  • 文档对象与元数据
  • 工作流与编排

章节正文

LightRAG 类与管线 Orchestration

原始 DeepWiki 页面https://deepwiki.com/HKUDS/LightRAG/2.1-lightrag-class-and-pipeline-orchestration

LightRAG 类与管线编排

相关源文件

本章引用的主要源码文件：

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

LightRAG 类作为整个框架的中央入口点和编排器。它管理存储后端的生命周期，提供用于文档入库和检索的高级 API，并协调将原始文本转换为与向量搜索集成的结构化知识图谱的多阶段管线。

LightRAG 类生命周期

LightRAG 类被定义为一个最终的 dataclass，它继承自多个混入类以提供专门功能：_RoleLLMMixin 用于大语言模型（LLM）配置，_StorageMigrationMixin 用于模式更新，以及 _PipelineMixin 用于文档处理 lightrag/lightrag.py:157-160。

初始化与存储设置

在实例化时，LightRAG 会配置其工作环境并初始化其存储组件。存储架构是可插拔的，允许用户为键值（KV）、向量和图数据指定不同的后端 lightrag/lightrag.py:171-181。

  1. initialize_storages：此内部方法根据提供的配置字符串（例如 JsonKVStorage、NetworkXStorage）实例化存储类。它使用工厂模式解析存储类，并调用它们各自的 initialize() 方法 lightrag/lightrag.py:440-496。
  2. finalize_storages：此方法确保所有待处理操作都已提交，并释放资源。它会遍历所有已初始化的存储命名空间，并调用它们的 finalize() 和 index_done_callback() 方法 lightrag/lightrag.py:516-525。
工作空间隔离

workspace 属性支持在同一存储后端内实现数据隔离。如果设置了该属性，它会使用工作空间名称作为前缀或命名空间标识符来对数据进行分区 lightrag/lightrag.py:186-188。

主要接口

该类暴露了三个主要的异步方法，用于与检索增强生成（RAG）系统进行交互：

方法用途关键参数
ainsert将原始文本入库到知识图谱和向量数据库中content（字符串或列表）
aquery使用支持的查询模式之一执行检索增强生成（RAG）查询query（字符串），param（QueryParam）
aquery_data检索原始上下文数据，而不生成大语言模型（LLM）响应query（字符串），param（QueryParam）

来源：lightrag/lightrag.py:560，lightrag/lightrag.py:657，lightrag/lightrag.py:688

知识图谱构建管线

由 ainsert 触发的入库过程遵循一个结构化的管线，该管线在 lightrag/operate.py 中管理。此管线弥合了非结构化自然语言与正式图结构之间的差距。

管线流程：从文本到图谱
  1. 片段切分：使用 chunking_by_token_size 将输入文本分割成更小的片段，以确保它们适合大语言模型（LLM）的上下文窗口 lightrag/lightrag.py:588。
  2. 提取：对每个片段调用 extract_entities。它使用大语言模型（LLM）根据 entity_extraction_system_prompt 识别实体和关系 lightrag/operate.py:106，lightrag/prompt.py:34。
  3. 合并与摘要：将提取的实体和关系合并到现有图谱中。如果同一实体存在多个描述，_handle_entity_relation_summary 会执行 map-reduce 摘要以创建统一的描述 lightrag/operate.py:198-213。
  4. 索引：最终的实体、关系和片段被嵌入并存储在向量数据库（entities_vdb、relationships_vdb、chunks_vdb）中 lightrag/lightrag.py:465-475。
自然语言到代码实体的映射

下图说明了在构建过程中，自然语言概念如何映射到特定的代码实体和存储命名空间。

图：入库编排映射

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

来源：lightrag/lightrag.py:588-610，lightrag/operate.py:106-213，lightrag/base.py:180-200

_PipelineMixin 与异步编排

_PipelineMixin 提供了异步处理长时间运行文档任务的基础设施。它管理任务队列，并确保系统在大量入库期间保持响应 lightrag/lightrag.py:159。

关键管线机制
  • 并发控制：使用 priority_limit_async_func_call 和信号量来限制并行大语言模型（LLM）调用和存储操作的数量，防止速率限制问题 lightrag/lightrag.py:120，lightrag/lightrag.py:255。
  • 协作让步：operate.py 中的长时间运行循环会调用 _cooperative_yield（通过 asyncio.sleep(0)），以允许事件循环处理其他任务，例如心跳检查或状态查询 lightrag/operate.py:46。
  • 状态跟踪：使用 doc_status_storage 监控文档在 PENDING、PARSING、PROCESSING 和 COMPLETED 等状态之间的进度 lightrag/lightrag.py:180-181。
检索编排

当调用 aquery 时，编排会转向 kg_query。此函数协调关键词提取、子图检索和上下文组装。

图：检索数据流

LightRAG · 检索编排 · 图 2
LightRAG · 检索编排 · 图 2

来源：lightrag/lightrag.py:657-686，lightrag/operate.py:107-108

关键函数摘要
  • lightrag/lightrag.py：
  • LightRAG.ainsert：添加数据的入口点 lightrag/lightrag.py:560。
  • LightRAG.aquery：查询的入口点 lightrag/lightrag.py:657。
  • lightrag/operate.py：
  • extract_entities：基于大语言模型（LLM）的知识图谱提取逻辑 lightrag/operate.py:106。
  • kg_query：多模式知识图谱检索逻辑 lightrag/operate.py:107。
  • _handle_entity_relation_summary：用于合并图谱节点的 map-reduce 逻辑 lightrag/operate.py:198。

来源：lightrag/lightrag.py，lightrag/operate.py，lightrag/base.py，lightrag/prompt.py