数据截至 2026-08-14(上游 commit 4fe4bde114a2)

MinerU 是什么 + 全景 + 阅读地图

30 秒导读: MinerU 是一个文档解析引擎——把 PDF、DOCX/PPTX/XLSX、图片这些"人看得懂、机器读不整齐"的文件,转成干净的 Markdown / 结构化 JSON,专供 LLM、RAG、Agent 消费。它的核心设计:无论用哪种解析方法,中间都收敛到同一份中间表示 middle_json,再由同一个渲染出口吐出多种格式。方法本身可插拔——传统流水线、视觉大模型、二者混合,加上 Office 文件的直接解析,四条路各司其职。

---

1. 这是什么(零基础也能懂)

一句话定义: MinerU 把各种文档"翻译"成 LLM 能吃的结构化文本(Markdown / JSON)。

解决什么问题 / 给谁用。 假设你在做一个 RAG 知识库,手里有一堆 PDF——有的是扫描件、有的是双栏排版、有的满页公式和表格。直接把 PDF 的字节丢给大模型是没用的:公式变乱码、表格错位、页眉页脚混进正文、阅读顺序全乱。MinerU 就是站在你和大模型之间的那一层:它先把文档读懂(版面、阅读顺序、公式、表格、图),再输出成排好序、去掉页眉页脚、公式转 LaTeX、表格转 HTML 的 Markdown。

它能做什么(README 顶部能力表,摘录):

能力	说明
多格式输入	原生支持 PDF、DOCX、PPTX、XLSX、图片
公式 / 表格	公式 → LaTeX,表格 → HTML,还原版面
难样本	扫描件、手写、多栏、跨页表格合并
阅读顺序	按人类阅读顺序输出,自动去页眉页脚
双引擎	VLM + OCR 双引擎,109 种语言 OCR

用起来什么样(最小 CLI 用例):

mineru -p a.pdf -o out

-p 是输入文件(或目录),-o 是输出目录。跑完 out/ 里就有 a.md、a_content_list.json、a_middle.json,以及画了版面框的可视化 a_layout.pdf。这两个选项由 mineru/cli/client.py:1040-1055 的 -p/--path、-o/--output 定义,二者都是 required=True。

一句话直觉/类比: 把 MinerU 想成一个"文档到 Markdown 的编译器"——前端认各种源格式,中间收敛成一份统一的 IR(中间表示 middle_json),后端再从这份 IR 生成不同目标产物。换前端(用哪种模型解析)不影响后端(怎么渲染),这正是它可插拔的来源。

本节不出现底层代码细节。目标:完全不懂的人读完知道"这是干嘛的"。

---

2. 顶层全景(它大概怎么转)

2.1 主线一张图

先给"怎么读这张图":从左到右是一条流水线,输入文件先变成字节,按格式/后端分派到不同解析器,所有解析器最终都汇成同一份 middle_json,再由 mkcontent 渲染成多路输出。

                                              ┌──────────────────────────────┐
  输入文件            读字节+认格式             │        四条解析路(可插拔)      │
  a.pdf / a.docx  →  read_fn 读 bytes    →    │                              │
  a.png / ...        guess_suffix 猜后缀       │  ① pipeline  传统多模型流水线  │
                          │                    │  ② vlm       单视觉模型端到端  │  ─┐
                          │  do_parse 按后缀     │  ③ hybrid    混合(vlm+文本层) │   │
                          └── 与 backend 分派 → │  ④ office    DOCX/PPTX/XLSX直解│   │
                                              └──────────────────────────────┘   │
                                                                                  │
                    ┌─────────────────────────────────────────────────────────────┘
                    ↓
          ┌────────────────────┐    mkcontent      ┌───────────────────────────┐
          │  统一中间表示        │    union_make     │  多路输出(_process_output)  │
          │  middle_json         │  ───────────────→ │  a.md / content_list.json  │
          │  {"pdf_info":[页...]} │                   │  a_middle.json / 可视化 pdf │
          └────────────────────┘                    └───────────────────────────┘

这张图的三个"关节"是理解 MinerU 的全部:

1. 入口收字节 + 认格式 —— 不管你给的是 PDF 还是图片还是 Office,先读成 bytes 再按格式走。
2. 中间收敛成 middle_json —— 四条解析路各干各的,但都必须产出同一形状的 middle_json(顶层是 {"pdf_info": [每页...]})。
3. 统一出口 _process_output —— 拿到 middle_json 后,渲染逻辑对所有后端是共享的,只按 process_mode 挑不同的 union_make。

2.2 八个命令行入口

MinerU 不是单一命令,而是一组工具。pyproject.toml:128-136 的 [project.scripts] 声明了 8 个入口:

