MinerU_安装部署完全指南

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

MinerU 是由 OpenDataLab 开源的 PDF 文档解析工具，GitHub 星标 25000+，GitHub 地址：https://github.com/opendatalab/MinerU。它可以将 PDF 精准转换为 Markdown、JSON 等格式，支持 OCR 109 种语言识别、公式转 LaTeX、表格转 HTML、自动阅读顺序排序、标题分级、水印过滤等功能。
当前版本：v3.1.x

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

一、硬件与软件环境要求
二、安装前的准备工作
三、CPU 部署（纯 CPU 环境）
四、GPU 部署（Conda + CUDA 加速）
五、Docker 部署
六、Gradio Web 界面部署
七、HTTP Client/Server 分离部署
八、常用命令与使用方式
九、常见问题排查 FAQ
十、总结与方案选择

一、硬件与软件环境要求

1.1 硬件要求

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

GPU 支持：所有 2017 年及之后的 NVIDIA 显卡（RTX 20/30/40 系列、GTX 16 系列、Tesla/A100/H100 等）。不满足可用 CPU 模式。

1.2 软件要求

软件	版本	说明
操作系统	Windows 10/11、Linux (2019+)、macOS 14+	三平台均可用
Python	3.10 ~ 3.12（Windows 不支持 3.13）	通过 Conda 管理
Conda	任意版本	强烈推荐用于环境管理
NVIDIA 驱动	最新	仅 GPU 模式需要

1.3 检查 GPU 和 CUDA（GPU 用户必看）

nvidia-smi

输出示例：

+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 572.70                 Driver Version: 572.70         CUDA Version: 12.8     |
|-----------------------------------------+------------------------+----------------------+
|   0  NVIDIA GeForce RTX 3050      WDDM  |   00000000:01:00.0  On |                  N/A |
| 41%   44C    P0             25W /   70W |    1050MiB /   6144MiB |      0%      Default |
+-----------------------------------------+------------------------+----------------------+

关键信息：

CUDA Version: 12.8 — 驱动支持的最高 CUDA 版本
RTX 3050 / 6144MiB — 显卡型号和 6GB 显存

注意：这里的 CUDA 版本是驱动支持的上限。安装 PyTorch 时选择 cu124（CUDA 12.4） 兼容性最好，向下兼容。

二、安装前的准备工作

2.1 安装 Conda

Windows 用户：

前往清华大学镜像站下载：https://mirrors.tuna.tsinghua.edu.cn/anaconda/archive/

选择最新版本（如 Anaconda3-2020.11-Windows-x86.exe），下载后运行安装程序。

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 --version
# 应输出：conda 24.x.x

2.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

2.3 创建并激活 Conda 虚拟环境

conda create -n mineru python=3.12 -y
conda activate mineru

为什么选 Python 3.12？ Windows 下 ray 依赖不支持 Python 3.13，3.12 是当前最佳选择。

2.4 配置 pip 国内镜像源

pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
pip config set global.trusted-host mirrors.aliyun.com

安装 uv（比 pip 更快的包安装工具）：

pip install uv

三、CPU 部署（纯 CPU 环境）

适用场景： 没有 NVIDIA 显卡、只需快速体验、偶尔解析少量 PDF。
预计耗时： 20-40 分钟（主要取决于模型下载速度）

3.1 安装 MinerU

uv pip install -U "mineru[all]"

重要提醒：这条命令安装的是 CPU 模式！

mineru[all] 会自动安装 PyTorch 的 CPU 版本。即使你有 NVIDIA 显卡，执行这条命令后也 无法使用 GPU 加速。

如果你的设备有 NVIDIA 显卡且希望使用 GPU 加速，请跳到第四章 GPU 部署。

3.2 下载模型文件

国内用户使用 ModelScope（魔搭）源：

mineru-models-download -s modelscope -m all

模型文件约 3-5GB，下载完成后会自动生成配置文件 mineru.json（位于用户目录）。

3.3 运行测试

建议显式指定 pipeline 后端（轻量、稳定、纯 CPU 即可运行）：

mineru -p "你的PDF路径" -o "输出目录" -b pipeline

例如：

mineru -p "demo1.pdf" -o "./output" -b pipeline

解析完成后，输出目录会包含 .md（Markdown）和 .json 等格式的结果文件。

CPU 模式速度较慢，处理 10 页纯文字 PDF 约需 2-5 分钟。如果需要批量处理大量 PDF，建议使用 GPU 模式。

四、GPU 部署（Conda + CUDA 加速）

