选对镜像：避开驱动冲突的第一道坎

刚拿到 DevCloud 账号准备折腾 AMD GPU 时，最容易踩的坑就是“盲目追新”。很多开发者习惯性地拉取最新的 ROCm 镜像，或者试图在基础 Ubuntu 镜像上手动安装驱动，结果发现宿主机内核模块与容器内的用户态库版本不匹配。在 AMD 生态里，这一点比 NVIDIA 生态更为敏感：宿主机的 kfd 驱动版本必须与容器内的 ROCm 用户态库严格对应，否则 rocm-smi 命令会直接报错，甚至无法识别 GPU，导致后续所有工作无法开展。

在 DevCloud 平台上，最稳妥的方案其实是直接使用控制台提供的“预置开发镜像”。这些镜像通常已经通过了平台方的兼容性测试，内置了与当前节点驱动完美匹配的 ROCm 7.x 环境。创建实例时，务必在镜像市场筛选带有"ROCm 7.x"且标注为“推荐”或“稳定版”标签的选项。如果因为特殊需求必须自定义 Dockerfile，请务必先通过 cat /etc/os-release 确认宿主机基础环境，并严格锁定 rocm-dev 的版本号，千万不要使用 latest 标签。这一步看似简单，却能节省后续数小时的排查时间，避免陷入“驱动地狱”。

启动后的“体检”：编写设备可见性诊断脚本

容器启动成功并不代表万事大吉，第一步必须是验证硬件是否真正“就位”。不要只依赖命令行工具的输出，在自动化脚本或 CI/CD 流程中，我们需要更程序化的检查方式。我习惯在容器入口写一个简单的 Python 诊断脚本，利用 torch 和 hip 接口快速摸底。

以下这段代码可以直接复用，它能帮你确认设备数量、显存大小以及是否支持 BF16 等关键特性，这是运行大模型推理的前提：

import torch
import sys

def check_rocm_health():
    # 在 ROCm 环境下，torch 依然使用 cuda 作为后端别名
    if not torch.cuda.is_available():
        print("❌ 错误：未检测到可用的 ROCm 设备")
        print("   请检查 HIP_VISIBLE_DEVICES 环境变量或 --device 映射")
        return False
    
    device_count = torch.cuda.device_count()
    print(f"✅ 检测到 {device_count} 个加速卡")
    
    for i in range(device_count):
        props = torch.cuda.get_device_properties(i)
        free_mem = torch.cuda.mem_get_info(i)[0] / 1024**3
        total_mem = props.total_memory / 1024**3
        
        print(f"\n--- 卡 {i}: {props.name} ---")
        print(f" 显存总量：{total_mem:.2f} GB")
        print(f" 可用显存：{free_mem:.2f} GB")
        
        # 检查 BF16 支持，这对大模型推理至关重要
        # MI300 系列通常 major >= 9
        if props.major >= 9:
            print(" ✅ 支持 BF16 加速 (推荐用于 vLLM)")
        else:
            print(" ⚠️ 需确认是否开启 FP16 兼容模式")
            
    return True

if __name__ == "__main__":
    if not check_rocm_health():
        sys.exit(1)
    print("\n🎉 环境健康检查通过，准备启动服务")

将这段脚本保存为 health_check.py 并在容器内运行。如果看到红色的错误提示，第一时间检查启动参数中的 --device 映射（如 /dev/kfd 和 /dev/dri）或环境变量 HIP_VISIBLE_DEVICES 是否被错误限制。只有当脚本顺利输出"🎉 环境健康检查通过”时，才能进行下一步操作。

核心工具链验证：rocm-smi 与 hipcc

在运行 Python 脚本之前，建议先用原生工具链做一次底层确认。这能帮助我们区分是驱动层问题还是框架层问题。

首先执行 rocm-smi 命令。如果该命令能清晰列出所有 GPU 的温度、功耗、显存使用率以及当前的频率策略，说明内核态驱动工作正常。如果提示"command not found"或报错，说明 ROCm 工具包未正确安装或环境变量 PATH 未包含 /opt/rocm/bin。

# 查看 GPU 状态概览
rocm-smi

# 查看详细的硬件架构信息，确认 GFX 版本
rocminfo | grep -i "name.*gfx"

接下来验证编译器环境。ROCm 7.x 高度依赖 hipcc 编译器来构建自定义算子。尝试编译一个简单的 HIP 程序或直接查看版本，确保开发环境已就绪：

# 检查 hipcc 版本
hipcc --version

# 简单测试：创建一个 hello.cpp 文件并编译
echo '#include <hip/hip_runtime.h>
int main() { printf("ROCm is working\\n"); return 0; }' > hello.cpp
hipcc hello.cpp -o hello
./hello

如果能成功输出"ROCm is working"且无链接错误，则表明底层的 C++ 开发环境已完全就绪。这一步看似繁琐，但能提前暴露 80% 以上的硬件识别与编译链路问题，避免在后续编译 vLLM 时因缺少底层支持而报错。

常见驱动与容器版本不匹配排查

在实际操作中，即便使用了预置镜像，偶尔也会遇到“隐形”的兼容性问题。最典型的情况是：rocm-smi 能运行，但 PyTorch 无法识别设备，或者报错信息含糊不清。

场景一：权限组缺失
如果在容器内运行 rocm-smi 提示权限不足，或者 Python 脚本报错"Permission denied"，通常是因为当前用户未加入 video 和 render 用户组。虽然 DevCloud 预置镜像通常已处理此问题，但在自定义构建时需注意：

# 将当前用户加入视频渲染组（需重启或重新登录生效）
sudo usermod -aG video,render $USER

在容器环境中，更直接的方法是确保 Docker 启动时添加了 --group-add video 参数。

场景二：环境变量冲突
有时系统中同时存在多个版本的 ROCm 库，导致链接器找到了错误的 .so 文件。检查 LD_LIBRARY_PATH 是否包含了正确的路径（通常是 /opt/rocm/lib）。如果不确定，可以尝试显式导出：

export LD_LIBRARY_PATH=/opt/rocm/lib:$LD_LIBRARY_PATH
export HIP_PATH=/opt/rocm

场景三：NFS 挂载导致的假死
在 DevCloud 上，模型文件通常存放在共享存储中。如果容器内能看到挂载目录，但读取大文件时速度极慢甚至进程假死，这通常是网络文件系统的小文件读取策略问题。解决方案是在加载模型前，先将权重文件复制到容器本地的临时高速存储（如 /tmp 或内存盘）中。对于 7B 以上的模型，虽然复制需要几分钟，但能换来推理时稳定的 I/O 吞吐，避免因为网络抖动导致的首字延迟飙升。

当你在终端看到 Uvicorn running on http://0.0.0.0:8000 且没有任何报错堆栈，同时之前的健康检查脚本全部通过时，恭喜你已经跨过了最艰难的适配期。此时，一套基于 DevCloud + ROCm 7.x 的稳固推理底座才算真正搭建完成，接下来的工作就是根据实际业务流量，微调 vLLM 的并发参数与量化策略了。

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