当前位置：首页 > news >正文

MinerU_安装部署完全指南

news 2026/4/18 18:54:13

MinerU 安装部署完全指南：CPU、GPU、Docker 保姆级教程

MinerU 是由 OpenDataLab 开源的 PDF 文档解析工具，GitHub 星标 25000+。它可以将 PDF 精准转换为 Markdown、JSON 等格式，支持 OCR 84 种语言识别、公式转 LaTeX、表格转 HTML、自动阅读顺序排序、标题分级、水印过滤等功能。

本文将从零开始，一步一步带你完成 所有部署方式，涵盖每一个安装细节和常见问题的解决方案。无论你是 Windows 用户还是 Linux 用户，无论你是用 CPU 还是 GPU，都能找到对应的完整教程。

一、MinerU 是什么？
二、硬件与软件环境要求
三、安装前的准备工作
四、本机 CPU 部署（纯 CPU 环境）
五、本机 GPU 部署（CUDA 加速）
六、Docker 部署
七、Gradio Web 界面部署
八、CPU 与 GPU 推理方式详解
九、常见问题排查 FAQ
十、总结与部署方案选择建议

一、MinerU 是什么？

MinerU 是一款将 PDF 转化为机器可读格式（如 Markdown、JSON）的开源工具。它诞生于书生-浦语大模型预训练过程中，主要用于解决科技文献中的符号转化问题。

核心功能

精准版面分析：删除页眉、页脚、脚注、页码等干扰元素，保留文档真实内容
智能阅读顺序：支持单栏、多栏、复杂排版，自动排序为人类可读的顺序
结构保持：自动识别标题、段落、列表，保留原文档层级结构
公式识别：自动检测文档中的数学公式，转换为 LaTeX 格式
表格识别：自动识别表格并转换为 HTML 格式
OCR 多语言支持：支持 84 种语言的文字识别，自动检测扫描版 PDF 并启用 OCR
标题分级：自动对标题进行分级，提升文档结构化程度
多格式输出：支持 Markdown（多模态 / NLP）、按阅读顺序排序的 JSON 等多种格式
多平台支持：兼容 Windows、Linux、macOS
纯 CPU 运行：无需 GPU 也可运行，同时支持 CUDA / NPU / MPS 加速

二、硬件与软件环境要求

在开始安装之前，请确认你的设备满足以下最低要求：

2.1 硬件要求

硬件	最低要求	推荐配置
CPU	x86_64 或 ARM64	Intel i5 / AMD Ryzen 5 及以上
内存	16GB	32GB 及以上
硬盘空间	20GB	SSD 100GB（模型文件较大）
GPU（可选）	6GB 显存的 NVIDIA 显卡（Volta 2017 架构及之后）	8GB+ 显存

GPU 支持的显卡型号说明：所有 2017 年及之后发布的、带有 Tensor Core 的 NVIDIA 显卡均可使用。常见的包括：

RTX 20 系列、30 系列、40 系列

GTX 16 系列（部分型号）

Tesla / A100 / H100 等数据中心卡

如果你的显卡不满足要求，仍然可以使用 纯 CPU 模式，只是速度会慢一些。

2.2 软件要求

软件	版本	说明
操作系统	Windows 10/11、Ubuntu 20.04+、macOS 11+	三种系统均可使用
Python	>= 3.10	推荐 3.10 或 3.11
Conda	任意版本	用于环境管理，强烈推荐
NVIDIA 驱动	最新版本	仅 GPU 模式需要
CUDA	11.8 / 12.4 / 12.6 / 12.8	由 PyTorch 版本决定

2.3 检查你的 GPU 和 CUDA 版本

如果你打算使用 GPU 加速，请先运行以下命令检查：

nvidia-smi

正常输出应该类似：

+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 572.70                 Driver Version: 572.70         CUDA Version: 12.8     |
|-----------------------------------------+------------------------+----------------------+
| GPU  Name                  Driver-Model | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
|=========================================+========================+======================|
|   0  NVIDIA GeForce RTX 3050      WDDM  |   00000000:01:00.0  On |                  N/A |
| 41%   47C    P0             22W /   70W |    1368MiB /   6144MiB |      6%      Default |
+-----------------------------------------+------------------------+----------------------+

关键信息解读：

Driver Version: 572.70 — 这是你的显卡驱动版本
CUDA Version: 12.8 — 这是你的驱动支持的最高 CUDA 版本
NVIDIA GeForce RTX 3050 — 这是你的显卡型号
6144MiB — 这是你的显存（6GB），刚好满足最低要求

重要提示：这里显示的 CUDA Version 是你驱动支持的最高版本，实际安装 PyTorch 时需要选择 11.8 或 12.4 或 12.6 版本。如果你的驱动支持 12.8，安装 CUDA 12.4 的 PyTorch 是完全兼容的。

三、安装前的准备工作

3.1 安装 Conda

如果你还没有安装 Conda，请按以下步骤操作。

Windows 用户：

前往清华大学开源软件镜像站下载：

https://mirrors.tuna.tsinghua.edu.cn/anaconda/archive/

选择最新版本（如 Anaconda3-2024.06-1-Windows-x86_64.exe），下载并运行安装程序
安装过程中建议选择"Add Anaconda to my PATH environment variable"（虽然安装程序不推荐，但这样更方便）

Linux 用户：

# 下载 Miniconda（轻量版）
wget https://mirrors.tuna.tsinghua.edu.cn/anaconda/miniconda/Miniconda3-latest-Linux-x86_64.sh# 运行安装脚本
bash Miniconda3-latest-Linux-x86_64.sh# 按提示操作，完成后刷新配置
source ~/.bashrc