适用场景： 有 NVIDIA 显卡（显存 >= 6GB），需要高性能解析，批量处理 PDF。
预计耗时： 30-60 分钟（主要取决于 PyTorch 和模型下载速度）
速度提升： 相比 CPU 模式快 3-15 倍

4.1 安装 MinerU

uv pip install -U "mineru[all]"

关键说明： 这一步会自动安装 PyTorch 的 CPU 版本。因此接下来必须执行第 4.2 步手动覆盖为 CUDA 版本。

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

这是最容易踩坑的一步！ 如果你只执行了 uv pip install -U "mineru[all]" 就开始使用，那么你用的仍然是 CPU 模式，即使你有 RTX 显卡。

必须手动将 PyTorch 替换为 CUDA 版本：

pip install --force-reinstall torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

命令解释：

--force-reinstall — 强制重新安装，覆盖 mineru[all] 自动安装的 CPU 版 PyTorch

--index-url .../cu124 — 从 PyTorch 官方 CUDA 12.4 仓库下载

虽然你的 CUDA 驱动可能是 12.8，但 cu124 向下兼容，兼容性最好

4.3 验证 CUDA 可用

python -c "import torch; print('CUDA:', torch.cuda.is_available()); print('Device:', torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'None')"

正常输出：

CUDA: True
Device: NVIDIA GeForce RTX 3050

必须看到 CUDA: True，否则 GPU 不可用！ 如果返回 False，说明 PyTorch 仍是 CPU 版本，请重新执行 4.2 步。

4.4 下载模型文件

mineru-models-download -s modelscope -m all

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

4.5 运行测试

GPU 模式下直接运行即可，会自动使用 GPU 加速：

mineru -p "你的PDF路径" -o "输出目录"

例如：

mineru -p "demo1.pdf" -o "./output"

运行过程中可以在另一个终端窗口运行 nvidia-smi -l 1 观察 GPU 使用情况，应该能看到 GPU 利用率和显存占用上升。

4.6 CPU vs GPU 性能对比参考

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

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

4.6 监控 GPU 使用情况

运行解析任务时，在另一个终端窗口运行：

nvidia-smi -l 1

关键指标：

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

五、Docker 部署

适合服务器部署、团队协作、CI/CD 集成、环境隔离等场景。

仅支持 Linux 和 Windows（WSL2）。macOS 用户请用前面提到的 Conda 方式。

5.1 前置条件

已安装 Docker（Windows 用户安装 Docker Desktop 并启用 WSL2 后端）
GPU 模式还需安装 NVIDIA Container Toolkit

验证 Docker GPU 支持：

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

5.2 获取 Dockerfile

MinerU 项目自带两个 Dockerfile：

文件	适用场景	模型源
`docker/china/Dockerfile`	国内用户	ModelScope（魔搭）
`docker/global/Dockerfile`	海外用户	HuggingFace

国内用户：

# 如果你已 clone 项目，进入目录
cd MinerU/docker/china

# 或者复制 Dockerfile 到空目录
cp MinerU/docker/china/Dockerfile ./

5.3 构建镜像

docker build -t mineru:latest .

构建过程约 30-60 分钟，主要耗时在下载安装包和模型。

5.4 运行容器

进入容器交互：

docker run -it --name mineru --gpus=all mineru:latest /bin/bash

挂载宿主机目录解析：

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

说明： -v 挂载目录，--rm 容器运行结束后自动删除，--gpus=all 启用 GPU。

CPU 模式运行（去掉 --gpus=all）：

docker run --rm -v /d/pdfs:/data/pdfs -v /d/output:/data/output mineru:latest mineru -p /data/pdfs/sample.pdf -o /data/output -b pipeline

六、Gradio Web 界面部署

提供图形化 Web 界面，适合不喜欢命令行的用户。

6.1 启动 Gradio

conda activate mineru
mineru-gradio --server-name 0.0.0.0 --server-port 7860

6.2 访问

浏览器打开：http://127.0.0.1:7860

外网访问：http://你的IP地址:7860

MinerU Gradio 界面

MinerU Gradio 界面展示

七、HTTP Client/Server 分离部署

这种架构将 MinerU 的推理服务和客户端调用分离，适合 分布式部署、多机协同、边缘设备接入 等场景。推理服务运行在一台机器上（通常是有 GPU 的服务器），客户端通过 HTTP 协议发送解析请求并获取结果。

核心优势： 客户端机器不需要安装 PyTorch 等重型依赖，只需一个轻量 HTTP Client 即可调用远程 GPU 服务器的解析能力。

7.1 架构说明

MinerU 提供两种 HTTP Client 后端：

