MinerU+PaddleOCR：扫描PDF转Markdown的文档解析实战

最近我被一批扫描版论文折腾得够呛。连着一周几乎每天都有同事丢来一份 PDF说“帮我转成 Markdown我要喂给知识库做检索”。最开始我也天真地以为 PDF 转 Markdown 不就是 OCR 一下嘛真上手才发现问题根本不是“认字”而是“懂版”。就是在这个背景下我把 MinerU 和 PaddleOCR 拼到了一起做了一个还算顺手的智能文档解析管线。先说结论MinerU 擅长版面解析和结构化输出PaddleOCR 擅长中文文字识别和图像预处理。两个一搭配刚好补齐彼此的短板OCR 终于从“能用”走到了“好用”。这篇文章把整个思路、踩坑过程、参数选型和常见问题都摊开讲清楚适合正在做文档解析、知识库建设、RAG 前处理或者单纯被 PDF 结构搞到头秃的开发者和技术爱好者参考。1. 为什么是 MinerU PaddleOCR组合思路拆解1.1 单用 OCR 卡在哪很多项目的起点是“把图片里的字认出来”所以第一反应是上 OCR。可等真正处理起一份完整 PDF你会发现纯 OCR 输出的东西往往没法直接交差。纯 OCR 的典型输出是一堆检测框和识别文本。比如“标题”“正文”“表格里的数字”在结果里全都变成了差不多的文本块原来的层级关系、阅读顺序、段落归属全部丢失。要是文档还有双栏、页眉页脚、浮动图片、表格跨页那基本就是一场灾难。还有一个更常见的问题公式。OCR 模型识别公式符号容易出错就算认出了字符输出也是一行乱码样的文本根本没法在 Markdown 里还原成标准数学公式。这就像一个人认字认得很快但他读不懂版式不知道哪里是标题不知道表格有几列不知道公式从哪里开始到哪里结束。放到文档解析场景里“认字”只是最底层的一步之后还需要做版面分析、阅读顺序重建、结构化表示。除开结构问题单用通用 OCR 处理特殊文档也很吃力。扫描版合同、带水印的工程图纸、有噪声的老书页这些场景下识别率会直线下降。于是你会开始给 OCR 调参数、做图像增强、写一堆后处理规则最后代码量比业务逻辑还多。1.2 MinerU 和 PaddleOCR 各自擅长的活儿MinerU 这个项目我是在社区里偶然注意到的它的定位是智能文档解析输入 PDF输出结构化的 Markdown 或 JSON。它会把文档切分成板块识别出标题、段落、图片、表格、公式这些不同的元素并且尽量保持阅读顺序。也就是说它做的是“读懂版面”这件事。MinerU 的强项在于版面分析比较可靠表格解析有专门的模型公式可以转成 LaTeX输出结果适合直接进知识库或 RAG 管线。我跑过几份排版比较规整的现代论文默认参数下大部分版面都能重建出来段落顺序基本正确表格也不会乱到完全没法修复。PaddleOCR 的强项则是“认字”它对中文场景支持非常友好自带方向分类、文本检测、文本识别三段式管线可以单独调用也可以拆开做定制化预处理。相比 MinerU 内置的 OCR 能力PaddleOCR 在应对低质量图像、模糊背景、混合语言时往往更抗造。而且 PaddleOCR 的模型是模块化设计的。遇到某一步效果不好只需要替换其中一个子模型不用整个重来。这在调优过程中会省下大量时间。1.3 组合的真正价值从“认得字”到“读懂版”现在很多文档解析工具都内置了 OCR为什么还要单独把 PaddleOCR 拿进来凑对我在实际处理中总结了几个场景这几个场景单靠任何一方都搞不定。第一种是低质量扫描件。MinerU 处理清晰、规则的电子版 PDF 很稳可遇到那种复印了好多遍、纸都泛黄的老合同内置识别会明显吃力。这时候先用 PaddleOCR 做图像矫正、去噪、方向分类再把处理过的图像交给 MinerU 做版面解析效果会稳定很多。第二种是复杂表格。MinerU 解析有线表格还可以但是碰到无线表格、有背景色干扰、单元格合并很夸张的情况输出的 Markdown 经常会对不齐。PaddleOCR 生态里有专门的表格结构识别能力先用这部分把单元格坐标和结构找出来再拿这个信息去修正 MinerU 的输出能救回不少。第三种是针对性识别。比如某个业务场景里只关心身份证号、发票编号、合同金额这些关键字段没必要跑完整版面解析直接用 PaddleOCR 检测加识别又快又准。而 MinerU 适合做全局解析两者不是替代关系而是分工关系。所以我把这两个工具拆成两个阶段来用PaddleOCR 管“图像到文本”的质量MinerU 管“文本到结构”的还原。谁擅长哪段就干哪段这比幻想有一个工具能包打天下靠谱得多。2. 环境准备与工具选型2.1 基础环境与安装先说环境。这两套工具都是 Python 生态都依赖深度学习推理框架所以环境隔离是第一课。我强烈建议用独立的虚拟环境别直接往系统 Python 里塞依赖不然某个依赖版本冲突能让你排查一整天。我的基本步骤如下创建虚拟环境。当前这两套工具都对 Python 3.10 及以上支持得比较顺利。安装 MinerU。它依赖的组件比较多包含模型推理、版面分析、公式识别这些模块安装时间会略长耐心等就行。安装 PaddleOCR。这一步会顺带安装深度学习框架如果是 N 卡尽量装对应的 GPU 版本。具体安装命令以两个项目在官方文档里的说明为准因为版本更新很快网上搜到的老命令很可能已经失效。我自己的习惯是新项目开工前先去仓库 README 里看一遍最新的安装方式这个习惯帮我避开了很多坑。有一点特别建议装完以后先跑一遍自带的小测试文件。许多项目下载完模型之后通过一个简单的示例文件验证环境是否通顺能省掉很多“代码报错但不知道是环境问题还是模型问题”的排查时间。我见过有人跳过这个步骤最后折腾了两天才发现是依赖没装完整。2.2 模型与参数怎么选模型选型这块说白了就是考虑“精度、速度、资源占用”三个维度。PaddleOCR 这边方向上分检测模型、方向分类模型、识别模型。对于大多数中文文档场景我会优先选中文识别模型并打开方向分类。如果文档以印刷体为主默认的通用模型就能跑如果涉及手写或者很特殊的字体才需要考虑微调或者找专项模型。另外PaddleOCR 的推理参数里有一个阈值控制检测框的敏感度。阈值设太低可能会识别出很多无关噪声设太高又会漏掉浅色文字。我一般在 0.3 到 0.5 之间去试先跑几页看效果再定而不是拿着一个万能参数用到底。MinerU 侧部署时有 CPU 和 GPU 的选择。我自己主要在 GPU 上跑因为公式识别和版面模型都比较吃算力CPU 跑一份几十页的文档要等很久。如果是偶尔处理少量文件CPU 也能接受但要批量处理GPU 基本是必备的。批处理规模也需要考虑。有的朋友喜欢一次性丢几百份 PDF 进去跑这会遇到显存不够、进程卡死、输出文件互相覆盖等各种问题。更稳的做法是分批处理比如每批 20 份左右跑完一批检查输出再跑下一批。贪多嚼不烂在文档解析这件事上体验特别明显。3. 实操过程把一份扫描版 PDF 变成结构化 Markdown3.1 第一轮跑通用默认参数“先看结果”我不会在一开始就追求参数最优而是选择先用默认参数把整份 PDF 跑通输出一份结果来看看整体状态。比如拿到一份几十页的扫描版论文我大概会这样做把 PDF 每一页拆成清晰的图像注意输出分辨率不要压得太低同时避免翻拍照片那种带角度和阴影的情况。用 MinerU 的默认配置跑一遍版面解析生成初步的 Markdown 文件。把 Markdown 和原始 PDF 放在一起逐段检查标题、正文、图表、公式的位置和顺序。这一步的重要目标不是调好效果而是看清“烂在哪”。比如有的页面整体识别效果不错但表格崩了有的页面图片被错误识别成了表格还有的公式下标全部丢失。把这些现象记录下来后面才有针对性的调优方向。我在第一次跑的时候典型情况是主体段落识别得不错但目录页、公式多的页面以及跨页表格非常难看。目录页的页码会被当成正文内容公式里复杂的根号和分式变成了一堆没法看的符号跨页表格干脆被拆成了两个独立表格。这个阶段不必焦虑能做到心里有数就很好了。3.2 低质量扫描件用 PaddleOCR 做预处理和补齐如果发现前面的输出里很多文字识别错了、漏了尤其集中在扫描质量差的页面上我就会把 PaddleOCR 拉进来做图像预处理和二次识别。我的常见流程是对问题页面单独用 PaddleOCR 做方向分类先把旋转纠正过来。这个步骤看起来基础但实际很救命。扫描件经常出现轻微倾斜或 90 度旋转方向不对后续一切解析都白搭。方向纠正之后再做必要的图像增强。我是基于页面效果手动判断太暗就提亮度太糊就做锐化背景有大量黑点就做降噪。这里有个技巧图像增强别过度。有些同事一上来就搞高反差、强锐化结果文字边缘出现严重白边识别率反而下降。适度永远好过用力过猛。如果某些页面的文字已经被噪声严重破坏默认 OCR 已经救不回来我会改用 PaddleOCR 对整页做全量识别拿到带坐标的文本块再手动标注出哪些文本属于标题、正文、表格、页眉页脚。说白了就是用人的判断力补一步“版面规则”这种页面让模型从零猜到对实在太为难它了。补齐之后我会把这份带有坐标信息的文本结果作为辅助数据结合 MinerU 的版面输出一起生成最终的 Markdown。实际操作中这种“轻重结合”的思路比单纯换一个大模型可靠得多。3.3 表格与公式场景的处理与调优表格和公式是文档解析里公认的两座大山。我单独把它们拎出来说是因为它们最能体现“从能用走向好用”的差别。先说表格。MinerU 对格式规整的表格表现不错但对无线表格、复杂合并单元格以及跨页表格容易出错。我的处理思路分三步先用 MinerU 把页面整体结构跑出来定位到表格所在区域。遇到结构崩坏的表格单独把这块区域截出来交给表格结构识别模型拿到单元格坐标和行列关系。最后根据单元格坐标把文本按行列重组手动生成符合 Markdown 语法的表格。这个流程看起来麻烦实际只对少数难搞的表格走完整流程大部分简单表格交给 MinerU 一步到位能省下很多工作量。另外表格识别结果里经常出现空格错位的问题我每次生成完都要用脚本检查一下每行的竖线数量是否一致这能快速定位被截断的表格。公式这边的情况更微妙。MinerU 支持公式转 LaTeX但长公式、复杂矩阵、多层嵌套的分式仍然会出问题。我自己总结的检查点主要有三个一是上下标是否正确二是根号和分式的边界是否完整三是多行公式的对齐符号有没有乱。还有一个小坑有些公式被误识别成图片或者图片被误识别成公式。这会让最终 Markdown 里多出一堆奇怪的图片引用或者公式块。遇到这种情况我会调整版面解析时的阈值让分类更保守一些宁可把不确定的内容标成图片也不要硬生成错误公式毕竟图片还能人工确认但错公式几乎没法自动修复。4. 常见问题与排查技巧实录4.1 表格错位、合并单元格丢失表格问题是最容易出现的也是我处理数量最多的。症状表现包括表格被拆成上下两张表、列数和行数对不上、合并单元格的内容只出现在其中一个格子里。我的排查步骤是先确认原始 PDF 里的表格是否有完整边框。无线表格和有边框表格的处理逻辑完全不同模型在两种场景下的表现差异也很大。检查表格上方和下方是否有多余的文本块有时候标题和表格被识别成一个大区域导致结构混乱。单独对表格区域截图再识别一次。如果第二次识别仍然错就手动重建不要试图靠调参解决所有问题。实际操作中我发现跨页表格是最难自动处理的对象之一。模型通常会把上下两页的同一张表当成两个不同表格后续合并时要靠人工判断。我的经验是在喂给模型之前先把跨页表格按相同内容拼接成一张长图再交给识别模型效果比分别识别好得多。还有一点表格内文本如果包含多行Markdown 里没有直接的换行机制。我通常会把单元格内的换行转换成br这样既能在渲染时保持效果又不会破坏表格结构。4.2 公式乱码与上下标问题公式识别错误往往是“看着像一回事复制出来全是车祸现场”。比如x^2变成了x2分式a/b变成了ab根号直接丢失。另一个极端是公式里混入了大量空格和奇怪转义符号。我通常的做法是把所有公式从 Markdown 里单独提取出来逐个渲染成图片再和原文档对照。这一步虽然费时但比在代码里盯字符串直观得多。优先修复上下标。上下标可以通过 LaTeX 的^和_重新标注不能靠模型自动完成的就手动改。根号和分式检查边界。这类问题不能只靠眼睛看还是得逐个渲染确认。我试过用后处理正则去自动修正但在公式领域正则基本只能处理一些固定的缺失模式。公式一复杂自动化的收益就很低不值得浪费时间。所以我的习惯是公式特别多的文档直接降低预期重点保证正文和表格正确公式部分保留待人工校对。4.3 中文标点和引号被吃很多人容易忽略的一个问题OCR 识别英文引号和中文引号经常混淆中文的省略号、破折号也经常被拆成多个点或短线。这类问题不会导致解析失败但会让最终文本显得很廉价进知识库之后检索效果也受影响。解决这个问题的关键不在模型而在后处理。我会准备一份常见字符映射表把识别结果里常见的中英文标点做统一替换。比如把半角逗号与全角逗号按上下文修正把连续的句点合并成中文省略号把破折号识别成--的情况还原成中文破折号。这里提醒一句后处理规则不能写太猛。有些规则会把合法的英文标点也改掉尤其是涉及时差、日期、代码片段的内容。我的策略是先只改那些在文档语境里几乎不可能合法出现的组合再人工检查一小部分样例确定规则不会误伤。4.4 性能优化大批量文档怎么跑当你要处理的文档从几份变成几百份性能问题就会浮出水面。我遇到过三个主要瓶颈显存不足、CPU 空转、磁盘 IO 卡顿。显存不足最直接的解决方法是缩小批大小。深度学习模型一次性吃太多图像会爆显存我一般把批大小调小到能稳定跑完一批。还有一种做法是分页处理把长文档按页面切开处理完再合并结果。这个方法看起来笨但稳定性极高。CPU 空转通常出现在预处理阶段。有些库默认会使用所有 CPU 核但并不代表越快越好因为多进程会带来额外的调度开销。我习惯手动限制进程数先设为物理核心数的一半观察实际吞吐再根据资源占用调整。磁盘 IO 被很多人忽视。文件解析过程中会读写大量临时图片和中间结果如果硬盘负载太高速度会被拖得很明显。我把临时目录放到专门的 SSD 分区上结果整体处理速度快了不少。这种细节平时没人提但批量处理时经常成为隐藏瓶颈。5. 我的几点体会与后续会怎么用折腾完这个组合之后我最大的感受是没有银弹只有合适的分工。MinerU 帮我解决“版面结构还原”PaddleOCR 帮我兜住“低质量图像上的文字识别”。它们配合起来比任何一方单打独斗都稳。我现在处理新文档的流程基本固定先跑一遍 MinerU 默认产出再按页面难度分档普通页面直接用结果问题页面交给 PaddleOCR 预处理和二次识别表格和公式单独检查最后统一做一次后处理清洗。这套流程跑熟之后一份几十页的扫描版论文能在一个小时内出可用的 Markdown这在以前是我不敢想的。再分享一个后期的小建议解析结果不要直接当成最终答案尽量保留原始 PDF 和中间图片。出问题的时候能溯源、能对比比反复调参数有用得多。文档解析本质上是个工程问题耐心、可复现、良好的人工兜底机制比堆叠更强大的模型更能决定交付质量。这套方案后续我还会继续扩展比如把 PaddleOCR 的微调能力用起来针对特定印刷体做专项优化或者把 MinerU 的输出 JSON 直接对接知识库的自动清洗流程。OCR 这条线从“能用”到“好用”绝不是换个更贵的模型那么简单而是把工程细节一点点磨到位。希望这篇记录能对你有所帮助少走我走过的弯路。