命令	入口符号	干什么
mineru	mineru.cli.client:main	主 CLI:解析文件(上面的 -p/-o)
mineru-vllm-server	mineru.cli.vlm_server:vllm_server	起一个 vLLM 后端的 VLM 推理服务
mineru-lmdeploy-server	mineru.cli.vlm_server:lmdeploy_server	起 LMDeploy 后端的 VLM 服务
mineru-openai-server	mineru.cli.vlm_server:openai_server	起 OpenAI 兼容的 VLM 服务
mineru-models-download	mineru.cli.models_download:download_models	下载所需模型权重
mineru-api	mineru.cli.fast_api:main	起 FastAPI 解析服务
mineru-router	mineru.cli.router:main	多实例路由/调度
mineru-gradio	mineru.cli.gradio_app:main	起 Gradio Web UI

对初学者:你只需要记住 mineru(解析)和 mineru-models-download(先下模型)。其余是把解析能力搬到服务/网页/多机的外壳,内核都通向同一个 do_parse。

2.3 部件一句话职责

部件	干什么	在哪(path:符号)
CLI 入口	解析命令行、编排一次解析	mineru/cli/client.py:1185 main
读字节	把路径读成 bytes	mineru/cli/common.py:171 read_fn
认格式	靠字节魔数猜后缀	mineru/utils/guess_suffix_or_lang.py:174 guess_suffix_by_bytes
总调度	按 backend/后缀分派到四条路	mineru/cli/common.py:668 do_parse(异步版 aio_do_parse:760)
pipeline 路	传统多模型流水线	mineru/cli/common.py:351 _process_pipeline
vlm 路	单视觉语言模型端到端	mineru/cli/common.py:467 _process_vlm
hybrid 路	混合后端	mineru/cli/common.py:508 _process_hybrid
office 路	DOCX/PPTX/XLSX 直解	mineru/cli/common.py:618 _process_office_doc
统一出口	从 middle_json 渲染多路产物	mineru/cli/common.py:259 _process_output

---

3. 全流程主线:走一遍 do_parse

这节把"输入 → 输出"在代码层面串一遍(高层,不钻任一后端内部)。do_parse(mineru/cli/common.py:668)是所有路径的汇合点,分五步。

3.1 第一步:规范化后端名

backend = normalize_backend(backend)   # common.py:693

normalize_backend(mineru/cli/backend_options.py:39)把旧别名(如 hybrid-auto-engine)映射到当前公开名,并校验合法性。合法后端有 5 个(backend_options.py:13-22):pipeline、vlm-engine、vlm-http-client、hybrid-engine、hybrid-http-client。默认是 hybrid-engine(DEFAULT_BACKEND,backend_options.py:11)。

3.2 第二步:Office 文件先被"截胡"

注意顺序——Office 直解跑在后端分派之前:

need_remove_index = _process_office_doc(...)   # common.py:694
for index in sorted(need_remove_index, reverse=True):
    del pdf_bytes_list[index]; del pdf_file_names[index]; ...

_process_office_doc(mineru/cli/common.py:618)遍历所有输入,凡是 .docx/.pptx/.xlsx(office_suffixes,common.py:44-47)就地解析掉,并把它们的下标从待处理列表里删除。这解释了 Office 的分工:它不经过下面三大后端,而是走一条独立的、纯结构解析的短路——因为 Office 文件本身就带结构(XML),不需要 OCR/视觉模型去"看"。

3.3 第三步:PDF 字节预处理

pdf_bytes_list = _prepare_pdf_bytes(pdf_bytes_list, start_page_id, end_page_id)  # common.py:714

剩下的 PDF/图片按 -s/-e 指定的页码范围裁剪字节(_prepare_pdf_bytes:250)。

3.4 第四步:按 backend 分派到三大后端

这是"可插拔"的心脏。do_parse 用一组 if/elif 把控制流交给对应处理器:

backend == "pipeline"      → _process_pipeline   (common.py:716→717)
backend.startswith("vlm-") → _process_vlm        (common.py:725→734)
backend.startswith("hybrid-") → _process_hybrid   (common.py:741→751)

对 vlm-/hybrid-,还会先剥掉前缀,若剩 engine 则调 get_vlm_engine(...)(common.py:728-729、745-746)自动选一个可用推理引擎。三个处理器签名对齐(都在 common.py:351/467/508),内部各自调 pipeline_doc_analyze_streaming / vlm_doc_analyze / hybrid_doc_analyze,但返回值都是 (middle_json, infer_result)——形状统一,这就是收敛点。

三后端 + Office 的分工一表看清:

路	触发条件	怎么解析	适合
pipeline	backend=pipeline	传统多模型流水线:版面检测 + 公式/表格/OCR 各专用模型	CPU/GPU 皆可、稳定、无幻觉
vlm	backend=vlm-*	单个视觉语言模型端到端"看图说话"	高精度,吃本地/远端算力
hybrid	backend=hybrid-*	VLM + PDF 原生文本层混合(inline_formula_enable、effort 控深浅)	高精度 + 原生取字、低幻觉(默认)
office	后缀是 docx/pptx/xlsx	解析 XML 结构直出,不过模型	Office 文档,快

