为什么选择 Docker 封装 ROCm 环境

在 DevCloud 或本地工作站部署 AMD Instinct GPU 推理服务时，最让人头疼的往往不是模型本身，而是“环境地狱”。ROCm 驱动版本、GCC 编译器、PyTorch 依赖以及 vLLM 的算子兼容性，任何一环出错都可能导致服务无法启动。更麻烦的是，开发机跑通的代码，换台机器就报错，排查成本极高。

为了解决这一痛点，将整套环境封装进 Docker 镜像是最稳妥的方案。一次构建，到处运行，不仅能固化依赖版本，还能通过容器参数灵活透传硬件资源。本文将基于 Ubuntu 22.04 和 ROCm 7.x，手把手带你编写一个生产级的 Dockerfile，并详解启动时的关键参数配置，让你彻底告别环境配置焦虑。

编写适配 DevCloud 的 Dockerfile

构建镜像的核心在于平衡“完整性”与“轻量化”。我们需要在镜像中预装 ROCm 用户态库、Python 环境及核心框架，但又要避免将内核驱动打入镜像（驱动应由宿主机提供）。

以下是经过实战验证的 Dockerfile 内容：

FROM ubuntu:22.04

# 避免交互式安装提示，确保构建过程自动化
ENV DEBIAN_FRONTEND=noninteractive
ENV PYTHONUNBUFFERED=1

# 1. 安装基础构建工具与系统依赖
RUN apt-get update && apt-get install -y \
    wget gnupg2 curl git cmake ninja-build \
    python3 python3-pip python3-venv \
    libnuma1 libhwloc-dev \
    && rm -rf /var/lib/apt/lists/*

# 2. 添加 ROCm 7.x 官方软件源并安装运行时库
# 注意：容器内只需安装用户态库（rocm-libs, miopen-hip 等），无需安装内核模块
RUN wget https://repo.radeon.com/rocm/rocm.gpg.key -O - | apt-key add - \
    && echo 'deb [arch=amd64] https://repo.radeon.com/rocm/apt/7.0 jammy main' > /etc/apt/sources.list.d/rocm.list \
    && apt-get update \
    && apt-get install -y rocm-libs miopen-hip rocblas hip-runtime-amd hip-dev \
    && rm -rf /var/lib/apt/lists/*

# 3. 配置关键环境变量
# HSA_OVERRIDE_GFX_VERSION 需根据实际显卡架构调整，MI250 通常为 9.4.2，MI300 为 9.5.0
ENV PATH=/opt/rocm/bin:$PATH \
    LD_LIBRARY_PATH=/opt/rocm/lib:$LD_LIBRARY_PATH \
    HSA_OVERRIDE_GFX_VERSION=9.4.2

# 4. 创建非 root 用户并配置 GPU 访问权限
# 这一步至关重要，否则容器内进程无法访问 /dev/kfd 等设备
RUN useradd -m -u 1000 devuser && \
    usermod -aG video,render devuser

# 5. 预装 PyTorch (ROCm 版) 与 vLLM
# 生产环境建议锁定具体版本号，此处以 ROCm 7.0 兼容版本为例
RUN pip3 install --no-cache-dir torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm7.0 \
    && pip3 install --no-cache-dir vllm

# 6. 设置工作目录与启动入口
WORKDIR /workspace
USER devuser
ENTRYPOINT ["vllm", "serve"]

这个 Dockerfile 有几个关键点值得注意：首先，它显式安装了 hip-dev 和编译工具，以防后续需要动态编译某些算子；其次，创建了 devuser 并将其加入 video 和 render 组，这是 ROCm 容器化部署的硬性要求；最后，通过 HSA_OVERRIDE_GFX_VERSION 强制指定架构版本，有效规避因自动识别失败导致的“非法指令”错误。

容器启动：设备透传与共享内存技巧

镜像构建完成后（假设镜像名为 rocm-vllm:latest），如何正确启动容器才是发挥性能的关键。很多开发者忽略了设备透传和共享内存设置，导致容器内找不到显卡或推理进程频繁崩溃。

核心参数解析

启动命令必须包含以下关键标志：

• --device /dev/kfd --device /dev/dri：这是 ROCm 容器的“生命线”。/dev/kfd 是内核态驱动接口，/dev/dri 负责直接渲染基础设施。缺少任何一个，PyTorch 都无法识别到 GPU。
• --group-add video：即使 Dockerfile 中已配置用户组，启动时再次显式添加 video 组能确保万无一失，解决权限拒绝问题。
• --ipc=host：vLLM 重度依赖共享内存进行进程间通信（尤其是多卡张量并行时）。使用 host 模式的 IPC 命名空间可以避免默认的 64MB 限制，防止 OOM。
• --shm-size 16g：作为双重保险，显式增大容器内的 /dev/shm 大小。对于大模型推理，建议至少设置为 8GB 以上，根据模型参数量可适当调大至 16GB 或 32GB。

完整的 docker run 示例

以下命令可直接用于生产环境启动，监听 8000 端口并加载 Llama 3 模型：

docker run -d \
  --name vllm-rocm-instance \
  --device /dev/kfd \
  --device /dev/dri \
  --group-add video \
  --ipc=host \
  --shm-size 16g \
  -p 8000:8000 \
  --env HSA_OVERRIDE_GFX_VERSION=9.4.2 \
  rocm-vllm:latest \
  --model meta-llama/Meta-Llama-3-8B-Instruct \
  --tensor-parallel-size 2 \
  --gpu-memory-utilization 0.92 \
  --host 0.0.0.0 \
  --port 8000

在这个命令中，--env 再次确认了架构版本，确保容器内环境与宿主机驱动匹配。--tensor-parallel-size 2 表示启用双卡并行，这要求宿主机至少有两张 Instinct GPU 且已通过 NVLink 或 Infinity Fabric 互联。--gpu-memory-utilization 0.92 是一个经验值，预留 8% 的显存给系统缓冲，能有效防止因瞬时峰值导致的崩溃。

从开发到生产的无缝迁移

通过上述步骤，你将得到一个高度一致的运行环境。在开发机上构建好的镜像，可以直接推送到 DevCloud 的私有仓库，然后在云端实例上一键拉起。由于屏蔽了底层操作系统差异，你不再需要担心云端 Ubuntu 小版本不同导致的依赖缺失，也不用反复调试编译器版本。

这种容器化方案不仅提升了部署效率，还为后续的 CI/CD 流水线打下了基础。你可以将镜像构建集成到 Git 提交钩子中，每次代码更新自动生成新镜像，确保测试环境与生产环境完全同源。对于团队协作而言，这意味着新人入职只需一条 docker pull 命令即可获得全套可用的推理环境，极大地降低了沟通与维护成本。

200小时GPU算力已就位，快来领取：https://marketing.csdn.net/questions/Q2604140858304426315?utm_source=AIpaper