为什么选择 Docker 作为 ROCm 开发沙箱

在尝试将大模型推理或训练任务迁移到 AMD GPU 平台时，最让人头疼的往往不是代码逻辑本身，而是环境配置的“地狱”。ROCm 软件栈对操作系统内核版本、驱动版本以及用户组权限有着极其严苛的要求。很多开发者在宿主机上反复安装、卸载各种依赖库，结果导致系统环境变量混乱，甚至影响了原有的图形界面或其他开发任务。

为了解决这一痛点，容器化部署成为了最佳实践。通过 Docker，我们可以将 HIPify 转换工具、SGLang 推理框架以及所有底层依赖封装在一个隔离的沙箱中。这不仅保证了环境的一致性，让“在我机器上能跑”变成“在任何地方都能跑”，更重要的是，它彻底避免了对宿主机的污染。无论你的宿主机是 Ubuntu 20.04 还是 22.04，只要内核支持且安装了正确的 AMD 驱动，容器内部的环境都可以保持完全一致，极大降低了复现实验和协作开发的门槛。

构建预装工具链的 Dockerfile

构建一个开箱即用的开发镜像，核心在于编写一个高效的 Dockerfile。我们需要基于官方提供的 ROCm 基础镜像进行扩展，预先集成 HIPify 代码迁移工具和 SGLang 运行时环境。

首先，基础镜像的选择至关重要。建议直接使用 rocm/dev-ubuntu-22.04 系列标签，确保与主流服务器环境兼容。在此基础上，我们需要安装 Python 依赖并配置代码转换工具。以下是一个经过验证的 Dockerfile 示例：

FROM rocm/dev-ubuntu-22.04:6.0

# 设置环境变量，避免交互式安装提示
ENV DEBIAN_FRONTEND=noninteractive
ENV PYTHONUNBUFFERED=1

# 更新源并安装基础构建工具
RUN apt-get update && apt-get install -y \
    python3-pip \
    git \
    vim \
    curl \
    && rm -rf /var/lib/apt/lists/*

# 安装 HIPify 工具链，用于 CUDA 到 HIP 的自动转换
# 这里假设使用 pip 安装最新版的 hipify-python，也可通过 apt 安装 rocmlir 相关包
RUN pip3 install --no-cache-dir hipify-python

# 安装 SGLang 及其 ROCm 后端依赖
# 注意：需指定对应的 torch 版本以匹配当前 ROCm 版本
RUN pip3 install --no-cache-dir \
    torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm6.0 \
    sglang[all]

# 设置工作目录
WORKDIR /workspace

# 默认启动命令
CMD ["/bin/bash"]

在这个构建文件中，我们特意分离了系统级依赖和 Python 级依赖的安装步骤，利用分层缓存机制加速后续构建。特别需要注意的是 torch 的安装源，必须明确指向带有 rocm 标识的索引地址，否则默认拉取的将是 CUDA 版本，导致容器内无法调用 GPU。

关键配置：设备透传与权限管理

有了镜像只是第一步，如何让容器“看见”并“使用”宿主机上的 AMD GPU 才是成败关键。与 NVIDIA Docker 不同，ROCm 容器的设备映射需要更细致的权限控制。

在启动容器时，必须通过 --device 参数将 /dev/kfd 和 /dev/dri 设备透传给容器。/dev/kfd 是 AMD GPU 的内核驱动接口，负责内存管理和调度；而 /dev/dri 则包含具体的渲染节点。此外，还需要将当前用户加入 video 和 render 用户组，以避免权限拒绝错误。

下面是一个标准的启动脚本片段，你可以将其保存为 run_rocm_dev.sh：

#!/bin/bash

IMAGE_NAME="rocm-dev-sandbox:latest"
CONTAINER_NAME="rocm-sandbox"

# 检查镜像是否存在，不存在则构建
if ! docker images $IMAGE_NAME | grep -q .; then
    echo "镜像未找到，正在构建..."
    docker build -t $IMAGE_NAME .
fi

# 启动容器
docker run -it --rm \
    --name $CONTAINER_NAME \
    --device /dev/kfd \
    --device /dev/dri \
    --group-add video \
    --group-add render \
    --cap-add=SYS_PTRACE \
    --security-opt seccomp=unconfined \
    --shm-size 16G \
    -v $(pwd):/workspace \
    -w /workspace \
    $IMAGE_NAME

这段脚本中，--shm-size 16G 是一个容易被忽视但至关重要的参数。大模型推理和编译过程（尤其是 HIPify 处理大型项目时）会消耗大量的共享内存，默认的 64MB 限制极易导致进程被 OOM Killer 杀死。同时，挂载当前目录到 /workspace 方便我们在容器内外无缝编辑代码，实时验证 HIPify 的转换结果或调试 SGLang 服务。

一键验证：从 HIPify 转换到 SGLang 启动

容器启动后，我们立刻进入了一个纯净且功能完备的开发环境。为了验证一切就绪，可以先运行 rocminfo 命令。如果输出了详细的 GPU 架构信息（如 GFX900, GFX940 等），说明设备透传成功。

接下来是核心工作流测试。假设你有一个包含 CUDA 代码的旧项目目录，可以直接在容器内运行 hipify-perl 或 hipify-clang 进行批量转换。例如：

hipify-perl -project-root=./my_cuda_project ./my_cuda_project

转换完成后，无需退出容器，即可直接利用预装的 SGLang 启动推理服务。针对 AMD 显卡，启动时需显式指定后端参数。以下是一个典型的启动命令：

python3 -m sglang.launch_server \
    --model-path meta-llama/Llama-3-8B-Instruct \
    --port 30000 \
    --host 0.0.0.0 \
    --mem-fraction-static 0.85 \
    --tp 1

在这里，--mem-fraction-static 用于控制显存占用比例，防止因显存预留不足导致服务崩溃。如果一切正常，你将看到服务成功加载模型并开始监听端口。此时，你可以在宿主机或其他机器上通过 HTTP 请求测试推理效果，整个过程完全不需要在宿主机安装任何 Python 库或配置复杂的环境变量。

通过这种“镜像即环境”的模式，团队内的每位成员都能获得完全一致的开发体验。无论是新入职的工程师需要快速上手，还是需要在不同版本的 ROCm 之间切换测试，只需修改 Dockerfile 中的基础镜像标签并重新构建即可。这种标准化流程不仅提升了效率，也为后续将应用部署到生产环境打下了坚实基础。

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