企业官网建设流程全解析

手头有200页的学术PDF要转成Markdown喂给大模型，试了好几个工具，转出来的内容不是公式乱码就是表格错位，那段时间我一度怀疑是不是自己打开方式不对。后来接触到MinerU和Docling这两个智能文档处理框架，折腾了大概两周，总算是把这条解析链路跑顺了。今天这篇就把我实际部署和对比的心得整理出来，尤其会把MinerU在Windows 11上的CPU部署细节、两个框架在不同文档上的表现差异讲清楚，给后面要选型或者准备踩坑的朋友一个参考。

先说结论：两者都不是“开箱即用”的玩具，但也都不是难用到劝退的项目。MinerU更像一个为PDF转Markdown而生的专项选手，公式、表格、版面的处理能力非常扎实；Docling则是一个更通用的文档解析框架，输入格式更丰富，输出结构更工程化。具体怎么选，取决于你手里是什么文档、要拿解析结果去干什么。

1. 两个框架的设计思路，从一开始就不一样

在对比之前，我觉得有必要先把这两个项目的“出身”讲清楚。因为很多人在选型时只对比功能列表，却忽略了它们的设计目标完全不同，这会导致后续使用时出现“明明别人说好用，到我手里就不顺”的情况。

1.1 MinerU：把PDF“拆穿”的专项选手

MinerU的定位非常聚焦，核心目标就是PDF转Markdown，尤其是那些排版复杂、带公式、带双栏的学术论文。它内部跑了一套完整的深度学习pipeline：版面检测、公式检测、公式识别、表格识别、OCR文字识别、阅读顺序还原，最后再统一输出成Markdown格式。这个链路是端到端的，用户不需要自己去拼装各种模型，装好之后一条命令就能从PDF得到结构化的Markdown。

我用下来的感觉是，MinerU对“论文类PDF”的优化是刻在骨子里的。比如它处理双栏文档时不会把左边栏和右边栏的文字搞混，处理行内公式时能判断出这是公式而不是普通文本，这些细节在实际工作中特别重要。如果你主要是在跟学术文献、技术文档、说明书这类PDF打交道，MinerU几乎是为你量身定做的。

1.2 Docling：更像文档解析的“中央厨房”

Docling走的是另一条路。它不是一个只做PDF转Markdown的工具，而是一个文档解析框架。它支持PDF、Word、PPT、HTML、图片等多种输入格式，解析之后会生成一个统一的“文档中表示”，你可以把这个中间结果导出成Markdown、JSON、HTML等不同的目标格式。这意味着它的定位更像是给开发者用的基础设施，而不是给普通用户用的“一键转换工具”。

我理解Docling的核心优势在两点：一是格式覆盖广，除了PDF，它还愿意处理Office和网页文档；二是输出结构化程度高，解析结果保留了段落、标题、表格、列表等语义信息，这在构建知识库、做RAG、做文档数据清洗时特别有用。如果你需要把多种格式的文档统一清洗成结构化数据，Docling会更顺手。

1.3 选型定位：场景决定工具，而不是参数决定工具

真实选型时，我建议把你的核心场景摆出来，然后对号入座：

• 场景A：大量学术PDF要转成干净的Markdown，目标是给大模型做RAG，那MinerU的PDF解析质量会明显更省心。
• 场景B：企业内部文档多种格式并存，有PDF有Word有PPT，需要统一抽取内容、建立数据管道，那Docling的格式兼容性和结构化输出更有优势。
• 场景C：不想用云服务，数据必须留在本地，那两者都支持本地部署，但MinerU在Windows上的开箱体验更友好一些。

我在实际项目中遇到的比较多的是场景A，所以后面我会把MinerU的部署和实测作为重点，同时用Docling跑相同文档做对照，让大家直观看到差异。

2. 核心能力与输出质量的逐项对比

这一部分我准备按“公式、表格、OCR、版面结构”四个维度来拆。这几个维度基本决定了一个文档解析工具的质量上限，也是大家在选型时最容易纠结的地方。

2.1 公式识别：学术文档的分水岭

