agentic_huge_data_base / wiki
页面 LightRAG · 5 Web 用户接口·DeepWiki 中文全文译文
DeepWiki 中文译文 / LightRAG / 5

5 · Web 用户接口（Web User Interface）

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

项目LightRAG 章节5 状态全文译文 模块界面与交互、图谱与关系、测试、发布与运维、系统架构
项目要点页2.5 参考项目 项目章节目录LightRAG DeepWiki 原始章节Web User Interface 上一章4.6 下一章5.1
源码线索
  • docs/FrontendBuildGuide.md
  • lightrag_webui/README.md
  • lightrag_webui/bun.lock
  • lightrag_webui/eslint.config.js
  • lightrag_webui/package.json
  • lightrag_webui/src/components/retrieval/ChatMessage.tsx
  • lightrag_webui/src/components/ui/Table.tsx
  • lightrag_webui/vite.config.ts
模块标签
  • 界面与交互
  • 图谱与关系
  • 测试、发布与运维
  • 系统架构
  • 检索、召回与索引

章节正文

文档入库管线

原始 DeepWiki 页面https://deepwiki.com/HKUDS/LightRAG/5-document-ingestion-pipeline

文档入库管线

相关源文件

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

  • lightrag/api/routers/document_routes.py
  • lightrag/parser_routing.py
  • lightrag/pipeline.py
  • lightrag/utils_pipeline.py
  • tests/test_document_routes_docx_archive.py
  • tests/test_pipeline_release_closure.py

文档入库管线是一个多阶段、异步的系统，旨在将原始文件转换为结构化的知识图谱（KG）实体和向量索引。它负责处理文件解析、多模态分析（图像/表格）、文本片段切分以及大语言模型（LLM）驱动的实体-关系提取。

管线总览

该管线采用级联工作队列模型。文档通过由 _PipelineMixin 管理、并由 DocStatusStorage 状态机协调的不同状态进行流转。

高层流程
  1. 入库 API：文档通过 upload、scan 或 insert_text 端点进入系统。
  2. 入队：文档被分配一个 track_id，并标记为 PENDING 或 PARSING 状态。
  3. 解析：使用原生或外部引擎（MinerU、Docling）将文件转换为标准的中间表示（IR）。
  4. 分析：多模态元素（图像/表格）由视觉语言模型（VLM）处理。
  5. 提取：文本片段由大语言模型（LLM）处理，以提取知识图谱的节点和边。
  6. 集成：提取的数据被合并到图谱和向量存储中。
代码实体映射：入库生命周期

下图将概念性的管线阶段映射到负责执行的具体类和方法。

标题：文档入库逻辑流程

LightRAG · 代码实体映射：入库生命周期 · 图 1
LightRAG · 代码实体映射：入库生命周期 · 图 1

来源：lightrag/api/routers/document_routes.py:32-36, lightrag/pipeline.py:208-215, lightrag/pipeline.py:172-191, lightrag/operate.py:44-45

5.1 文档路由与管线编排

document_routes.py 中的 API 层管理所有文档操作的入口点。它使用复杂的锁定策略来确保并发操作期间的数据一致性，使用了诸如 busy、scanning_exclusive 和 destructive_busy 等标志。

核心编排逻辑位于 _PipelineMixin 中，它负责管理文档在 DocStatus 状态间的转换（例如，PENDING -> PARSING -> ANALYZING -> PROCESSING -> PROCESSED）。

关键组件：

  • 工作队列：使用 asyncio.Queue 来管理解析引擎和提取阶段之间的流程 lightrag/pipeline.py:172-191。
  • 批次上下文：_BatchRunContext 用于跟踪文档批次的进度 lightrag/pipeline.py:172-191。

详情请参见文档路由与管线编排。

5.2 解析引擎与路由

LightRAG 支持多种解析引擎，通过 resolve_file_parser_directives 进行选择。选择遵循优先级顺序：文件名提示（例如 file.[mineru].pdf）、环境变量（LIGHTRAG_PARSER），最后是遗留的回退方案。

支持的引擎：

  • 原生引擎：内置支持 .txt、.md 和 .docx 格式 lightrag/pipeline.py:40。
  • 外部引擎：集成 MinerU 和 Docling，用于处理复杂的 PDF 和文档布局 lightrag/pipeline.py:38-39。

处理选项： 用户可以使用 i（图像）、t（表格）、e（公式）等标志以及 F/R/V/P 等片段切分策略来控制解析行为 lightrag/parser_routing.py:82-86。

详情请参见解析引擎与路由。

5.3 伴生格式与多模态处理

使用高级解析器时，LightRAG 会在 __parsed__ 目录中生成"伴生"文件。这些文件包含文档的中间表示（IR），包括表格和图像的结构化数据。

多模态能力：

  • VLM 分析：图像和表格会被发送给视觉语言模型（VLM）进行描述和摘要 lightrag/pipeline.py:42。
  • IR 结构：使用 IRDoc、IRBlock 和 IRTable 来维护提取过程中的文档层级结构。
  • 上下文组装：多模态描述会被注入到文本片段中，以便在知识图谱提取期间为大语言模型（LLM）提供完整的文档上下文。

详情请参见伴生格式与多模态处理。

数据一致性与存储

该管线通过在每个阶段更新 DocStatusStorage 来确保持久性。如果进程被中断，系统可以通过识别处于 FAILED 或 INFLIGHT 状态的文档来恢复执行 lightrag/pipeline.py:94-100。

标题：文档状态转换

LightRAG · 数据一致性与存储 · 图 2
LightRAG · 数据一致性与存储 · 图 2

来源：lightrag/pipeline.py:94-100, lightrag/base.py:28-32, lightrag/utils_pipeline.py:98-117

管线状态汇总表
状态负责的工作者输出产物
PARSINGq_native/q_mineru/q_doclingIR 伴生文件 / Markdown
ANALYZINGq_analyze (VLM)图像/表格描述
PROCESSINGq_process (LLM)图谱节点/边
PROCESSED_insert_done更新后的图谱与向量数据库

来源：lightrag/pipeline.py:172-191, lightrag/pipeline.py:33-41