Files

T

cjw cbe5388e57 x

2026-06-15 10:48:31 +08:00

15 KiB

Raw Blame History

MinerU AMD GPU Docker 部署指南

Ubuntu 24.04 + ROCm 7.2.1 + PyTorch 2.11.0+rocm7.2 + vllm main + MinerU 3.2.0 面向原生 Linux，通过 Docker 容器化一键部署实测通过：RX 9070 (gfx1201)，其他 RDNA2/3/4 显卡按相同流程套用

0. 为什么用 Docker

方案	适用场景
裸机部署（MinerU本地部署教程.md）	单机开发、追求极致性能
Docker 部署（本文）	团队共享、CI/CD、环境隔离、快速迁移

Docker 方案的优势：

宿主机只需安装 ROCm 内核驱动 + Docker，不需要污染系统 Python/库
镜像一次构建，多机复用
模型和 MIOpen 缓存通过卷挂载持久化，容器重建不丢失
支持 CLI / WebUI / API 三种运行模式

与 WSL2 教程的关键区别（原生 Linux 用户看这里）：

	WSL2 教程	本 Docker 文档
librocdxg 编译	必需	不需要（原生 KFD 驱动）
Windows SDK	必需	不需要
vllm 平台检测补丁（9.10 节）	必需	不需要（amdsmi 原生可用）
Hyper-V / 镜像网络 / DNS	必需	不需要（Docker 网络独立）
ROCm 头文件补丁	5 个	5 个（Dockerfile 自动应用）
MinerU RDNA 补丁	3 个	3 个（Dockerfile 自动应用）

1. 宿主机要求

1.1 硬件

项目	最低要求	推荐
GPU	AMD RDNA2/3/4 独显	RX 7900 / RX 9070 / RX 7800 等
显存	8 GB	16 GB+
内存	16 GB	32 GB+
磁盘	50 GB	100 GB+ (SSD)

1.2 软件

组件	版本	说明
操作系统	Ubuntu 24.04 (noble)	也支持 22.04 (jammy)，但需改用 ROCm 7.1.1
ROCm 内核驱动	7.2.x	`amdgpu-dkms` + `rocm-dkms`，容器共享宿主机内核驱动
Docker	≥ 24.0	需要 GPU 设备透传能力
Docker Compose	≥ 2.0	可选，简化容器管理

1.3 显卡兼容性

查自己的 gfx 代号：

rocminfo | grep gfx

显卡	gfx 代号	编译参数	状态
RX 9070 XT / 9070 / 9070 GRE	gfx1201	`ARCH=gfx1201`	实测通过
RX 9060 XT / 9060 XT LP	gfx1200	`ARCH=gfx1200`	ROCm 7.2 起正式支持
RX 7900 XTX / XT / GRE	gfx1100	`ARCH=gfx1100`	原生支持
RX 7800 XT / 7700 XT	gfx1101	`ARCH=gfx1101`	ROCm 较新版原生支持
RX 7600 XT / 7600	gfx1102	`ARCH=gfx1102`	vllm 支持，可能需伪装
RX 6950 / 6900 / 6800 XT / 6800	gfx1030	`ARCH=gfx1030`	预期可用
RX 6750 XT / 6700 XT	gfx1031	`ARCH=gfx1030`	伪装编译

不支持的：RDNA1 (gfx1010/gfx1012)、Navi 23 (gfx1032/gfx1034)、APU 核显。

2. 宿主机准备

2.1 安装 ROCm 内核驱动（仅内核部分）

容器里的 ROCm 用户空间库是自带的，但内核驱动必须在宿主机上。

# 添加 AMD ROCm 仓库
wget https://repo.radeon.com/rocm/rocm.gpg.key -O - | \
    sudo gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/rocm.gpg > /dev/null
echo 'deb [arch=amd64] https://repo.radeon.com/rocm/apt/7.2.1 noble main' | \
    sudo tee /etc/apt/sources.list.d/rocm.list
sudo apt update

# 只装内核驱动部分（不装整个 ROCm 用户空间）
sudo apt install -y amdgpu-dkms rocm-dkms

# 把自己加入 render/video 组
sudo usermod -a -G render,video $USER

# 重启
sudo reboot

验证驱动：

