最近在做一个企业知识库类的RAG项目客户丢过来一堆扫描版PDF和排版复杂的Word文档市面上叫得上名字的智能文档处理框架我基本试了一圈。跑完几套常见的文本提取工具说实话有点崩溃——表格结构直接丢了数学公式变成乱码双栏论文读起来前言不搭后语。后来在社区里频繁看到MinerU和Docling两个名字一个被称作PDF解析利器一个被当成文档转换全家桶但不少人总把它们摆在一起比来比去。这篇博文就把我对这两个框架的理解、实测情况、选型思路和落地部署经验完整写下来尤其会重点覆盖MinerU在Windows 11 CPU环境下的本地部署和OpenAPI模式实战供正在做文档解析选型的朋友参考。1. 为什么要把MinerU和Docling放在一张桌子上对比1.1 传统解析方案的三类痛点做文档解析这个方向的人大概率都经历过这几个老问题。第一类是纯文本层提取的局限。PDF文件看起来是一个整体但里面其实分成两类一类有真实的文本层可以用pdfplumber、PyPDF2这类库直接抽取文字另一类是扫描件或纯图片型PDF压根没有文本层你用任何文本提取工具拿到的都是空字符串。就算是有文本层的PDF遇到双栏排版、多级标题、页眉页脚混排的时候提取出来的文字顺序经常是错乱的上一段还在正文下一段忽然跳到页脚根本没法直接用。第二类是OCR方案“认字不认版”。扫描件必须走OCRTesseract这类老牌OCR可以识别出文字但识别结果是一堆纯文本标题层级、表格线、公式结构、阅读顺序这些信息全部丢失。你拿到的是一大段连续字符串想要恢复成结构化的Markdown或JSON还得自己写一堆后处理逻辑而且每次遇到新的版面格式都要重新调规则非常痛苦。第三类是格式转换工具割裂。做DOCX、PPTX、HTML、PDF转换的时候通常一个格式对应一个库一个转换链对应一套输出规范。今天处理PDF用一套代码明天处理PPTX又要换另一套下游系统接收到的数据结构五花八门清洗和适配成本远大于解析本身。这三类痛点叠加起来导致“文档解析”成了RAG知识库项目里最脏最累的活。很多团队花了大把时间不是在调模型而是在跟各种格式的“意外情况”搏斗。1.2 两种解法两个出发点MinerU和Docling正是在这种背景下出现的但它们解决问题的出发点完全不同。MinerU的核心目标是把PDF文件高质量地转换为结构化的Markdown和JSON。它把版面检测、公式识别、表格还原、阅读顺序排列串成一套完整流水线尤其擅长处理扫描版PDF和含数学公式的学术论文。本质上MinerU更像一个“PDF专用精加工车间”只做一件事但把这件事做得很深。Docling是IBM开源的项目目标比MinerU宽得多。它要把PDF、DOCX、PPTX、XLSX、HTML、图片等各类文档统一转换成一种名为DoclingDocument的结构化数据模型再从这个模型导出Markdown、JSON、HTML等格式。Docling的思路是“不管入口是什么格式出口都给你同一套结构”相当于文档处理领域的“通用翻译中间层”。这两者定位不同但在实际项目里经常被放到一起比较因为很多人只是想找个工具把文档转成干净的Markdown喂给RAG并不关心底层设计哲学。所以下面几章我会先分别拆解两个框架的技术链路再做实测对比最后给出部署和选型建议。2. MinerU技术链路拆解从PDF文件到结构化Markdown2.1 MinerU不是简单的“PDF转Markdown”而是四层流水线MinerU的解析链路大体可以拆成四个阶段每个阶段解决一类独立问题。第一阶段是预处理。对于扫描版PDFMinerU会把每一页渲染成高分辨率图像供后续视觉模型使用对于有文本层的数字原生PDF它会尝试抽取文本层信息作为后续识别的辅助信号。这一步的价值在于不是所有PDF都值得做完整OCR能拿到文本层的就直接用文本层能省掉大量不必要的计算。第二阶段是版面检测与内容分类。MinerU会利用版面分析模型把每一页划分成不同的区域标记出标题、正文、图片、表格、公式、页眉页脚等元素的位置和类型。这一步决定了后面所有内容的结构顺序如果区域划分错了后续的公式识别和表格还原都会跟着错位。实际操作中双栏论文的版面检测是最容易出问题的场景MinerU在这一块做了不少针对性优化。第三阶段是精细化内容识别。对检测出来的公式区域MinerU会调用公式识别模型把公式图片转换为LaTeX表达式对表格区域通过表格结构识别模型还原出行列关系对普通文字区域使用OCR模型做文字识别。这个阶段产出的不是普通文本而是带有格式语义的结构化片段。第四阶段是阅读顺序排列与内容拼接。检测出来的各个版面区域会按照人类阅读习惯重新排序再结合公式和表格的识别结果最终输出一份层级清晰、结构完整的Markdown文档。MinerU还会同步输出JSON格式的中间结果保留每个内容块的位置坐标和类型信息方便下游做精细化处理。2.2 为什么MinerU适合做RAG管道中的数据清洗层我在实际项目里最看重MinerU的一点是它输出的Markdown本身就带着完整的标题层级和段落结构。这意味着下游做文本切块chunking的时候可以直接按照#、##、###的层级来切而不是靠固定字符数硬切。固定字符数切块经常把完整的段落拦腰截断导致检索时语义碎片化按标题层级切块虽然不能保证每个块都一样长但每个块在语义上是完整的。另外MinerU输出的表格是真正的Markdown表格公式是LaTeX格式代码块有独立标记。这些结构化的内容喂给大模型做知识问答时模型能够更容易理解文档的组织方式回答的准确率也会更高。这一点我是做过对照实验的同一个PDF用普通文本提取工具和用MinerU解析后喂给同一个RAG系统答案的引用准确率差距非常明显。2.3 依赖模型与硬件选择的现实问题MinerU的能力建立在多个视觉模型和OCR模型之上它依赖PaddleOCR、版面检测模型、公式识别模型等一系列权重文件。这意味着首次使用时需要下载大量模型权重后续每次解析时的推理计算量也不小。硬件方面MinerU支持GPU和CPU两种执行模式。GPU模式速度快但对显存有要求建议至少8GB显存起步CPU模式速度慢一些但胜在部署简单不依赖特定显卡。我测试下来普通办公电脑的CPU在解析扫描版PDF时一页大约需要几秒到十几秒一整本几十页的文档等几分钟属于正常现象。所以MinerU更适合做离线批处理不太适合做毫秒级实时解析。如果你打算在生产环境使用MinerU建议在部署前把模型权重提前下载好避免运行时临时拉取导致首次任务卡住。这点在后面Windows 11部署章节会详细展开。3. Docling的设计逻辑为什么它被看作文档处理全家桶3.1 DoclingDocument把一切文档抽象成一种数据结构Docling最核心的设计是DoclingDocument数据模型。这个模型把文档里的所有内容元素抽象为统一的类型包括文本块、标题、表格、图片、列表、引用等。每个元素都带有层级关系、位置信息和元数据整个文档在内存中就是一棵结构化的树。这个设计的下游价值非常大。传统做法是每种输入格式对应一种输出结构PDF解析出来是一套字段DOCX解析出来是另一套字段下游程序要针对每种格式写适配逻辑。Docling把所有格式都映射到同一个DoclingDocument模型下游应用只需要认识这一种数据结构就够了。这就像家里各种电器都用同一个型号的插座接线再也不用为每种电器单独准备转换头。Docling支持的输出格式也很多包括Markdown、HTML、JSON、纯文本以及直接返回DoclingDocument对象。其中JSON输出保留了完整的结构信息和位置坐标特别适合做精细化的文档分析和信息抽取。3.2 多格式支持从PDF到PPTX都能吃的“食堂窗口”Docling的输入格式覆盖范围让我印象很深。除了常见的PDF包括扫描版和数字原生版它还支持DOCX、PPTX、XLSX、HTML以及多种图片格式。这个覆盖面在开源文档处理项目里算是非常全的。处理扫描版PDF时Docling可以接入OCR能力支持配置不同的OCR后端。处理DOCX和PPTX时它利用的是文件内部的XML结构信息解析速度快而且能保留标题层级、表格结构这些关键信息。像PPTX这种格式如果用纯粹的OCR方案处理每一页幻灯片会被当成一整张图片文字和结构的还原度很差Docling直接读取底层的XML数据拿到的内容质量比OCR高出一大截。不过需要说明的是Docling对扫描版PDF的复杂表格和公式处理没有MinerU做得那么精细。它在多格式覆盖上是全能选手但单项深度上不如MinerU这种专攻PDF的工具。3.3 Docling与RAG生态的集成路径Docling在RAG生态里的接入方式很成熟。LlamaIndex官方提供了DoclingReaderLangChain社区也有对应的Loader实现。你可以直接把Docling的解析结果喂给索引流程省掉自己写文档加载器的时间。我使用Docling时最喜欢的流程是用Docling把混合格式的文档统一解析成JSON再把JSON里需要索取的文本字段提取出来做向量化。这样不管上游来的是Word还是PDF下游处理的都是统一格式的数据。对于企业知识库这种上游文件类型杂、格式不规范的项目Docling的“统一中间模型”设计能省掉大量重复的字段适配工作。4. 同一批测试文档两种框架的实际表现差异4.1 测试环境与四组测试样例实测环境是一台Windows 11办公机i7处理器32GB内存无独立GPU。这正好对应你手上那台常见的Win11电脑没有显卡加速纯粹看CPU解析能力。测试文档准备了三类内容一份含双栏排版和数学公式的学术论文PDF一份扫描版的合同档案PDF一份排版复杂的DOCX文档。其中扫描版PDF只能靠OCR识别学术论文PDF既有文本层又有公式图片DOCX则主要用来测试Docling的多格式能力。4.2 版面还原、表格与公式的实际结果对比直接说结论表格见下。测试项MinerU表现Docling表现扫描版PDF文字识别文字识别准确率高阅读顺序基本正确文本可识别但复杂双栏版面偶有顺序错位学术论文双栏排版版面还原很稳标题层级清晰整体可读跨栏表格识别不如MinerU精细数学公式还原能输出可复用的LaTeX公式公式变体支持有限复杂公式容易出现结构混乱DOCX文档解析不支持直接解析结构还原完整标题、列表、表格均正常输出Markdown结构质量标题层级、表格、公式区分明确结构完整度不错但公式和代码块语义较弱从我的测试来看MinerU在PDF场景下的版面还原能力确实明显更强尤其是扫描版和含公式的论文。Docling在面对纯PDF时也不差但细节处理上不如MinerU精细特别是在表格和公式这两个关键维度上。Docling真正的优势体现在多格式文档混合处理上。当一批文档里既有PDF又有Word和PPT时Docling能用统一的数据结构处理完所有文件而MinerU只能处理PDF。如果你的项目文档类型比较单一且以PDF为主MinerU是更优解如果文档类型五花八门Docling的通用性价值会体现得更明显。4.3 速度与资源占用的量级感受在CPU模式下MinerU解析一份30页左右的标准论文PDF从提交任务到拿到完整Markdown我这边观察到的耗时大约在几分钟的级别。其中大部分时间花在版面检测和公式识别上纯文本页的速度会快很多。Docling在解析有文本层的PDF时速度会快一些但如果需要触发完整OCR流水线速度也不会有太大优势。内存占用方面两个框架在解析过程中都会把模型权重加载到内存里MinerU因为串联的模型更多内存占用略高一些。我这台32GB内存的机器跑起来没有压力但如果你用的是8GB内存的老机器建议一次只跑一个任务。综合来看CPU模式下两个框架都不是为实时解析设计的更适合放在异步任务队列里跑批处理。5. Windows 11 CPU环境部署MinerU的完整记录5.1 环境准备Python版本、虚拟环境与两个最容易踩的坑先强调一个我踩过的关键问题MinerU在Windows 11上部署时Python版本一定要用3.10千万不要图新鲜装3.12。MinerU依赖的PaddleOCR和PyTorch版本对3.12的支持还不完善我在测试环境里用3.12装完依赖一启动就报类型签名错误排查了半天最后换回3.10才稳定跑起来。第二个坑是虚拟环境。尽量不要直接往系统全局Python里装依赖MinerU的依赖链条很长容易跟其他项目冲突。我习惯用conda单独建一个环境隔离干净出问题也能直接删掉重建。第三个坑是Microsoft C Build Tools。Windows上安装MinerU时一些依赖包需要本地编译系统里没有C编译环境的话会直接报Microsoft Visual C 14.0 or greater is required的错误。解决办法是安装Visual Studio Build Tools勾选“适用于Windows的C CMake工具”和Windows 10/11 SDK这两个组件。5.2 安装依赖与验证环境准备好之后按下面的命令执行即可。conda create -n mineru python3.10 -y conda activate mineru pip install mineru[core]安装过程取决于网络状况如果某些包下载慢可以换成国内PyPI镜像源加速。安装完成后先验证核心命令是否正常。mineru --version能正常输出版本号说明核心组件已经就位。如果你看过老版本的MinerU文档可能会遇到magic-pdf这个包名不用担心MinerU改名之前就叫这个核心用法是一致的。5.3 一条命令跑通PDF解析验证通过后拿一份测试PDF直接跑解析。mineru -p ./sample.pdf -o ./output_dir -m auto参数含义如下-p指定输入PDF路径-o指定输出目录-m指定执行后端。auto模式会自动识别当前环境是否有可用的CUDA设备没有GPU时自动回退到CPU模式。如果你确定不想让MinerU尝试GPU路径也可以直接显式指定CPU模式。跑完之后输出目录下会生成一个与PDF同名的子目录里面包含Markdown文件、图片资源子目录以及JSON格式的中间结果。打开Markdown文件检查一下标题层级、表格和公式是否完整如果一切正常说明本地部署已经成功了。5.4 首次运行模型加载体验首次执行解析时MinerU会加载版面检测模型、PaddleOCR模型和公式识别模型这一步比较耗时而且需要联网下载模型权重。如果你在下载环节卡住可以提前用国内可正常访问的模型仓库把权重拉下来放到MinerU的模型缓存目录里让离线环境也能跑通。这里有个细节值得注意模型缓存目录不能放在带中文或空格的路径下否则部分模型加载时会因为路径编码问题报错。我在第一次部署时就因为用户名是中文导致模型目录解析异常后面改到纯英文路径下才正常。另外第一次解析单页文档时你会明显感觉到前几页速度偏慢后面逐渐稳定这是因为模型加载是一次性的加载完成后后续页面就快多了。6. 把MinerU封装成可调用的解析服务OpenAPI模式实战6.1 MinerU的OpenAPI能力概览本地命令行解析适合手动处理文件但如果要让业务系统远程调用就得把MinerU封装成服务。MinerU官方提供了基于FastAPI的OpenAPI接口支持上传文档、创建解析任务、查询任务状态、获取解析结果。整个调用模型是标准的异步任务模式提交文件后获得一个任务ID前端轮询任务状态完成后获取结果。这种异步设计对CPU环境很友好。解析一个几十页的PDF需要几分钟如果采用同步接口HTTP请求会一直挂着连接很容易超时异步模式则把耗时操作放入后台队列请求层始终保持快速响应。6.2 CPU模式启动API服务按照MinerU的安装方式安装API依赖后可以通过mineru-api命令启动服务。不同的MinerU版本启动参数会有些差异建议先查看帮助文档确认当前版本的具体参数。mineru-api --help启动服务的通用方式是指定监听地址和端口。mineru-api --host 0.0.0.0 --port 8000在CPU模式下服务启动后会自动加载模型权重加载完成前的第一个请求可能会非常慢。建议启动后先请求一次健康检查接口确认模型已经加载完毕再对外暴露服务避免用户体验到超长等待。打开浏览器访问http://127.0.0.1:8000/docs就能看到FastAPI自动生成的Swagger接口文档页面里面列出了所有可用的接口和请求参数这是确认当前版本接口路径最靠谱的方式。6.3 用Python请求库调用一次完整任务服务启动后用Python脚本模拟一次完整调用。先上传文件并创建任务。import requests base_url http://127.0.0.1:8000 with open(./sample.pdf, rb) as f: resp requests.post( f{base_url}/file_parse, files{file: f}, ) resp.raise_for_status() task resp.json() task_id task[task_id] print(task_id)拿到任务ID后循环轮询任务状态。import time state pending while state not in (finished, failed): status requests.get(f{base_url}/task/{task_id}).json() state status.get(state) print(当前状态:, state) if state in (finished, failed): break time.sleep(5)任务完成后请求结果接口获取解析产物。result requests.get(f{base_url}/task/{task_id}/result).json() print(result)返回结果中通常包含Markdown内容、JSON中间结果和图片资源列表。你可以把Markdown内容直接写入数据库或把JSON结果交给下游程序进一步处理。我这里给出的接口路径是基于当前版本比较常见的写法但不同版本之间可能调整命名。最稳妥的方式是打开/docs页面对照页面里的实际路径修改请求URL。6.4 CPU模式下API服务的几个调优经验CPU模式的算力很宝贵有几个经验值得分享。第一个经验是控制并发数。CPU环境下不要开太多并发解析任务我测试下来同时跑2到3个任务时吞吐量最高并发数再往上加CPU线程互相争抢资源总耗时反而增加内存占用也明显上涨。如果你的业务方会同时提交很多文件建议在服务前面加一层请求队列限制同时进入解析流程的任务数量。第二个经验是做好超时和重试机制。CPU解析耗时不稳定网络层容易超时API客户端要做好合理的超时设置和失败重试。我一般把连接超时设为10秒读取超时设为60秒重试次数设为3次这样既能覆盖偶发抖动又不会卡住主业务流程。第三个经验是长期运行的内存监控。MinerU解析服务长时间运行后内存占用会缓慢上涨。如果发现内存持续走高最省事的办法是每天凌晨定时重启一次服务进程成本低、见效快。7. 选型建议什么场景该用哪个框架7.1 按文档类型选型结合前面的实测结果可以给出一个比较清晰的选型方向。使用场景优先选择理由扫描版PDF为主MinerU完整OCR链路版面还原能力强含大量数学公式的论文MinerU公式LaTeX还原质量高PDF、Word、PPT混合文档库Docling多格式统一解析输出结构一致RAG数据清洗需要优质MarkdownMinerU标题层级清晰方便按结构切块需要JSON结构化元数据做精细处理DoclingDoclingDocument天然结构化为JSON中文扫描件复杂表格MinerU对中文场景的优化更充分如果你的项目90%以上的文件是PDF选MinerU大概率不会错。如果文件类型很杂Word和PPT占有相当比例Docling能帮你省掉大量适配不同格式的重复工作。7.2 按团队技术栈与集成深度选型团队技术栈也是选型的重要参考。如果你们已经使用了LlamaIndex或者LangChainDocling的集成路径更顺滑官方Loader和社区插件做得比较完善。如果你需要的是一个能独立部署、能提供HTTP API的文档解析服务MinerU自带的OpenAPI模式对后端接入更友好。Docling的Python API设计得非常Pythonic适合作为库嵌入到现有代码流程里。MinerU则更像一套完整的工具链既能命令行使用也能通过API服务对外提供能力适合以独立服务的形式部署。7.3 生态活跃度、许可证与维护节奏从社区活跃度看MinerU的更新节奏明显更快Issue响应和PR合并都比较积极这可能得益于它在中文开发者社区里的热度。Docling背靠IBM社区规模相对小一些但代码质量和设计文档都很扎实适合愿意花时间研究文档内容的团队。许可证方面两个项目都是开源可用做商业集成前建议去GitHub仓库确认一下许可证最新条款确保符合你的合规要求。7.4 一个更省事的搭法两个都装按文件类型分流最后分享一个我在实际项目中采用的方案两个框架同时部署按照文件类型做路由分流。PDF文件交给MinerU解析输出Markdown和JSONDOCX、PPTX、XLSX这些格式交给Docling处理统一输出JSON。下游系统接收到的都是统一的结构化数据再加上一层轻量清洗就能喂给RAG流程了。这套组合跑下来文档解析的成功率基本稳定既能吃下扫描件这种硬骨头又能兼顾混合格式文档的高效处理。唯一需要控制的点是部署成本两个框架同时运行对内存有一定要求建议服务器内存至少16GB以上。个人而言我不太建议在框架选型上做“二选一”的决定。文档解析这个领域最大的特点就是你的文档长什么样效果就是什么样任何人的基准测试都代替不了真实业务文档的验证。最快的办法是把两个框架都装在测试环境里拿自己手上最典型的几十份文档跑一遍看到真实结果再做决定。这种投入成本远小于上线之后发现选错框架再迁移。