我最近在整理本地论文库和知识库的时候被 PDF 转 Markdown 这个需求反复折磨。正儿八经的 PDF 解析不是把文字抠出来那么简单公式、表格、双栏排版、扫描页任何一个环节出了问题后面接 RAG 也好、做阅读笔记也好都会收到一堆怎么切都不对的内容。后来我从 magic-pdf 一路用到 MinerU 3.4.5算是把这条管线彻底跑顺了。这篇东西没有太多官腔主要记录我自己的真实用法和一些踩坑结论适合想做知识库、RAG 数据清洗、批量把论文电子书转成可编辑 Markdown 的人参考。1. 为什么 PDF 转 Markdown 是刚需而 MinerU 值得学1.1 PDF 的“反数据”本质先说一个经常被误解的事实PDF 是一种“最终呈现格式”不是“数据格式”。PDF 文件里保存的是每个字符放在页面哪个位置、用什么字体、多大字号、哪条线连到哪个框至于“这个段落是标题还是正文”“这一列和下一列什么关系”“这个表格第三行第二列是什么”PDF 本身并不关心。所以你会发现用 PyMuPDF 或 pdfplumber 这类传统工具提取文本单栏的纯文本文件效果还行一旦遇到双栏论文、复杂表格、数学公式、页眉页脚结果就是灾难双栏的左右两栏会穿插成一段公式变成一堆乱码字符表格的单元格东一块西一块。如果 PDF 本身是扫描图片那更是直接无解。我用一个生活化类比来解释PDF 像一张拍好的菜谱照片上面有标题、配料表、步骤图但你想让照片自己告诉你“第几步要放多少盐”它给不了。传统提取工具等于对着照片念上面的字念完还是乱的。MinerU 做的事情更像把照片里的菜单重新输入成一份结构化的文档先识别出照片里哪里是标题、哪里是步骤、哪里是图片再按人眼阅读的顺序整理成 Markdown。1.2 Markdown 才是中间态的正确答案既然 PDF 不能直接用那中间格式选什么我的答案很明确Markdown。原因有三个。第一Markdown 保留了结构信息标题层级、列表、表格、代码块、图片引用都有明确的语法标记喂给大模型做上下文切分时切出来的 chunk 语义更完整不会像纯文本那样在句子中间拦腰斩断。第二Markdown 是人类可读的纯文本你可以直接浏览、修改、批注也可以随时转成 PDF、Word、HTML、Excel。第三Markdown 是生态最通用的格式VS Code、Obsidian、Notion、语雀、GitHub 全部原生支持你解析出来的文档可以无缝进入自己的笔记系统。所以我选定了一个目标PDF 进来Markdown 出去。这个目标听起来简单但要同时处理好版面分析、阅读顺序、公式还原、表格结构化、图片抽取和扫描件 OCR就不是随便一个开源库能做到的事了。1.3 MinerU 到底解决了什么MinerU早期项目名叫 magic-pdf就是冲着这个目标去的。它不是单一模型而是一整套文档解析管线先对 PDF 页面做版面检测把页面拆成标题、正文、表格、图片、公式区域再做阅读顺序排序接着对每个区域做内容识别文本型 PDF 直接抽取文字扫描型 PDF 走 OCR公式区域单独交给公式识别模型输出 LaTeX 语法表格区域单独做表格结构化输出成 Markdown 表格最后统一渲染成 Markdown 和 JSON。这套管线最大的价值是把“杂活”整合成了开箱即用的工具。你不需要自己去拼装检测模型、OCR 模型、公式模型也不用操心模型权重从哪下载、格式怎么统一。而且它支持本地部署模型权重跑在你自己机器上文档内容不用上传到第三方服务这对处理私密资料和内部文档非常重要。1.4 和其他方案的直观对比为了让你更清楚 MinerU 的位置我列一张对比表方案双栏版面数学公式表格还原扫描件 OCR部署方式PyMuPDF / pdfplumber差差差不支持本地库Tesseract 纯 OCR差差差勉强本地商业 PDF 转换器中中中部分支持在线/客户端MinerU / magic-pdf好好好好本地/自托管如果你只是偶尔把一份 PDF 转成 Word商业转换器可能够用但如果你要批量处理大量论文、电子书、扫描合同并且希望结果直接进入自动化流程MinerU 这种开源自托管方案的优势是碾压级的。2. 从 magic-pdf 到 MinerU命名、命令与架构的演变2.1 初识 magic-pdf一切从这条命令开始我最早接触这个项目时它还叫 magic-pdf。那时候安装比较简单粗暴pip install magic-pdf[full]然后命令行工具也叫magic-pdfmagic-pdf -p demo.pdf -o output_dir -m auto当时的体验其实是“能跑但有不少毛糙感”模型要单独下载环境变量要手动配置第一次跑的时候容易在检测模型加载那里卡住。但核心思路已经非常先进了PDF 进入后先做版面检测不是傻乎乎地抽文本。那时候我就觉得这个方向一定会成为 PDF 解析的主流。2.2 版本更迭为什么我停在 3.4.5项目后来统一改为 MinerU 这个品牌版本也从 0.x 一路升到 1.x、2.x、3.x。我实际主力使用的版本落在 3.4.5这个版本在稳定性、模型质量和易用性之间做到了很好的平衡。3.x 系列有几个明显变化安装包从原来的魔法般的一堆依赖变成更清晰的模块划分CLI 命令从magic-pdf切换成mineru输出目录结构更加规范每个 PDF 对应一个同名目录里面有 Markdown、JSON、图片目录对 CPU 的友好度也提升了不少不再强制要求 GPU 才能有可用体验。社区里我也看到 4.0 方向的动作但我对 3.4.5 的熟悉度最高下面的实操经验都以这个版本为主线同时我会标注哪些地方在新版本里可能要调整。2.3 命令迁移对照老用户需要知道的变化如果你之前用的是 magic-pdf 命令切换到 MinerU 后的第一件事就是改命令名。我给一个对照表动作老命令magic-pdf新命令mineru解析单个 PDFmagic-pdf -p input.pdf -o out -m automineru -p input.pdf -o out -m auto带 OCR 强制模式magic-pdf -p input.pdf -o out -m ocrmineru -p input.pdf -o out -m ocr查看帮助magic-pdf --helpmineru --help这个变化的背后是项目品牌重塑不只是换皮底层模型和代码结构也在重构。所以如果你在网上看到老教程注意看命令是magic-pdf还是mineru旧命令可能已经不被新版本支持了。2.4 模型缓存与目录结构的变化另一个老用户容易踩坑的地方是模型缓存目录。老版本把模型权重放在一个固定的本地目录升级之后新版本可能改用了默认的缓存路径如果你没有重新下载模型运行时会一直报加载失败。我的建议是升级后先把旧模型目录备份或者清掉让 MinerU 按新版本逻辑重新下载避免新旧模型文件混在一起。3.4.5 在首次运行时会下载版面检测、公式识别、OCR 等模型文件加起来不小建议用稳定的网络环境或者提前到官方文档确认模型离线放置方式。2.5 内部架构组成不只是“一个库”理解 MinerU 的结构能帮你排查问题时少走弯路。简单拆解就是三层输入层接收 PDF 文件和配置参数负责 PDF 解码、页面拆分成图像或文本流。解析层版面检测模型、阅读顺序模型、OCR 模型、公式识别模型、表格模型按顺序组合成管线。输出层把解析结果渲染成 Markdown、JSON并抽取图片资源。也就是说MinerU 更像一个“文档解析框架”而不是单个模型。你在使用过程中遇到问题首先要判断问题出在输入层、解析层还是输出层再决定是调参数还是换模型。3. 解析管线拆解MinerU 是怎么把 PDF 变成 Markdown 的3.1 从“文本框提取”到“版面理解”传统工具把 PDF 解析当成“按坐标提取文本”MinerU 把它当成“视觉版面理解”。第一步是对每一页做目标检测页面里的标题、正文段落、表格、图片、公式、页眉页脚会被分别框出来。这一步非常关键因为只有先搞清楚“哪里是标题”“哪里是表格”后续的处理才有意义。有个例子我印象很深一份双栏 PDF 论文传统工具会从左栏第 1 行读到右栏第 1 行再折回读出来的文本顺序完全是乱的。MinerU 先检测出栏区域和每个内容块的位置再通过阅读顺序模型把“左栏从上到下、右栏从上到下”的真实顺序排出来最终 Markdown 里段落顺序就和人类阅读体验一致了。3.2 数学公式的 LaTeX 还原论文类 PDF 里最让人头疼的就是数学公式。普通的文本提取会把积分符号、分式、希腊字母拆成乱七八糟的字符而 MinerU 对公式区域做了单独识别输出为 LaTeX 格式。行内公式和块级公式区分得很清楚行内公式嵌入在段落里输出为$...$形式。块级公式独立成段输出为$$...$$形式。这个设计对做学术知识库的人尤其友好因为 LaTeX 格式可以方便地被 Obsidian、Typora、Jupyter 等工具渲染也可以直接喂给大模型做数学运算相关的理解。3.3 表格怎么变成 Markdown 表格PDF 中的表格有各种形态有的有完整框线有的只有横线没有竖线有的是图片型表格。MinerU 的表格结构化模块会把表格区域识别成“行、列、单元格”再输出成标准的 Markdown 表格。实测下来框线清晰、结构规整的表格准确率很高单元格内容基本不会错位。但是遇到复杂表头、合并单元格、跨页表格仍然需要人工检查。如果你后续要“Markdown 表格转换 Excel”这种输出也能直接复制到表格工具或者写脚本转成 CSV效率翻倍。3.4 OCR 与语言模型扫描件是怎么处理的扫描版 PDF 在 MinerU 的-m auto模式下会被自动识别出来然后走 OCR 流程。OCR 模型负责把页面图像里的文字识别成文本公式区域仍然交给公式识别模型表格区域仍然做表格结构化。如果 PDF 是图片型或扫描型OCR 是绕不开的MinerU 的模型对中英文混排的支持不错。这里要提醒一句OCR 毕竟是对图像的识别识别率跟原始扫描件的清晰度、倾斜程度、背景干净度直接相关。扫描件模糊、文字发灰、页面倾斜都会直接影响最终 Markdown 的准确性。所以我在后面专门用一章讲低质量扫描件的预处理。3.5 输出产物不只是 .md 文件MinerU 跑完一个 PDF 后输出目录不只是一个大 .md 文件。以我用的 3.4.5 为例输出结构大致是output/ └── demo/ ├── demo.md ├── demo.json └── images/ ├── img0.jpg ├── img1.png └── table0.jpgdemo.md是渲染好的 Markdown 文件demo.json是结构化数据保留了每个块的坐标、类型、内容、层级关系方便做程序化处理images/目录存放抽取出来的图片和表格原始截图。这种设计对开发者非常友好运营一个 RAG 知识库的人可以直接对着 JSON 做精细切分而不必重新解析 Markdown。4. 环境准备与本地部署CPU、GPU、Docker 三种方式对比4.1 怎么选部署方式先看你的使用场景部署 MinerU 之前先想清楚自己要干什么。我给三种场景的建议部署方式适合场景优点缺点CPU 直装一次性转换、文档量不大环境简单不挑机器大 PDF 慢显存不用想GPU 直装批量处理、追求速度解析快体验最好需要一套带 GPU 的环境Docker服务化、多机器部署环境隔离便于迁移镜像大GPU 透传有点门槛我自己最终采用的是 Docker GPU 方案。原因是我经常要在不同的服务器上跑Docker 把模型的 Python 依赖和系统库封装好迁移起来很省事。如果你只是在自己电脑上偶尔转几份文档CPU 直装就够了不要一上来就折腾 Docker。4.2 pip 安装与 torch 加速技巧CPU 直装流程比较简单pip install mineru装完后先跑一下mineru --help确认命令可用。如果机器上没有装过 PyTorchpip install mineru可能会自动拉取一个比较大的 torch 版本安装时间会比较长。我建议你先单独装 PyTorch再装 mineru这样你可以选择适合自己机器的版本。一个小技巧GPU 机器的 PyTorch 装 CUDA 版CPU 机器装 CPU 版。如果你误装了 GPU 版而机器没有 GPU运行时会报 CUDA 相关错误这时候重装 PyTorch CPU 版就好。4.3 首次运行模型下载与缓存部署完第一件事是跑一个 1 页的测试 PDF。首次运行会自动下载模型权重文件体积不小如果网络环境不好下载失败是常事。3.4.5 在设计上支持模型加载失败时重试但我遇到过的实际问题是下载到一半断掉再跑一次会从缓存里读一个损坏的模型文件导致加载报错。解决办法是如果反复下载失败先把模型缓存目录里对应的文件删掉再重新跑。另外离线环境可以先把模型文件传到目标机器上放到 MinerU 指定的模型目录通过环境变量或配置文件指向它这样就不会每次启动都尝试联网下载。4.4 Docker 部署与挂载参数Docker 部署核心思路是把宿主机的输入目录和输出目录挂载到容器里让容器进程直接读写宿主机的文件。常见的命令格式docker run --rm \ -v /host/input:/input \ -v /host/output:/output \ mineru-image \ mineru -p /input/demo.pdf -o /output -m auto具体镜像名和 tag 要以官方仓库为准我这里主要想表达挂载方式。如果你用的不是最新版本容器内模型路径、工作目录可能有变化先以官方文档命令为准。我踩过的一个坑是挂载目录后容器内没有读取权限表现为“Permission denied”。解决办法是在挂载时加上权限参数或者保证宿主机目录是当前用户可读写的然后以非 root 或指定用户运行容器。你也可以先用docker run --entrypoint bash进入容器手动查看挂载是否正常再跑解析命令。4.5 验证测试跑通第一个 PDF部署完成后我建议不要直接上大文件先找一份 3 到 5 页的 PDF 做验证。观察点有三个是否成功输出 Markdown图片是否抽取完整解析耗时是否符合预期。如果这份小样本在几分钟内产出了结构清晰的 Markdown你的环境就基本没问题了。5. 三种调用形态CLI 命令、Python API、服务化5.1 CLI 命令日常使用的绝对主力日常批量转换我最常用 CLImineru -p ./input/demo.pdf -o ./output -m auto这里的-m auto表示自动判断 PDF 是文本型还是扫描型扫描型自动启用 OCR。如果你想强制对每个 PDF 都走 OCR用-m ocr如果确定是纯文本型 PDF想追求速度用-m txt之类的纯文本模式具体参数名要以mineru --help为准。CLI 的优势是脚本友好可以写个 for 循环批量处理几十个 PDFfor f in ./input/*.pdf; do mineru -p $f -o ./output -m auto done注意输出目录会按 PDF 名建子目录不会互相覆盖。处理完成后你可以直接检查每个子目录里的 .md 文件如果发现某些 PDF 没有被正确处理日志里会有记录。5.2 Python API二次开发的基础当你不满足于命令行想嵌入到自己的业务系统时就要用 Python API。3.4.5 上的用法大致是初始化一个解析器对象然后对 PDF 文件执行解析from mineru import MinerU pipeline MinerU( model_dirmodels/MinerU, devicecuda, # CPU 机器改为 cpu ocrTrue, ) pipeline.parse_pdf(demo.pdf, output_diroutput)不同小版本之间 API 名字和参数可能有微调我建议你在自己环境里先翻一下官方 examples 目录确认初始化方式。这个 API 设计最大的意义是你可以在一个服务进程里复用已经加载好的模型不用每次解析都重新加载省下的时间和内存非常可观。5.3 HTTP 服务化给外部系统提供 PDF 解析能力如果你要给团队或外部系统提供解析能力最好封装一个 HTTP 接口。MinerU 官方仓库里有一些后端服务示例社区也有 Web 界面封装但我在生产环境常用的思路是用 FastAPI 包一层 Python API接收文件路径或上传文件后台解析完成后返回 Markdown 内容和图片路径。大致的伪代码思路from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class ParseRequest(BaseModel): pdf_path: str app.post(/parse) def parse_pdf(req: ParseRequest): result pipeline.parse_pdf(req.pdf_path, output_diroutput) return {status: ok, files: result}服务化的好处是可以把模型常驻在内存里多个请求复用同一套模型减少冷启动时间。坏处是要处理并发问题MinerU 解析任务比较吃内存并发太高容易 OOM。我习惯用队列把解析请求串行化限制同时只有一个任务在跑这样系统最稳定。6. 实战案例一份论文 PDF 到 Markdown 的输出效果与对比6.1 测试样本与参数为了展示真实效果我拿了一份典型的学术论文 PDF 来做测试。样本包含中英文内容、双栏排版、标题层级、引用文字、数学公式、一个数据表格和两张图片。我用的命令是mineru -p paper.pdf -o output -m auto机器是单张消费级 GPU整体解析耗时大约在几十秒量级如果换纯 CPU 可能需要几分钟具体取决于机器性能。6.2 输出效果从“乱码”到“可编辑”解析完成后打开paper.md效果已经非常接近我理想中的样子。标题正确变成了 Markdown 的一级/二级标题摘要和正文按双栏阅读顺序准确排列段落之间没有串行数学公式区域被还原成了$$...$$的 LaTeX 块虽然在原 PDF 里是图片渲染但输出的是可编辑公式表格被转成了标准 Markdown 表格列和行对应关系正确两张图片被抽取到images/目录并在 Markdown 中引用了相对路径。相比我之前用 PyMuPDF 跑出来的结果段落顺序错乱公式变成符号片段表格内容散落成一堆文字。这个差距是体验级的。对大模型知识库来说MinerU 的输出可以直接split成高质量 chunk而传统提取结果还需要大量清洗。6.3 与 PyMuPDF 的详细对比我用一张表总结测试样本上的对比结果维度PyMuPDFMinerU 3.4.5双栏阅读顺序错乱正确标题层级识别无有数学公式字符散乱LaTeX 还原表格结构内容堆砌Markdown 表格图片抽取手动自动扫描件 OCR不支持支持输出 JSON无有6.4 资源占用与速度实测解析速度和资源占用是很多人关心的。我的经验是文本型 PDF 走-m auto会跳过 OCR速度较快扫描型 PDF 需要 OCR耗时显著上升。内存方面模型加载后会占据数个 GB如果同时处理大批 PDF建议设置一定的间隔或分批次处理避免内存峰值过高导致系统卡顿。如果你追求极限速度可以先把 PDF 拆分成多个单页小文件并行处理最后合并结果。这个操作对我来说收益明显但注意并发数量不要超过 CPU/GPU 的内存承载能力。6.5 Markdown 后续处理VSCode 插件与表格转 Excel解析出的 Markdown 我一般先用 VS Code 打开预览。我习惯装的插件有 Markdown All in One提供目录、快捷键和格式化、Markdown Preview Mermaid Support预览 Mermaid 图和表格。处理表格时如果要把 Markdown 表格拷贝到 Excel 使用常见做法是复制到支持表格粘贴的工具中或者写个简单的 Python 脚本把 Markdown 表格转成 CSV再导入 Excel。这个环节虽然简单但实际工作流里非常实用。7. 踩坑与调优低质量扫描件、OCR、公式、表格的处理7.1 扫描件歪斜与发灰先做预处理再交给 MinerU我在热搜词里看到“pdf 歪斜校正纠偏”“漂白加深清晰”这些词说明扫描版 PDF 的处理是普遍痛点。MinerU 的版面检测和 OCR 本身对清晰的扫描件效果不错但低质量扫描件歪斜、发灰、字迹模糊会明显拉低准确率。我的做法是扫描件在进入 MinerU 之前先用图像预处理工具把页面处理一下——校正倾斜、增加对比度、去掉灰色背景、让文字更清晰。MinerU 3.4.5 的管线本质上是视觉模型在干活输入图像越干净识别准确率越高。这就像人要抄写一份字迹潦草的手稿你先帮他把字描清楚他抄得才准。如果你批量处理大量扫描件我建议把预处理和 MinerU 串成一条自动化流程扫描 PDF 转图片、图像增强、再合成清晰 PDF、最后跑 MinerU。虽然多了一步但整体准确率的提升非常值得。7.2 OCR 中文乱码与语言模型问题如果你处理的 PDF 里有中文跑完 OCR 发现中文乱码大概率是语言模型配置问题。MinerU 下载模型时会包含默认的 OCR 语言模型但有些场景需要明确配置。我的建议是在任何新环境里先用一份包含中文和英文的样本 PDF 测试 OCR 输出如果中文不对再检查模型仓库里是否缺少对应语言模型。这类问题很容易在“pdf 图片中文设置”相关的检索中找到答案但最靠谱的方式还是去官方模型仓库看语言模型清单确认你依赖的模型文件是否存在。7.3 公式识别失败怎么办公式识别不是 100% 完美的。常见的失败模式有两种一是公式区域被当成普通图片结果是 Markdown 里插入了一张截图而不是 LaTeX二是公式识别出来了但 LaTeX 语法有误渲染不出理想效果。我的经验是首先尽量用清晰度的原始 PDF不要用二次压缩的版本其次如果你的文档公式密度很高可以考虑在解析参数里对公式模型做专门配置或者后期对公式密集页面做人工抽查。遇到关键公式识别错误手动改 LaTeX 是难免的事但相比从零开始手打公式效率已经高出太多了。另外说一句如果你的知识库场景对公式的语义理解要求很高解析出的 LaTeX 块不要直接当纯文本存储建议保留$$...$$语义结构。这样后续检索时可以把数学语义单独处理不会被普通文本切断。7.4 表格还原的边界MinerU 对框线清晰、结构标准的表格还原能力很强但有三个高频坑合并单元格、跨页表格、无框线表格。合并单元格在 Markdown 表格语法里本身表达能力有限所以输出时会被拆成多个单元格视觉上会失真跨页表格会被拆成多个表格块需要手动合并无框线表格容易被版面检测当成普通段落需要靠 OCR 和人工修正。我的经验是如果你的业务场景必须处理大量复杂表格不要指望一次解析就能完美交付而是要在流程后面加一个人工复核步骤或者用脚本对 JSON 输出里的表格结果做二次修正。7.5 CPU 上的性能调优如果只有 CPU 机器也未必不能跑 MinerU但要管理好预期。我实测下来一份 10 页左右的扫描 PDF 在 CPU 上可能要跑几分钟文本型 PDF 快很多。如果你要在 CPU 上批量处理建议注意三点每次解析任务之间留出缓存清理时间避免内存累积。尽量拆分成单页或小文件并行而不是一个大 PDF 从头跑到尾。模型加载后常驻进程不要每个文件都重新加载模型。7.6 版本升级导致的“作业失踪”问题从老版本升到新版本后最常见的问题就是明明文件还在但命令行找不到命令。这通常是安装包改名后可执行文件名称变了。早期的magic-pdf命令在新版本中被替换成了mineru你输入mineru --version和magic-pdf --version会得到完全不同的结果。另一个常见问题是新版本对 Python 版本有要求。我在一个老服务器上因为 Python 版本偏低安装时报了一堆依赖冲突。如果你也遇到类似情况推荐用虚拟环境或者 Docker 把 MinerU 的 Python 依赖和系统环境隔离开能省掉很多莫名其妙的麻烦。最后说点我自己的流程习惯如果你的目标和我的类似——把零散 PDF 转成结构化 Markdown 再进知识库那我现在的默认流程是先按文档类型分类扫描件先做图像预处理再统一用 MinerU 3.4.5 跑-m auto模式输出后看一眼 JSON 的坐标信息和 Markdown 的表格、公式表现关键页面抽样人工检查最后存入知识库。这套流程跑熟之后处理效率远不是传统“PDF 抽取文本”能比的。不要迷信任何工具开箱即用MinerU 也一样。找一份你自己的真实样本文档反复测几次摸清它在公式、表格、扫描件上的能力和边界比你收藏一百篇教程都管用。