5 分钟跑通 MinerU：从 PDF 到 LLM-ready Markdown 的文档解析完整路线
项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU 上周我把一份 40 页的行业报告喂进公司的 RAG 系统，检索结果里全是乱码和错位的表格。排查到最后发现，问题根本不在向量库，而在最上游——PDF 保存的是"视觉排版"，不是"可读文本"。如果你也在给大模型、RAG 或 Agent 喂资料时栽过同样的跟头，MinerU 值得花 5 分钟试一下：这是一款能把 PDF、图片以及 DOCX、PPTX、XLSX 统一转换为 LLM-ready 的 Markdown 与 JSON 的文档解析工具。
一句话说清它的价值：MinerU 负责把"机器看不懂的文档"翻译成"模型吃得了的结构化数据"，让检索、抽取、问答的准确率从源头开始就站得住。
能力速览：一份清单看懂它能干什么
动手之前，先花 30 秒建立全局认知。MinerU 的核心能力拆成三块：
- 输入广：PDF、扫描件/图片、DOCX、PPTX、XLSX 全格式覆盖
- 输出稳：符合人类阅读顺序的 Markdown（多模态 / NLP 两套）、带坐标与语义的 JSON、中间格式，以及 layout / span 可视化文件用于质检
- 还原准：公式转 LaTeX、表格转 HTML、自动去除页眉页脚页码、跨页表格自动合并，OCR 检测与识别支持 109 种语言
纠结"该选哪个解析后端"时，这张表就是判断依据：
| 解析后端 | 最低显存 | 能否纯 CPU | OmniDocBench v1.6 得分 | 适合谁 |
|---|---|---|---|---|
| pipeline | 4GB | 可以 | 86.47 | 通用文档、资源有限的环境 |
| hybrid | 8GB | 不行 | 95.26（medium）/ 95.39（high） | 复杂版面、追求精度 |
| vlm | 8GB | 不行 | 95.30 | 高精度解析与图像/图表分析 |
一句话总结：要省资源选 pipeline，要精度选 hybrid，要做大规模批量任务再考虑 vlm 与分布式编排。
快速上手：3 条命令完成首次解析
安装用 UV 包管理器，全程两条命令（国内网络建议加阿里云镜像加速）：
pip install --upgrade pip -i https://mirrors.aliyun.com/pypi/simple
pip install uv -i https://mirrors.aliyun.com/pypi/simple
uv pip install -U "mineru[core]" -i https://mirrors.aliyun.com/pypi/simple
装完后先切模型源。默认从 HuggingFace 拉权重，国内网络经常失败，一条环境变量切到 ModelScope：
export MINERU_MODEL_SOURCE=modelscope
首次运行会自动下载模型（pipeline 后端约几个 GB），之后就是一条命令的事。拿项目自带的样例 PDF 跑一次最简流程：
mineru -p demo/pdfs/demo1.pdf -o ./output
去输出目录看结果，你会得到一套完整的解析产物：
demo1.md：可直接投喂给 LLM 的 Markdowndemo1_model.json/demo1_middle.json：含坐标与语义的结构化数据demo1_layout.pdf：版面布局可视化，每个框右上角的数字就是阅读顺序images/：文档中提取的图片与图表资源
验证输出很简单：先打开 *_layout.pdf 看阅读顺序编号是否从左到右、从上到下；再打开 .md 抽查公式和表格有没有变形。
深度体验：用一篇学术论文验证三个硬场景
以 demo 目录里的学术论文为样本，MinerU 最见功力的场景有三个：
1. 公式还原。 行内公式与独立公式会被自动识别并转成 LaTeX，解析结果可以直接送进问答系统，不会出现"图片式"的乱码公式。
2. 跨页表格合并。 表格被分页截断是解析工具的经典翻车点，MinerU 会把拆散的表格重新拼成完整的 Markdown 表格，表头与结构都能保留。
3. 阅读顺序。 双栏论文按栏阅读而不是按行交错，MinerU 输出的 Markdown 符合真实人类阅读顺序，页眉页脚被去掉，语义更连贯。
进阶调优时记住两个实用命令：
# 用 hybrid 后端 + high 强度换极致精度
mineru -p demo/pdfs/demo1.pdf -o ./output -b hybrid --effort high
# 启动 Gradio 可视化界面，上传文件即可解析
mineru-gradio --server-port 7860
其中 --effort 是 hybrid 后端的解析强度参数：medium 精度只降 0.13，但速度在不同设备上能提升 35%~220%，适合日常大批量任务；high 则解锁图像/图表分析能力，给精度敏感的场景用。默认就是 medium，日常场景不用额外配置。
避坑指南：4 个高频问题的排查清单
① 模型下载失败或极慢。 优先设置 MINERU_MODEL_SOURCE=modelscope；想离线部署时，模型缓存命中后不会重复下载，相关配置详见 docs/zh/usage/model_source.md。
② 显存不够跑不动。 4GB 显存选 pipeline，低于 8GB 别碰 hybrid/vlm。实在没有 GPU，pipeline 支持纯 CPU 推理，只是会慢一些。
③ Windows 下没有 CUDA 加速。 去 PyTorch 官网按自己的 CUDA 版本重装 torch 与 torchvision，CLI 才能自动走 GPU。
④ 长文档内存爆掉。 3.x 版本用滑动窗口优化了解析链路，上万页文档不需要手动拆分；解析支持多线程并发，配合 mineru-router 可一键多卡部署、任务自动负载均衡。
生态与资源：从命令行到企业级部署
MinerU 不只是一个 CLI 工具，接入方式相当齐全：
- API 化：
mineru-api提供 FastAPI 接口（异步POST /tasks+ 同步POST /file_parse），mineru-router负责多服务 / 多 GPU 的统一入口 - AI 工具链：内置 MCP Server，可接入 Cursor、Claude Desktop 等 AI 编程工具；与 LangChain、Dify、FastGPT、RAGFlow 等框架原生集成
- 全平台：Windows / Linux / macOS 通吃，还适配了昇腾、寒武纪、摩尔线程等十余款国产算力
- 可视化质检：除 CLI 外，
mineru-gradio提供 WebUI；docs/zh/reference/output_files.md详细解释了每个输出文件的用途
核心流程的源码入口在 mineru/backend/pipeline/，想深入理解解析链路或做二次开发，从 pipeline_analyze.py 读起最顺。
现在就动手：你的第一份 PDF 只差一条命令
别再让格式错乱、表格丢失、公式变形成为 RAG 和 Agent 的上游瓶颈。MinerU 把"PDF 转 Markdown"这件事从"凑合能用"做到了"开箱即用"，你只需要付出 5 分钟和一条命令。跑通 demo 之后，把你手头最难啃的那份 PDF 丢给它，对比一下前后效果，大概率会有惊喜。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
