硅基铁匠丙午年 · 独立刊物
← 返回全部文章
技术与 AI约 9 分钟

PDF 直接丢给 AI？先用 MinerU 拆成 Markdown

MinerU 能把 PDF、图片和 Office 新格式拆成 Markdown、JSON 与图片。这里给出在线试用、CPU 和 GPU 本地教程，也核对 4 倍 Token、节省 80% 等热门说法。

把一份几十页的 PDF 直接扔给 AI，方便是方便，账单和效果却不太好控制。扫描页要做视觉识别，双栏、表格、公式和图片也会增加处理难度。等模型回答错了，使用者还很难判断问题出在理解阶段，还是 PDF 一开始就解析坏了。

最近流传着两个很抓眼的数字：直接上传 PDF 会多花 4 倍 Token，先转 Markdown 能省 80% 。这两个比例没有出现在 MinerU 仓库、文档或 Release 里，也不适用于所有模型。 PDF 、图片和纯文本的计费方式各不相同，省多少只能拿自己的文件实测。

思路本身成立。先把文档拆成可检查的 Markdown 、 JSON 和图片，再交给 AI 做摘要、问答或 RAG，输入内容更透明，错误也容易定位。

MinerU 就是这条链路里的文档解析器。项目目前有约 7.6 万 GitHub Star，稳定版是 3.4.4，可以处理 PDF 、常见图片，以及 DOCX、PPTX、XLSX。旧版 DOC、PPT、XLS 不在当前公开支持列表里。

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

MinerU 会产出什么

MinerU 不只抽一份纯文本。一次解析可以得到：

  • 多模态 Markdown，保留标题层级、图片引用、表格和公式结果；
  • content_list.json 等结构化文件，方便后续分块和索引；
  • images/ 目录，保存提取或裁剪出的图片；
  • layout.pdf 与 span.pdf，用来检查版面区域和识别范围；
  • 中间结果 JSON，方便排错或二次开发。

上图及后面的演示关键帧来自项目 README 。它们能证明官方提供了这套工作流，不能当作本机独立实测。

“保留排版”也要说准。 Markdown 无法无损复制 PDF 的字体、坐标、页边距和视觉版式。 MinerU 做的是结构化提取：识别阅读顺序、标题、段落、表格、公式和图片，再用 Markdown 与 JSON 表达这些关系。

金额、日期、脚注、公式和复杂表格仍要人工抽查。整页空白很容易发现，负号、百分号或表格单元格悄悄错位更容易混进知识库。

三条解析路线怎么选

稳定版提供 pipeline、vlm-engine 和 hybrid-engine 等后端。

Pipeline：普通电脑先走这条

Pipeline 使用布局、 OCR 、公式与表格等专用组件，再做阅读顺序和段落整理。它可以纯 CPU 运行，兼容面较广，适合第一次验证安装和输出结构。

纯 CPU 能跑不代表很快。几十页扫描件仍可能占用大量内存和时间，但它省去了 NVIDIA 显卡门槛。

VLM：让视觉模型统一解析

VLM 后端使用 MinerU2.5-Pro-2605-1.2B 。 Linux 走 vLLM，Windows 使用 LMDeploy，Apple Silicon 使用 MLX 。维护者给出的最低显存是 8GB，本地运行还需要至少 16GB 内存和约 20GB 磁盘空间。

Hybrid：稳定版默认路线

Hybrid 把原生 PDF 文本、 Pipeline 的布局/OCR/公式能力和 VLM 组合起来。默认 effort=medium，会关闭完整的图片分析；需要分析图表内容时再切到 high，显存和耗时也会增加。

这张流程图来自项目仓库，适合帮助理解模块分工。 MinerU 更新很快，稳定版 3.4.4 之外已经出现 v4.0.0a4 预发布。 Alpha 版本改动了后端和依赖，当前教程只使用 3.4.4 命令，避免把两条版本线混在一起。

第一次使用，在线试一个非敏感文件

官方提供网站、 ModelScope 和 Hugging Face Space 。找一份公开论文、产品手册或自己生成的测试 PDF，先看四个结果：

  1. 双栏阅读顺序有没有串；
  2. 表格行列是否对齐；
  3. 公式、脚注和小字有没有丢；
  4. 图片是否被正确提取并放回对应段落。

在线入口可能排队，也可能有文件大小、页数或频率限制。项目没有承诺“网页无限使用”。合同、身份证、内部报告和客户资料不要拿去测试公共演示站，在线服务的数据保留规则无法从开源代码推断。

没有显卡，先跑 CPU 版

Python 支持 3.10 至 3.13 。 Windows 受 Ray 依赖影响，官方矩阵只列到 3.12 。这里选 Python 3.11，兼容性更省心。

在独立目录创建环境，并锁定稳定版：

mkdir mineru-test && cd mineru-test
uv venv --python 3.11
source .venv/bin/activate

uv pip install "mineru[pipeline]==3.4.4" \
  -i https://mirrors.aliyun.com/pypi/simple

