MinerU保姆级上手:把PDF变成Agent数据

这次在 GitHub Trending daily 里看到 opendatalab/MinerU，我的第一反应是：这不是又一个“PDF 转 Markdown”小工具吗？

看完 README、文档站、3.4 release、最近提交和几篇技术报告后，判断变了。

MinerU 更像是给 RAG、Agent、知识库做“文档进料”的基础设施。它要解决的不是把字抠出来这么简单，而是把 PDF、图片、DOCX、PPTX、XLSX 这类复杂文档，尽量还原成机器能读、能检索、能继续加工的 Markdown 和 JSON。

项目地址： https://github.com/opendatalab/MinerU

讲真，如果你做过企业知识库，应该懂这个痛点：大模型看起来什么都能读，真碰到扫描件、双栏论文、公式、跨页表格、页眉页脚、PPT 截图，马上就开始“凭感觉理解”。MinerU 的价值，正好卡在这里。

它到底解决什么问题

AI智能体学习网站：ai-agent-phd.com

普通 OCR 把图片里的字识别出来，很多时候就算完成任务了。

但 Agent 和 RAG 不够。

一个可靠的文档解析结果，至少要做到几件事：阅读顺序不能乱，标题层级要尽量保住，页眉页脚别混进正文，公式要转成 LaTeX，表格最好能变成 HTML 或结构化 JSON，图片、图表、表注也要有位置和上下文。

MinerU 的 README 里把自己定位得很清楚：面向 LLM、RAG、Agent 工作流的高精度文档解析引擎。当前开源仓库侧支持本地 PDF、图片、DOCX、PPTX、XLSX 输入；官网产品形态还提供在线版、客户端、开发者 API，并强调对主流 Agent 框架和 MCP 协议的接入。

我觉得它最值得关注的点有三个：

输出不是一坨纯文本，而是 Markdown、content list、middle JSON、layout 可视化等多种结果。
后端分层比较清楚：pipeline 稳、轻、可 CPU 跑；vlm-engine 偏高精度；hybrid-engine 试图把原生文本提取、OCR、VLM 能力折中起来。
最近版本明显在补工程可用性，不只是刷榜。3.4 重点升级了 pipeline 后端的 PP-OCRv6，官方称 OCR 相关指标在 OmniDocBench v1.6 上提升约 11%，OCR 处理速度提升约 100%，还做了模型源自动选择和缓存复用。

一句话：

MinerU 适合把复杂文档变成可消费的数据，不适合拿来当“万能无脑阅读器”。

论文笔记：它为什么不直接端到端硬读

AI智能体学习网站：ai-agent-phd.com

仓库里明确链接了技术报告，不是只有 README 营销文案。

主线可以按四层理解。

第一层是 2024 年的 MinerU 技术报告。那个阶段的核心思路偏工程管线：基于 PDF-Extract-Kit 等模型和大量预处理、后处理规则，把版面分析、公式识别、表格抽取这些模块组织起来，追求稳定的内容提取。

这一路线的好处是可解释、可调试。坏处也很明显：模块一多，前面错了，后面跟着错；环境依赖也容易变复杂。

第二层是 MinerU2.5 技术报告。这里开始转向文档解析 VLM，但它没有粗暴地把整页高分辨率图片全塞进模型。论文的关键设计是“粗到细”的两阶段策略：

先在降采样页面上做全局版面分析，找到结构元素；再回到原始高分辨率图里裁剪局部区域，针对文本、公式、表格做细粒度识别。

这个设计很务实。文档页里有很多空白、边距、低信息区域，如果原图整页进模型，视觉 token 会很浪费；只看低清缩略图，公式和小字又会糊。MinerU2.5 把“看全局”和“读细节”拆开，本质上是在省计算的同时保住解析质量。

论文里给出的 MinerU2.5 模型规模是 1.2B，在 OmniDocBench 等评测中表现突出。更重要的是，它解释了为什么小模型也能在文档解析上打得动：文档理解未必需要超大的语言模型脑容量，真正难的是版面、表格、公式和高分辨率细节。

第三层是 MinerU2.5-Pro 技术报告。它的重点不是换一个更大的架构，而是把数据工程做重。报告里提到数据引擎从不足 1000 万样本扩展到 6550 万样本，并围绕覆盖度、信息量、标注准确性做采样、交叉模型一致性验证和 Judge-and-Refine 流程。

结果也很直接：技术报告给出 MinerU2.5-Pro 在 OmniDocBench v1.6 Full 上的 Overall 分数为 95.69，比同架构的 MinerU2.5 基线高 2.71 分。表格、公式、阅读顺序这些细项，也都是它强调的核心战场。

