MinerU：PDF 解析与文档转换指南

MinerU：PDF 解析与文档转换指南

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

手头有一份含公式和表格的扫描 PDF，需要转成可检索的 Markdown 喂给 RAG 系统？MinerU 就是做这件事的开源工具：PDF 解析后直接输出结构化的 Markdown 与 JSON。本文覆盖 MinerU 文档转换的安装步骤、后端选择和常见问题排查。

项目是什么

MinerU 是面向大模型、RAG 与 Agent 场景的开源文档解析工具，把 PDF、图片和 DOCX / PPTX / XLSX 转成机器可读格式，便于检索、抽取与二次处理。能力点如下：

• 原生解析 PDF、图片、DOCX、PPTX、XLSX，自动识别扫描件并启用 OCR
• 公式自动转成 LaTeX，表格转成 HTML，保留标题、段落、列表结构
• 输出按人类阅读顺序排列，自动去除页眉、页脚、页码
• OCR 支持 109 种语言的检测与识别
• 提供命令行、FastAPI、Gradio WebUI 与 Docker 部署方式，兼容 Windows、Linux、macOS，可纯 CPU 运行

三分钟上手

安装使用 uv 即可，mineru[all]包含全部核心功能：

uv pip install -U "mineru[all]"

首次运行会自动下载所需模型，之后走本地缓存。仓库自带示例文档，直接试：

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

没有 GPU 或显存不足时，指定 pipeline 后端即可在纯 CPU 环境跑通。

它如何工作

解析过程分三步：

1. 预处理：读取文档页面，区分文本型与扫描型，决定走直接抽取还是 OCR。
2. 模型分析：版面检测识别标题、正文、公式、表格区域，再逐区域做文字识别、公式识别和表格结构识别。
3. 结果转换：按阅读顺序组织内容，公式落为 LaTeX、表格落为 HTML，写出 Markdown 与 JSON。

典型使用场景

个人阅读：把 PDF 论文转成带 LaTeX 公式的 Markdown，便于本地编辑和全文检索。扫描件、多栏排版的论文也可以直接丢进去，无需手动整理结构。

团队协作：通过 Gradio WebUI 做可视化解析，配合 layout、span 可视化结果核对输出质量。多人共用一台解析服务器时，用 FastAPI 接口统一提交任务即可。

自动化流水线：命令行支持目录输入，适合批量转换存量文档。生产环境可部署 API 服务并用 mineru-router 做多 GPU 任务路由，为 RAG 知识库持续供给结构化数据。

常见问题排查

现象：模型下载失败或很慢。默认模型托管在 huggingface，无法访问时切换到国内镜像源：

export MINERU_MODEL_SOURCE=modelscope

现象：Windows 直接安装后推理速度很慢。多为 CUDA 加速依赖未正确安装。按显卡架构到 PyTorch 官网选择对应命令安装支持 CUDA 的 torch 与 torchvision；RTX 50 系显卡则需安装 cu128 版本的 lmdeploy wheel。

现象：Linux 上解析结果缺失部分中文文字。通常是系统缺少 CJK 字体，渲染 PDF 页面时丢字。安装字体包后刷新字体缓存：

sudo apt install fonts-noto-core fonts-noto-cjk fc-cache -fv

后端按环境选，精度分数来自 OmniDocBench v1.6 端到端评测：

继续深入

• 后端解析主逻辑：mineru/backend/（pipeline、hybrid、vlm 三个子目录）
• 布局、公式、表格模型实现：mineru/model/
• CLI 与服务入口：mineru/cli/（fast_api.py、gradio_app.py、router.py）
• 官方文档入口：docs/zh/index.md，常见问题在 docs/zh/faq/index.md
• 端到端测试用例：tests/unittest/test_e2e.py

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