cjw/mineru-rocm

Fork 0

Files

T

History

cjw 18898057e6 x

2026-06-11 17:05:40 +08:00

scripts

2026-06-10 15:14:00 +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-11 11:40:46 +08:00

Dockerfile

2026-06-11 17:05:40 +08:00

env.example

2026-06-03 15:39:09 +08:00

ISSUES.md

2026-06-09 11:22:04 +08:00

README.md

2026-06-03 15:39:09 +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 交互模式（调试 / 手动处理）

# docker compose
docker compose run --rm mineru

# 或 docker run
docker run -it --rm \
    --device /dev/kfd --device /dev/dri \
    --security-opt seccomp=unconfined \
    --group-add video --group-add render \
    --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.2 CLI 模式（一键处理）

docker compose run --rm mineru \
    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.3 WebUI 模式

修改 docker-compose.yml：

command: mineru-gradio --server-name 0.0.0.0 --server-port 7860
ports:
  - "7860:7860"

docker compose up -d
# 浏览器打开 http://<宿主机IP>:7860

4.4 API 模式

command: mineru-api --host 0.0.0.0 --port 8000
ports:
  - "8000:8000"

API 用法参考 MinerU 官方文档。

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

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

docker compose run --rm -e MINERU_MODEL_SOURCE=modelscope mineru \
    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 mineru

# 运行预热
python /opt/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 mineru 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: 构建时 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 mineru

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 mineru 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 交互模式（调试 / 手动处理）

4.2 CLI 模式（一键处理）

4.3 WebUI 模式

4.4 API 模式

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

5. MIOpen 缓存预热

6. 验证

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

8. Dockerfile 补丁清单

9. 常见问题

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

11. 升级指南

升级 MinerU

升级 vllm / ROCm

README.md