ls /dev/kfd /dev/dri/render*   # 三个设备节点都应该存在
/opt/rocm/bin/rocminfo         # 如果装了 rocminfo

如果你已经完整安装过 ROCm 7.2.1（包括用户空间），不需要重复装内核驱动，直接跳到 2.2。

2.2 安装 Docker

# 官方脚本（推荐）
curl -fsSL https://get.docker.com | sudo sh

# 把自己加入 docker 组，免 sudo
sudo usermod -aG docker $USER
newgrp docker

# 验证
docker run --rm hello-world

2.3 创建数据目录

mkdir -p ~/mineru-docker/data/{input,output,models,miopen}
cd ~/mineru-docker

将本仓库 docker/ 目录下的所有文件复制到 ~/mineru-docker/（或直接在仓库目录下操作）。

目录结构：

~/mineru-docker/
├── Dockerfile
├── docker-compose.yml
├── env.example
├── scripts/
│   └── cache_warmer.py
└── data/
    ├── input/          # 放待处理的 PDF
    ├── output/         # 处理结果输出
    ├── models/         # HuggingFace / ModelScope 模型缓存
    └── miopen/         # MIOpen kernel 缓存

复制 env.example 并根据你的 GPU 修改：

cp env.example .env
# 编辑 .env，将 ARCH=gfx1201 改为你的 gfx 代号

3. 构建镜像

3.1 构建

# 方式一：docker build（直接指定 ARCH）
docker build \
    --build-arg ARCH=gfx1201 \
    -t mineru-rocm:7.2.1 \
    -f Dockerfile .

# 方式二：docker compose（使用 .env 中的 ARCH）
docker compose build

构建时间参考：

下载 ROCm 包：~5 分钟
编译 vllm：30-45 分钟（LLVM 22，-j4）
安装 MinerU + 依赖：~3 分钟
总计：约 40-60 分钟（首次，后续利用 Docker 层缓存会快很多）

如果编译中途 OOM 被杀（exit 137），把 Dockerfile 第 155 行的 ninja -j4 改成 ninja -j2。

3.2 关键构建参数

参数	默认值	说明
`ARCH`	`gfx1201`	GPU 架构代号，见 1.3 节表格
`PYTHON_VER`	`3.12`	Python 版本
`VENV`	`/opt/mineru_venv`	虚拟环境路径
`TORCH_INDEX`	`https://download.pytorch.org/whl/rocm7.2`	PyTorch wheel 源

4. 运行容器

4.1 启动 WebUI 服务（默认推荐）

当前 docker-compose.yml 默认只启动一个 GPU 直连的 gradio WebUI 服务，避免单卡机器因为 worker1 或可选 Router 退出导致整组服务不可用：

服务	宿主机端口	容器内端口	用途
`gradio`	`10002`	`7860`	WebUI 前端 + 本地推理

docker compose up -d

# 查看容器是否都已启动
docker compose ps -a

# WebUI 健康检查：应返回 HTML 或 HTTP 状态，而不是 Connection refused
curl -v http://localhost:10002/

浏览器打开：http://<宿主机IP>:10002。

如果 docker compose ps 为空或显示 Exited，说明服务进程启动后退出，请先看日志：

docker compose logs --tail=200 gradio

注意：直接 docker run mineru-rocm:7.2.1 使用的是 Dockerfile 默认 CMD ["bash"]，只会进入/运行 shell，不会启动 WebUI/API，也就不会监听 10002。如需直接 docker run 暴露 WebUI，必须显式传入 mineru-gradio 命令并映射端口。

4.2 交互模式（调试 / 手动处理）

# docker compose（复用 gradio 的 GPU/卷配置，覆盖 command 进入 bash）
docker compose run --rm gradio bash

# 或 docker run
docker run -it --rm \
    --device /dev/kfd --device /dev/dri \
    --security-opt seccomp=unconfined \
    --group-add video \
    --ipc host \
    -v ./data/input:/data/input:ro \
    -v ./data/output:/data/output \
    -v ./data/models:/opt/models \
    -v ./data/miopen:/root/.cache/miopen \
    mineru-rocm:7.2.1

进入容器后，虚拟环境已自动激活，可直接使用：

# 验证 GPU
python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"

