MinerU：高效智能PDF文档解析工具完全指南

MinerU是一款开源的智能文档解析工具，专注于将PDF等文档高效转换为Markdown和JSON等结构化格式。在当前大语言模型(LLM)蓬勃发展的时代，高质量的结构化数据对于训练和微调LLM至关重要。MinerU通过其强大的智能文档解析能力，不仅可以为LLM提供清晰的训练语料，还能作为AI应用的重要数据预处理工具。与传统PDF处理工具不同，MinerU的智能解析能力涵盖了文本、图片、表格和公式等多模态内容，尤其适用于多语言文档和复杂布局的PDF文件批量处理。本文将重点介绍MinerU的核心特点、环境配置，以及详细的使用教程。

官网链接：https://github.com/opendatalab/MinerU/tree/master

二、主要功能

删除页眉、页脚、脚注、页码等元素，确保语义连贯

输出符合人类阅读顺序的文本，适用于单栏、多栏及复杂排版

保留原文档的结构，包括标题、段落、列表等

提取图像、图片描述、表格、表格标题及脚注

自动识别并转换文档中的公式为LaTeX格式

自动识别并转换文档中的表格为HTML格式

自动检测扫描版PDF和乱码PDF，并启用OCR功能

OCR支持84种语言的检测与识别

支持多种输出格式，如多模态与NLP的Markdown、按阅读顺序排序的JSON、含有丰富信息的中间格式等

支持多种可视化结果，包括layout可视化、span可视化等，便于高效确认输出效果与质检

支持纯CPU环境运行，并支持 GPU(CUDA)/NPU(CANN)/MPS 加速

兼容Windows、Linux和Mac平台

特点：

三、环境支持

1. 软硬件环境支持说明

|----------|----------------------------------|------------------|---------------------|
| 解析后端 | pipeline | vlm-transformers | vlm-sglang |
| 操作系统 | windows/linux/mac | windows/linux | windows(wsl2)/linux |
| CPU推理支持 | ✅ | ❌ ||
| GPU要求 | Turing及以后架构，6G显存以上或Apple Silicon | Turing及以后架构，8G显存以上 ||
| 内存要求 | 最低16G以上，推荐32G以上 |||
| 磁盘空间要求 | 20G以上，推荐使用SSD |||
| python版本 | 3.10-3.13 |||

2. 系统与硬件要求

为了确保MinerU的稳定运行，官网建议在以下环境中部署：

操作系统：Linux（2019年后版本）、Windows 10/11、macOS 11+
内存：至少16GB，推荐32GB以上
存储：至少20GB，推荐使用SSD
Python版本：3.10（请使用conda创建Python虚拟环境）

硬件加速支持

CPU模式：支持所有现代x86_64或ARM64架构的CPU。
GPU模式：支持NVIDIA显卡（8GB显存及以上），需要安装CUDA 11.8及cuDNN v8.7.0。
NPU模式：支持华为Ascend NPU（Ascend 910b），需要安装CANN 8.0+。

四、本地部署

1. 创建Python虚拟环境

使用conda创建一个独立的Python 3.10虚拟环境：

bash 复制代码

conda create -n MinerU python=3.10
conda activate MinerU

2. 安装 MinerU

2.1 使用 pip 或 uv 安装

bash 复制代码

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

2.2 源码安装

bash 复制代码

git clone https://github.com/opendatalab/MinerU.git
cd MinerU
uv pip install -e .[core] -i https://mirrors.aliyun.com/pypi/simple

Linux和macOS系统安装后自动支持cuda/mps加速，Windows用户如需使用cuda加速，请前往 Pytorch官网选择合适的cuda版本安装pytorch。

3. 使用MinerU

3.1 命令行使用方式

基础用法

最简单的命令行调用方式如下：

bash 复制代码

mineru -p <input_path> -o <output_path>

<input_path>：本地 PDF/图片文件或目录（支持 pdf/png/jpg/jpeg/webp/gif）
<output_path>：输出目录

查看帮助信息

获取所有可用参数说明：

bash 复制代码

mineru --help

参数详解

复制代码

Usage: mineru [OPTIONS]

Options:
  -v, --version                   显示版本并退出
  -p, --path PATH                 输入文件路径或目录（必填）
  -o, --output PATH               输出目录（必填）
  -m, --method [auto|txt|ocr]     解析方法：auto（默认）、txt、ocr（仅用于 pipeline 后端）
  -b, --backend [pipeline|vlm-transformers|vlm-sglang-engine|vlm-sglang-client]
                                  解析后端（默认为 pipeline）
  -l, --lang [ch|ch_server|ch_lite|en|korean|japan|chinese_cht|ta|te|ka|latin|arabic|east_slavic|cyrillic|devanagari]
                                  指定文档语言（可提升 OCR 准确率，仅用于 pipeline 后端）
  -u, --url TEXT                  当使用 sglang-client 时，需指定服务地址
  -s, --start INTEGER             开始解析的页码（从 0 开始）
  -e, --end INTEGER               结束解析的页码（从 0 开始）
  -f, --formula BOOLEAN           是否启用公式解析（默认开启）
  -t, --table BOOLEAN             是否启用表格解析（默认开启）
  -d, --device TEXT               推理设备（如 cpu/cuda/cuda:0/npu/mps，仅 pipeline 后端）
  --vram INTEGER                  单进程最大 GPU 显存占用(GB)（仅 pipeline 后端）
  --source [huggingface|modelscope|local]
                                  模型来源，默认 huggingface
  --help                          显示帮助信息

3.2 模型源配置

MinerU 默认在首次运行时自动从 HuggingFace 下载所需模型。若无法访问 HuggingFace，可通过以下方式切换模型源：

切换至 ModelScope 源

bash 复制代码

mineru -p <input_path> -o <output_path> --source modelscope

或设置环境变量：

bash 复制代码

export MINERU_MODEL_SOURCE=modelscope
或：
# 若因网络问题无法访问 Hugging Face Hub
export HF_ENDPOINT=https://hf-mirror.com  # 使用国内镜像

mineru -p <input_path> -o <output_path>

3.3 使用本地模型

1. 下载模型到本地

bash 复制代码

mineru-models-download --help

或使用交互式命令行工具选择模型下载：

bash 复制代码

mineru-models-download

下载完成后，模型路径会在当前终端窗口输出，并自动写入用户目录下的 mineru.json。

2. 使用本地模型进行解析

bash 复制代码

mineru -p <input_path> -o <output_path> --source local

或通过环境变量启用：

bash 复制代码

export MINERU_MODEL_SOURCE=local
mineru -p <input_path> -o <output_path>

总结

MinerU是一款功能强大且灵活的智能文档解析工具，通过其API和命令行工具，用户可以高效地将PDF转换为结构化数据格式。在AI和大语言模型快速发展的今天，MinerU的价值不仅体现在传统的文档处理领域，更在于其为LLM提供高质量训练数据的能力。通过与大语言模型的深度结合，MinerU可以实现更智能的文档理解和知识提取，为未来的AI应用打开更多可能性。无论是在学术研究还是企业应用中，MinerU都展现出了卓越的性能和广泛的适用性。随着LLM技术的不断进步，MinerU这样的智能文档解析工具将在AI生态系统中扮演越来越重要的角色。