第四层是 MinerU-Diffusion。这篇更像研究侧探索：把 OCR 看成“逆渲染”，用扩散式并行去噪替代传统自回归逐字生成。报告称相对自回归基线最高可带来 3.2 倍解码加速，并降低长序列错误传播。

对普通使用者来说，不需要把这些论文全背下来。

你只要记住一个判断：MinerU 的路线不是“让大模型自由发挥”，而是尽量把文档拆成结构、位置、内容，再用不同机制把它们拼成可靠输出。

保姆级上手：先别急着部署

AI智能体学习网站：ai-agent-phd.com

我的建议很保守：先用在线版或 Gradio demo 试两三份自己的文档。

尤其是这几类：

一份扫描版 PDF，看 OCR 稳不稳。
一份有复杂表格的 PDF，看表格是否能还原。
一份你真实业务里的 DOCX、PPTX 或 XLSX，看原生解析是否符合预期。

别拿项目 demo 成功就下结论。文档解析这件事很吃样本分布，你的文档才是真评测集。

如果效果能接受，再本地部署。

本地安装：新手按这个来

准备环境：

Python 3.10 到 3.13。
内存最低 16GB，推荐 32GB。
磁盘至少 20GB，最好 SSD。
如果要跑 VLM 或 hybrid 本地后端，建议有 8GB 以上显存；没有 GPU 就用 pipeline。

创建虚拟环境后安装：

pipinstall--upgradepip-ihttps://mirrors.aliyun.com/pypi/simple
pipinstalluv-ihttps://mirrors.aliyun.com/pypi/simple
uvpipinstall-U"mineru[all]"-ihttps://mirrors.aliyun.com/pypi/simple

如果你更喜欢源码安装：

gitclonehttps://github.com/opendatalab/MinerU.git
cdMinerU
uvpipinstall-e.[all]-ihttps://mirrors.aliyun.com/pypi/simple

国内网络建议先设置模型源：

exportMINERU_MODEL_SOURCE=modelscope

Windows PowerShell 写法是：

$env:MINERU_MODEL_SOURCE="modelscope"

3.4 版本已经加入模型源自动选择和本地缓存复用，但我仍建议国内环境显式设成 ModelScope，少一点玄学。

跑第一份文档

最简单命令：

mineru-p./demo/pdfs/demo1.pdf-o./output

如果你没有可用 GPU，直接指定 pipeline：

mineru-p./demo/pdfs/demo1.pdf-o./output-bpipeline

如果只想跑某几页：

mineru-p./paper.pdf-o./output-s0-e4

如果文档 OCR 语言需要手动指定，可以用 -l。不过 3.4 版本已经把日语、繁中、英文、拉丁文等部分选择统一路由到 ch 模型，配置比旧版本简化了不少。

跑完后，不要只看 Markdown。

重点看这几个文件：

*.md：给人读、给轻量 RAG 切分用。
*_content_list.json：按阅读顺序平铺的结构化内容，适合后续程序处理。
*_content_list_v2.json：3.0 起新增的通用结构化输出，类型加内容结构更统一，但文档也提醒仍可能调整。
*_middle.json：更完整的中间结构，适合二次开发和调试。
*_layout.pdf、*_span.pdf：看版面框和识别顺序，排查问题很有用。

很多人踩坑，是因为只盯着 Markdown 说“这里不对”。其实你应该打开 layout 可视化文件，看是版面识别错了、阅读顺序错了，还是 Markdown 生成阶段损失了信息。

后端怎么选

新手直接照这个表来：

场景	推荐选择
普通电脑、只想能跑	`-b pipeline`
扫描件多、表格公式多、有 8GB 以上显存	默认 `hybrid-engine` 先试
想要更高精度，能接受慢一点	`hybrid-engine --effort high`
只是边缘设备调用远端服务	`vlm-http-client` 或 `hybrid-http-client`
批量服务、多 GPU	`mineru-router`

默认 CLI 后端是 hybrid-engine，Hybrid 还有 medium 和 high 两档。3.3 release 里提到，默认 medium 相比 high 精度只差很小，但速度提升明显；不过 medium 不支持 image analysis。要做图表、图片语义分析，就切到 high。

mineru-p./docs-o./output-bhybrid-engine--efforthigh--image-analysistrue

如果只是把大量普通 PDF 进知识库，我会先用 pipeline 做基线。它更稳定、更省资源，也更容易定位问题。

API、WebUI 和批量部署

本地起 FastAPI：

mineru-api--host0.0.0.0--port8000

然后浏览器打开：

http://127.0.0.1:8000/docs

常用接口有三个：

POST /tasks：异步任务提交。
POST /file_parse：同步解析，兼容老插件。
GET /tasks/{task_id} 和 GET /tasks/{task_id}/result：查状态和拿结果。

如果你想给同事一个可视化页面：

mineru-gradio--server-name0.0.0.0--server-port7860