# 处理 PDF
mineru -p /data/input/example.pdf -o /data/output -b hybrid-auto-engine

4.3 CLI 模式（一键处理）

docker compose run --rm gradio \
    mineru -p /data/input/example.pdf -o /data/output -b hybrid-auto-engine

或修改 docker-compose.yml 的 command 为：

command: mineru -p /data/input/example.pdf -o /data/output -b hybrid-auto-engine

4.4 可选：Router API 多 Worker 模式

如果确实需要独立 API Router，可启用 router-api profile。默认只启用 worker0，避免单卡机器启动 worker1 失败：

docker compose --profile router-api up -d
curl -v http://localhost:8000/

双卡时再启用 dual-gpu profile，并在 .env 中设置：

ROUTER_API_URLS=http://mineru-worker0:8001,http://mineru-worker1:8002

docker compose --profile router-api --profile dual-gpu up -d

API 用法参考 MinerU 官方文档。

4.5 中国用户：使用 ModelScope 下载模型

设置环境变量即可切换下载源：

docker compose run --rm -e MINERU_MODEL_SOURCE=modelscope gradio \
    mineru -p /data/input/example.pdf -o /data/output -b hybrid-auto-engine

或修改 .env：MINERU_MODEL_SOURCE=modelscope

5. MIOpen 缓存预热

容器首次使用前，建议预热 MIOpen kernel 缓存（约 3-4 分钟）。缓存通过卷挂载持久化，只需执行一次。

# 进入容器
docker compose run --rm gradio bash

# 运行预热
python /opt/scripts/cache_warmer.py --device cuda --max_side 960 --step 32

输入尺寸	冷启动耗时	预热后
(1, 3, 544, 672)	~1320 ms	~30 ms
(1, 3, 416, 704)	~1133 ms	~30 ms

缓存存在 ./data/miopen/，升级 ROCm 版本后需重新预热。

6. 验证

docker compose run --rm gradio python -c "
import torch
from vllm.platforms import current_platform

print('=== Environment Check ===')
print(f'PyTorch  : {torch.__version__}')
print(f'ROCm     : {torch.version.hip}')
print(f'GPU      : {torch.cuda.get_device_name(0)}')
print(f'GPU Avail: {torch.cuda.is_available()}')
print(f'Platform : {type(current_platform).__name__}')
print(f'is_rocm  : {current_platform.is_rocm()}')

# 快速算力测试
x = torch.randn(100, 100).cuda()
print(f'Compute  : {(x @ x).shape} PASS')
"

# 期望输出：
# PyTorch  : 2.11.0+rocm7.2
# GPU Avail: True
# Platform : RocmPlatform
# is_rocm  : True
# Compute  : torch.Size([100, 100]) PASS

7. 性能参考（RX 9070，13 页 example.pdf）

阶段	耗时 / 速度
VLM 推理 (Two Step Extraction)	~5 秒 (2+ it/s)
Layout Predict	1.2-1.5 秒
OCR-det	~20 it/s
Processing pages	65-71 it/s
13 页总耗时	5-7 秒

得益于 hipBLASLt 在线 GEMM 调优（ROCm 7.2 相比 7.1 提升约 106%）和 RX 9070 的 640 GB/s 显存带宽。

8. Dockerfile 补丁清单

Dockerfile 自动应用了以下所有补丁，了解即可（排查问题时有用）：

#	补丁	目标文件	原因
1	hipcc/clang 符号链接	系统	`hipcc.pl` 硬编码 `clang-17`，ROCm 7.2 实际带 `clang-22`
2	`__hip_internal::conditional`	`/opt/rocm/include/hip/*.h`	LLVM 22 不接受此命名空间
3	`warpSize` 常量	`amd_warp_functions.h`	`__AMDGCN_WAVEFRONT_SIZE` 在 LLVM 22 未定义
4	`__activemask()`	`amd_warp_sync_functions.h`	替换为 `__builtin_amdgcn_read_exec()`
5	mamba `operator+` 冲突	`vllm csrc/mamba/.../selective_scan.h`	ROCm 7.2 头文件已自带定义
A	imgW 32 对齐	MinerU `predict_rec.py`	RDNA MIOpen 最优尺寸
B	批次填充	MinerU `predict_rec.py`	避免 MIOpen 冷启动
C	contiguous 检查	MinerU `predict_det.py`	RDNA 内存布局兼容