验证 Conda 是否安装成功：

conda --version

应输出类似：conda 24.x.x

3.2 配置 Conda 国内镜像源（国内用户推荐）

由于默认下载源在国外，建议配置清华大学镜像源加速：

# 添加清华镜像源
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
conda config --set show_channel_urls yes# 验证配置
conda config --show channels

3.3 检查 Python 版本

# 查看当前系统中的 Python 版本
python --version

如果显示的版本低于 3.10 或未安装 Python，不用担心——我们在下一步创建 Conda 环境时会自动安装 Python 3.10。

四、本机 CPU 部署（纯 CPU 环境）

本章节适合以下用户：

没有 NVIDIA 显卡
只是想快速体验一下 MinerU
处理少量 PDF 文件（不需要高性能）

预计耗时：20-40 分钟（主要取决于模型下载速度）

4.1 创建 Conda 环境

打开终端（Windows 用户可以打开 Anaconda Prompt 或 Git Bash），执行以下命令：

conda create -n mineru python=3.10 -y

命令逐字解释：

conda create — 创建一个新的 Conda 环境
-n mineru — 给这个环境起名为 mineru（你可以改成任意名字）
python=3.10 — 在这个环境中安装 Python 3.10
-y — 自动确认所有提示，不需要手动按 Y

创建过程会输出类似如下内容：

Collecting package metadata (repodata.json): ...working... done
Solving environment: ...working... doneThe following NEW packages will be INSTALLED:bzip2              conda-forge/win-64::bzip2-1.0.8-h0ad9c76_9python             conda-forge/win-64::python-3.10.20-hc20f281_0_cpythonpip                conda-forge/noarch::pip-26.0.1-pyh8b19718_0...（省略中间内容）

激活环境：

conda activate mineru

激活后，你的命令行提示符应该会变成类似这样：

(mineru) C:\Users\用户名>

注意：(mineru) 前缀表示你当前正处于 mineru 这个 Conda 环境中。之后所有的命令都需要在这个环境下执行。

验证 Python 版本：

python --version

应输出：Python 3.10.x

4.2 升级 pip 并安装 magic-pdf

首先升级 pip 到最新版本：

pip install --upgrade pip

然后安装 magic-pdf（这是 MinerU 的核心 Python 包）：

pip install -U "magic-pdf[full]" -i https://mirrors.aliyun.com/pypi/simple

命令逐字解释：

pip install — 使用 pip 安装包
-U — 等同于 --upgrade，如果已安装则会升级到最新版
"magic-pdf[full]" — 安装 magic-pdf 的完整版。[full] 表示包含所有可选依赖（OCR、公式识别、表格识别等）。如果只写 magic-pdf 则是最小安装，部分功能不可用
-i https://mirrors.aliyun.com/pypi/simple — 使用阿里云的 PyPI 镜像，国内下载速度远快于官方源

安装过程会发生什么：

pip 会从阿里云镜像源下载 magic-pdf 及其所有依赖包
依赖包包括：PyTorch、OpenCV、PyMuPDF、Numpy、Pillow 等
整个安装过程会下载约 1-2GB 的文件
安装完成后会自动在 Python 环境中注册 magic-pdf 命令

安装完成后，验证安装是否成功：

magic-pdf --version

如果输出类似 magic-pdf, version 1.3.12，说明安装成功。

重要提示：此时安装的是 CPU 版本的 PyTorch，这是正常的——CPU 模式下不需要 CUDA 支持。

4.3 安装模型下载工具

MinerU 需要下载预训练的深度学习模型文件才能正常运行。这些模型文件包括：

布局检测模型（doclayout_yolo）：识别文档中的文字、图片、表格、公式等区域
OCR 模型：识别图片中的文字
公式识别模型（unimernet_small）：识别数学公式
表格识别模型（rapid_table）：识别表格结构

模型文件约 3-5GB，需要从 ModelScope（魔搭社区）或 HuggingFace 下载。

安装 modelscope（模型下载工具）：

pip install modelscope

下载官方模型下载脚本：

# 使用 curl 下载（Windows Git Bash 和 Linux 通用）
curl -L https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/scripts/download_models.py -o download_models.py

如果 jsdelivr 链接无法访问，也可以直接从项目源码中获取：
# 如果你已经 clone 了 MinerU 项目
cp /path/to/MinerU/scripts/download_models.py ./

执行模型下载脚本：

python download_models.py

模型下载过程的输出类似：

2026-04-18 17:41:14,400 - modelscope - INFO - Got 33 files, start to download ...
Downloading Model from https://www.modelscope.cn to directory: C:\Users\Administrator\.cache\modelscope\hub\models\opendatalab\PDF-Extract-Kit-1.0Processing 33 items:   0%|          | 0.00/33.0 [00:00<?, ?it/s]
Downloading [models/OCR/paddleocr_torch/ch_PP-OCRv4_rec_server_doc_infer.pth]:   0%|          | 0.00/96.5M [00:00<?, ?B/s]
...

注意：模型文件总共约 3-5GB，下载时间取决于网速，请耐心等待。下载完成后，模型文件会存放在以下位置：

Windows：C:\Users\用户名\.cache\modelscope\hub\models\opendatalab\PDF-Extract-Kit-1.0

Linux：/home/用户名/.cache/modelscope/hub/models/opendatalab/PDF-Extract-Kit-1.0

4.4 检查并配置 magic-pdf.json

