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

文档入库管线（中文译文）

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

翻译时间：2026-05-27T08:45:12.584Z

翻译模型：deepseek-chat

原文字符数：6384

项目：LightRAG (lightrag)

---

文档入库管线

相关源文件

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

• 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. 集成：提取的数据被合并到图谱和向量存储中。

代码实体映射：入库生命周期

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

标题：文档入库逻辑流程

graph TD
    subgraph "API 层"
        [POST /upload] --> ["pipeline_index_files"]
        [POST /scan] --> ["run_scanning_process"]
    end

    subgraph "编排层 (_PipelineMixin)"
        ["pipeline_index_files"] --> ["apipeline_enqueue_documents"]
        ["apipeline_enqueue_documents"] --> ["apipeline_process_enqueue_documents"]
    end

    subgraph "工作队列"
        ["apipeline_process_enqueue_documents"] --> Q1["q_native / q_mineru / q_docling"]
        Q1 --> Q2["q_analyze (VLM)"]
        Q2 --> Q3["q_process (KG 提取)"]
    end

    subgraph "存储集成"
        Q3 --> ["_process_extract_entities"]
        ["_process_extract_entities"] --> ["merge_nodes_and_edges"]
    end

来源：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。

标题：文档状态转换

stateDiagram-v2
    [*] --> PENDING: apipeline_enqueue_documents
    PENDING --> PARSING: q_parser
    PARSING --> ANALYZING: q_analyze
    ANALYZING --> PROCESSING: q_process
    PROCESSING --> PROCESSED: _insert_done
    PROCESSING --> FAILED: 出错时
    FAILED --> PENDING: 重新处理

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

管线状态汇总表

状态	负责的工作者	输出产物
PARSING	q_native/q_mineru/q_docling	IR 伴生文件 / Markdown
ANALYZING	q_analyze (VLM)	图像/表格描述
PROCESSING	q_process (LLM)	图谱节点/边
PROCESSED	_insert_done	更新后的图谱与向量数据库

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