公式识别是学术PDF解析的硬骨头。很多PDF中的公式并不是矢量文本，而是嵌入的图片或特殊字体，普通解析工具拿到手就是乱码。MinerU的处理方式是先做公式检测，把页面中的公式区域框出来，然后用专门的公式识别模型转换成LaTeX格式。我在测试中拿了一些带行内公式的论文，转换结果基本能保留公式结构和大部分符号，少数极端复杂的矩阵或特殊符号会出错，但整体可用率很高。

Docling的公式处理策略不太一样。它更依赖底层的解析引擎，如果PDF本身带有文本层的公式信息，它能较好地保留；但遇到扫描版或图片型公式时，表现就不如MinerU那套专门的检测加识别链路。这倒不能说Docling不行，而是它的侧重点不在“极致还原”上。所以我的建议是：如果你的文档以数理公式为主，MinerU是更稳妥的选择；如果公式只占一小部分，Docling的输出也能凑合着用。

2.2 表格还原：谁更接近“所见即所得”

表格是另一个容易翻车的地方。PDF里的表格经常没有真正的表格结构，只是一堆线条和文字摆成了网格的样子。MinerU在表格识别上投入了不少功夫，测试中无论是规则的三线表还是稍微复杂一点的合并单元格表格，它还原出来的Markdown表格结构都比较规整，列对齐和行列关系基本正确。这点对于做数据整理的人来说太关键了，因为表格一旦错位，后续清洗数据要花的时间比重做一遍还多。

Docling在表格处理上的表现也不算差，但它输出表格的方式更倾向于保留为HTML结构，这样在导出成JSON时能保留更多细节。如果你只是想要一个能直接粘贴到笔记软件里的Markdown表格，MinerU的体验更顺滑；如果你需要以结构化数据的形式去访问每一个单元格，Docling的中间表示反而更好用。

2.3 OCR与扫描件处理

扫描件是最考验OCR能力的场景。MinerU内置了OCR链路，对扫描版PDF或者图片型页面会自动走文字识别流程，中文、英文混排也能应付。实测下来，清晰扫描件的中文识别准确率相当高，但手写批注或者低分辨率扫描件还是会出问题，这一点目前没有工具能完美解决。

Docling在处理扫描件时需要外接OCR引擎，默认配置下对纯电子版PDF没有问题，但遇到扫描件会明显感觉吃力一些。如果你经常要处理扫描版书籍或老旧的纸质文档，MinerU的集成度更高，不用自己去拼装OCR组件。

2.4 版面分析与阅读顺序

版面分析决定了文档的“阅读顺序”是否正确。双栏PDF如果处理不好，左边栏读完一行就跳到右边栏，那输出基本没法看。MinerU在这一块做了专门的版面检测模型，能识别标题、正文、页眉页脚、图表区域，然后按照合理的阅读顺序重新组织内容。我觉得它在双栏论文上的表现尤其突出，顺序还原非常接近人眼阅读的逻辑。

Docling也有一套版面分析机制，但给我的感觉更偏“文档对象检测”，也就是识别出页面上有什么块、各自的位置在哪，输出时会保留这些空间信息。这样的好处是很适合做文档结构分析，但如果你只是想拿到一段顺畅通读的文本，MinerU做得更符合人类的阅读习惯。

3. MinerU在Windows 11下的本地部署实录

接下来是重头戏。我这边主力机是Windows 11，没有独立显卡，所以所有测试都在CPU环境下完成。很多人在这一步就被劝退了，总觉得AI工具必须要有好显卡，其实像MinerU这种工具，CPU部署完全可行，只是速度会慢一些。下面我把从零到能调用API的完整过程记录下来，包含我踩过的坑。

3.1 部署形态与硬件选择

MinerU的部署方式大概有三种：一是直接用官方提供的命令行工具，适合一次性转换；二是用Docker部署服务，适合服务器环境；三是在本地Python环境里跑，然后自己封装一个API服务，适合集成到现有系统中。

CPU环境下怎么选？我的建议是用Python环境加命令行工具，然后自己起一个FastAPI服务来暴露接口。这样做的好处是不依赖Docker编排，调试方便，资源占用也相对可控。内存方面，我16GB内存跑起来勉强够用，但转换大文档时内存占用会飙高，建议至少16GB，32GB会更舒服。

模型方面，MinerU会下载一组预训练模型，包括版面检测、公式检测、公式识别、表格识别和OCR相关模型，总体积好几个GB，而且默认从HuggingFace下载。这一步在国内网络环境下经常失败，后面我会专门讲怎么处理。