3.5 第五步:统一出口渲染

所有后端拿到 middle_json 后,都调同一个 _process_output(mineru/cli/common.py:259)。它按 process_mode 挑渲染函数(common.py:278-286):

if process_mode == "pipeline":   make_func = pipeline_union_make
elif process_mode == "vlm":      make_func = vlm_union_make
elif process_mode in office_suffixes: make_func = office_union_make

三个 union_make(分别在 pipeline/pipeline_middle_json_mkcontent.py:968、vlm/vlm_middle_json_mkcontent.py:892、office/mkcontent/output_builders.py:756)吃同一形状的 pdf_info,吐出 Markdown 字符串与 content_list。随后 _process_output 把结果写盘:.md(common.py:314)、_content_list.json / _content_list_v2.json(:321-333)、_middle.json(:336)、_model.json(:342),以及可选的可视化 _layout.pdf / _span.pdf(:288-298)。

注意:主 CLI mineru(client.py:1185 main → run_orchestrated_cli)默认经由一个 FastAPI 服务执行,该服务内部才调 do_parse/aio_do_parse(mineru/cli/fast_api.py:35-36, 864-866)。do_parse 因此是 CLI 与 API 共享的唯一解析内核。编排细节见 01-orchestration.md。

---

4. 巧妙之处速览

读者要带走的三个设计精华:

1. 统一 middle_json 作为 IR。 不论 pipeline / vlm / hybrid / office,四条完全不同的解析路都产出 {"pdf_info": [...]} 同一形状(见各处理器返回 middle_json["pdf_info"],common.py:457/498/551/656)。这让"解析方法"和"输出格式"彻底解耦——加一种新解析法,只要它能填出 middle_json,就白拿全部输出格式。

2. 可插拔后端 = 一个分派表 + 对齐签名。 do_parse 里的 if/elif(common.py:716-757)是唯一的分派点;三个处理器签名、返回值都对齐。换后端对上层是透明的,连 _process_output 都不用改——它只认 process_mode 字符串。

3. 统一渲染出口。 _process_output(common.py:259)是所有产物的唯一收口:一处决定写哪些文件、画哪些可视化。想加一种新输出格式,只在这一处动。

---

5. 阅读地图

本章是全景与路由。想深入某一块,按下表下钻(建议顺序即从上到下):

章节	讲什么	什么时候读
01-orchestration.md	入口与编排:从字节到多路输出——main / do_parse / _process_output 全链路	想搞清"一次解析从命令到落盘"的完整控制流
02-pipeline-backend.md	pipeline 后端:传统多模型流水线(版面/公式/表格/OCR 各专用模型)	关心无幻觉、CPU 可跑的经典方案
03-vlm-backend.md	vlm 后端:单个视觉语言模型端到端解析	关心高精度视觉模型怎么"一次看懂整页"
04-middle-json-and-markdown.md	统一中间表示 middle_json、magic_model 与 Markdown 渲染	想吃透那个把一切串起来的 IR 与 union_make
05-hybrid-and-office.md	hybrid 混合后端与 Office 直解	关心默认后端 hybrid,或 DOCX/PPTX/XLSX 直解

本章刻意不深入任何一个后端内部——那是上面各章的活。

---

6. 代码地图(导航索引)

主题	文件路径	符号名
8 个命令行入口	pyproject.toml([project.scripts])	mineru / mineru-api / mineru-models-download …
主 CLI 入口	mineru/cli/client.py	main
读字节	mineru/cli/common.py	read_fn
认格式(魔数)	mineru/utils/guess_suffix_or_lang.py	guess_suffix_by_bytes
总调度(核心)	mineru/cli/common.py	do_parse / aio_do_parse
后端名规范/默认	mineru/cli/backend_options.py	normalize_backend / DEFAULT_BACKEND
pipeline 处理器	mineru/cli/common.py	_process_pipeline
vlm 处理器	mineru/cli/common.py	_process_vlm
hybrid 处理器	mineru/cli/common.py	_process_hybrid
office 直解	mineru/cli/common.py	_process_office_doc
统一渲染出口	mineru/cli/common.py	_process_output
pipeline 渲染	mineru/backend/pipeline/pipeline_middle_json_mkcontent.py	union_make
vlm 渲染	mineru/backend/vlm/vlm_middle_json_mkcontent.py	union_make
office 渲染	mineru/backend/office/mkcontent/output_builders.py	union_make
CLI 内核实为 API	mineru/cli/fast_api.py	do_parse / aio_do_parse 调用点