开头如果你经常和 PDF 打交道应该会有这种感觉PDF 这玩意儿天生就不是给人读的。它的排版逻辑是这一块内容放在这一页的这个位置而不是这段话是一级标题这段话是正文这个区域是表格。所以想把 PDF 里的内容提出来重新利用——不管是喂给大模型做知识库还是转成 Markdown 存进笔记系统第一关永远是解析。MinerU 这个开源项目就是专门解决这个问题的。它把 PDF 转 Markdown 这件事儿做到了开箱即用的程度底层用深度学习模型做版面分析、公式识别、表格重建最终输出结构干净的 Markdown 文件。我最早接触它的时候还叫 magic-pdf后来项目改名 MinerU版本迭代到 3.x功能和稳定性跟早期版本已经完全是两个量级了。这篇文章我会从项目背景讲起手把手带你把 MinerU 部署起来跑通 PDF 转 Markdown 的完整流程然后把我在实际使用中踩过的坑、排查过的问题、优化过的参数全部整理出来。不管你是想给本地知识库准备语料还是想把纸质书变成电子笔记这篇指南应该都能帮上忙。项目开源地址在 GitHub 上搜 MinerU 就能找到文档也写得比较全建议配合官方文档一起看。1. MinerU 是什么为什么 PDF 解析这么难1.1 从 magic-pdf 到 MinerU项目的前世今生MinerU 前身是 magic-pdf早期版本用 Python 实现定位是PDF 魔法解析器核心思路是把 PDF 里的内容分层抽取再用规则加模型的方式还原文档结构。那时候的功能已经比传统的 pdfplumber、PyMuPDF 这类工具强不少至少能识别标题、正文、表格这些基本结构但面对复杂的双栏排版、带公式的论文、扫描版书籍还是会翻车。后来项目改名 MinerU做了几件比较大的事。第一是把底层模型全面升级版面检测、公式识别、表格结构还原都换成了更强大的深度学习模型第二是重新设计了输出流程强调结构化三个字输出的 Markdown 不只是文本堆叠而是尽量还原文档的逻辑层级第三是提供了完整的本地部署方案支持 CPU 和 GPU 两种模式还开放了 API 接口。从 magic-pdf 到版本迭代最直观的感受是早期版本处理一篇普通的论文有时候会出现段落错乱、表格被拆散的问题而 3.x 版本在这方面的表现已经相当稳定了。我实测下来对于排版规整的 PDF转换结果基本可以直接用。1.2 PDF 解析的常见痛点和 MinerU 的核心思路为什么 PDF 解析这么难我用一个通俗的类比来解释。PDF 文件里存储的是一堆绘制指令——把这段文字放在这里、这条线画在那里、这个图片插入到某个位置。文件格式本身并不包含这是一个标题这是一个表格这样的语义信息。PDF 解析要做的事情就是从这些绘制指令中推算出原本的文档结构相当于看一张渲染好的成品图然后把它的 HTML 源码还原出来。传统解析工具的做法是基于规则的比如根据字体大小判断标题、根据位置坐标判断段落这种方法在简单的文档上有效但一旦遇到复杂的排版——双栏、图文混排、公式、嵌套表格、页眉页脚——规则就失灵了。MinerU 的核心理战是用深度模型来做版面分析先把整页图片输入模型模型会输出每个区域的位置和类型正文、标题、表格、图片、公式等然后针对不同类型的区域用不同的模型做细粒度识别。公式用专门的公式识别模型转成 LaTeX表格用表格结构还原模型重建 Markdown 表格图片则提取出来单独保存并生成引用路径。这就是版面分析→区域识别→结构还原的三层流水线每一层各司其职也是它比传统工具效果好那么多的根本原因。2. 本地部署实战从安装到跑通第一个任务2.1 环境准备与安装方式选择MinerU 的部署方式有三种pip 直接安装、Docker 容器化部署、源码运行。对于大多数用户我建议直接用 pip 安装简单省事依赖关系由包管理器自动处理。如果你之前用过 conda也可以建一个独立环境避免和系统里其他 Python 包冲突。先交代一下我自己的环境方便你对照。我的测试机器是一台 Ubuntu 20.04 的服务器CPU 是 Intel Xeon内存 32G没有独立显卡所以走的是 CPU 推理路线。另外还有一台 Windows 电脑RTX 3060 显卡做了 GPU 测试。两条路都走得通但体验差别很大后面细说。安装命令很简单# 建一个干净的 Python 环境推荐 3.10 或 3.11 conda create -n mineru python3.11 -y conda activate mineru # 安装 MinerU pip install mineru安装过程中会自动拉取很多依赖包括 PyTorch、transformers、opencv 这些重量级库。第一次安装可能比较慢耐心等就行。如果你只有 CPU建议安装 CPU 版的 PyTorch体积小很多启动也快pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu2.2 模型下载与初始化MinerU 的架构是代码 模型分离的安装完代码之后还需要下载模型权重。这一步是新手最容易卡住的地方因为模型文件比较大而且默认从 Hugging Face 下载网络不好的话很容易失败。初始化命令是mineru-cli --download-models它会自动下载所有需要的模型文件放在~/.cache/mineru目录下。如果你发现下载速度很慢或者一直失败可以设置镜像源用 Hugging Face 的国内镜像export HF_ENDPOINThttps://hf-mirror.com这个镜像站的速度要快很多。下载完成后你会看到模型目录里有版面分析模型、公式识别模型、表格结构模型等几个子目录。整个模型包加起来有几个 G磁盘空间要预留好。如果你用的是 3.4.5 版本模型管理方式有一些变化支持通过配置文件指定模型源。打开配置文件看一眼里面会列出各个模型的下载地址你可以手动下载然后放到对应路径。这个机制对于内网部署特别有用——可以在有网的机器上把模型下载好再拷贝到无网环境。2.3 CPU 模式下跑通第一个解析任务模型准备好之后先拿一份简单的 PDF 试试手。命令行用法很直观mineru-cli -p input.pdf -o output_dir-p指定输入 PDF 文件-o指定输出目录。CPU 机器上跑第一次会比较慢因为要加载所有模型到内存。我这边测试一份 10 页左右的 PDF纯 CPU 模式大约需要 3 到 5 分钟具体时间取决于页面复杂度。执行完之后输出目录里会生成一个.md文件还有一个images文件夹里面是 PDF 中提取出来的图片。打开 Markdown 文件你会看到标题、段落、列表都被还原成了对应的语法结构图片被替换成了相对路径引用。如果你的机器没有 GPU又觉得 CPU 太慢还有一个思路先用--device cpu参数明确指定设备然后适当调低模型的精度。比如在配置里开启--model-dtype float32以外的选项虽然会损失一点精度但速度能提上来不少。后面我专门讲参数调优的时候再展开。2.4 API 服务方式给其他项目提供解析能力MinerU 3.x 提供了本地 API 服务模式这是很多做知识库项目的同学特别关心的功能。启动方式很简单mineru-cli --server --host 0.0.0.0 --port 8080启动后服务会监听 8080 端口你可以通过 HTTP 请求上传 PDF 并获取解析结果。请求格式大概是这样的import requests url http://localhost:8080/file_parse files {file: open(test.pdf, rb)} resp requests.post(url, filesfiles) data resp.json()返回的 JSON 里包含了 Markdown 文本、图片列表、解析耗时等信息。这个接口对开发非常友好——你不需要在业务代码里直接调用 MinerU 的命令行而是把它当做一个独立的解析服务来使用可以用 Docker 单独部署一台解析服务器业务系统通过网络来调它。我在实际项目里就是这么干的一台 GPU 服务器专门跑 MinerU 服务其他应用通过 API 提交 PDF 任务解析完成之后回调通知。这样可以做到解析能力的独立扩展和复用。3. 核心功能实操PDF 转 Markdown 的完整流程3.1 命令行深度使用常用参数全解读跑通第一个任务之后我们来深入了解命令行参数。MinerU 的命令行参数很多但核心的就那几个我先列一个我常用的参数组合mineru-cli -p input.pdf -o output_dir \ --device cpu \ --lang zh \ --formula \ --table \ --batch 1参数含义逐个解释--device指定推理设备可选cpu或cuda不设的话会自动检测。--lang文档语言zh表示中文en表示英文auto是自动检测。这里特别重要——如果你解析的文档是中文的但没指定zhOCR 模型和语言模型可能选错效果会差很多。--formula启用公式识别。默认情况下 MinerU 不会把所有公式都转成 LaTeX加了这个参数之后会启用专门的公式模型。--table启用表格识别和重建。如果你的 PDF 里有大量表格这个参数必须开。--batch批量推理的批次大小。CPU 模式下建议设 1GPU 模式可以设 4 或 8提速明显。还有两个我经常用的高级参数--output-format3.x 版本支持输出不同格式默认是 Markdown未来还支持其他格式。保持默认就行。--save-images控制是否提取并保存 PDF 里的图片。如果你只需要纯文本内容可以关掉这个选项加速解析且减少磁盘占用。3.2 公式识别LaTeX 转换的原理与效果公式识别是 MinerU 的一大亮点。我们看学术论文的时候里面密密麻麻的数学公式如果用传统 OCR 工具提取出来的基本上是一堆乱码。MinerU 的做法是用专门的公式识别模型基于图像到序列的深度学习架构把公式图片直接映射成 LaTeX 源码。实际测试一个简单的例子。假设 PDF 里有一个公式$$\int_0^1 x^2 dx \frac{1}{3}$$MinerU 转成 Markdown 后是$ \int_0^1 x^2 dx \frac{1}{3} $完美嵌入 Markdown 的数学语法。对于复杂的多行公式、矩阵、分段函数MinerU 也有不错的还原度。我记得刚上手的时候拿了一篇经典论文测试里面有几十个复杂公式包括大括号分段、连乘符号、上下标嵌套MinerU 识别出来的 LaTeX 可以直接在 Typora 里渲染成和原版几乎一致的公式。这个效果让我挺意外的比我之前用过的任何工具都好。不过公式识别偶尔也会出错特别是在模糊的扫描件上。识别错误通常表现为缺符号或括号不匹配建议解析完成后用支持 LaTeX 渲染的编辑器快速过一遍公式部分。不要盲目信任模型输出。3.3 表格识别从像素到 Markdown 表格表格重建是另一个技术难点。PDF 里的表格呈现方式千奇百怪——有线框表、无线框表、跨页表、合并单元格表、图片型表格。MinerU 的表格识别模型会先检测表格区域然后识别表格的行列结构最后把每个单元格的内容提取出来组成 Markdown 表格。我实测了几种常见情况有线框的规整表格基本能无损还原包括表头、对齐、合并单元格。无线框表格还原效果取决于表格的排版是否规整如果行列对不齐偶尔会出现单元格错位的现象。跨页表格MinerU 会把跨页表格拆分成两个表格而不是合并成一个。这个逻辑可以理解——它在逐页分析跨页的上下文关联本来就是难点。图片型表格扫描件里的表格需要开启 OCR 功能识别速度会慢一些但准确率也在可以接受的范围内。表格还原这类问题我的建议是重要表格宁可自己手动核验一遍也不要直接拿模型输出当最终结果。毕竟表格里的数据可能直接进数据库或被程序读取一个小数点错位都会造成严重后果。3.4 OCR 扫描版 PDF 的处理经验扫描版 PDF 是解析界的老大难。这类 PDF 本质上是图片集合根本没有文本层任何解析工具拿到手里都是纯盲区。MinerU 内置了 OCR 识别能力遇到这种 PDF 会自动调用 OCR 引擎识别文字内容。使用方法就是在命令行里加--ocr参数。开启后处理流程会多一步先把 PDF 页面转成图片然后对图片做 OCR 文字识别识别结果再进入版面分析流程。这里有个细节要注意MinerU 的 OCR 是基于 PaddleOCR 的支持中文、英文以及中英混合场景。用--lang zh参数指定中文之后OCR 的中文识别准确率会明显提升。我自己扫描过一本繁体竖排的老书虽然识别效果没法跟人工录入比但已经把大部分内容还原出来可以搜索了。OCR 模式最耗性能CPU 上速度会慢很多。如果你要批量处理扫描版 PDF我强烈建议上 GPU体验差别非常大。CPU 跑一页扫描件可能要半分钟GPU 上可能就两三秒。3.5 输出目录结构解析解析完成后的输出目录有这么几个东西output_dir/ ├── input.md ├── images/ │ ├── 1.jpg │ ├── 2.png │ └── ... └── input_meta.jsoninput.md是最终结果images目录存放从 PDF 中抽取的图片input_meta.json里包含了页面数量、模型版本、解析时间等元信息。图片文件的引用路径是相对路径在 Markdown 里写作这样的形式。你把整个输出目录拷贝到别处只要结构不变Markdown 里的图片就能正常显示。如果你想把图片上传到图床或者把 Markdown 导入到笔记软件需要自己处理图片路径的替换。我写过一个简单的脚本遍历 Markdown 里所有图片引用自动上传图床并替换链接这样导入语雀或 Notion 就很方便了。4. 常见报错与排查技巧实录4.1 模型下载失败与网络问题这是个高频问题报错信息通常是Connection error或者Model not found。原因基本就是网络访问 Hugging Face 不稳定。解决方式在前面也提过设置HF_ENDPOINT环境变量用镜像源。另外还有一个思路手动去模型仓库把所有文件下载下来放到~/.cache/mineru下面对应的目录里再用离线模式跑。这个方案在服务器部署场景下非常实用尤其是那种只有内网环境的机器直接用移动硬盘拷模型文件过去就行。4.2 CPU 推理速度太慢怎么提速如果你没有 GPU处理大文档时 CPU 推理速度确实会让人着急。我的经验是一定要用--batch 1虽然批次为 1 看起来最慢但实际上它避免了内存频繁交换反而稳定。能用float32就用float32有些模型默认是float32但如果你用半精度float16反而可能让 CPU 变慢需要支持 AVX512 的 CPU 才有优势。打开OMP_NUM_THREADS环境变量把它设置成 CPU 核心数的一半左右有时候比默认全部核心更快——因为太高的线程数会导致上下文切换开销。export OMP_NUM_THREADS8先用小文件测试参数确认没问题再跑大批量不然一个晚上都在处理一个错误配置的任务很心累。4.3 中文乱码与字号识别不准偶尔会出现中文内容被识别成乱码的情况。首先确认有没有指定--lang zh如果没有模型可能选中了英文语言模型中文识别必然不行。其次如果 PDF 本身字体嵌入有问题比如一些老式 PDF 没有嵌入字体解析出来的文本会出现方块字或者空格。这种情况不是 MinerU 能解决的建议先用专业 PDF 工具比如 Acrobat 的 OCR 功能预处理一下。还有一类问题是中英文混排时中文识别成英文。这种情况下可以对比一下原文档如果中文占比明显更高就指定--lang zh如果英文学术文献里夹杂少量中文名字默认自动检测可能更好。这东西没有万能解得按实际文档来。4.4 升级版本带来的兼容性问题从 magic-pdf 升级到 MinerU 3.x或者从 3.0 升级到 3.4.5有几个兼容性变化值得注意命令行入口从magic-pdf变成了mineru-cli老命令直接失效。模型缓存目录变了升级后第一次运行需要重新下载模型或者手动把旧目录里的模型移动过去。配置文件格式有调整如果你用了自定义配置升级后需要按照新格式修改。如果你有正在跑的生产环境升级前一定要先在测试环境验证一遍确认输出结果没有明显变化再切过去。格式解析这类工具版本的微小变化可能导致输出 Markdown 结构出现差异盲目升级容易把原本正常的流程搞挂。4.5 表格乱、图片丢失、段落错乱等解析质量排查表格重建出现单元格错位时尝试调整--table相关参数或者检查原 PDF 是否是有线框表格无线框表格的还原难度本来就高适当降低预期。图片没有被提取大概率是图片在 PDF 里被嵌入到了矢量图形中不是独立的位图这种情况需要看原文档的结构。段落错乱通常发生在复杂的多栏排版或图文混排场景MinerU 会尝试做阅读顺序还原但复杂版面偶尔也会判断失误。一个常用的绕过方法先用 LibreOffice 或 Acrobat 把 PDF 转成 Word再重新导出规整的 PDF然后再交给 MinerU 解析有时候反而效果更好。5. 应用场景与进阶玩法5.1 知识库构建把 PDF 变成 RAG 的优质语料MinerU 出现之后RAG检索增强生成的文档处理环节一下子顺畅了很多。之前做本地知识库最头疼的就是文档预处理——PDF 里的内容提不出来检索效果就无从谈起。现在流程变成了MinerU 解析 PDF → MarkdownMarkdown 按标题切分成 chunk嵌入模型向量化存入向量数据库如 Milvus、Chroma 或 Elasticsearch这个流程比直接把 PDF 塞给解析库再切割成固定长度文本的效果好太多了。原因在于 MinerU 输出的 Markdown 保留了文档结构按标题切分出来的 chunk 在语义上是完整的检索命中率自然更高。我用这套方案给一个企业的内部知识库做过文档预处理几百份 PDF 产品手册、技术文档解析成功率在 90% 以上剩下的 10% 主要是扫描质量太差的老资料人工处理一下也能用。5.2 论文阅读与笔记系统联动对科研党来说MinerU 最实用的场景是把论文批量转成 Markdown导入到 Obsidian、Logseq 等笔记软件里。这样做的好处是论文里的公式可以作为 LaTeX 源码可编辑表格可以修改引用可以链接所有内容都可以被全局搜索。我的工作流是这样的下载论文 PDF 到/papers/目录写一个循环脚本批量调用 MinerU 解析每个 PDF 生成一个以论文标题命名的 Markdown 文件图片存在同名的资源文件夹手动过一遍解析结果修正明显的公式或表格错误在 Obsidian 里做阅读笔记可以直接引用原文段落配合双链记录自己的想法这套流程让我读论文的效率提升了一个档次。之前用 PDF 阅读器的时候笔记都是零散的现在所有笔记、原文、公式都在一个库里搜索、回溯都很方便。5.3 批量文档转换的编排技巧批量处理大量 PDF 时有几个工程细节值得注意。第一是要做失败重试和结果校验——批量处理中总有一两个文件会失败或结果异常脚本里要捕获异常并记录失败日志。第二是控制并发——如果你用的是多卡的 GPU 服务器并发解析可以大幅提升吞吐量但要注意显存分配避免 OOM。第三是做好断点续跑——解析到一半断了最好能从断点继续而不是全部重新跑。我写过一个简单的 Shell 脚本for pdf in /data/pdfs/*.pdf; do name$(basename $pdf .pdf) out/data/output/$name if [ -f $out/$name.md ]; then echo 跳过已处理: $name continue fi mineru-cli -p $pdf -o $out --device cuda --batch 8 --lang zh done这个脚本的核心逻辑是如果输出目录里已经有了 Markdown 文件就跳过当前 PDF实现断点续跑。批处理任务跑挂了重启不会白白浪费之前的时间。批量解析的过程中我还习惯把每次解析的日志重定向到文件方便事后排查。如果中途遇到权限问题或者路径带空格的情况记得给路径加引号避免出现肉眼很难发现的 bug。5.4 与其他文档解析工具的对比心得我试用过不少 PDF 解析工具包括开源的 pdfplumber、PyMuPDF、tabula以及商业的 Adobe Acrobat、ABBYY 等和 MinerU 横向对比下来各有优劣。传统开源工具擅长的是规则解析处理规整的文档纯文本、有明确的行列位置效率很高但遇到扫描件和复杂版面就束手无策。商业 OCR 工具强在识别精度尤其是扫描件、手写体但价格不便宜而且输出的是 Word 或纯文本结构化程度不高不适合直接作为知识库的语料。MinerU 的特点在于 知识文档 这个目标非常明确它不是在泛泛地做文字识别而是在努力理解文档结构输出带语义的 Markdown。所以如果你的核心诉求是构建知识库、建设语料库、做文档结构化MinerU 应该是最顺手的选择。它在学术文献、技术文档、产品手册这类规整电子 PDF 上的表现尤其优秀。什么情况它不适合美术排版极强的画册、杂志或者复杂的手写笔记扫描件这类内容对版面理解要求极高而且可复用的价值本身也不高不建议拿 MinerU 硬磕。版本迭代观察从 3.x 到未来的方向MinerU 的版本迭代速度是比较快的。我用的 3.4.5 版本在模型精度和推理速度上已经比早期版本好太多。从一个长期使用者的角度观察这个项目有几个变化趋势值得关注第一项目的定位越来越聚焦文档解析这个垂直场景而不是什么都做。它在版面分析、公式识别、表格还原这些点上的深耕已经形成一个完整的能力矩阵。第二半正式接口和 API 服务越来越成熟说明项目在支持多人协作、团队使用、生产环境部署这些方向上下了不少功夫。第三模型训练数据在持续增加特别是中文学术论文和书籍的样本量在扩大中文文档的解析效果提升明显。从行业角度看大模型时代文档的结构化解析是数据工程很基础也很关键的一环。不管是大模型训练的数据清洗还是 RAG 场景下的文档处理都需要先把非结构化数据变成结构化数据MinerU 正好卡在这个生态位上。它的价值不是替代 OCR而是成为一个连接 PDF 和大模型之间的桥梁。我个人比较期待的方向有两个一是希望它能进一步优化跨页表格的合并逻辑这是当前最大的使用痛点二是希望未来的版本能支持更多输出格式比如 docx 或 reStructuredText这样能覆盖更多使用场景。当然对于开源项目来说这些功能的推进速度取决于社区的需求和贡献需要大家多去提 issue 和 PR。最后再分享一个我在实际使用中的小技巧如果你用 MinerU 解析中文 PDF在做完转换后建议用脚本做一次质量抽检随机抽取 10% 的页面人工核对标题层级是否合理、表格是否对齐、公式是否完整。解析工具不可能保证 100% 准确有一个抽检的习惯你会对自己的数据质量有更清醒的认知页面级的抽查成本也很低但能帮你及时发现模型在处理某种版面时的系统性偏差比如某个固定的表格样式总是识别错误。提前发现就能提前在后续的知识库构建或发布流程里做好补救。
MinerU实战：开源PDF解析工具，轻松转为结构化Markdown
开头如果你经常和 PDF 打交道应该会有这种感觉PDF 这玩意儿天生就不是给人读的。它的排版逻辑是这一块内容放在这一页的这个位置而不是这段话是一级标题这段话是正文这个区域是表格。所以想把 PDF 里的内容提出来重新利用——不管是喂给大模型做知识库还是转成 Markdown 存进笔记系统第一关永远是解析。MinerU 这个开源项目就是专门解决这个问题的。它把 PDF 转 Markdown 这件事儿做到了开箱即用的程度底层用深度学习模型做版面分析、公式识别、表格重建最终输出结构干净的 Markdown 文件。我最早接触它的时候还叫 magic-pdf后来项目改名 MinerU版本迭代到 3.x功能和稳定性跟早期版本已经完全是两个量级了。这篇文章我会从项目背景讲起手把手带你把 MinerU 部署起来跑通 PDF 转 Markdown 的完整流程然后把我在实际使用中踩过的坑、排查过的问题、优化过的参数全部整理出来。不管你是想给本地知识库准备语料还是想把纸质书变成电子笔记这篇指南应该都能帮上忙。项目开源地址在 GitHub 上搜 MinerU 就能找到文档也写得比较全建议配合官方文档一起看。1. MinerU 是什么为什么 PDF 解析这么难1.1 从 magic-pdf 到 MinerU项目的前世今生MinerU 前身是 magic-pdf早期版本用 Python 实现定位是PDF 魔法解析器核心思路是把 PDF 里的内容分层抽取再用规则加模型的方式还原文档结构。那时候的功能已经比传统的 pdfplumber、PyMuPDF 这类工具强不少至少能识别标题、正文、表格这些基本结构但面对复杂的双栏排版、带公式的论文、扫描版书籍还是会翻车。后来项目改名 MinerU做了几件比较大的事。第一是把底层模型全面升级版面检测、公式识别、表格结构还原都换成了更强大的深度学习模型第二是重新设计了输出流程强调结构化三个字输出的 Markdown 不只是文本堆叠而是尽量还原文档的逻辑层级第三是提供了完整的本地部署方案支持 CPU 和 GPU 两种模式还开放了 API 接口。从 magic-pdf 到版本迭代最直观的感受是早期版本处理一篇普通的论文有时候会出现段落错乱、表格被拆散的问题而 3.x 版本在这方面的表现已经相当稳定了。我实测下来对于排版规整的 PDF转换结果基本可以直接用。1.2 PDF 解析的常见痛点和 MinerU 的核心思路为什么 PDF 解析这么难我用一个通俗的类比来解释。PDF 文件里存储的是一堆绘制指令——把这段文字放在这里、这条线画在那里、这个图片插入到某个位置。文件格式本身并不包含这是一个标题这是一个表格这样的语义信息。PDF 解析要做的事情就是从这些绘制指令中推算出原本的文档结构相当于看一张渲染好的成品图然后把它的 HTML 源码还原出来。传统解析工具的做法是基于规则的比如根据字体大小判断标题、根据位置坐标判断段落这种方法在简单的文档上有效但一旦遇到复杂的排版——双栏、图文混排、公式、嵌套表格、页眉页脚——规则就失灵了。MinerU 的核心理战是用深度模型来做版面分析先把整页图片输入模型模型会输出每个区域的位置和类型正文、标题、表格、图片、公式等然后针对不同类型的区域用不同的模型做细粒度识别。公式用专门的公式识别模型转成 LaTeX表格用表格结构还原模型重建 Markdown 表格图片则提取出来单独保存并生成引用路径。这就是版面分析→区域识别→结构还原的三层流水线每一层各司其职也是它比传统工具效果好那么多的根本原因。2. 本地部署实战从安装到跑通第一个任务2.1 环境准备与安装方式选择MinerU 的部署方式有三种pip 直接安装、Docker 容器化部署、源码运行。对于大多数用户我建议直接用 pip 安装简单省事依赖关系由包管理器自动处理。如果你之前用过 conda也可以建一个独立环境避免和系统里其他 Python 包冲突。先交代一下我自己的环境方便你对照。我的测试机器是一台 Ubuntu 20.04 的服务器CPU 是 Intel Xeon内存 32G没有独立显卡所以走的是 CPU 推理路线。另外还有一台 Windows 电脑RTX 3060 显卡做了 GPU 测试。两条路都走得通但体验差别很大后面细说。安装命令很简单# 建一个干净的 Python 环境推荐 3.10 或 3.11 conda create -n mineru python3.11 -y conda activate mineru # 安装 MinerU pip install mineru安装过程中会自动拉取很多依赖包括 PyTorch、transformers、opencv 这些重量级库。第一次安装可能比较慢耐心等就行。如果你只有 CPU建议安装 CPU 版的 PyTorch体积小很多启动也快pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu2.2 模型下载与初始化MinerU 的架构是代码 模型分离的安装完代码之后还需要下载模型权重。这一步是新手最容易卡住的地方因为模型文件比较大而且默认从 Hugging Face 下载网络不好的话很容易失败。初始化命令是mineru-cli --download-models它会自动下载所有需要的模型文件放在~/.cache/mineru目录下。如果你发现下载速度很慢或者一直失败可以设置镜像源用 Hugging Face 的国内镜像export HF_ENDPOINThttps://hf-mirror.com这个镜像站的速度要快很多。下载完成后你会看到模型目录里有版面分析模型、公式识别模型、表格结构模型等几个子目录。整个模型包加起来有几个 G磁盘空间要预留好。如果你用的是 3.4.5 版本模型管理方式有一些变化支持通过配置文件指定模型源。打开配置文件看一眼里面会列出各个模型的下载地址你可以手动下载然后放到对应路径。这个机制对于内网部署特别有用——可以在有网的机器上把模型下载好再拷贝到无网环境。2.3 CPU 模式下跑通第一个解析任务模型准备好之后先拿一份简单的 PDF 试试手。命令行用法很直观mineru-cli -p input.pdf -o output_dir-p指定输入 PDF 文件-o指定输出目录。CPU 机器上跑第一次会比较慢因为要加载所有模型到内存。我这边测试一份 10 页左右的 PDF纯 CPU 模式大约需要 3 到 5 分钟具体时间取决于页面复杂度。执行完之后输出目录里会生成一个.md文件还有一个images文件夹里面是 PDF 中提取出来的图片。打开 Markdown 文件你会看到标题、段落、列表都被还原成了对应的语法结构图片被替换成了相对路径引用。如果你的机器没有 GPU又觉得 CPU 太慢还有一个思路先用--device cpu参数明确指定设备然后适当调低模型的精度。比如在配置里开启--model-dtype float32以外的选项虽然会损失一点精度但速度能提上来不少。后面我专门讲参数调优的时候再展开。2.4 API 服务方式给其他项目提供解析能力MinerU 3.x 提供了本地 API 服务模式这是很多做知识库项目的同学特别关心的功能。启动方式很简单mineru-cli --server --host 0.0.0.0 --port 8080启动后服务会监听 8080 端口你可以通过 HTTP 请求上传 PDF 并获取解析结果。请求格式大概是这样的import requests url http://localhost:8080/file_parse files {file: open(test.pdf, rb)} resp requests.post(url, filesfiles) data resp.json()返回的 JSON 里包含了 Markdown 文本、图片列表、解析耗时等信息。这个接口对开发非常友好——你不需要在业务代码里直接调用 MinerU 的命令行而是把它当做一个独立的解析服务来使用可以用 Docker 单独部署一台解析服务器业务系统通过网络来调它。我在实际项目里就是这么干的一台 GPU 服务器专门跑 MinerU 服务其他应用通过 API 提交 PDF 任务解析完成之后回调通知。这样可以做到解析能力的独立扩展和复用。3. 核心功能实操PDF 转 Markdown 的完整流程3.1 命令行深度使用常用参数全解读跑通第一个任务之后我们来深入了解命令行参数。MinerU 的命令行参数很多但核心的就那几个我先列一个我常用的参数组合mineru-cli -p input.pdf -o output_dir \ --device cpu \ --lang zh \ --formula \ --table \ --batch 1参数含义逐个解释--device指定推理设备可选cpu或cuda不设的话会自动检测。--lang文档语言zh表示中文en表示英文auto是自动检测。这里特别重要——如果你解析的文档是中文的但没指定zhOCR 模型和语言模型可能选错效果会差很多。--formula启用公式识别。默认情况下 MinerU 不会把所有公式都转成 LaTeX加了这个参数之后会启用专门的公式模型。--table启用表格识别和重建。如果你的 PDF 里有大量表格这个参数必须开。--batch批量推理的批次大小。CPU 模式下建议设 1GPU 模式可以设 4 或 8提速明显。还有两个我经常用的高级参数--output-format3.x 版本支持输出不同格式默认是 Markdown未来还支持其他格式。保持默认就行。--save-images控制是否提取并保存 PDF 里的图片。如果你只需要纯文本内容可以关掉这个选项加速解析且减少磁盘占用。3.2 公式识别LaTeX 转换的原理与效果公式识别是 MinerU 的一大亮点。我们看学术论文的时候里面密密麻麻的数学公式如果用传统 OCR 工具提取出来的基本上是一堆乱码。MinerU 的做法是用专门的公式识别模型基于图像到序列的深度学习架构把公式图片直接映射成 LaTeX 源码。实际测试一个简单的例子。假设 PDF 里有一个公式$$\int_0^1 x^2 dx \frac{1}{3}$$MinerU 转成 Markdown 后是$ \int_0^1 x^2 dx \frac{1}{3} $完美嵌入 Markdown 的数学语法。对于复杂的多行公式、矩阵、分段函数MinerU 也有不错的还原度。我记得刚上手的时候拿了一篇经典论文测试里面有几十个复杂公式包括大括号分段、连乘符号、上下标嵌套MinerU 识别出来的 LaTeX 可以直接在 Typora 里渲染成和原版几乎一致的公式。这个效果让我挺意外的比我之前用过的任何工具都好。不过公式识别偶尔也会出错特别是在模糊的扫描件上。识别错误通常表现为缺符号或括号不匹配建议解析完成后用支持 LaTeX 渲染的编辑器快速过一遍公式部分。不要盲目信任模型输出。3.3 表格识别从像素到 Markdown 表格表格重建是另一个技术难点。PDF 里的表格呈现方式千奇百怪——有线框表、无线框表、跨页表、合并单元格表、图片型表格。MinerU 的表格识别模型会先检测表格区域然后识别表格的行列结构最后把每个单元格的内容提取出来组成 Markdown 表格。我实测了几种常见情况有线框的规整表格基本能无损还原包括表头、对齐、合并单元格。无线框表格还原效果取决于表格的排版是否规整如果行列对不齐偶尔会出现单元格错位的现象。跨页表格MinerU 会把跨页表格拆分成两个表格而不是合并成一个。这个逻辑可以理解——它在逐页分析跨页的上下文关联本来就是难点。图片型表格扫描件里的表格需要开启 OCR 功能识别速度会慢一些但准确率也在可以接受的范围内。表格还原这类问题我的建议是重要表格宁可自己手动核验一遍也不要直接拿模型输出当最终结果。毕竟表格里的数据可能直接进数据库或被程序读取一个小数点错位都会造成严重后果。3.4 OCR 扫描版 PDF 的处理经验扫描版 PDF 是解析界的老大难。这类 PDF 本质上是图片集合根本没有文本层任何解析工具拿到手里都是纯盲区。MinerU 内置了 OCR 识别能力遇到这种 PDF 会自动调用 OCR 引擎识别文字内容。使用方法就是在命令行里加--ocr参数。开启后处理流程会多一步先把 PDF 页面转成图片然后对图片做 OCR 文字识别识别结果再进入版面分析流程。这里有个细节要注意MinerU 的 OCR 是基于 PaddleOCR 的支持中文、英文以及中英混合场景。用--lang zh参数指定中文之后OCR 的中文识别准确率会明显提升。我自己扫描过一本繁体竖排的老书虽然识别效果没法跟人工录入比但已经把大部分内容还原出来可以搜索了。OCR 模式最耗性能CPU 上速度会慢很多。如果你要批量处理扫描版 PDF我强烈建议上 GPU体验差别非常大。CPU 跑一页扫描件可能要半分钟GPU 上可能就两三秒。3.5 输出目录结构解析解析完成后的输出目录有这么几个东西output_dir/ ├── input.md ├── images/ │ ├── 1.jpg │ ├── 2.png │ └── ... └── input_meta.jsoninput.md是最终结果images目录存放从 PDF 中抽取的图片input_meta.json里包含了页面数量、模型版本、解析时间等元信息。图片文件的引用路径是相对路径在 Markdown 里写作这样的形式。你把整个输出目录拷贝到别处只要结构不变Markdown 里的图片就能正常显示。如果你想把图片上传到图床或者把 Markdown 导入到笔记软件需要自己处理图片路径的替换。我写过一个简单的脚本遍历 Markdown 里所有图片引用自动上传图床并替换链接这样导入语雀或 Notion 就很方便了。4. 常见报错与排查技巧实录4.1 模型下载失败与网络问题这是个高频问题报错信息通常是Connection error或者Model not found。原因基本就是网络访问 Hugging Face 不稳定。解决方式在前面也提过设置HF_ENDPOINT环境变量用镜像源。另外还有一个思路手动去模型仓库把所有文件下载下来放到~/.cache/mineru下面对应的目录里再用离线模式跑。这个方案在服务器部署场景下非常实用尤其是那种只有内网环境的机器直接用移动硬盘拷模型文件过去就行。4.2 CPU 推理速度太慢怎么提速如果你没有 GPU处理大文档时 CPU 推理速度确实会让人着急。我的经验是一定要用--batch 1虽然批次为 1 看起来最慢但实际上它避免了内存频繁交换反而稳定。能用float32就用float32有些模型默认是float32但如果你用半精度float16反而可能让 CPU 变慢需要支持 AVX512 的 CPU 才有优势。打开OMP_NUM_THREADS环境变量把它设置成 CPU 核心数的一半左右有时候比默认全部核心更快——因为太高的线程数会导致上下文切换开销。export OMP_NUM_THREADS8先用小文件测试参数确认没问题再跑大批量不然一个晚上都在处理一个错误配置的任务很心累。4.3 中文乱码与字号识别不准偶尔会出现中文内容被识别成乱码的情况。首先确认有没有指定--lang zh如果没有模型可能选中了英文语言模型中文识别必然不行。其次如果 PDF 本身字体嵌入有问题比如一些老式 PDF 没有嵌入字体解析出来的文本会出现方块字或者空格。这种情况不是 MinerU 能解决的建议先用专业 PDF 工具比如 Acrobat 的 OCR 功能预处理一下。还有一类问题是中英文混排时中文识别成英文。这种情况下可以对比一下原文档如果中文占比明显更高就指定--lang zh如果英文学术文献里夹杂少量中文名字默认自动检测可能更好。这东西没有万能解得按实际文档来。4.4 升级版本带来的兼容性问题从 magic-pdf 升级到 MinerU 3.x或者从 3.0 升级到 3.4.5有几个兼容性变化值得注意命令行入口从magic-pdf变成了mineru-cli老命令直接失效。模型缓存目录变了升级后第一次运行需要重新下载模型或者手动把旧目录里的模型移动过去。配置文件格式有调整如果你用了自定义配置升级后需要按照新格式修改。如果你有正在跑的生产环境升级前一定要先在测试环境验证一遍确认输出结果没有明显变化再切过去。格式解析这类工具版本的微小变化可能导致输出 Markdown 结构出现差异盲目升级容易把原本正常的流程搞挂。4.5 表格乱、图片丢失、段落错乱等解析质量排查表格重建出现单元格错位时尝试调整--table相关参数或者检查原 PDF 是否是有线框表格无线框表格的还原难度本来就高适当降低预期。图片没有被提取大概率是图片在 PDF 里被嵌入到了矢量图形中不是独立的位图这种情况需要看原文档的结构。段落错乱通常发生在复杂的多栏排版或图文混排场景MinerU 会尝试做阅读顺序还原但复杂版面偶尔也会判断失误。一个常用的绕过方法先用 LibreOffice 或 Acrobat 把 PDF 转成 Word再重新导出规整的 PDF然后再交给 MinerU 解析有时候反而效果更好。5. 应用场景与进阶玩法5.1 知识库构建把 PDF 变成 RAG 的优质语料MinerU 出现之后RAG检索增强生成的文档处理环节一下子顺畅了很多。之前做本地知识库最头疼的就是文档预处理——PDF 里的内容提不出来检索效果就无从谈起。现在流程变成了MinerU 解析 PDF → MarkdownMarkdown 按标题切分成 chunk嵌入模型向量化存入向量数据库如 Milvus、Chroma 或 Elasticsearch这个流程比直接把 PDF 塞给解析库再切割成固定长度文本的效果好太多了。原因在于 MinerU 输出的 Markdown 保留了文档结构按标题切分出来的 chunk 在语义上是完整的检索命中率自然更高。我用这套方案给一个企业的内部知识库做过文档预处理几百份 PDF 产品手册、技术文档解析成功率在 90% 以上剩下的 10% 主要是扫描质量太差的老资料人工处理一下也能用。5.2 论文阅读与笔记系统联动对科研党来说MinerU 最实用的场景是把论文批量转成 Markdown导入到 Obsidian、Logseq 等笔记软件里。这样做的好处是论文里的公式可以作为 LaTeX 源码可编辑表格可以修改引用可以链接所有内容都可以被全局搜索。我的工作流是这样的下载论文 PDF 到/papers/目录写一个循环脚本批量调用 MinerU 解析每个 PDF 生成一个以论文标题命名的 Markdown 文件图片存在同名的资源文件夹手动过一遍解析结果修正明显的公式或表格错误在 Obsidian 里做阅读笔记可以直接引用原文段落配合双链记录自己的想法这套流程让我读论文的效率提升了一个档次。之前用 PDF 阅读器的时候笔记都是零散的现在所有笔记、原文、公式都在一个库里搜索、回溯都很方便。5.3 批量文档转换的编排技巧批量处理大量 PDF 时有几个工程细节值得注意。第一是要做失败重试和结果校验——批量处理中总有一两个文件会失败或结果异常脚本里要捕获异常并记录失败日志。第二是控制并发——如果你用的是多卡的 GPU 服务器并发解析可以大幅提升吞吐量但要注意显存分配避免 OOM。第三是做好断点续跑——解析到一半断了最好能从断点继续而不是全部重新跑。我写过一个简单的 Shell 脚本for pdf in /data/pdfs/*.pdf; do name$(basename $pdf .pdf) out/data/output/$name if [ -f $out/$name.md ]; then echo 跳过已处理: $name continue fi mineru-cli -p $pdf -o $out --device cuda --batch 8 --lang zh done这个脚本的核心逻辑是如果输出目录里已经有了 Markdown 文件就跳过当前 PDF实现断点续跑。批处理任务跑挂了重启不会白白浪费之前的时间。批量解析的过程中我还习惯把每次解析的日志重定向到文件方便事后排查。如果中途遇到权限问题或者路径带空格的情况记得给路径加引号避免出现肉眼很难发现的 bug。5.4 与其他文档解析工具的对比心得我试用过不少 PDF 解析工具包括开源的 pdfplumber、PyMuPDF、tabula以及商业的 Adobe Acrobat、ABBYY 等和 MinerU 横向对比下来各有优劣。传统开源工具擅长的是规则解析处理规整的文档纯文本、有明确的行列位置效率很高但遇到扫描件和复杂版面就束手无策。商业 OCR 工具强在识别精度尤其是扫描件、手写体但价格不便宜而且输出的是 Word 或纯文本结构化程度不高不适合直接作为知识库的语料。MinerU 的特点在于 知识文档 这个目标非常明确它不是在泛泛地做文字识别而是在努力理解文档结构输出带语义的 Markdown。所以如果你的核心诉求是构建知识库、建设语料库、做文档结构化MinerU 应该是最顺手的选择。它在学术文献、技术文档、产品手册这类规整电子 PDF 上的表现尤其优秀。什么情况它不适合美术排版极强的画册、杂志或者复杂的手写笔记扫描件这类内容对版面理解要求极高而且可复用的价值本身也不高不建议拿 MinerU 硬磕。版本迭代观察从 3.x 到未来的方向MinerU 的版本迭代速度是比较快的。我用的 3.4.5 版本在模型精度和推理速度上已经比早期版本好太多。从一个长期使用者的角度观察这个项目有几个变化趋势值得关注第一项目的定位越来越聚焦文档解析这个垂直场景而不是什么都做。它在版面分析、公式识别、表格还原这些点上的深耕已经形成一个完整的能力矩阵。第二半正式接口和 API 服务越来越成熟说明项目在支持多人协作、团队使用、生产环境部署这些方向上下了不少功夫。第三模型训练数据在持续增加特别是中文学术论文和书籍的样本量在扩大中文文档的解析效果提升明显。从行业角度看大模型时代文档的结构化解析是数据工程很基础也很关键的一环。不管是大模型训练的数据清洗还是 RAG 场景下的文档处理都需要先把非结构化数据变成结构化数据MinerU 正好卡在这个生态位上。它的价值不是替代 OCR而是成为一个连接 PDF 和大模型之间的桥梁。我个人比较期待的方向有两个一是希望它能进一步优化跨页表格的合并逻辑这是当前最大的使用痛点二是希望未来的版本能支持更多输出格式比如 docx 或 reStructuredText这样能覆盖更多使用场景。当然对于开源项目来说这些功能的推进速度取决于社区的需求和贡献需要大家多去提 issue 和 PR。最后再分享一个我在实际使用中的小技巧如果你用 MinerU 解析中文 PDF在做完转换后建议用脚本做一次质量抽检随机抽取 10% 的页面人工核对标题层级是否合理、表格是否对齐、公式是否完整。解析工具不可能保证 100% 准确有一个抽检的习惯你会对自己的数据质量有更清醒的认知页面级的抽查成本也很低但能帮你及时发现模型在处理某种版面时的系统性偏差比如某个固定的表格样式总是识别错误。提前发现就能提前在后续的知识库构建或发布流程里做好补救。