模型下载完成后，系统会自动在你用户目录生成 magic-pdf.json 配置文件。

找到配置文件：

系统	路径
Windows	`C:\Users\你的用户名\magic-pdf.json`
Linux	`/home/你的用户名/magic-pdf.json`
macOS	`/Users/你的用户名/magic-pdf.json`

查看配置文件内容：

在 Windows 上可以直接用记事本打开：

notepad C:\Users\%USERNAME%\magic-pdf.json

在 Linux/macOS 上：

cat ~/magic-pdf.json

一个典型的配置文件内容如下（已去除注释）：

{"bucket_info": {"bucket-name-1": ["ak","sk","endpoint"]},"models-dir": "C:\\Users\\Administrator\\.cache\\modelscope\\hub\\models\\opendatalab\\PDF-Extract-Kit-1.0/models","layoutreader-model-dir": "C:\\Users\\Administrator\\.cache\\modelscope\\hub\\models\\ppaanngggg\\layoutreader","device-mode": "cpu","layout-config": {"model": "doclayout_yolo"},"formula-config": {"mfd_model": "yolo_v8_mfd","mfr_model": "unimernet_small","enable": true},"table-config": {"model": "rapid_table","sub_model": "slanet_plus","enable": true,"max_time": 400}
}

关键字段说明：

字段	说明	默认值
`device-mode`	推理设备：`cpu`、`cuda`、`mps`	模型下载脚本自动设为 `cuda`
`models-dir`	模型文件路径	自动生成的，一般不需要修改
`layout-config.model`	布局检测模型：`doclayout_yolo`	`doclayout_yolo`
`formula-config.enable`	是否启用公式识别	`true`
`table-config.enable`	是否启用表格识别	`true`
`table-config.max_time`	表格识别最大耗时（毫秒）	`400`

CPU 模式下，确保 device-mode 的值为 cpu：

{"device-mode": "cpu"
}

如果当前值是 cuda，请用文本编辑器手动修改为 cpu。

4.5 第一次运行测试

下载一个官方样例 PDF 并测试解析效果：

# 下载样例 PDF（一个包含 OCR 内容的扫描版 PDF）
curl -L https://github.com/opendatalab/MinerU/raw/master/demo/pdfs/small_ocr.pdf -o small_ocr.pdf# 解析 PDF
magic-pdf -p small_ocr.pdf -o ./output

命令逐字解释：

magic-pdf — MinerU 的命令行工具
-p small_ocr.pdf — 指定要解析的 PDF 文件路径（-p 是 --path 的简写）
-o ./output — 指定输出目录（-o 是 --output 的简写），解析结果会保存在 ./output 目录下

运行过程中你会看到类似输出：

2026-04-18 17:57:14.502 | INFO | magic_pdf.data.dataset - lang: None
2026-04-18 17:57:18.912 | INFO | magic_pdf.libs.pdf_detect - detect result: ...
2026-04-18 17:57:19.123 | INFO | magic_pdf.model.doc_analyze - processing page 1...
...

解析完成后，输出目录结构如下：

output/
└── small_ocr/├── small_ocr.md          # Markdown 格式的解析结果├── small_ocr.json        # JSON 格式的解析结果（包含更多结构化信息）├── images/               # 提取出的图片│   ├── 0_0.png│   └── ...└── layout_vis/           # 版面分析可视化（可选）└── ...

打开 small_ocr.md 文件即可查看 Markdown 格式的解析结果。

4.6 CPU 模式性能参考

以 RTX 3050 + i5 配置为例：

文档类型	CPU 模式耗时
纯文字 10 页 PDF	约 2-5 分钟
含图片 50 页 PDF	约 10-20 分钟
扫描版 OCR 20 页 PDF	约 15-30 分钟

提示：CPU 模式下速度较慢，如果需要批量处理大量 PDF，强烈建议使用 GPU 模式。

五、本机 GPU 部署（CUDA 加速）

本章节适合以下用户：

有 NVIDIA 显卡（显存 >= 6GB）
需要高性能解析
需要批量处理 PDF 文件

预计耗时：30-60 分钟（主要取决于 PyTorch 和模型下载速度）

5.1 前置检查：确认你的 GPU 环境

5.1.1 检查 NVIDIA 显卡驱动

nvidia-smi

如果看到类似输出，说明显卡驱动已正确安装：

+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 572.70                 Driver Version: 572.70         CUDA Version: 12.8     |
|-----------------------------------------+------------------------+----------------------+
| GPU  Name                  Driver-Model | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
|=========================================+========================+======================|
|   0  NVIDIA GeForce RTX 3050      WDDM  |   00000000:01:00.0  On |                  N/A |
| 41%   47C    P0             22W /   70W |    1368MiB /   6144MiB |      6%      Default |
+-----------------------------------------+------------------------+----------------------+

如果没有输出或报错：

Windows 用户：前往 NVIDIA 驱动下载页面下载并安装最新驱动
Linux 用户：执行 sudo apt install nvidia-driver-550（或最新版本）

5.1.2 检查 CUDA 版本

在 nvidia-smi 的输出右上角，找到 CUDA Version: 12.8 这样的信息。这表示你的显卡驱动支持的最高 CUDA 版本。

关键理解：这里的 CUDA 版本只是驱动支持的版本号，实际使用时需要安装对应版本的 PyTorch CUDA 运行时库。MinerU 支持的 CUDA 版本为 11.8、12.4、12.6。通常选择 12.4 版本兼容性最好。

5.2 创建 Conda 环境

