agentic_huge_data_base / wiki
页面 LightRAG · 5.2 文档管理接口·DeepWiki 中文全文译文
DeepWiki 中文译文 / LightRAG / 5.2

5.2 · 文档管理接口（Document Management Interface）

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

项目LightRAG 章节5.2 状态全文译文 模块文档对象与元数据、测试、发布与运维、界面与交互、系统架构
项目要点页2.5 参考项目 项目章节目录LightRAG DeepWiki 原始章节Document Management Interface 上一章5.1 下一章5.3
源码线索
  • lightrag_webui/src/api/lightrag.test.ts
  • lightrag_webui/src/api/lightrag.ts
  • lightrag_webui/src/components/documents/ClearDocumentsDialog.tsx
  • lightrag_webui/src/components/documents/DeleteDocumentsDialog.tsx
  • lightrag_webui/src/components/documents/PipelineStatusDialog.tsx
  • lightrag_webui/src/components/documents/UploadDocumentsDialog.tsx
  • lightrag_webui/src/components/graph/LayoutsControl.tsx
  • lightrag_webui/src/components/graph/PropertyEditDialog.tsx
  • lightrag_webui/src/components/ui/Dialog.tsx
  • lightrag_webui/src/components/ui/FileUploader.tsx
模块标签
  • 文档对象与元数据
  • 测试、发布与运维
  • 界面与交互
  • 系统架构
  • 工作流与编排

章节正文

解析器引擎与路由

原始 DeepWiki 页面https://deepwiki.com/HKUDS/LightRAG/5.2-parser-engines-and-routing

解析器引擎与路由

相关源文件

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

  • docs/FileProcessingPipeline-zh.md
  • docs/FileProcessingPipeline.md
  • docs/LightRAGSidecarFormat.md
  • docs/ParagraphSemanticChunking-zh.md
  • docs/ParagraphSemanticChunking.md
  • docs/ParserDebugCLI-zh.md
  • docs/ParserDebugCLI.md
  • lightrag/api/routers/document_routes.py
  • lightrag/external_parser/docling/cache.py
  • lightrag/external_parser/docling/client.py
  • lightrag/external_parser/docling/manifest.py
  • lightrag/external_parser/mineru/cache.py
  • lightrag/external_parser/mineru/client.py
  • lightrag/external_parser/mineru/manifest.py
  • lightrag/native_parser/docx/drawing_image_extractor.py
  • lightrag/native_parser/docx/numbering_resolver.py
  • lightrag/native_parser/docx/omml/cleaners.py
  • lightrag/native_parser/docx/omml/ommlparser.py
  • lightrag/native_parser/docx/omml/utils.py
  • lightrag/native_parser/docx/parse_document.py
  • lightrag/native_parser/docx/table_extractor.py
  • lightrag/native_parser/docx/utils.py
  • lightrag/parser_cli.py
  • lightrag/parser_debug.py
  • lightrag/parser_routing.py
  • lightrag/pipeline.py
  • lightrag/table_markup.py
  • lightrag/utils_pipeline.py
  • tests/external_parser/docling/test_cache.py
  • tests/external_parser/docling/test_client.py
  • tests/external_parser/docling/test_manifest.py
  • tests/external_parser/mineru/test_cache.py
  • tests/external_parser/mineru/test_client.py
  • tests/native_parser/docx/test_native_docx_golden.py
  • tests/test_document_routes_docx_archive.py
  • tests/test_parse_docling_sidecar.py
  • tests/test_parse_mineru_sidecar.py
  • tests/test_parser_cli.py
  • tests/test_pipeline_release_closure.py

LightRAG 文档入库管线采用了一套精密的路由机制，用于决定文件在被切分和索引之前如何解析为结构化中间表示（IR）。该系统支持多种解析引擎，从轻量级的原生提取器到重量级的外部多模态服务，并允许通过环境变量和文件名提示进行细粒度控制。

解析器指令解析

路由逻辑遵循严格的优先级层级，以确定应对特定文件应用哪种引擎和处理选项。该过程主要由 resolve_file_parser_directives 函数管理。

优先级层级
  1. 文件名提示：嵌入在文件名中的显式指令（例如 document.[mineru-iet].pdf）。
  2. 环境规则（LIGHTRAG_PARSER）：文件扩展名到引擎-选项对的全局映射。
  3. 传统回退：如果没有规则匹配，系统默认使用 legacy 引擎和固定大小切分（F）。
文件名提示语法

用户可以通过在文件扩展名前添加方括号提示来覆盖全局设置：

  • [ENGINE]：设置引擎，使用默认选项（例如 report.[docling].pdf）。
  • [ENGINE-OPTIONS]：同时设置引擎和选项（例如 memo.[native-teP].docx）。
  • [-OPTIONS]：覆盖选项，但保留由全局规则确定的引擎（例如 data.[-!].csv）。
