在服务器上部署 MinerU 的完整实践指南
在深度学习的应用场景中，部署往往是最让人头疼的一环。对于研究者和开发者来说，如何在服务器环境下顺利跑通工具，既考验基础环境配置能力，也涉及到显卡驱动、CUDA 兼容、依赖管理等多方面的知识。本文结合实验室在 AutoDL 平台上部署 MinerU 的过程，从环境准备到实际使用，整理成一份详尽的实践指南。
一、环境与硬件要求
在动手之前，需要明确 MinerU 对运行环境的要求。根据官方文档与实验测试，推荐配置如下：
- 操作系统：Windows 11（Linux 亦可，关键是驱动和依赖兼容）
- 显卡：NVIDIA GeForce RTX 4060Ti（显存至少 8GB，推荐更大）
- CUDA 版本：≥ 11.8（实验环境中使用 12.8 和 12.9，兼容性良好）
- 内存：≥ 16GB，推荐 32GB
- Python 环境：Anaconda（便于管理虚拟环境）
- 显卡驱动：需正确安装并支持对应 CUDA 版本
这一环节的重点在于 显卡与 CUDA 的匹配。CUDA 版本决定了后续安装的 PyTorch 是否能直接跑在 GPU 上，因此建议在部署前先用 nvidia-smi 检查驱动与 CUDA 的对应关系。
二、部署步骤
1. 创建容器实例
在 AutoDL 平台或实验室服务器上，先创建一个容器实例。本次实践中容器命名为 Eureka，对应 Python 3.12 环境。
2. 配置环境
（1）创建 Conda 环境
conda create -n mineru python=3.12 -y
conda activate mineru
为避免下载依赖过慢，可指定国内镜像源（如清华源、阿里源）。
（2）验证显卡与 CUDA
nvidia-smi
确认 CUDA 驱动可用，并记录 CUDA 版本，以便后续安装对应版本的 PyTorch。
（3）安装 MinerU 及依赖
- 升级 pip
- python -m pip install –upgrade pip -i https://mirrors.aliyun.com/pypi/simple
- 安装 uv 工具（用于加速依赖安装）：
- pip install uv -i https://mirrors.aliyun.com/pypi/simple
- 安装 MinerU 本体：
- uv pip install -U "mineru[core]" -i https://mirrors.aliyun.com/pypi/simple
（4）安装 PyTorch
根据 CUDA 版本，在 PyTorch 官网生成对应安装命令。例如 CUDA 12.8 环境下：
pip3 install torch torchvision –index-url https://download.pytorch.org/whl/cu121
安装完成后可用以下命令验证：
import torch
print(torch.cuda.is_available()) # True 表示可用
print(torch.cuda.get_device_name(0)) # 输出显卡型号
三、下载 MinerU 模型
MinerU 默认会从 HuggingFace 下载，但在国内环境中常遇到网络问题。因此需要设置下载源为 ModelScope：
- 云服务器版本：
- export MINERU_MODEL_SOURCE=modelscope
- 本地 PowerShell 版本：
- $env:MINERU_MODEL_SOURCE = "modelscope"
随后运行：
mineru-models-download
选择 all 下载所需模型。
四、启动 MinerU 服务
MinerU 提供两种主要运行模式：
方式一：API 模式
方式二：WebUI 模式
五、实际使用与脚本优化
1. API 与 WebUI 的使用
- API 模式适合需要集成到其他系统中的场景；
- WebUI 模式则更适合交互式处理，例如直接上传 PDF 并导出 Markdown 文件。
2. 服务器端批处理脚本
为了简化操作，实验中编写了两个脚本：
- batch_convert.sh：用于批量 PDF → TXT 转换；
- run_all.sh：一键进入环境、配置 MinerU 并完成批处理。
赋予脚本可执行权限后：
chmod +x run_all.sh
./run_all.sh
只需将 PDF 文件放入 input 文件夹，即可自动完成解析并输出到 output。
六、常见问题与解决
- pip 报 Warning：root 用户运行 → 在 Conda 环境中可忽略。
- 端口被占用 → 修改 –port 参数，如 9000。
- 下载缓慢或失败 → 使用 ModelScope 或断点续传。
- 显卡不支持最新 CUDA → 降级使用 CUDA 12.6 或 11.8。
七、总结
从环境准备到实际部署，MinerU 的上手并不算复杂，但每一步都需要细致检查，尤其是显卡驱动与 CUDA 的匹配，以及依赖安装时的版本控制。通过 API 与 WebUI 两种方式，MinerU 既能支持后端服务化，也能满足交互式需求。进一步结合批处理脚本，还能实现高效的文档处理流程，为科研与工程任务带来显著便利。