后端名称	说明	本地依赖要求
`vlm-http-client`	轻量远程客户端，通过 HTTP 调用远程 VLM 服务	不要求本地安装 torch
`hybrid-http-client`	混合模式，需要本地具备 pipeline 依赖	需要本地安装 `mineru[pipeline]` 及 torch 等依赖

7.2 启动 OpenAI 兼容服务器

首先在有 GPU 的机器上启动推理服务（需要先安装 vllm 或 lmdeploy 环境）：

# 启动 OpenAI 兼容服务器，默认端口 30000
mineru-openai-server --port 30000

Tip： 该服务基于 vllm 或 lmdeploy 推理框架，因此需要预先安装对应环境：
# 安装 vllm 环境
pip install vllm
# 或安装 lmdeploy 环境
pip install lmdeploy

服务启动后，会监听 http://127.0.0.1:30000（或你指定的地址）。

7.3 使用 HTTP Client 连接服务器

在另一个终端中，使用 HTTP Client 连接 OpenAI 兼容服务器进行文档解析：

# 使用 hybrid-http-client 后端（需要本地有 pipeline 依赖）
mineru -p <input_path> -o <output_path> -b hybrid-http-client -u http://127.0.0.1:30000

# 使用 vlm-http-client 后端（轻量，不要求本地安装 torch）
mineru -p <input_path> -o <output_path> -b vlm-http-client -u http://127.0.0.1:30000

参数说明：

-p <input_path> — 要解析的 PDF/图片/DOCX 等文件路径
-o <output_path> — 输出目录
-b — 指定后端类型（hybrid-http-client 或 vlm-http-client）
-u — 远程 OpenAI 兼容服务器的地址

7.4 典型部署场景

场景一：本机 Server + Client

所有组件在同一台机器上运行，适合单机多进程并行处理：

# 终端 1：启动服务器
mineru-openai-server --port 30000

# 终端 2：发起解析请求
mineru -p document.pdf -o ./output -b hybrid-http-client -u http://127.0.0.1:30000

场景二：远程服务器 + 轻量客户端

服务器（有 GPU）运行推理服务，客户端（无 GPU、无 PyTorch）远程调用：

# 服务器端（192.168.1.100，有 GPU）
mineru-openai-server --port 30000 --host 0.0.0.0

# 客户端（无 GPU 的笔记本）
mineru -p document.pdf -o ./output -b vlm-http-client -u http://192.168.1.100:30000

vlm-http-client 的优势： 客户端只需安装 mineru 核心包，不需要 torch 等重型依赖，非常适合边缘设备或资源受限的环境。

场景三：多客户端共享一台 GPU 服务器

多个客户端同时连接一台 GPU 服务器，实现资源复用：

客户端 A (192.168.1.10) ──┐
客户端 B (192.168.1.11) ──┤── GPU 服务器 (192.168.1.100:30000)
客户端 C (192.168.1.12) ──┘

每个客户端使用相同的服务器地址发起解析请求。

八、常用命令与使用方式

7.1 命令行解析

# 基本用法（自动选择后端，GPU 用户优先使用此方式）
mineru -p <PDF路径> -o <输出目录>

# 指定 pipeline 后端（CPU 用户推荐）
mineru -p <PDF路径> -o <输出目录> -b pipeline

# 指定 hybrid-auto-engine 后端（GPU 用户，高精度）
mineru -p <PDF路径> -o <输出目录> -b hybrid-auto-engine

# 指定 vlm-auto-engine 后端（GPU 用户，VLM 高精度）
mineru -p <PDF路径> -o <输出目录> -b vlm-auto-engine

7.2 常用命令速查

操作	命令
创建环境	`conda create -n mineru python=3.12 -y`
激活环境	`conda activate mineru`
安装 MinerU	`uv pip install -U "mineru[all]"`
安装 CUDA PyTorch（GPU 必须）	`pip install --force-reinstall torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124`
验证 GPU	`python -c "import torch; print(torch.cuda.is_available())"`
下载模型（国内）	`mineru-models-download -s modelscope -m all`
下载模型（海外）	`mineru-models-download -s huggingface -m all`
解析 PDF	`mineru -p sample.pdf -o ./output`
启动 Gradio	`mineru-gradio --server-name 0.0.0.0 --server-port 7860`
启动 OpenAI 兼容服务器	`mineru-openai-server --port 30000`
HTTP Client 远程调用	`mineru -p sample.pdf -o ./output -b vlm-http-client -u http://服务器IP:30000`
查看版本	`mineru --version`
查看帮助	`mineru --help`

7.3 配置文件说明

模型下载后自动生成 mineru.json（位于用户目录），内容示例：

