高质量文档解析引擎 — 将 PDF / Office 文档转化为 LLM-Ready 的 Markdown 与 JSON
MinerU 是由 OpenDataLab 团队开源的高质量文档解析工具，核心使命是将复杂的 PDF、Office（DOCX/PPTX/XLSX）文档转化为 LLM 可直接消费的 Markdown 和 JSON 格式，为 Agentic 工作流提供高质量的结构化数据输入。
MinerU 采用分层架构设计，自顶向下分为接口层、后端引擎层、模型层、数据层和工具层，各层之间通过中间 JSON（Middle JSON）进行数据流转与解耦。
| 原则 | 描述 | 实现方式 |
|---|---|---|
| 引擎解耦 | 三种解析后端独立实现，通过统一接口调用 | Backend 抽象层 + Middle JSON 中间格式 |
| 模型可插拔 | AI 模型可独立替换和升级 | Model 层独立封装，配置化加载 |
| 存储抽象 | 数据读写与存储后端解耦 | Data Reader/Writer 抽象基类 |
| 多格式统一 | PDF 和 Office 文档统一处理流程 | 统一 Middle JSON 中间表示 |
| 部署灵活 | 支持本地、服务化、容器化部署 | CLI + FastAPI + Gradio + Docker |
后端引擎层是 MinerU 的核心，包含四种处理引擎，每种引擎针对不同场景和文档类型优化。
传统 ML 流水线引擎，通过多模型串联完成文档解析
基于视觉语言模型的端到端解析引擎
Pipeline + VLM 混合引擎，兼顾精度与泛化能力
Pipeline 引擎采用经典的多阶段流水线架构，每个阶段由独立的 AI 模型处理，阶段间通过结构化数据传递结果。
| 模块 | 文件 | 代码量 | 职责 |
|---|---|---|---|
| 批量分析 | batch_analyze.py | ~39KB | 批量文档解析调度，任务分发与结果聚合 |
| 模型初始化 | model_init.py | ~14KB | 统一初始化各 AI 模型，管理模型生命周期 |
| 模型输出转换 | model_json_to_middle_json.py | ~12KB | 将各模型原始输出转换为统一 Middle JSON |
| 段落拆分 | para_split.py | ~21KB | 基于规则和模型结果进行段落级拆分 |
| Pipeline 分析 | pipeline_analyze.py | ~13KB | Pipeline 引擎主控流程 |
| Magic Model | pipeline_magic_model.py | ~21KB | 封装模型调用逻辑，管理推理过程 |
| 内容生成 | pipeline_middle_json_mkcontent.py | ~39KB | 从 Middle JSON 生成最终 Markdown/JSON 输出 |
VLM 引擎利用视觉语言模型（如 Qwen-VL、InternVL 等）对文档页面进行端到端理解，直接从页面图像生成结构化内容。
| 模块 | 文件 | 代码量 | 职责 |
|---|---|---|---|
| VLM 分析 | vlm_analyze.py | ~26KB | VLM 引擎主控流程，页面切分与 VLM 推理调度 |
| VLM Magic Model | vlm_magic_model.py | ~15KB | 封装 VLM 模型调用，支持 vLLM/LMDeploy 后端 |
| 输出转换 | model_output_to_middle_json.py | ~5KB | VLM 输出转换为 Middle JSON |
| 内容生成 | vlm_middle_json_mkcontent.py | ~38KB | VLM Middle JSON 生成最终输出内容 |
| VLM 工具 | utils.py | ~9KB | VLM 相关辅助函数 |
Hybrid 引擎融合 Pipeline 和 VLM 的优势：先通过 Pipeline 模型获取版面结构和 OCR 结果，再利用 VLM 对复杂区域进行补充理解。
| 模块 | 文件 | 代码量 | 职责 |
|---|---|---|---|
| 混合分析 | hybrid_analyze.py | ~40KB | Hybrid 引擎主控流程，协调 Pipeline + VLM |
| 混合 Magic Model | hybrid_magic_model.py | ~19KB | 统一封装 Pipeline 和 VLM 模型调用 |
| 输出转换 | hybrid_model_output_to_middle_json.py | ~11KB | 混合输出合并为 Middle JSON |
Office 引擎处理 DOCX、PPTX、XLSX 格式文档，通过解析 Office 文档的原生结构信息，转换为统一的 Middle JSON 格式。
| 模块 | 文件 | 代码量 | 职责 |
|---|---|---|---|
| DOCX 分析 | docx_analyze.py | ~2KB | DOCX 文档解析入口 |
| PPTX 分析 | pptx_analyze.py | ~2KB | PPTX 文档解析入口 |
| XLSX 分析 | xlsx_analyze.py | ~2KB | XLSX 文档解析入口 |
| Office Magic Model | office_magic_model.py | ~31KB | Office 文档结构化解析核心逻辑 |
| 输出转换 | model_output_to_middle_json.py | ~7KB | Office 解析结果转 Middle JSON |
| 内容生成 | office_middle_json_mkcontent.py | ~1KB | Office Middle JSON 生成输出 |
模型层集成了多种深度学习模型，每个模型负责文档解析流水线中的一个特定任务。模型通过统一的初始化和调用接口与后端引擎交互。
DocLayoutv2（pp_doclayoutv2.py, ~65KB）
| 模型 | 文件 | 代码量 | 功能 |
|---|---|---|---|
| PaddleOCR (PyTorch) | pytorch_paddle.py | ~13KB | 文本检测 + 文本识别，支持多语言 |
| 印章检测 | seal_det_warp.py | ~27KB | 印章/公章区域检测与矫正 |
| 印章裁剪 | seal_crop.py | ~15KB | 印章区域裁剪与预处理 |
| 模型 | 目录 | 功能 |
|---|---|---|
| UniMERNet | model/mfr/unimernet/ | 通用数学公式识别，输出 LaTeX |
| PP-FormulaNet+ M | model/mfr/pp_formulanet_plus_m/ | PaddlePaddle 公式识别模型 |
公式识别工具函数（mfr/utils.py, ~15KB）提供模型推理的辅助功能，包括图像预处理、后处理和 LaTeX 格式化。
表格识别分为两个子任务：
| 服务 | 文件 | 功能 |
|---|---|---|
| vLLM Server | model/vlm/vllm_server.py | 基于 vLLM 的高性能 VLM 推理服务 |
| LMDeploy Server | model/vlm/lmdeploy_server.py | 基于 LMDeploy 的 VLM 推理服务 |
VLM 服务支持多种开源视觉语言模型（如 Qwen2-VL、InternVL 等），通过 OpenAI 兼容 API 提供推理服务。
接口层提供多种用户交互方式，从命令行到 Web UI，从本地部署到云端 API。
| 模块 | 文件 | 代码量 | 功能描述 |
|---|---|---|---|
| CLI 客户端 | cli/client.py | ~36KB | 命令行主入口，支持 PDF/Office 解析、批量处理 |
| FastAPI 服务 | cli/fast_api.py | ~49KB | RESTful API 服务，支持异步任务和文件上传 |
| Gradio Web UI | cli/gradio_app.py | ~77KB | 交互式 Web 界面，实时预览解析结果 |
| API 路由 | cli/router.py | ~61KB | API 路由定义，任务管理、文件管理、结果查询 |
| API 客户端 | cli/api_client.py | ~35KB | 远程 API 调用客户端 |
| API 请求 | cli/api_request.py | ~8KB | HTTP 请求封装 |
| 通用逻辑 | cli/common.py | ~32KB | CLI 共享逻辑，参数解析、配置加载 |
| 模型下载 | cli/models_download.py | ~6KB | AI 模型权重自动下载与管理 |
| VLM 服务 | cli/vlm_server.py | ~2KB | VLM 推理服务启动入口 |
| VLM 预加载 | cli/vlm_preload.py | ~2KB | VLM 模型预加载与缓存 |
| 可视化 | cli/visualization.py | ~3KB | 解析结果可视化展示 |
| 输出路径 | cli/output_paths.py | ~1.5KB | 输出文件路径管理 |
命令行直接运行
适合开发调试和小批量处理
FastAPI 服务化部署
适合生产环境和集成调用
容器化一键部署
适合云原生和分布式场景
数据层通过抽象基类模式，将数据读写操作与底层存储实现解耦，支持多种存储后端的无缝切换。
| 组件 | 文件 | 功能 |
|---|---|---|
| 抽象基类 | data_reader_writer/base.py | 定义 Reader/Writer 统一接口 |
| 本地文件 | data_reader_writer/filebase.py | 本地文件系统读写实现 |
| S3 存储 | data_reader_writer/s3.py | Amazon S3 兼容存储读写 |
| 多桶 S3 | data_reader_writer/multi_bucket_s3.py | 多 S3 桶统一读写，支持桶级路由 |
| Dummy 实现 | data_reader_writer/dummy.py | 空实现，用于测试和开发 |
| 协议 | 文件 | 功能 |
|---|---|---|
| IO 基类 | io/base.py | 定义数据传输协议接口 |
| HTTP 协议 | io/http.py | HTTP/HTTPS 数据传输 |
| S3 协议 | io/s3.py | S3 协议数据传输 |
工具层提供跨模块共享的辅助功能，是整个系统的基础支撑。
| 分类 | 模块 | 代码量 | 功能 |
|---|---|---|---|
| PDF 处理 | pdf_classify.py | ~23KB | PDF 文本型/扫描型/OCR型分类 |
| pdf_image_tools.py | ~17KB | PDF 图像提取与处理 | |
| pdf_text_tool.py | ~3KB | PDF 文本提取工具 | |
| pdf_reader.py | ~2KB | PDF 文件读取封装 | |
| OCR 辅助 | ocr_utils.py | ~17KB | OCR 预处理、后处理、结果合并 |
| span_pre_proc.py | ~22KB | 文本 Span 预处理 | |
| span_block_fix.py | ~6KB | 文本块修正与对齐 | |
| 表格处理 | table_merge.py | ~41KB | 跨页表格合并 |
| table_continuation.py | ~1KB | 表格续表检测 | |
| 几何计算 | boxbase.py | ~8KB | 边界框基础运算 |
| bbox_utils.py | ~1KB | 边界框工具函数 | |
| cut_image.py | ~1KB | 图像裁剪 | |
| 配置管理 | config_reader.py | ~6KB | JSON 配置文件读取 |
| os_env_config.py | ~1KB | 环境变量配置 | |
| enum_class.py | ~4KB | 枚举类型定义 | |
| LLM 辅助 | llm_aided.py | ~13KB | LLM 辅助的文档理解与修正 |
| 可视化 | draw_bbox.py | ~17KB | 边界框可视化绘制 |
| 模型管理 | model_utils.py | ~9KB | 模型加载与推理工具 |
| 语言检测 | language.py / guess_suffix_or_lang.py | ~8KB | 文档语言自动检测 |
| Office 格式 | office_rich_text.py | ~13KB | Office 富文本处理 |
| 标题处理 | title_level_postprocess.py | ~2KB | 标题层级后处理 |
以下展示 MinerU 处理一份 PDF 文档的完整数据流。
| 领域 | 技术 | 用途 |
|---|---|---|
| 编程语言 | Python 3.10+ | 主要开发语言 |
| 深度学习框架 | PyTorch / PaddlePaddle | AI 模型推理 |
| VLM 推理 | vLLM / LMDeploy | 视觉语言模型高效推理 |
| OCR 引擎 | PaddleOCR | 文字检测与识别 |
| PDF 处理 | PyMuPDF (pymupdf) | PDF 解析与渲染 |
| Web 框架 | FastAPI | RESTful API 服务 |
| UI 框架 | Gradio | 交互式 Web 界面 |
| 对象存储 | boto3 (AWS S3) | S3 兼容存储读写 |
| 容器化 | Docker | 容器化部署 |
| 包管理 | uv / pip | 依赖管理与安装 |
| 文档 | MkDocs | 项目文档站点 |
| 模型 | 任务 | 框架 | 输出格式 |
|---|---|---|---|
| DocLayoutv2 | 版面检测 | PaddlePaddle | BBox + 类别 |
| PaddleOCR | 文字识别 | PaddlePaddle → PyTorch | 文本 + 坐标 |
| UniMERNet | 公式识别 | PyTorch | LaTeX |
| PP-FormulaNet+ M | 公式识别 | PaddlePaddle | LaTeX |
| Table CLS | 表格分类 | PaddlePaddle | 类别标签 |
| Table REC | 表格结构识别 | PaddlePaddle | HTML |
| Qwen2-VL / InternVL | VLM 推理 | vLLM / LMDeploy | 结构化文本 |
| 优势 | 说明 |
|---|---|
| 🧩 模块化设计 | 引擎层、模型层、数据层清晰分离，各模块可独立开发与测试 |
| 🔄 多引擎灵活切换 | Pipeline / VLM / Hybrid 三引擎覆盖不同精度与性能需求 |
| 📐 统一中间表示 | Middle JSON 作为统一数据交换格式，解耦模型输出与内容生成 |
| 📦 存储抽象 | Reader/Writer 抽象基类支持本地、S3、多桶 S3 无缝切换 |
| 🚀 多种部署模式 | CLI / API / Web UI / Docker 满足不同场景需求 |
| 🤖 AI 模型可插拔 | 模型独立封装，可按需加载和替换 |
Model → Middle JSON → Content 的三阶段处理流程将文档转化为高质量 Markdown，用于向量检索增强生成
大规模文档解析，生成 LLM 预训练语料
为 AI Agent 提供结构化文档理解能力
扫描件/纸质文档的数字化与结构化提取