MinerU 实战指南：把 PDF 与 Office 文档一次性转为 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
MinerU 是一个开源文档解析工具，把 PDF、DOCX、PPTX、XLSX 和图片文件转换成 Markdown、JSON 这类机器可读的格式，供检索、抽取和大模型工作流使用。如果你的需求是 PDF 转 Markdown、给 RAG 知识库建语料，或者要把大量合同、报告文件批量结构化，它就是为这类场景设计的。纯 CPU 机器和 GPU 机器都能跑，兼容 Windows、Linux 和 macOS。
它解决什么问题
常见文本提取工具的产出往往不好直接用：多栏版面的阅读顺序会乱，表格和公式丢失或变成乱码，扫描版 PDF 根本没有文本层。MinerU 按阅读顺序输出文本，自动去掉页眉、页脚、页码，把表格转成 HTML、公式转成 LaTeX，并能自动识别扫描版和乱码 PDF 后启用 OCR，省掉了大部分后续人工整理。
安装 MinerU 并跑通第一次转换
安装走一条 pip 命令，mineru[all]包含全部核心功能：
uv pip install -U "mineru[all]" # 或者：pip install -U "mineru[all]"需要改源码的话，从 https://gitcode.com/GitHub_Trending/mi/MinerU 克隆仓库，然后执行uv pip install -e .[all]即可。
装好后，第一次运行只需要一条命令。输入可以是单个文件，也可以是一个目录，支持 PDF、图片和 DOCX / PPTX / XLSX：
mineru -p demo/pdfs/demo1.pdf -o output首次使用有两个注意点：
- 首次运行会自动下载所需模型文件，之后直接复用本地缓存。如果网络访问不了 huggingface，先执行
export MINERU_MODEL_SOURCE=modelscope切换到国内镜像源。 - 机器没有 GPU 时，加上
-b pipeline参数，pipeline 后端支持纯 CPU 环境推理。
上图是 MinerU 解析流程的全景：一份文件经过预处理、版面与公式检测、坐标修复和段落合并等管线处理，最后以 Markdown、JSON 和中间态（middle_json）等统一格式输出。
如果你更喜欢图形界面，用内置的 Gradio WebUI 即可：
mineru-gradio启动后在浏览器访问 http://127.0.0.1:7860，上传文件并勾选解析选项就能出结果。
核心能力拆解
多格式文档如何解析
能做什么：原生解析 PDF、图片、DOCX、PPTX、XLSX，不需要先把 Word 转成 PDF 再处理，DOCX 走原生解析链路，端到端速度明显快于"先转 PDF"的传统做法。
怎么用：mineru -p <输入文件> -o <输出目录>即可，输入给目录时可以一次解析目录下所有受支持的文件。
表格与公式如何转换
能做什么：识别文档中的表格并转成 HTML，识别公式并转成 LaTeX，支持表格内图片/公式、跨页表格合并等复杂场景。
怎么用：表格和公式识别默认开启，直接出结果；如果只处理纯文本、想加快解析速度，可以通过命令行参数关闭这两项，参数说明见命令行工具文档。
OCR 与多语言内容如何处理
能做什么：自动检测扫描版 PDF 和乱码 PDF 并启用 OCR，OCR 支持 109 种语言的检测与识别，中英文混合文档开箱可用。
怎么用：解析方式默认是auto，由 MinerU 自行判断走文本提取还是 OCR；使用 pipeline 后端时还可以传语言提示参数辅助识别。
输出格式与可视化校验
能做什么：除 Markdown 外，还输出按阅读顺序排序的 JSON 和包含丰富信息的中间格式，图片、图注、表格、脚注都会被提取保留。内置 layout 可视化和 span 可视化，把识别出的区块画回原页面上，便于质检输出质量。
怎么用：解析完成后在输出目录打开对应结果文件即可；做质量核对时，先看 layout 可视化图，确认区块划分和阅读顺序是否符合预期。
上图是 layout 可视化示例：页面上的正文段落、章节标题、公式块都被框出标注，一眼能看出版面切分是否正确。
适合谁、与相邻工具的差异
文档处理工具大致分三类，可以对照自己的需求选择：
| 工具类型 | 特点 | 局限 |
|---|---|---|
| 纯文本提取工具 | 快，直接抽文本层 | 多栏版面易乱序，表格公式丢失，扫描件无能为力 |
| OCR 服务 | 解决扫描件无文本层问题 | 产出多为无结构文本，版面重建要自己再做 |
| MinerU | 先识别版面，再按阅读顺序输出，表格公式直接转换 | 对 GPU 机型有更高配置要求（可选） |
对开发者来说，两个最实用的入口是 CLI 和mineru-api（FastAPI 服务），后者提供异步任务接口，方便搭批量解析流水线；也提供 MCP Server 和 Dify、RAGFlow、FastGPT 等框架的原生集成，接入 AI 编程工具或知识库平台都比较直接。
硬件上按需选择：pipeline 后端兼容性好，纯 CPU 就能跑；hybrid / vlm 后端精度更高，适合显存 8GB 以上的 GPU 机型。
资源导航
- 官方文档（中文）：docs/zh/
- 快速上手与使用指南：docs/zh/usage/quick_usage.md
- 核心解析源码：mineru/backend/
- 示例文件与演示脚本：demo/
【免费下载链接】MinerUTransforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.项目地址: https://gitcode.com/GitHub_Trending/mi/MinerU
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
