锁定版本：告别“依赖地狱”的第一步

在 AMD GPU 上跑大模型，最劝退的往往不是算法本身，而是环境配置。相信不少朋友都经历过这样的崩溃时刻：昨天还能跑的代码，今天更新了一个系统包就报错；或者团队里新来的同事按照文档操作，结果因为 PyTorch 和 ROCm 驱动版本不匹配，整整两天都在解决 ImportError 和 HIP runtime failed。

这种“依赖地狱”的核心原因在于版本锁定的缺失。ROCm 生态对版本极其敏感，PyTorch、ROCm 驱动、甚至底层的 Linux 内核版本之间存在着严格的对应关系。一旦某个环节“自由发挥”自动升级，整个链路就会断裂。因此，构建稳定环境的第一原则就是：显式锁定一切。

不要依赖 pip install torch 这种模糊指令，它往往会拉取最新但不一定兼容你当前硬件的版本。我们需要明确指定三个核心坐标：

1. ROCm 驱动版本：这是地基，必须与你的显卡固件及操作系统内核匹配。对于较新的 Instinct 系列或 Radeon RX 7000 系列，通常建议锁定在 ROCm 6.x 或更新的稳定版（具体视硬件而定），切忌混用不同大版本的驱动库。
2. PyTorch ROCm 构建版：PyTorch 官方提供了预编译的 ROCm 版本，但必须严格对应上述驱动版本。例如，若宿主机安装了 ROCm 6.2，则必须安装与之匹配的 torch==2.x+rocm6.2 变体。
3. 关键算子库：如 vLLM、flash-attention 等，这些库在编译时强依赖特定的 HIP 编译器版本。如果容器内外的 HIP 版本不一致，运行时必然崩溃。

在实际操作中，我习惯先在一个干净的虚拟机或容器中，通过 rocminfo 确认驱动版本，然后去 PyTorch 官网查找对应的安装命令，将完整的版本号（包括 +rocm 后缀）记录在 requirements.txt 中。这一步看似繁琐，却能避免后续 90% 的诡异报错。

Dockerfile 实战：一键复现的开发环境

有了明确的版本号，下一步就是将其固化。对于团队协作或个人多项目并行，Docker 是最佳选择。它能将操作系统层、驱动映射层和应用层隔离开来，确保“在我机器上能跑”变成“在任何地方都能跑”。

下面是一个经过验证的 Dockerfile 示例，专门针对 AMD GPU 环境构建。它基于官方 Ubuntu 镜像，预设了 ROCm 运行时的基础依赖，并锁定了 PyTorch 和 vLLM 的版本。

# 基础镜像：选择带有基本 ROCm 运行时支持的 Ubuntu 版本
# 注意：实际运行时需要宿主机安装对应的 rocm-dkms 和驱动
FROM ubuntu:22.04

# 设置环境变量，避免交互式安装卡住
ENV DEBIAN_FRONTEND=noninteractive
ENV PYTORCH_ROCM_ARCH="gfx90a;gfx942" 
# 上面这行很重要，根据你的显卡架构调整，MI250/MI300 通常是 gfx90a/gfx942

# 安装基础工具链和 HIP 编译依赖
RUN apt-get update && apt-get install -y \
    python3.10 python3-pip python3-dev \
    git cmake build-essential \
    rocblas hipblaslt rccl \
    && rm -rf /var/lib/apt/lists/*

# 工作目录
WORKDIR /workspace

# 核心步骤：精确安装 PyTorch ROCm 版本
# 这里以 torch 2.4.0 + rocm6.2 为例，请根据实际需求替换版本号
RUN pip3 install --no-cache-dir \
    torch==2.4.0 \
    torchvision==0.19.0 \
    torchaudio==2.4.0 \
    --index-url https://download.pytorch.org/whl/rocm6.2

# 验证安装
RUN python3 -c "import torch; print(f'PyTorch version: {torch.__version__}'); print(f'CUDA available: {torch.cuda.is_available()}'); print(f'ROCm HipBLAS status: {torch.backends.hip.is_available()}')"

# 安装 vLLM (需编译，依赖上述 HIP 环境)
# 建议使用社区优化过的分支或特定 tag，这里演示安装稳定版
RUN pip3 install --no-cache-dir vllm==0.5.4 --no-build-isolation

# 清理缓存，减小镜像体积
RUN apt-get clean && rm -rf /var/cache/apt/archives/*

CMD ["/bin/bash"]

这个 Dockerfile 有几个关键点值得注意：

• 架构声明：PYTORCH_ROCM_ARCH 环境变量告诉 PyTorch 编译时针对哪些 GPU 架构优化。如果你的显卡是 MI250X，务必包含 gfx90a；如果是 MI300X，则需包含 gfx942。漏掉这个会导致运行时提示“不支持的架构”。
• 索引源指定：安装 PyTorch 时必须使用 --index-url 指向 ROCm 专用的 whl 源，否则 pip 会尝试安装 CUDA 版本或 CPU 版本。
• 编译隔离：安装 vLLM 时加上 --no-build-isolation，是为了让它直接使用容器内已安装的 HIP 工具链，而不是重新下载一套冲突的编译环境。这在解决 hipcc 找不到或版本不匹配问题上非常有效。

构建好镜像后，团队成员只需一条命令即可启动开发环境：

docker run --device /dev/kfd --device /dev/dri --group-add video --ipc=host --shm-size 16G -it my-rocm-env:latest

这里的 --device 参数是将宿主机的 GPU 设备透传给容器，--group-add video 则是解决权限问题的常见操作（AMD 显卡通常需要用户属于 video 组才能访问 /dev/kfd）。

避坑指南与持续维护

即使有了标准化的 Docker 镜像，实际使用中仍可能遇到一些“玄学”问题。根据在社区中的实践观察，以下几个高频坑点需要特别留意：

首先是权限问题。很多新手在容器内运行代码时报 Permission denied，这通常是因为宿主机上的 /dev/kfd 或 /dev/dri/renderD128 设备文件权限限制。解决方法是在宿主机执行 sudo usermod -aG render $USER 和 sudo usermod -aG video $USER，然后重启。在 Docker 启动参数中加上 --group-add video 也能缓解大部分问题。

其次是显存碎片化与 OOM。在某些复杂的多卡推理场景下，即便显存总量足够，也可能因为分配策略不当导致 Out Of Memory。如果在 vLLM 中遇到此类问题，可以尝试调整 --gpu-memory-utilization 参数，或者检查是否启用了正确的 PagedAttention 后端。社区中有一些针对特定拓扑优化的 vLLM 分支，它们在处理多卡通信（RCCL）时表现更稳健，如果遇到官方版本死锁，不妨去 Github 上搜索相关的 fork 版本试试。

最后是版本迭代的节奏。ROCm 生态更新较快，新显卡往往需要新驱动支持。当团队需要引入新硬件（如从 MI250 升级到 MI300）时，不要试图在原镜像上打补丁，最好的做法是新建一个分支，基于新的基准版本重新构建 Docker 镜像，并更新 requirements.txt 中的版本号。保持环境的“不可变性”（Immutable Infrastructure）是长期稳定的关键。

通过这套“锁定版本 + Docker 固化”的流程，我们团队已经将环境搭建时间从平均 4 小时压缩到了 15 分钟。新人入职第一天，拿到文档和 Docker 命令，下午就能开始跑通第一个大模型 Demo。这种确定性，或许才是深度学习工程化中最宝贵的资产。