3.2 环境准备：Python与PyTorch

我建议用conda创建独立的虚拟环境，避免污染其他项目的依赖。Python版本我推荐3.10，太新的版本某些依赖可能还没跟上，太旧的版本又可能不支持新特性。

conda create -n mineru python=3.10 -y conda activate mineru

然后是安装PyTorch。CPU环境下不需要装CUDA版本，直接执行：

pip install torch torchvision torchaudio

如果机器有NVIDIA显卡，建议先装好CUDA驱动和cuDNN，再通过PyTorch官网给出的命令安装对应CUDA版本的PyTorch。这里有个小技巧：GPU环境装完后可以用python -c "import torch; print(torch.cuda.is_available())"验证一下，输出True就说明识别到显卡了。

3.3 安装MinerU与模型准备

环境就绪后，直接装MinerU的Python包：

pip install mineru

安装过程会自动拉取一部分依赖，包括transformers、paddleocr这些重组件，所以时间会比较长。装完以后可以用mineru --help验证安装是否成功。

模型下载是第一个坑。MinerU在首次运行时会自动下载模型，但国内网络经常连不上HuggingFace，导致卡在下载步骤。我的处理办法是这样的：

第一，手动从HuggingFace页面下载模型文件，然后放到指定目录。模型目录一般在用户主目录下的.cache/modelscope/hub或者MinerU的models目录里，具体路径可以用环境变量控制。

第二，配置镜像源。如果用的是ModelScope平台，可以设置环境变量指向国内镜像，下载速度会快很多。

第三，如果模型已经下载到了本地，可以通过设置环境变量来指定模型路径，让MinerU跳过在线下载。这一步能省下大量等待时间。

3.4 写一个服务层：从Python调用到API封装

MinerU本身提供了命令行工具，一条命令就能把PDF转成Markdown：

mineru -p input.pdf -o output_dir

命令行的好处是简单直接，但工程化项目里更常用的方式是调用它的Python接口。我查了源码，MinerU暴露了一个比较清晰的处理类，基本思路是创建解析器对象，然后传入文件路径，最后获得解析结果。这一步不同的版本API有差异，建议装完以后先用官方文档里的示例跑通。

为了后续好对接业务系统，我用FastAPI封装了一个简单的文件上传转Markdown接口，核心代码如下：

from fastapi import FastAPI, UploadFile, File from pathlib import Path import tempfile from mineru import MinerU app = FastAPI() @app.post("/pdf2md") async def pdf2md(file: UploadFile = File(...)): suffix = Path(file.filename).suffix with tempfile.NamedTemporaryFile(suffix=suffix, delete=False) as tmp: tmp.write(await file.read()) tmp_path = tmp.name parser = MinerU() result = parser.parse(tmp_path) return {"markdown": result.get_markdown()}

这个服务本身不复杂，主要就是接收上传文件、调用MinerU解析、返回结果。实际部署时还需要考虑超时设置、并发限制、临时文件清理这些问题，但作为雏形已经足够用了。启动服务只需要执行：

uvicorn main:app --host 0.0.0.0 --port 8000

然后就可以用curl或者Postman测试接口了：

curl -X POST http://localhost:8000/pdf2md \ -F "file=@test.pdf"

需要注意的是，CPU环境下首次解析会非常慢，因为模型需要加载到内存，后面再调用会快一些，但也不能指望它有GPU那种速度。我实测一个20页的论文PDF，CPU模式下大概需要5到10分钟，中间还会出现内存占用飙升的情况，属于正常现象。

4. 实战对比：同一份文档，两个框架的结果差在哪

为了让大家更直观地理解两个框架的差异，我特意准备了一份混合文档，里面有标题、正文、双栏排版、一个三线表、几个行内公式和一个块状公式，然后分别用MinerU和Docling跑了一遍，对比它们的输出质量。

4.1 测试文档与评测方法

测试文档我选了一份开源的技术报告，大约12页，电子版PDF，带文字层，核心内容包括：一段双栏的综述引言、两个跨栏的公式、一个占据半页的三线表、若干图注和参考文献。评测时我分三个维度打分：公式还原度、表格结构还原度、阅读顺序准确性。打分标准是主观的，但能反映实际使用体验。

4.2 MinerU输出质量复盘

