MinerU是一款将PDF转化为机器可读格式的工具(如markdown、json),可以很方便地抽取为任意格式。
目录
[1. 软硬件环境支持说明](#1. 软硬件环境支持说明)
[2. 系统与硬件要求](#2. 系统与硬件要求)
[1. 创建Python虚拟环境](#1. 创建Python虚拟环境)
[2. 安装 MinerU](#2. 安装 MinerU)
[2.1 使用 pip 或 uv 安装](#2.1 使用 pip 或 uv 安装)
[2.2 源码安装](#2.2 源码安装)
[3. 使用MinerU](#3. 使用MinerU)
[3.1 命令行使用方式](#3.1 命令行使用方式)
[3.2 模型源配置](#3.2 模型源配置)
[3.3 使用本地模型](#3.3 使用本地模型)
一、简介
MinerU是一款开源的智能文档解析工具,专注于将PDF等文档高效转换为Markdown和JSON等结构化格式。在当前大语言模型(LLM)蓬勃发展的时代,高质量的结构化数据对于训练和微调LLM至关重要。MinerU通过其强大的智能文档解析能力,不仅可以为LLM提供清晰的训练语料,还能作为AI应用的重要数据预处理工具。与传统PDF处理工具不同,MinerU的智能解析能力涵盖了文本、图片、表格和公式等多模态内容,尤其适用于多语言文档和复杂布局的PDF文件批量处理。本文将重点介绍MinerU的核心特点、环境配置,以及详细的使用教程。
二、主要功能
- 删除页眉、页脚、脚注、页码等元素,确保语义连贯
- 输出符合人类阅读顺序的文本,适用于单栏、多栏及复杂排版
- 保留原文档的结构,包括标题、段落、列表等
- 提取图像、图片描述、表格、表格标题及脚注
- 自动识别并转换文档中的公式为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生态系统中扮演越来越重要的角色。