Windows PowerShell 激活命令改成：

.venv\Scripts\Activate.ps1

准备一份 sample.pdf，执行：

mineru -p sample.pdf -o output -b pipeline

先跑一两页。-s 和 -e 的页码从 0 开始，例如只测第一页：

mineru -p sample.pdf -o output -b pipeline -s 0 -e 0

输出目录会按文件名和后端继续分层。打开 Markdown 看内容，再对照 layout.pdf。页面看起来很漂亮不代表结构一定正确，质检文件能直接暴露标题框、表格区域和阅读顺序是否跑偏。

模型会在首次运行时下载。3.4.4 的代码默认使用 auto：先探测 Hugging Face，可达就使用 HF，否则切到 ModelScope，并把实际模型目录记录到 ~/mineru.json。

国内网络可以提前指定：

export MINERU_MODEL_SOURCE=modelscope
mineru-models-download -s modelscope -m pipeline

下载完成后，需要离线运行时设置：

export MINERU_MODEL_SOURCE=local
mineru -p sample.pdf -o output -b pipeline

离线前先断网实测一次，确认模型和配置已经缓存完整。首次安装会联网下载依赖、模型和配置模板，“本地部署”从模型准备完成后才算成立。

有 8GB 以上显存，再试默认 Hybrid

Linux 、 Windows 和 Apple Silicon 的推理引擎不同，完整安装包会根据平台选择依赖：

uv pip install "mineru[all]==3.4.4" \
  -i https://mirrors.aliyun.com/pypi/simple

默认命令会使用 Hybrid：

mineru -p sample.pdf -o output

中国网络可以先下载全部模型：

mineru-models-download -s modelscope -m all

维护者给出的硬件下限是 8GB 显存、 16GB 内存和 20GB 磁盘，建议内存为 32GB 。高分辨率扫描件、长 PDF 和 effort=high 会继续增加资源消耗。安装前还要确认显卡驱动、 CUDA 和 PyTorch 版本，别在已有生产 Python 环境里直接升级整套依赖。

想给团队用，服务先绑本机

MinerU 自带 FastAPI 与 Gradio 入口。程序默认绑定 127.0.0.1，没有内置账号体系。单机试用保持回环地址：

mineru-api --host 127.0.0.1 --port 8000
mineru-gradio --server-name 127.0.0.1 --server-port 7860

API 文档位于：

http://127.0.0.1:8000/docs

提交一个异步任务：

curl -X POST http://127.0.0.1:8000/tasks \
  -F "files=@sample.pdf" \
  -F "return_md=true"

上传文件会保存到 ./output/<任务ID>/uploads/，结果也放在同一任务目录。完成或失败的任务默认保留 24 小时后清理，进程重启和多进程部署时，内存里的任务状态不保证继续可查。

把服务改成 0.0.0.0 后，同网段设备就能访问。准备给团队使用时，需要在前面补反向代理、 TLS 、登录认证、上传大小限制和访问日志，同时明确文件保留与删除规则。不要把无认证的解析接口直接暴露到公网。

HTTP Client 后端还会把推理数据发送到指定的 OpenAI-compatible 服务；启用 LLM 辅助配置也会调用第三方模型。选择这些模式时，文档不再完全留在本机。

4 倍 Token 和省 80%，怎么自己测

准备三份有代表性的文件：一份原生文字 PDF 、一份扫描件、一份带复杂表格和公式的报告。对每份文件做两组输入：

  • A 组：把 PDF 直接交给当前使用的模型；
  • B 组：先用 MinerU 转成 Markdown，再把 Markdown 与必要图片交给模型。

两组使用同一模型、同一问题和同一输出长度限制。记录输入 Token 、图片计费、总费用、响应时间和答案准确性。还要把 MinerU 的解析时间、 GPU 成本与人工校对算进去。

文本型 PDF 往往容易省下视觉处理，复杂图表却可能仍要把图片一并交给模型。少传图片能省费用，也可能让回答丢失信息。最后保留哪种输入，应该看任务准确率和总成本，不要套用一个固定百分比。

开源使用还有两条许可边界

当前代码使用 MinerU Open Source License，基础是 Apache 2.0，并附加了商业条款。用户及关联方合并统计的月活超过 1 亿，或月总收入超过 2000 万美元，需要另取商业许可。

基于 MinerU 向第三方提供在线服务，还要在界面或公开文档中显著标明使用 MinerU 。模型和第三方依赖各有自己的许可证，商业部署不能只检查主仓的 LICENSE.md。

MinerU 很适合放在 AI 、 Agent 和知识库前面，承担文档清洗与结构恢复。它无法替代结果验收。合同金额、财报数字、论文公式和跨页表格进入检索库前，仍然需要抽样核对。

如果每月要给 AI 处理几百份 PDF，你最想先优化哪一项：Token 费用、表格准确率，还是敏感文件不出内网？

来源：https://github.com/opendatalab/MinerU