企业官网建设流程全解析

MinerU 上手指南：把 PDF 解析成可编辑 Markdown 与结构化 JSON 的最短路径

【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU

手头一份 40 页双栏论文 PDF，目标是变成带 LaTeX 公式、结构化表格的可编辑 Markdown，再喂给检索或大模型流程。MinerU 是一款免费开源的 PDF 解析工具，把 PDF、图片以及 DOCX、PPTX、XLSX 统一解析为 Markdown 与 JSON，公式自动转 LaTeX、表格自动转 HTML，兼容 Windows、Linux 与 macOS。

能力边界：MinerU 支持哪些格式，边界在哪里

• 能做什么：输入 PDF、图片与 DOCX、PPTX、XLSX；输出 Markdown、按阅读顺序排序的 JSON，以及可用于二次开发的中间态；OCR 支持 109 种语言，可处理扫描版 PDF；自动去除页眉、页脚、页码。
• 边界在哪：复杂版面、手写体等极端场景结果可能不及预期，官方建议先评估样例效果，问题样例可到 issue 反馈；vlm 与 hybrid 后端需要 GPU，纯 CPU 只能跑 pipeline 后端。
• 与同类工具的差异：它不是单点 OCR 库，而是一条完整管线，覆盖布局检测、公式识别、跨页表格合并，并附带可视化质检文件；同时提供 MCP Server、LangChain、Dify 等生态集成入口。

最短路径：三条命令跑通首次 PDF 解析

先安装，要求 Python 3.10–3.13：

pip install uv uv pip install -U "mineru[all]"

安装完成后mineru命令可用，[all]包含全部后端能力。

有 GPU 的机器直接执行，默认使用 hybrid-engine 后端：

mineru -p ./demo/pdfs/demo1.pdf -o ./output

首次运行会自动下载并缓存模型；结果写入./output下以文件名命名的目录，包含解析出的.md、图片文件以及用于质检的layout.pdf。

纯 CPU 机器则显式指定 pipeline 后端：

mineru -p ./demo/pdfs/demo1.pdf -o ./output -b pipeline

pipeline 后端精度略低但无幻觉、资源占用小，适合低配机器批量跑。

机制拆解：三个关键设计为什么这样

统一中间态。各后端解析结果先落成统一的中间态 middle_json，再分别转换为 Markdown、JSON 与可视化 PDF。使用者拿到的是稳定、可切换的输出格式，做二次开发时也可以直接消费中间 JSON，而不必关心前端是哪个后端。

双后端分工。pipeline 是传统 CV 管线：布局检测、公式检测、表格结构识别、OCR 各用专用小模型，所以能在 CPU 上运行且显存要求低；hybrid 与 vlm 把版面交给视觉语言模型，精度更高，适合复杂排版。hybrid 的设计是让文本块走原生提取、复杂块走 VLM，兼顾速度与精度，还可用--effort参数在 medium 与 high 两档强度间切换。

阅读顺序与质检。输出按人类阅读顺序排序，多栏版面不会串行；layout.pdf、span.pdf会把每页的检测框和阅读顺序画出来。批处理场景下，出问题时靠质检文件定位比看准确率数字更有效。

选型决策：后端与部署方式对号入座

部署方式对应场景：个人本地用 CLI 即可；系统集成起mineru-api提供 REST 接口；团队协作用mineru-gradio的 WebUI；多 GPU 高吞吐场景用mineru-router做统一入口与任务路由。

进阶与边界：批量处理、API 与常见坑

• 批量：-p直接接受目录输入即可整目录解析；-s/-e指定页码范围，方便大文档分段处理或先试跑几页。
• 内存：处理长文档时可调MINERU_PROCESSING_WINDOW_SIZE控制处理窗口，降低内存峰值；3.0 版本起长文档链路已做滑动窗口优化，上万页无需手动拆分。
• ⚠️ 模型下载失败：默认模型源是 Hugging Face，国内网络先执行export MINERU_MODEL_SOURCE=modelscope切换镜像源再解析。
• ⚠️ 常见坑：Windows 下 CUDA 加速需要按 PyTorch 官网自行安装对应版本的 torch；vlm 2.5 后端的结构化输出与 pipeline 版本存在不兼容，基于 JSON 做二次开发前先看输出文件说明。
• 服务化调用：mineru-api启动后通过POST /tasks异步提交任务，参数细节可查 使用指南。

收尾

MinerU 的价值在于把“PDF 到 LLM 可用结构化数据”压缩成一条命令，同时用可质检的输出保住了工程上的可控性。下一步建议：先拿一份 10 页以内的文档跑通 pipeline 后端，确认公式、表格和阅读顺序的解析质量，再决定是否为复杂文档换用 hybrid 后端或转入服务化部署。

【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU