从报错现场开始：一次真实的 MI250X 踩坑记录

最近在 DevCloud 上调试一个大模型推理任务时，原本顺风顺水的流程突然在 AMD Instinct MI250X 卡上“趴窝”了。代码在 NVIDIA 环境跑得好好的，一切换到 ROCm 7.x 环境，直接抛出 HIP error: invalid device function。这个错误信息看着挺唬人，像是底层硬件不支持或者驱动彻底挂了，但检查 rocminfo 发现显卡识别正常，版本也对得上。

这种“明明环境看似没问题，就是跑不通”的情况最搞心态。经过大半天的排查和日志分析，终于定位到问题核心：并不是硬件不行，而是PyTorch 的编译方式和容器环境的库映射这两个细节没处理好。特别是当我们习惯性地使用 pip install -e .（可编辑模式）去调试源码时，在 ROCm 的容器化环境下极易引发符号链接断裂，导致运行时找不到正确的 HIP 内核函数。

核心病灶：可编辑模式与符号链接的陷阱

很多开发者（包括我）在调试 PyTorch 源码或自定义算子时，首选命令往往是：

PYTORCH_ROCM_ARCH=gfx90a pip install -e .

在传统的 CUDA 环境下，这通常没问题。但在 ROCm 7.x + Singularity 容器的组合拳下，这会埋个大雷。可编辑模式本质上是创建了一系列指向源码构建目录的符号链接。当程序在容器内运行时，如果容器挂载策略没有完美复刻宿主机的路径结构，或者 ROCm 的动态链接器无法正确解析这些跨层级的符号链接，就会导致加载到的库文件不完整。

具体表现就是：编译时一切正常，因为编译器能顺着链接找到头文件和中间产物；但运行时，动态链接器试图加载包含 GPU 内核的代码对象（Code Object）时，发现路径失效或文件缺失，于是抛出 invalid device function。这就好比你给同事指路说“去那个房间”，结果那个房间是个只有门框没有墙的“符号链接”，同事自然走不进去。

此外，Singularity 容器默认的安全策略可能会隔离 /dev/kfd 和 /dev/dri 设备，或者未能正确绑定主机上的 ROCm 库路径。如果容器内的 libamdhip64.so 版本与宿主机驱动不匹配，或者根本没能挂载进来，也会复现同样的错误。

解决方案：重构编译流程与容器配置

要解决这个问题，必须放弃“偷懒”的可编辑模式，转而采用更稳健的构建方式，并精细化配置容器环境。

1. 改用 Wheel 模式编译

最直接有效的办法是使用 pip wheel 进行完整构建，生成独立的二进制包，而不是依赖符号链接。这样生成的库文件是实打实的物理文件，不再受路径映射问题的困扰。

请将之前的安装命令替换为：

# 设置正确的 GPU 架构，MI250X 对应 gfx90a
export PYTORCH_ROCM_ARCH="gfx90a"

# 禁用构建隔离，确保使用系统已安装的 ROCm 依赖
# --no-deps 避免重复下载不必要的包，加速构建
pip wheel --no-deps --no-build-isolation .

# 安装生成的 wheel 包
pip install *.whl

这一步虽然编译时间稍长，但它确保了所有 HIP 内核代码都被正确地编译并打包进 Python 站点-packages 目录中，彻底切断了符号链接带来的不确定性。

2. 优化 Singularity 容器启动参数

如果你是在集群环境中通过 Singularity 运行，必须显式地告诉容器去映射哪些设备和库。默认的 --rocm 标志有时不够用，特别是在自定义构建的场景下。

建议的启动命令如下：

singularity exec \
  --bind /dev/kfd:/dev/kfd \
  --bind /dev/dri:/dev/dri \
  --bind /opt/rocm/lib:/opt/rocm/lib \
  --env PYTORCH_ROCM_ARCH=gfx90a \
  --env HSA_OVERRIDE_GFX_VERSION=9.0.0 \
  your_image.sif \
  python your_script.py

这里的关键点在于：

• 设备映射：显式绑定 /dev/kfd（AMD GPU 的内核驱动接口）和 /dev/dri（Direct Rendering Infrastructure），这是 GPU 通信的咽喉。
• 库路径绑定：强制将宿主机的 /opt/rocm/lib 映射到容器内，防止容器内自带的旧版库干扰。
• 环境变量注入：确保容器进程能感知到正确的架构版本。

深度调试：用 ldd 揪出隐藏的依赖问题

如果按照上述步骤操作后仍然报错，不要盲目重试，需要用工具“照妖镜”来查看动态库依赖。ldd 是 Linux 下检查共享库依赖的神器。

找到 PyTorch 的核心动态库文件（通常位于 site-packages/torch/lib/ 或类似路径），运行：

ldd /path/to/torch/_C.cpython-3x-x86_64-linux-gnu.so | grep hip

正常情况下，你应该能看到类似 libamdhip64.so => /opt/rocm/lib/libamdhip64.so 的解析结果。如果输出显示 not found，或者指向了一个奇怪的路径（比如指向了构建目录的临时文件），那就说明依赖解析确实出了问题。

此时，可以结合 AMD_LOG_LEVEL 环境变量来获取更详细的运行时日志：

export AMD_LOG_LEVEL=5
export TORCH_LOGS="+dynamo,+inductor"
# 再次运行你的脚本
python your_script.py

详细日志会打印出内核加载的具体过程，通常会明确指出是哪个具体的 kernel 函数加载失败，这能帮你进一步确认是否是架构参数（gfx90a）设置偏差导致的。

避坑总结与环境验证

修复完上述问题后，别急着跑大模型，先写个最小的 Demo 验证环境是否真正通畅。以下代码片段能在几秒钟内告诉你 GPU 是否就绪：

import torch

print(f"ROCm available: {torch.cuda.is_available()}")
if torch.cuda.is_available():
    print(f"Device count: {torch.cuda.device_count()}")
    print(f"Current device: {torch.cuda.get_device_name(0)}")
    
    # 尝试创建一个张量并移动到 GPU
    x = torch.randn(3, 3).to('cuda')
    y = x * 2
    print("Tensor operation on MI250X successful!")
else:
    print("GPU not detected, check driver and container mapping.")

这次经历让我深刻意识到，在 AMD ROCm 生态下，“能编译”不等于“能运行”。特别是涉及容器化和源码调试时，文件系统的物理布局和环境变量的精确传递至关重要。对于 MI250X 这类高性能计算卡，只要绕开可编辑模式的符号链接陷阱，并确保容器对底层设备的透明访问，PyTorch 的表现其实非常稳定。希望这篇复盘能帮到正在被 invalid device function 折磨的你，让大家在 DevCloud 上的炼丹之路少一些波折。

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