{
    "models-dir": {
        "pipeline": "C:\\Users\\用户名\\.cache\\modelscope\\hub\\models\\OpenDataLab\\PDF-Extract-Kit-1___0",
        "vlm": "C:\\Users\\用户名\\.cache\\modelscope\\hub\\models\\OpenDataLab\\MinerU2___5-Pro-2604-1___2B"
    },
    "config_version": "1.3.1"
}

字段	说明
`models-dir.pipeline`	pipeline 后端模型路径
`models-dir.vlm`	VLM 后端模型路径

7.4 可用后端一览

后端名称	特点	适用场景
`pipeline`	快速稳定、无需 GPU	CPU 用户、追求速度
`hybrid-auto-engine`	高精度，原生文本提取	高精度需求、GPU 用户
`vlm-auto-engine`	VLM 视觉语言模型	复杂版面、GPU 用户
`vlm-http-client`	轻量远程客户端，不要求本地安装 torch	边缘设备、远程调用
`hybrid-http-client`	混合 HTTP 客户端	需要本地 pipeline 依赖

7.5 Python API 调用

from mineru.tools.cli import do_parse

# 一行代码解析
do_parse("sample.pdf", "./output")

九、常见问题排查 FAQ

Q1: `uv pip install -U "mineru[all]"` 后 GPU 不可用？

这是最常见的误区！

mineru[all] 依赖中包含 PyTorch，但 pip 默认安装的是 CPU 版本。即使你有 NVIDIA 显卡，执行这条命令后也只能用 CPU 模式。

解决方案： 安装完成后，再执行一条命令覆盖为 CUDA 版 PyTorch：

pip install --force-reinstall torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

然后验证：

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

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

解决方案： 使用干净的 Conda 环境

conda env remove -n mineru -y
conda create -n mineru python=3.12 -y
conda activate mineru
pip install uv
uv pip install -U "mineru[all]"
# GPU 用户继续执行：
pip install --force-reinstall torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

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

排查步骤：

步骤 1：确认当前 PyTorch 版本

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

如果版本号中不包含 +cu124（如显示 2.8.0+cpu），说明是 CPU 版本。

步骤 2：强制安装 CUDA 版本

pip install --force-reinstall torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

步骤 3：验证

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

步骤 4：如果仍然为 False

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

nvidia-smi

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

Q4: 模型下载失败

解决方案： 切换到另一个镜像源

# 如果 ModelScope 下载失败，换 HuggingFace
mineru-models-download -s huggingface -m all

Q5: 显存不足 (OOM)

解决方案： 换用轻量后端

# 使用 pipeline 后端（显存占用最低）
mineru -p sample.pdf -o ./output -b pipeline

Q6: Windows 中文路径问题

为避免编码问题，PDF 文件路径尽量使用英文。

Q7: 如何更新到最新版本？

conda activate mineru
uv pip install -U "mineru[all]"
# GPU 用户别忘了重新安装 CUDA 版 PyTorch
pip install --force-reinstall torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
mineru-models-download -s modelscope -m all

十、总结与方案选择

9.1 各部署方式对比

部署方式	适合谁	安装难度	速度	维护成本
本机 CPU	个人体验、无 GPU	低	慢	低
本机 GPU	日常使用、有 GPU	中	快 3-15 倍	低
Docker	服务器、团队协作	中	取决于配置	低
Gradio Web	非技术用户	低	取决于底层	低
HTTP Client/Server	分布式部署、多机协同	中高	取决于服务器配置	中

9.2 推荐方案

场景	推荐	预计时间
个人体验（无 GPU）	本机 CPU 部署	20-40 分钟
个人体验（有 GPU）	本机 GPU 部署	30-60 分钟
团队/生产环境	Docker GPU 部署	60-120 分钟
提供 Web 服务	GPU + Gradio	30-60 分钟
多机协同/边缘设备	HTTP Client/Server	30-60 分钟

9.3 关键区别速览：CPU vs GPU 安装

步骤	CPU 模式	GPU 模式
安装 MinerU	`uv pip install -U "mineru[all]"`	`uv pip install -U "mineru[all]"`
安装 CUDA PyTorch	不需要	必须：`pip install --force-reinstall torch ... --index-url .../cu124`
验证	`python -c "import torch; print(torch.cuda.is_available())"` 返回 `False` 正常	必须返回 `True`
运行	`mineru -p xxx.pdf -o ./output -b pipeline`	`mineru -p xxx.pdf -o ./output`

遇到问题？ 前往 MinerU GitHub Issues 搜索或提交，附上操作系统版本、Python 版本、显卡型号及完整错误日志。

posted @ 2026-04-18 18:37 yejinxing 阅读(12241) 评论(7) 收藏举报

刷新页面返回顶部

yejinxing