# 如果之前创建过 mineru 环境，先删除重建
conda env remove -n mineru -y# 创建新环境
conda create -n mineru python=3.10 -y# 激活环境
conda activate mineru# 验证
python --version
# 应输出：Python 3.10.x

5.3 安装 magic-pdf

pip install --upgrade pip
pip install -U "magic-pdf[full]" -i https://mirrors.aliyun.com/pypi/simple

安装完成后验证：

magic-pdf --version
# 应输出：magic-pdf, version 1.x.x

5.4 关键步骤：安装 CUDA 版本的 PyTorch

这是 GPU 部署最容易踩坑的一步！

安装 magic-pdf[full] 时，pip 会自动安装 PyTorch。但默认安装的是 CPU 版本，即使你有显卡也无法使用 GPU 加速。因此必须强制安装 CUDA 版本。

5.4.1 检查当前 PyTorch 版本

python -c "import torch; print(f'PyTorch: {torch.__version__}'); print(f'CUDA: {torch.cuda.is_available()}')"

如果输出类似：

PyTorch: 2.11.0+cpu
CUDA: False

说明当前是 CPU 版本，需要替换。

5.4.2 强制安装 CUDA 版本

根据你的 CUDA 版本选择对应的安装命令：

CUDA 12.4（推荐，兼容性最好）：

pip install --force-reinstall torch torchvision "numpy<=2.1.1" --index-url https://download.pytorch.org/whl/cu124

CUDA 11.8：

pip install --force-reinstall torch torchvision "numpy<=2.1.1" --index-url https://download.pytorch.org/whl/cu118

命令逐字解释：

--force-reinstall — 强制重新安装，即使已经安装了也会覆盖
torch torchvision — PyTorch 核心包和视觉处理库
"numpy<=2.1.1" — 锁定 numpy 版本到 2.1.1 或更低，避免兼容性问题
--index-url https://download.pytorch.org/whl/cu124 — 从 PyTorch 官方的 CUDA 12.4 仓库下载

注意：CUDA 版 PyTorch 体积很大（约 2.5GB），下载需要一定时间。请耐心等待，不要中断安装。

5.4.3 验证 CUDA 版 PyTorch 安装成功

python -c "
import torch
print(f'PyTorch version: {torch.__version__}')
print(f'CUDA available: {torch.cuda.is_available()}')
print(f'CUDA version (compiled): {torch.version.cuda}')
print(f'cuDNN version: {torch.backends.cudnn.version()}')
print(f'Device count: {torch.cuda.device_count()}')
print(f'Device name: {torch.cuda.get_device_name(0)}')
print(f'Device memory: {torch.cuda.get_device_properties(0).total_memory / 1024**3:.1f} GB')
"

正常输出应该类似：

PyTorch version: 2.6.0+cu124
CUDA available: True
CUDA version (compiled): 12.4
cuDNN version: 90100
Device count: 1
Device name: NVIDIA GeForce RTX 3050
Device memory: 6.0 GB

关键检查点：

CUDA available: True — 必须为 True，否则 GPU 不可用
PyTorch version: 2.6.0+cu124 — 版本号中必须包含 +cu124 或 +cu118，如果是 +cpu 则说明没装对

5.5 下载模型文件

与 CPU 模式完全相同：

pip install modelscope
curl -L https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/scripts/download_models.py -o download_models.py
python download_models.py

如果之前 CPU 模式已经下载过模型，可以跳过此步。模型文件是通用的，CPU 和 GPU 共用同一套模型文件。

5.6 修改配置文件启用 GPU

打开用户目录下的 magic-pdf.json 文件，确保 device-mode 设置为 cuda：

{"device-mode": "cuda"
}

模型下载脚本默认会将 device-mode 设置为 cuda，所以你一般不需要手动修改。但如果之前被改成了 cpu，请记得改回来。

5.7 GPU 模式下根据显存调整功能开关

不同显存大小的显卡，能开启的功能不同。请根据自己的情况调整 magic-pdf.json：

6GB 显存（如 RTX 3050）

仅开启基础加速（layout + OCR），关闭公式和表格识别：

{"device-mode": "cuda","formula-config": {"enable": false},"table-config": {"enable": false}
}

8GB 显存（如 RTX 3060）

可以开启公式识别：

{"device-mode": "cuda","formula-config": {"enable": true},"table-config": {"enable": false}
}

10GB+ 显存（如 RTX 3080 / 4070）

可以开启全部功能：

{"device-mode": "cuda","formula-config": {"enable": true},"table-config": {"enable": true}
}

16GB+ 显存（如 RTX 4080 / A10）

最佳性能，可以启用批处理加速：

{"device-mode": "cuda","formula-config": {"enable": true},"table-config": {"enable": true}
}

5.8 GPU 模式第一次运行测试

# 下载测试 PDF
curl -L https://github.com/opendatalab/MinerU/raw/master/demo/pdfs/small_ocr.pdf -o small_ocr.pdf# 解析（GPU 自动加速）
magic-pdf -p small_ocr.pdf -o ./output

运行过程中，你可以打开另一个终端窗口运行 nvidia-smi 来观察 GPU 使用情况：

nvidia-smi -l 1

你应该能看到 GPU 利用率（GPU-Util）和显存占用明显上升。

5.9 GPU vs CPU 性能对比参考

以同一份 20 页扫描版 PDF 为例：

模式	耗时	速度提升
CPU	约 15-30 分钟	基准
GPU (RTX 3050, 6GB)	约 3-8 分钟	约 3-5x
GPU (RTX 3060, 12GB)	约 2-5 分钟	约 5-8x
GPU (RTX 4090, 24GB)	约 1-2 分钟	约 10-15x