如果你要做多服务、多 GPU 编排：

mineru-router--host0.0.0.0--port8002--local-gpusauto

这块是 MinerU 3.0 之后很重要的变化。现在 mineru 命令本身更像一个基于 mineru-api 的客户端；不传 --api-url 时，会自动拉起本地临时 API，传了就直连已有服务。

对企业落地，这比一个纯脚本舒服很多。

Docker 适合谁

Docker 只建议 Linux 或 Windows WSL2 用户用。macOS，尤其 Apple Silicon，不推荐走 Docker，因为 Docker 里吃不到 macOS 的 MPS、MLX 加速能力。

构建镜像：

wgethttps://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/china/Dockerfile
dockerbuild-tmineru:latest-fDockerfile.

启动容器：

dockerrun--gpusall\
--shm-size32g\
-p30000:30000-p7860:7860-p8000:8000-p8002:8002\
--ipc=host\
-itmineru:latest\
/bin/bash

它的 Docker 镜像默认围绕 vLLM 加速设计。你要确认显卡是 Volta 及以后架构，可用显存 8GB 以上，驱动也要匹配 CUDA 运行时。这个地方别硬上，环境不匹配时排错很费时间。

最近更新说明了什么

我看了一下最近提交，6 月 17 到 18 日这批变更基本围绕 3.4 release 收口：版本更新、changelog 更新、PP-OCRv6 相关文档、模型源配置和自动探测、snapshot 下载缓存、OCR 方向检测、表格 OCR batch 处理、DataLoader 内存管理优化等。

这说明项目还在高频打磨“跑得稳、下得动、批量处理不炸”的问题。

这点比单纯发一个漂亮模型更关键。

因为文档解析真正上线后，最麻烦的不是 demo 页能不能解析，而是几百份、几千份、格式乱七八糟的文档能不能持续产出可用结果。

适合场景和不适合场景

适合：

企业知识库入库前的文档清洗。
论文、研报、合同、说明书这类复杂 PDF 解析。
需要公式、表格、图片上下文的 RAG 项目。
想把 DOCX、PPTX、XLSX 也纳入同一套解析流程。
需要私有化、离线部署的团队。

不适合：

只需要提取几行普通文字的小脚本场景。
完全不愿意调环境、也不愿意看输出质量的人。
对每个标点都要求 100% 正确的强合规场景。
文档质量极差，还希望不做人工复核直接进生产的场景。

这里说句实话：MinerU 很强，但别神化它。

复杂文档解析就是难。尤其是低清扫描件、奇怪模板、嵌套表格、手写内容，没有任何开源工具能保证全自动完美。

商用和许可要看清

MinerU 现在不是 AGPLv3，而是基于 Apache 2.0 的 MinerU 开源许可证，并带附加条款。

普通商业使用门槛降低了，但有两点要注意：

如果你和关联方合并口径下月活超过 1 亿，或月总收入超过 2000 万美元，需要单独商业许可。
如果基于 MinerU 向第三方提供在线服务，需要在产品界面或公开文档里清楚标明使用了 MinerU。

大多数中小团队不用被这个吓住，但法务评审不能跳过。

我的实操建议

如果你是个人开发者：

先用在线版看效果；本地就装 mineru[all]；没 GPU 用 pipeline；输出优先看 Markdown 和 content list。

如果你在做 RAG：

别直接把 *.md 一切了事。建议把 content_list.json 或 content_list_v2.json 纳入管线，把标题层级、页码、bbox、表格 HTML、公式内容都保留下来。后面做 chunk、溯源、重排会舒服很多。

如果你在企业里落地：

先做 50 到 100 份真实文档的验收集，按“正文、表格、公式、图片说明、阅读顺序、页眉页脚清理”分别打分。评测通过后再上 API 或 router，不要一开始就追求大规模部署。

如果你要处理中文、英文、扫描件混合文档：

3.4 的 PP-OCRv6 和模型源优化值得试。但我建议把 layout.pdf、span.pdf 加到质检流程里，别只靠肉眼读最终 Markdown。

最终 verdict

MinerU 不是最轻的 PDF 工具，但它是目前很值得关注的开源文档解析基础设施。

它的优势在复杂文档：表格、公式、多栏、扫描件、Office 文件、结构化 JSON、API 服务化、私有化部署。它的门槛也在这里：模型下载、GPU/内存、后端选择、输出质检，都需要你认真对待。

我的结论很明确：

如果你正在做 Agent、RAG、企业知识库，MinerU 值得放进工具箱；如果你只是偶尔转一份普通 PDF，它可能有点重。

最佳落地路线是：在线试样本，pipeline 做基线，hybrid 提质量，content list 进数据管线，layout 可视化做质检。

别把它当魔法按钮。

把它当文档数据工程的入口，反而更容易用对。