MinerU:给 Agent 造一条文档解析流水线

10 月 29 日到 11 月 4 日，六天，八个 release。这是 MinerU 最近的发布节奏。这个项目在 GitHub 上收获了 83,258 个 star，6,896 次 fork，是 OpenDataLab 出品的文档解析工具。PDF、扫描件、Word、PPT、Excel、EPUB、OFD、网页存档，统统转成 Markdown 和 JSON，给大模型和 Agent使用。

它是什么

README 首屏那句定位翻译过来是，把 PDF 和 Office 这类复杂文档转换成大模型就绪的 Markdown 与 JSON，服务 Agent 工作流。我读完代码后的理解是，它在大模型数据准备这一步提供了一条工业化流水线，上游来者不拒什么格式都收，下游按九种目标格式吐结果，中间根据机器的硬件条件自动分档，从 2GB 内存的纯 CPU 机器到 8GB 显存的 N 卡都有对应的跑法。

先划清赛道。MinerU 做的是文档解析这一层，输入是文件，输出是结构化内容。它不是 RAG 框架，不是向量数据库，也不是问答应用，仓库里的 Agent Guide 把这三样排除得明明白白。它的位置在 RAG 链路的上游，切块和向量化之前的那道工序。

来历也值得交代。仓库创建于 2024 年 2 月底，背靠 OpenDataLab，这是上海人工智能实验室的数据开源平台。团队手上不止这一个项目，PDF-Extract-Kit 提供 PDF 内容抽取的模型底座，OmniDocBench 是文档解析评测基准，模型本身有三篇 arXiv 论文打底，从 2024 年的 MinerU 技术报告，到 2025 年的 MinerU2.5 解耦视觉语言模型，再到 2026 年的 MinerU2.5-Pro。一个细节，我打开 pyproject.toml 看依赖清单时，keywords 列表里保留着 magic-pdf 这个旧名字，那是项目前身的包名，老用户搜索时还能对上号。

它解决什么问题

大模型直接读 PDF 的体验很多人领教过：双栏论文按行读会把左右栏串起来，表格变成一堆散字，公式彻底乱码，扫描件更惨，连文字层都没有。

传统转换工具只会把文字抠出来，版面结构信息全丢。MinerU 的做法是把版面分析、OCR、公式识别、表格结构还原做成一条流水线，PDF 和图片走四档质量分级解析，Office 和电子书格式由 DocVortex 这个原生解析库兜着，最后统一成一份带结构的内容模型。

四个核心能力

① 四档解析分级。flash 极速解析最快但质量最低，只适合预览和建索引，README 的 Agent Guide 里写明它不能当最终阅读质量；basic 基础解析用 OCR 模型，2GB 内存的 CPU 机器就能跑；standard 标准解析是日常阅读的默认档；advanced 高级解析质量最高也最慢，留给难啃的文档。档位不是让你凭感觉选的，装好后程序会探测硬件，自动开放这台机器能跑的档。

② 十二类输入格式。PDF、常见图片、Word、PPT、Excel、RTF、OpenDocument 三件套、EPUB、OFD、HTML、MHTML 网页存档、CSV 和 TSV。纯文本文件不进流水线，直接读原文。

③ 九种渲染输出。一个文档模型支持 Markdown、HTML、LaTeX、DOCX、EPUB、PDF、结构化内容和两代内容列表，共九种导出目标，每条 CLI 和 API 各自开放其中一部分。

④ 本地文档库。这是 4.0 加进来的大件。解析结果缓存，内容可搜索，支持按页按块续读，引用位置有稳定的 locator 定位符，四段式寻址能精确到某页某块。配套还有目录监听，新文件落进监听目录自动建索引。

拆开一个模块看看

我打开 mineru/model/runtime/tier_recommendation.py 看了档位推荐的实现，这个文件 159 行，注释直接用中文写。核心逻辑在 tiers_for_hardware 函数：有 GPU 就开放全部四档，纯 CPU 的话至少 4 核开放 basic，至少 12 核开放 standard，都不满足就只留 flash。更有意思的是 CalibrationDecision 这个数据类，类注释写着避免把设备可用性当成实测胜出。ONNX 推理配了一套运行时校准机制，校准结果缓存复用，校准不稳定就老实退回 CPU 并记录原因。还有一处注释写着自动推荐不再查询或消费显存容量，字段保留只为 JSON 兼容。看得出来团队在硬件适配上踩过足够多的坑，每条规则背后都有具体教训。

为什么要这样设计