六、Docker 部署

Docker 部署适合以下场景：

服务器 / 云端部署
团队多人共用
CI/CD 集成
环境隔离

6.1 前置条件

6.1.1 安装 Docker

Windows 用户：

下载并安装 Docker Desktop：https://www.docker.com/products/docker-desktop/
安装完成后启动 Docker Desktop
在设置中确保 WSL2 后端已启用

Linux（Ubuntu）用户：

# 卸载旧版本（如有）
sudo apt remove -y docker docker-engine docker.io containerd runc# 安装依赖
sudo apt update
sudo apt install -y ca-certificates curl gnupg lsb-release# 添加 Docker 官方 GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg# 添加 Docker 仓库
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null# 安装 Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin# 将当前用户加入 docker 组（避免每次 sudo）
sudo usermod -aG docker $USER# 重新登录使变更生效
# 验证
docker --version

6.1.2 安装 NVIDIA Container Toolkit（GPU 模式需要）

如果你需要在 Docker 容器内使用 GPU 加速，必须安装 NVIDIA Container Toolkit。

Linux 用户：

# 添加 NVIDIA 软件源
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list# 安装
sudo apt update
sudo apt install -y nvidia-container-toolkit# 配置 Docker
sudo nvidia-ctk runtime configure --runtime=docker# 重启 Docker
sudo systemctl restart docker

Windows 用户（Docker Desktop + WSL2）：

Docker Desktop for Windows 默认已包含 NVIDIA GPU 支持，只要确保 WSL2 中的 NVIDIA 驱动已安装即可（通常 Windows 显卡驱动会自动安装到 WSL2 中）。

6.1.3 验证 Docker GPU 支持

docker run --rm --gpus=all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

如果能看到类似 GPU 信息，说明配置正确：

+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 572.70                 Driver Version: 572.70         CUDA Version: 12.8     |
| ... |
|   0  NVIDIA GeForce RTX 3050      WDDM  | ... |
+-----------------------------------------+

如果报错 could not select device driver，请检查 NVIDIA Container Toolkit 是否正确安装。

6.2 下载 Dockerfile

MinerU 官方提供了 Dockerfile，已经配置好了所有依赖和模型下载步骤。

# 下载适用于国内网络的 Dockerfile（使用国内镜像源）
curl -L https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/docker/china/Dockerfile -o Dockerfile

Dockerfile 内容详解：

这个 Dockerfile 做了以下事情：

基础镜像：使用 Ubuntu 22.04
安装 Python 3.10：通过 PPA 仓库安装
创建虚拟环境：在 /opt/mineru_venv 创建 Python 虚拟环境
安装 magic-pdf[full]：使用阿里云镜像源安装
下载模型文件：使用 ModelScope 下载所有模型
设置设备模式：将 device-mode 从 cpu 改为 cuda
安装中文和日文字体：确保 PDF 渲染时中文不会乱
安装 LibreOffice：支持 Word/PPT 文档处理
安装 poppler-utils：PDF 处理工具

6.3 构建 Docker 镜像

docker build -t mineru:latest .

构建过程说明：

Docker 会按顺序执行 Dockerfile 中的每一条指令：

Step 1/10: FROM ubuntu:22.04 — 拉取 Ubuntu 22.04 基础镜像
Step 2/10: ENV DEBIAN_FRONTEND=noninteractive — 设置非交互模式
Step 3/10: RUN apt-get update && apt-get install -y ... — 安装系统依赖（约 500MB）
Step 4/10: RUN update-alternatives ... — 设置 Python 3.10 为默认
Step 5/10: RUN python3 -m venv /opt/mineru_venv — 创建虚拟环境
Step 6/10: RUN pip3 install magic-pdf[full] — 安装 MinerU（约 2GB，最耗时）
Step 7/10: RUN pip3 install modelscope && python3 download_models.py — 下载模型（约 3-5GB）
...

预计构建时间：30-60 分钟，取决于网速。主要耗时在步骤 6（安装包下载）和步骤 7（模型下载）。

构建完成后，验证镜像是否创建成功：

docker images | grep mineru

应输出类似：

mineru    latest    abc123def456    2 minutes ago    10GB

6.4 运行 Docker 容器

6.4.1 CPU 模式运行

docker run -it --name mineru mineru:latest /bin/bash -c "source /opt/mineru_venv/bin/activate && exec bash"

命令逐字解释：

docker run — 运行一个容器
-it — 交互式终端（-i 保持标准输入，-t 分配伪终端）
--name mineru — 给容器起名为 mineru
mineru:latest — 使用的镜像名称和标签
/bin/bash -c "source /opt/mineru_venv/bin/activate && exec bash" — 启动后自动激活虚拟环境，然后进入 bash 交互模式

进入容器后：

# 验证安装
magic-pdf --version# 解析 PDF
magic-pdf -p /path/to/file.pdf -o /path/to/output

6.4.2 GPU 模式运行

docker run -it --name mineru --gpus=all mineru:latest /bin/bash -c "source /opt/mineru_venv/bin/activate && exec bash"

与 CPU 模式唯一的区别是多了 --gpus=all 参数，这会让容器能够访问宿主机的所有 GPU。

6.4.3 挂载宿主机目录

如果你需要让容器访问宿主机上的 PDF 文件，需要使用 -v 参数挂载目录：