全局路由：LIGHTRAG_PARSER

该环境变量接受一个逗号分隔的 扩展名:引擎-选项 规则列表。 示例： LIGHTRAG_PARSER="pdf:mineru-iteP,docx:native-teP,*:legacy-R"

  • pdf 文件使用 mineru 引擎和 iteP 选项。
  • docx 文件使用 native 引擎和 teP 选项。
  • 所有其他文件（*）使用 legacy 引擎和 R（递归）切分。

来源： lightrag/parser_routing.py:40-67，lightrag/parser_routing.py:441-482，docs/FileProcessingPipeline.md:51-120

处理选项与标志

ProcessOptions 类解码一个由单字符标志组成的字符串，这些标志控制文本提取后管线的行为。

标志名称描述
i图片启用基于视觉语言模型（VLM）的文档内图片分析。
t表格启用结构化表格提取和分析。
e公式启用 LaTeX 风格公式提取。
!跳过知识图谱跳过知识图谱提取（仅进行向量索引）。
F固定使用 FixedTokenChunking。
R递归使用 RecursiveCharacterChunking（传统引擎的默认值）。
V向量使用 SemanticVectorChunking。
P段落使用 ParagraphSemanticChunking（需要 native 引擎或侧车 IR）。

来源： lightrag/parser_routing.py:72-102，lightrag/constants.py:22-34，docs/FileProcessingPipeline.md:121-140

解析器引擎

LightRAG 支持四种主要的解析引擎，每种引擎适用于不同复杂度的文档。

1. 原生引擎（原生）

一个内置的高性能解析器，专门用于 .docx 文件。它无需外部依赖即可提取结构化的标题、段落和表格。它是段落语义（P）切分策略所需元数据的主要提供者。

  • 关键逻辑： lightrag/native_parser/docx/parse_document.py
  • 能力： 表格提取、OMMAL 公式解析以及绘图/图片提取。
2. 外部解析器：MinerU 和 Docling

这些引擎通过调用外部微服务来处理复杂的多模态 PDF 和 Office 文档。

  • MinerU（mineru）：支持 local（自托管）和 official（云端）API 模式。它会生成一个包含所有元素边界框的 content_list.json 包。
  • Docling（docling）：连接到 docling-serve。它针对高保真布局分析和 OCR 进行了优化。
3. 传统引擎（legacy）

回退引擎，使用标准 Python 库（如 python-docx、pdfplumber）提取原始文本。它不支持高级的多模态侧车 IR。

来源： lightrag/constants.py:37-41，lightrag/parser_routing.py:121-129，lightrag/external_parser/mineru/client.py:106-160，lightrag/external_parser/docling/client.py:83-112

技术数据流：从路由到提取

下图展示了在 _PipelineMixin 中，文件路径如何被转换为特定的解析器调用。

解析器选择逻辑
LightRAG · 解析器选择逻辑 · 图 1
LightRAG · 解析器选择逻辑 · 图 1

来源： lightrag/api/routers/document_routes.py:1022-1055，lightrag/pipeline.py:208-250，lightrag/parser_routing.py:441-460

调试与工具

parser_cli.py

LightRAG 提供了一个专用的命令行工具，供开发者在无需运行完整服务器的情况下测试解析器路由和提取。它允许检查生成的侧车 IR 和切分边界。

用法：

python -m lightrag.parser_cli parse my_doc.docx --engine native --options teP
路由优先级逻辑图

此图展示了解析器引擎的代码级决策树。

LightRAG · 路由优先级逻辑图 · 图 2
LightRAG · 路由优先级逻辑图 · 图 2

来源： lightrag/parser_routing.py:441-482，lightrag/parser_cli.py:1-50，tests/test_pipeline_release_closure.py:91-120

实现细节

resolve_file_parser_directives

该函数返回一个 (engine, process_options) 元组。它是路由的核心决策者。如果指定的引擎需要外部端点（如 mineru 或 docling），但环境中未配置该端点，函数会自动将引擎降级为 legacy，以防止管线停滞，同时记录一条警告日志。

ProcessOptions 数据类

ProcessOptions 对象是不可变的（frozen=True），并提供了辅助属性，如 chunking_explicit，用于区分默认的 F 策略和用户选择的 F 策略。这种区分对于管线决定是使用新的结构化切分契约还是传统的 chunking_func 至关重要。

来源： lightrag/parser_routing.py:72-102，lightrag/parser_routing.py:441-482，lightrag/pipeline.py:1005-1030