9. 常见问题

Q: docker: Error response from daemon: could not select device driver

Docker 没有 GPU 支持。安装 nvidia-container-toolkit 的 AMD 等价物——实际上 ROCm 不需要额外的 container runtime，只要 /dev/kfd 和 /dev/dri 存在即可。检查宿主机驱动：

ls /dev/kfd /dev/dri/render*

Q: 容器启动后 torch.cuda.is_available() 返回 False

确认容器有 --device /dev/kfd --device /dev/dri
确认 --security-opt seccomp=unconfined
确认当前用户在宿主机的 render 和 video 组
容器内运行 rocminfo 看能否检测到 GPU

Q: 启动时报 Unable to find group render: no matching entries in group file

这是因为 Docker Compose 的 group_add 使用的是容器内可解析的组名，而当前 Ubuntu 镜像内不一定存在 render 组。Compose 默认以 root 运行容器，并已透传 /dev/kfd 和 /dev/dri，因此默认只保留 video 组，不再添加 render。如果你改为非 root 用户运行容器，再按宿主机 /dev/dri/render* 的实际 GID 使用数字形式添加，例如 group_add: ["109"]。

Q: mineru-gradio 启动时报 ModuleNotFoundError

旧镜像只安装了 mineru[core]，可能缺少 WebUI CLI 依赖，例如 click 或 gradio。当前 Dockerfile 已显式安装 click gradio，并在构建期验证 mineru.cli.gradio_app 可导入、mineru-gradio --help 可执行。修改 Dockerfile 后需要重建镜像：

docker compose build --no-cache gradio
docker compose up -d --force-recreate

Q: 构建时 ninja 被 kill（exit 137）

内存不足。将 Dockerfile 中 ninja -j4 改为 ninja -j2 或 ninja -j1，或给 Docker 分配更多内存。

Q: 构建时 cmake 报 Failed to find ROCm root directory

/opt/rocm/bin 不在 PATH 中。检查 Dockerfile 中 ENV PATH 是否正确设置。

Q: 构建时 cmake 报 roc::hipsparselt target not found

hipsparselt-dev 没装上。检查 Dockerfile 阶段 6 的 apt install 列表。

Q: MinerU 运行时很慢（单页 > 10 秒）

大概率 MIOpen 在冷启动。先跑一次 cache_warmer.py。

Q: HuggingFace 连不上 / 模型下载失败

切换下载源：MINERU_MODEL_SOURCE=modelscope。或设置代理：

docker compose run --rm -e http_proxy=http://host:port -e https_proxy=http://host:port worker0 bash

Q: WebUI/API 端口无法访问

检查 docker-compose.yml 中 ports 是否取消注释。检查宿主机防火墙。

Q: 显存不足 (Out of Memory)

8GB 显卡设置 MINERU_VIRTUAL_VRAM_SIZE=6 触发保守策略
或改用 pipeline 后端：mineru -p input.pdf -o output -b pipeline

10. 镜像体积优化（可选）

完整镜像约 25-30 GB（含 ROCm 库、vllm 编译产物、Python 包）。如需优化：

# Dockerfile 构建完成后追加清理阶段：
RUN rm -rf /opt/vllm_build /opt/vllm/.git /opt/aiter/.git /opt/flash-attention/.git && \
    apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/* && \
    ${VENV}/bin/pip cache purge

11. 升级指南

升级 MinerU

docker compose run --rm gradio pip install --upgrade 'mineru[core]'
# 然后重新应用 RDNA 补丁（参考 Dockerfile 阶段 9）

升级 vllm / ROCm

重新构建镜像即可（补丁在 Dockerfile 中自动重应用）：

docker compose build --no-cache

ROCm 版本的补丁 1-4 需要 sudo 权限，构建时 Docker 容器内默认为 root，无需额外处理。

文档最后更新: 2026-06-03 实测环境：Ubuntu 24.04 + AMD RX 9070 (gfx1201) + ROCm 7.2.1 + PyTorch 2.11.0+rocm7.2 + vllm main + MinerU 3.2.0

15 KiB Raw Blame History Unescape Escape