cjw/mineru-rocm

Fork 0

Files

T

History

cjw eb81b0d420 x

2026-06-23 09:37:56 +08:00

data/input

2026-06-15 17:30:03 +08:00

scripts

2026-06-23 09:37:56 +08:00

.dockerignore

2026-06-05 11:14:53 +08:00

.env

2026-06-10 15:43:34 +08:00

docker-compose.yml

2026-06-16 10:28:49 +08:00

Dockerfile

2026-06-18 10:31:22 +08:00

env.example

2026-06-12 14:49:07 +08:00

ISSUES.md

2026-06-17 16:33:02 +08:00

nginx.conf

2026-06-15 17:46:45 +08:00

README.md

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

README.md

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

README.md Unescape Escape

MinerU AMD GPU Docker 部署指南

0. 为什么用 Docker

1. 宿主机要求

1.1 硬件

1.2 软件

1.3 显卡兼容性

2. 宿主机准备

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

2.2 安装 Docker

2.3 创建数据目录

3. 构建镜像

3.1 构建

3.2 关键构建参数

4. 运行容器

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

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

4.3 CLI 模式（一键处理）

4.4 可选：Router API 多 Worker 模式

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

5. MIOpen 缓存预热

6. 验证

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

8. Dockerfile 补丁清单

9. 常见问题

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

11. 升级指南

升级 MinerU

升级 vllm / ROCm

README.md