# Windows（使用 Git Bash / WSL）
docker run -it --gpus=all \-v /d/pdfs:/data/pdfs \-v /d/output:/data/output \mineru:latest \/bin/bash -c "source /opt/mineru_venv/bin/activate && exec bash"# Linux
docker run -it --gpus=all \-v /home/user/pdfs:/data/pdfs \-v /home/user/output:/data/output \mineru:latest \/bin/bash -c "source /opt/mineru_venv/bin/activate && exec bash"

挂载后，在容器内访问 /data/pdfs 就相当于访问宿主机的 /d/pdfs（Windows）或 /home/user/pdfs（Linux）。

然后在容器内执行：

magic-pdf -p /data/pdfs/sample.pdf -o /data/output

6.5 一行命令直接解析（不进入容器）

你也可以不进入容器交互，直接用一行命令解析 PDF：

docker run --rm --gpus=all \-v /d/pdfs:/data \mineru:latest \magic-pdf -p /data/sample.pdf -o /data/output

说明：

--rm — 容器运行结束后自动删除
这条命令会启动容器、运行 magic-pdf 命令、输出结果到挂载目录、然后清理容器

6.6 Docker Compose 方式（持久服务）

如果你希望以配置文件的方式管理 MinerU 容器，可以使用 Docker Compose。

创建 docker-compose.yml 文件：

version: '3.8'services:mineru:image: mineru:latestcontainer_name: minerudeploy:resources:reservations:devices:- driver: nvidiacount: allcapabilities: [gpu]volumes:- ./pdfs:/data/pdfs- ./output:/data/outputstdin_open: truetty: truerestart: unless-stopped

启动：

# 启动容器并进入交互模式
docker compose up -d
docker compose exec mineru /bin/bash -c "source /opt/mineru_venv/bin/activate && exec bash"# 在容器内执行解析
magic-pdf -p /data/pdfs/sample.pdf -o /data/output

停止：

docker compose down

七、Gradio Web 界面部署

MinerU 提供了基于 Gradio 的 Web 图形界面，适合不喜欢命令行的用户使用。

7.1 前置条件

确保你已经完成了本机 CPU 部署或本机 GPU 部署。

7.2 安装 Gradio 依赖

conda activate mineru
pip install gradio gradio-pdf

依赖说明：

gradio — Web 界面框架
gradio-pdf — PDF 预览组件

7.3 获取 Gradio 应用代码

MinerU 项目中包含了 Gradio 应用的示例代码，位于 projects/gradio_app/ 目录下。

如果你是通过 git clone 获取的项目：

cd projects/gradio_app

如果你没有 clone 整个项目，可以手动创建一个 app.py 文件：

import gradio as gr
from gradio_pdf import PDF
from magic_pdf.tools.cli import do_parse
import os
import tempfiledef parse_pdf(pdf_file):"""解析 PDF 文件并返回 Markdown 内容"""output_dir = tempfile.mkdtemp()result = do_parse(pdf_file, output_dir)return result# 创建 Gradio 界面
with gr.Blocks(title="MinerU PDF Parser") as demo:gr.Markdown("# MinerU PDF 解析器")with gr.Row():with gr.Column():pdf_input = gr.File(label="上传 PDF 文件", file_types=[".pdf"])parse_btn = gr.Button("开始解析")with gr.Column():pdf_preview = PDF(label="PDF 预览")md_output = gr.Markdown(label="解析结果")parse_btn.click(fn=parse_pdf,inputs=[pdf_input],outputs=[md_output])if __name__ == "__main__":demo.launch(server_name="0.0.0.0", server_port=7860)

注意：以上代码是一个简化示例。完整的 Gradio 应用请参考 MinerU 项目中的 projects/gradio_app/app.py。

7.4 启动应用

python app.py

启动后，终端会输出类似以下信息：

Running on local URL:  http://127.0.0.1:7860

7.5 访问 Web 界面

打开浏览器，访问：

http://127.0.0.1:7860

7.6 外网访问（可选）

如果你希望从其他设备访问，在启动时指定 server_name：

python app.py --server-name 0.0.0.0 --server-port 7860

然后通过 http://你的IP地址:7860 访问。

八、CPU 与 GPU 推理方式详解

本章节详细介绍 MinerU 的两种推理模式的使用方法。

8.1 推理模式对比

特性	CPU 模式	GPU 模式
设备要求	无特殊要求	NVIDIA 显卡，显存 >= 6GB
速度	较慢	快 3-15 倍
适用场景	小批量、非实时	批量处理、实时解析
配置	`device-mode: cpu`	`device-mode: cuda`
内存占用	较高（16GB+）	较低（显存分担）

8.2 切换推理模式

切换模式只需要修改 magic-pdf.json 中的 device-mode 字段：

切换到 CPU：

{"device-mode": "cpu"
}

切换到 GPU：

{"device-mode": "cuda"
}

切换到 MPS（Apple Silicon Mac）：

{"device-mode": "mps"
}

注意：切换到 GPU 模式前，请确保已经安装了 CUDA 版本的 PyTorch（参见 5.4 节）。

8.3 命令行使用

命令行用法在 CPU 和 GPU 模式下完全相同：

# 解析单个文件
magic-pdf -p sample.pdf -o ./output# 指定 OCR 语言（默认为 auto，自动检测）
magic-pdf -p sample.pdf -o ./output --lang ch# 指定解析方法（默认 auto，自动检测文档类型）
magic-pdf -p sample.pdf -o ./output --method auto

所有可用参数：

magic-pdf --help

输出类似：