MinerU跑完之后，我打开输出的Markdown文件，第一感受是页面顺序非常正常，没有出现左右栏错乱的问题。双栏部分的内容按从上到下、从左到右的顺序还原，阅读起来基本顺畅。公式方面，两个块状公式都成功转成了LaTeX格式，行内公式的识别也不错，个别符号有偏差但能看懂。表格还原得比较漂亮，三线表被还原成了工整的Markdown表格，表头、对齐关系、单元格内容都正确。

唯一的问题出现在OCR环节。虽然测试文档是电子版，但个别图表里的文字被MinerU当作扫描件处理，走了一遍OCR，导致那些文字的字体、大小和正文不一致。不过这不影响阅读，只是在格式层面有点突兀。

4.3 Docling输出质量复盘

Docling跑同一份文档的速度比MinerU快不少，CPU环境下大概三分钟左右就出结果了。它默认输出的JSON结构非常规整，文档的层级关系、段落类型、表格数据都分得很清楚，这一点对程序处理特别友好。但转成Markdown后，公式的表现略逊色，两个块状公式里有一个没能识别成LaTeX，而是保留了原始文本；表格部分倒是还原得不错，虽然Markdown表格的列宽处理不如MinerU精细，但数据没有错位。

4.4 从输出差异反推选型建议

对比完以后，我的选型建议很明确：如果目标是快速获得一份“读起来像原文”的Markdown，用于人工阅读或者丢给大模型做RAG，MinerU的输出质量更高，尤其是在公式密集型文档里优势明显。如果目标是构建一套文档处理系统，需要把不同格式的文档统一成结构化数据，后续还要做字段抽取、数据入库这些操作，Docling的中间表示能力更值得投入。

打个不恰当的比方，MinerU像是一个专业的书法家，能把一篇PDF“临摹”得漂亮工整；Docling更像是一个档案管理员，把文档拆解归档、贴标签、编目录，方便你后续检索使用。两者各有各的不可替代性，选错了方向才会觉得“不好用”。

5. 常见问题与排查技巧实录

不管是部署还是使用，我都遇到过不少报错和奇怪的问题。这里挑几个典型场景整理成表格，并补充一些我的排查心得，希望能帮大家少走弯路。

5.1 部署期的典型报错

下面是几个我在部署与运行过程中遇到的比较典型的问题：

5.2 模型下载慢或失败怎么办

模型下载是大家在本地部署时遇到频率最高的问题。我推荐的方式是：先确认MinerU请求的模型文件列表，然后到对应的模型托管平台手动下载。把文件放到约定目录后，通过环境变量指定路径。我的习惯是在启动脚本里统一设置：

export MINERU_MODEL_DIR="D:/models/mineru"

这样命令行和API服务都会优先读取指定目录下的模型，不会再触发在线下载。另外，如果换了一台机器，也可以直接把整个模型目录拷贝过去，省去重新下载的时间。

5.3 CPU环境下如何提升处理速度

CPU跑模型确实要有点耐心，但也不是没有办法优化。我的经验有三个：一是把大PDF按页拆分，用多进程并行解析，最后再合并结果；二是处理完一批文档后保持服务进程常驻，避免反复加载模型；三是如果机器内存够大，可以把模型一次性预加载到内存，虽然占用高但能显著减少单次任务的等待时间。对于工期比较紧的任务，我会优先选择拆页并行，实测在4核CPU上能提升两到三倍的吞吐量。

说实话，这两个框架我折腾了快一个月，从最初的“这个能用吗”到后来的“离不开了”，中间确实经历了不少怀疑人生的时刻。但一旦把部署、模型下载、API封装这条链路跑通，它们带来的效率提升是立竿见影的。我个人现在的做法是，日常处理学术文献和搭建RAG知识库用MinerU，需要做多格式文档统一清洗和结构化入库时用Docling，两者各自的生态环境互补性其实很强。

最后再分享一个经验：不要迷信“转换工具能完美解决一切PDF”。再强的解析框架，遇到严重损坏的PDF、极其复杂的排版或者低质量扫描件，也还是会出错。聪明的做法不是追求100%还原，而是把解析工具当成第一道自动化工序，人工只负责校对关键部分。这样既省时间，又能保证最终质量，是我在实际工作中摸索下来最务实的用法。