ubuntu 本地部署MinerU完成文档解析

从实际部署经验来看，在Ubuntu上搞定MinerU文档解析工具，这事儿其实并不复杂。大体上就三步走：先把系统环境调顺，然后安装MinerU本体，最后做几个测试验证一下。

下面我们把每一步拆开来看，保证清晰。得，直接开整。

1.系统环境配置

先看看手上有什么牌——CUDA版本是否满足要求。MinerU要求CUDA 11.8或以上版本，这一点需要提前确认。

nvcc --version

如果输出为空或者版本太低，那就老老实实装一下：

sudo apt install nvidia-cuda-toolkit

接下来用nvidia-smi看一下GPU的实时状态和显存情况。这条命令显示的CUDA版本是当前驱动支持的最高版本：

nvidia-smi

动手之前，先确认一下当前Python版本：

python --version

然后新建一个专用虚拟环境，干净卫生，依赖不会打架：

conda create -n mineru python=3.12.4
conda activate mineru

2.安装MinerU

先把uv这个快速包管理工具装上，后面都用它来安装，速度会快很多：

pip install uv

这里使用阿里云镜像站，下载速度更稳定：

uv pip install -U "mineru[core]" -i https://mirrors.aliyun.com/pypi/simple

版本对齐是个关键环节。先查清楚你系统里的CUDA版本：

nvcc -V

假设输出显示CUDA 12.1，那就选择适配的PyTorch版本（CUDA 12.1向下兼容12.0），安装命令如下：

pip install torch==2.5.0 torchvision==0.20.0 torchaudio==2.5.0 --index-url https://download.pytorch.org/whl/cu121

如果将来要升级到CUDA 12.6，对应的安装命令是：

pip install torch==2.8.0 torchvision==0.23.0 torchaudio==2.8.0 --index-url https://download.pytorch.org/whl/cu126

3.下载模型文件

模型是文档解析的“大脑”，得先下载下来。执行下面这条命令，会自动从ModelScope下载全部模型：

mineru-models-download --model_type all

4.功能测试

假设你的PDF存放在 /home/mac/wendang/pdfs，解析结果输出到 /home/mac/wendang/test_output。

这个模式把表格、公式、排版等识别任务拆成小模型处理。N卡能享受GPU加速。测试单个PDF：

mineru -p ./pdfs/demo1.pdf -o test_output/ --backend pipeline --device cuda

通过视觉大模型进行识别，准确率更高，但消耗的时间也更长：

mineru -p ./pdfs/demo1.pdf -o test_output/ --backend vlm-transformers --device cuda

一次搞定一整个文件夹的PDF，batch-size 8表示同时处理8个文档：

mineru -p ./pdfs -o test_output/ --backend pipeline --batch-size 8

5.启动web界面

首先确保虚拟环境激活：

conda activate mineru

然后启动Gradio界面（绑定所有网络接口，端口7860）：

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

到这一步，你就可以在浏览器里上传PDF并查看解析结果了。整个部署流程走下来，估计也就十几分钟的事。