mineru/cli/commands/parse.py 有 515 行，我在里面看到一处为 Agent 专门做的设计。parse 命令默认只解析前 10 页，输出末尾会追加一条 HTML 注释，内容是 Next 冒号加一条完整的续读命令，Agent 拿到输出照抄执行就能读到第 11 页往后，不用自己猜参数。配套的 locator 体系能定位到某一页某一个块，格式是 doc 冒号短 ID、tier、page、block 四级寻址，读过的内容反复引用不会漂移。这套设计解决的是长文档和有限上下文窗口的矛盾，不用一次全读，也不用每次重读。

另一处体现取舍的地方是隐私边界。默认全程本地解析，远程解析必须显式加 --remote 参数，而且 SKILL.md 里写死了本地失败不能静默回落到远程，要上传必须用户点头。对律师、医生、金融这类敏感文档场景，这条规则比性能参数重要得多。

用起来什么样

第一个场景，让 Agent 读一本 300 页的书。发一条 mineru parse book.pdf 加 --json，默认拿回前 10 页的内容加一条续读指令，Agent 判断需要更多上下文就执行输出里给的下一条命令，一段一段接力往下读。全程不用把 300 页塞进上下文窗口，读过的部分靠 locator 随时回查。

第二个场景，把常用文档目录变成可搜索的本地库。mineru watch add 加目录路径，后台自动发现新文件用 flash 档建索引，之后 mineru search 直接搜解析过的内容，搜到之后用 mineru read 按 locator 精读对应页。Python 侧有配套的 DoclibClient，ensure_parse 提交解析任务，轮询状态，read_content 按 locator 取内容，SDK 和命令行是同一套底座。

和同类工具比一比

四组数字均为 2026 年 11 月 7 日同一批次从 GitHub API 采集，marker 仓库已迁移到 datalab-to 名下。

微软的 markitdown 走轻量路线，不跑模型，简单文档转换快，扫描件和复杂版面就吃力；IBM 的 docling 和 marker 都是模型驱动，跟 MinerU 同一赛道。MinerU 的差异化在两处，一是档位分级把硬件门槛拉开了，2GB 内存的机器也有能跑的档，二是 4.0 之后的本地文档库加 Agent 续读协议，同赛道里独一份。open issue 只有 13 个，同等规模项目里这个数字低得反常，docling 是 950，markitdown 是 811，团队关 issue 关得很勤。

协议差异要单独提醒。MinerU 不是纯 Apache 2.0，附加条款写了两个商业门槛：月活超 1 亿，或月总收入超 2000 万美元，满足任一条要先拿商业授权；基于它做在线服务，要在界面或文档里标注使用了 MinerU。个人使用和绝大多数公司都碰不到这条线，但做产品的要提前知道。

怎么装，花多少钱

前置条件只有一条，Python 3.11 到 3.14，官方推荐 3.12 起步。三条命令：

pip install uvuv venv .mineru --python 3.12uv pip install -U "mineru>=4.0,<5"

装完先试一条 mineru-kit parse document.pdf，用 standard 档验证流水线通了，再跑 mineru-kit webui 起图形界面。pyproject.toml 里注册了七个命令行入口，mineru 系管文档库，mineru-kit 系管解析工具，各管一摊。

成本账算清楚。基础包免费开源，不需要任何 API Key。模型下载量 basic 档约 0.8GB，standard 档约 2GB；跑 standard 的 ONNX 路线要 8GB 内存，没有独显也能跑，README 给的数据是开启 GPU 加速后核心推理负载约为 CPU 的 2 到 3 倍速度。有 8GB 显存 N 卡的可以上 full 版走 vLLM 推理，多占约 5GB 磁盘。Windows 用户注意一个坑，full 版需要单独安装 GPU 版 torch，README 明确提示了。遥测默认开启，采集的是命令结果和性能指标这类聚合数据，不含文档内容和文件名，一条 mineru telemetry disable 关掉。

不适合谁

想要重图形界面工作流的不适合，主力是命令行，WebUI 只是附属品。偶尔转两页简单 PDF 的也不必上它，markitdown 三秒钟装完更合适。做在线服务且规模到了月活 1 亿或月收入 2000 万美元的，先去谈商业授权，在线服务还有署名义务。另外纯英文排版简单的文本文档，用不上版面分析这套重装备。

测试结构可以佐证工程质量，tests 目录下有 229 个 Python 测试文件，配合一周八个 release 的节奏，这不是玩票项目在维护。

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

技术报告：arxiv.org/abs/2409.18839（MinerU）

arxiv.org/abs/2509.22186（MinerU2.5）

arxiv.org/abs/2604.04771（MinerU2.5-Pro）

— END —

欢迎关注，后续获得更多 AI 工具分享

--开源开研，拆解每一个值得用的开源项目--