Usage: magic-pdf [OPTIONS]Options:-p, --path PATH        PDF 文件路径（必填）-o, --output PATH      输出目录（必填）--lang TEXT            OCR 语言，默认为 auto--method TEXT          解析方法，默认为 auto-h, --help             显示帮助信息

8.4 批量处理

方法一：Shell 脚本批量处理

#!/bin/bash# 设置输入输出目录
INPUT_DIR="/path/to/pdfs"
OUTPUT_DIR="./output"# 创建输出目录
mkdir -p "$OUTPUT_DIR"# 遍历目录下所有 PDF 文件
for pdf_file in "$INPUT_DIR"/*.pdf; do# 获取文件名（不含扩展名）filename=$(basename "$pdf_file" .pdf)echo "正在解析: $filename"# 解析 PDFmagic-pdf -p "$pdf_file" -o "$OUTPUT_DIR"echo "完成: $filename"echo "---"
doneecho "全部解析完成！"

保存为 batch_parse.sh，然后执行：

# Linux / macOS
chmod +x batch_parse.sh
./batch_parse.sh# Windows（Git Bash）
bash batch_parse.sh

方法二：Python 脚本批量处理

创建 batch_parse.py：

import os
import glob
from magic_pdf.tools.cli import do_parse# 设置输入输出目录
INPUT_DIR = "/path/to/pdfs"
OUTPUT_DIR = "./output"# 创建输出目录
os.makedirs(OUTPUT_DIR, exist_ok=True)# 获取所有 PDF 文件
pdf_files = glob.glob(os.path.join(INPUT_DIR, "*.pdf"))print(f"找到 {len(pdf_files)} 个 PDF 文件")for i, pdf_path in enumerate(pdf_files, 1):filename = os.path.basename(pdf_path)print(f"[{i}/{len(pdf_files)}] 正在解析: {filename}")try:do_parse(pdf_path, OUTPUT_DIR)print(f"  完成: {filename}")except Exception as e:print(f"  失败: {filename} - {e}")print("全部解析完成！")

执行：

conda activate mineru
python batch_parse.py

8.5 Python API 调用

如果你希望在 Python 代码中调用 MinerU，可以使用以下方式：

方法一：使用 API 接口

from magic_pdf.model.doc_analyze_by_custom_model import doc_analyze
from magic_pdf.data.dataset import PymuPDFDataset
from magic_pdf.tools.common import do_parse# 加载 PDF 文件
pdf_path = "sample.pdf"
dataset = PymuPDFDataset(pdf_path)# 执行版面分析（自动使用配置文件中的 device-mode）
result = doc_analyze(dataset, model_name="doclayout_yolo")# 解析并导出
do_parse(pdf_path,dataset,result,output_dir="./output",# 可选参数# lang="ch",           # 指定 OCR 语言# method="auto",       # 指定解析方法
)

方法二：使用 CLI 模块

from magic_pdf.tools.cli import do_parse# 一行代码搞定
result = do_parse("sample.pdf", "./output")print(result)

8.6 监控 GPU 使用情况

在 GPU 模式下运行时，可以在另一个终端窗口监控 GPU 使用情况。

Linux / Windows：

# 每秒刷新一次
nvidia-smi -l 1

输出示例：

Every 1.0s: nvidia-smi+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 572.70                 Driver Version: 572.70         CUDA Version: 12.8     |
|-----------------------------------------+------------------------+----------------------+
| GPU  Name                  Driver-Model | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
|=========================================+========================+======================|
|   0  NVIDIA GeForce RTX 3050      WDDM  |   00000000:01:00.0  On |                  N/A |
| 65%   72C    P2             65W /   70W |    4892MiB /   6144MiB |     95%      Default |
+-----------------------------------------+------------------------+----------------------+

关键指标：

GPU-Util: 95% — GPU 利用率，越高说明 GPU 越充分地被利用
Memory-Usage: 4892MiB / 6144MiB — 显存使用量，如果接近上限可能会 OOM
Temp: 72C — GPU 温度，超过 85C 建议增加散热

九、常见问题排查 FAQ

Q1: 安装时出现依赖冲突怎么办？

问题描述： 安装 magic-pdf[full] 时 pip 报错，提示某些包版本冲突。

解决方案：

使用干净的 Conda 环境

# 删除旧环境
conda env remove -n mineru -y# 重新创建
conda create -n mineru python=3.10 -y
conda activate mineru# 升级 pip
pip install --upgrade pip# 重新安装
pip install -U "magic-pdf[full]" -i https://mirrors.aliyun.com/pypi/simple

如果仍然失败，尝试逐个安装依赖

pip install numpy==2.1.1
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124
pip install "magic-pdf[full]" -i https://mirrors.aliyun.com/pypi/simple

Q2: CUDA 不可用（torch.cuda.is_available() 返回 False）

问题描述： 明明有 NVIDIA 显卡，但 GPU 就是无法使用。

排查步骤：

步骤 1：检查 PyTorch 版本

python -c "import torch; print(torch.__version__)"

如果输出中包含 +cpu（如 2.11.0+cpu），说明安装的是 CPU 版本。

步骤 2：强制安装 CUDA 版本

pip install --force-reinstall torch torchvision "numpy<=2.1.1" --index-url https://download.pytorch.org/whl/cu124

步骤 3：验证

python -c "import torch; print(torch.cuda.is_available())"
# 应输出: True

步骤 4：如果仍然为 False

检查 NVIDIA 驱动是否正确安装：

nvidia-smi

如果这个命令报错，说明显卡驱动有问题，需要先修复驱动。

Q3: 模型下载失败

问题描述： 执行 python download_models.py 时报网络连接错误。

解决方案 1：使用 HuggingFace 镜像

pip install huggingface_hub# 下载 HuggingFace 版本的模型下载脚本
curl -L https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/scripts/download_models_hf.py -o download_models_hf.py
python download_models_hf.py

解决方案 2：手动下载模型

如果脚本也下载不了，可以手动从 ModelScope 网站下载：

访问 https://www.modelscope.cn/models/opendatalab/PDF-Extract-Kit-1.0
下载所有文件到 ~/.cache/modelscope/hub/models/opendatalab/PDF-Extract-Kit-1.0 目录
手动修改 magic-pdf.json 中的 models-dir 路径

Q4: 运行时显存不足 (OOM)

问题描述： 运行时报错 CUDA out of memory。

解决方案：

方案 1：关闭部分功能

编辑 magic-pdf.json：

{"table-config": {"enable": false},"formula-config": {"enable": false}
}

方案 2：减少批处理大小

如果你有大批量 PDF 需要处理，建议逐个处理而非批量：

# 不要同时解析多个文件
magic-pdf -p file1.pdf -o ./output
magic-pdf -p file2.pdf -o ./output

方案 3：升级显卡或使用 CPU 模式

如果显存实在不够，可以切换到 CPU 模式：

{"device-mode": "cpu"
}

Q5: Windows 下中文路径或输出乱码

问题描述： 使用中文路径的文件无法解析，或者输出内容中文乱码。

解决方案：

配置文件路径使用双反斜杠

{"models-dir": "C:\\Users\\张三\\.cache\\modelscope\\hub\\models\\opendatalab\\PDF-Extract-Kit-1.0\\models"
}

PowerShell 中设置 UTF-8 编码

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

尽量使用英文路径

为了避免编码问题，建议 PDF 文件路径使用英文。

Q6: Docker 容器内无法访问 GPU

问题描述： 在 Docker 容器内运行 nvidia-smi 报错。

排查步骤：

确认 NVIDIA Container Toolkit 已安装

# 检查是否安装
dpkg -l | grep nvidia-container-toolkit

确认 Docker 已配置 NVIDIA 运行时

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

运行容器时必须加上 --gpus=all 参数

docker run --gpus=all ...

Q7: 解析结果不符合预期

问题描述： 解析出的 Markdown 内容缺失图片、公式或表格。

排查步骤：

确认所有功能已启用

检查 magic-pdf.json 中 formula-config.enable 和 table-config.enable 是否为 true。

查看日志输出

MinerU 运行时会输出详细信息，注意查看是否有 WARNING 或 ERROR 级别的日志。

尝试更新模型

pip install modelscope
curl -L https://gcore.jsdelivr.net/gh/opendatalab/MinerU@master/scripts/download_models.py -o download_models.py
python download_models.py

Q8: 如何更新 MinerU 到最新版本？

conda activate mineru# 更新 magic-pdf
pip install -U "magic-pdf[full]" -i https://mirrors.aliyun.com/pypi/simple# 更新模型文件
python download_models.py

十、总结与部署方案选择建议

10.1 各部署方式对比

部署方式	适合谁	安装难度	速度	维护成本
本机 CPU	个人体验、无 GPU 设备	低	慢	低
本机 GPU	日常使用、有 GPU 设备	中	快	低
Docker CPU	服务器部署、团队协作	低	慢	低
Docker GPU	生产环境、CI/CD 集成	中	快	中
Gradio Web	非技术用户	低	取决于底层	低

10.2 推荐部署方案

场景一：个人开发/体验

推荐：本机 GPU 部署
理由：最简单直接的方式，conda 环境隔离，不影响系统其他配置
预计安装时间：30-60 分钟

场景二：团队/生产环境

推荐：Docker GPU 部署
理由：环境一致性好，方便部署到任何支持 Docker 的平台
预计安装时间：60-120 分钟（含构建镜像）

场景三：无 GPU 设备 / 快速体验

推荐：本机 CPU 部署
理由：无需显卡即可运行，适合先体验效果
预计安装时间：20-40 分钟

场景四：提供 Web 服务给非技术人员

推荐：本机 GPU + Gradio Web 界面
理由：图形界面友好，上传 PDF 即可查看结果
预计安装时间：30-60 分钟

10.3 快速命令速查表

操作	命令
创建环境	`conda create -n mineru python=3.10 -y`
激活环境	`conda activate mineru`
安装 MinerU	`pip install -U "magic-pdf[full]" -i https://mirrors.aliyun.com/pypi/simple`
安装 CUDA PyTorch	`pip install --force-reinstall torch torchvision "numpy<=2.1.1" --index-url https://download.pytorch.org/whl/cu124`
验证 GPU	`python -c "import torch; print(torch.cuda.is_available())"`
下载模型	`python download_models.py`
解析 PDF	`magic-pdf -p sample.pdf -o ./output`
监控 GPU	`nvidia-smi -l 1`
Docker 构建	`docker build -t mineru:latest .`
Docker 运行	`docker run -it --gpus=all mineru:latest /bin/bash -c "source /opt/mineru_venv/bin/activate && exec bash"`
查看版本	`magic-pdf --version`

最后提示：如果你在安装过程中遇到本文未覆盖的问题，可以前往 MinerU GitHub Issues 搜索是否有类似问题的解决方案，或者提交新的 Issue 寻求帮助。提交 Issue 时请附上你的操作系统版本、Python 版本、显卡型号以及完整的错误日志，这样开发者才能更快地定位和解决问题。

查看全文

http://www.jsqmd.com/news/662165/