那些让我抓狂的头文件路径“鬼打墙”

刚开始用 hipify-perl 跑脚本时，我以为只要把 .cu 后缀改成 .hip，世界就和平了。结果编译器直接甩给我一个 fatal error: 'cuda_runtime.h' file not found。当时我第一反应是环境变量没配好，反复检查 ROCM_PATH，甚至重装了驱动，折腾半天才发现是工具链的“惯性”在作祟。

现象：编译报错提示找不到 CUDA 标准头文件，但系统中明明只安装了 ROCm。
原因：部分老旧的 CMake 列表或硬编码的 include 路径里，依然写死了 /usr/local/cuda/include。hipify 工具虽然能替换代码里的 API 调用（比如把 cudaMalloc 换成 hipMalloc），但它不会智能地修改构建系统里的路径配置。更坑的是，有些第三方库的 CMakeLists.txt 里显式查找 FindCUDA 模块，而 ROCm 环境下应该找 FindHIP。
修复方案：
别盲目改全局变量。首先搜索项目中所有硬编码的 cuda 路径，全部替换为 ${ROCM_PATH}/include。如果是 CMake 项目，将 find_package(CUDA) 改为 find_package(hip REQUIRED)。

如果你是在编译依赖包（比如某个自定义算子）时遇到这问题，可以在编译命令前强制指定 include 路径：

export CPLUS_INCLUDE_PATH=/opt/rocm/include:$CPLUS_INCLUDE_PATH
export HIP_PLATFORM=amd

还有一个隐蔽的坑：某些 IDE（如 VS Code）的智能提示插件可能还在索引旧的 CUDA 目录，导致你看着代码没红线，一编译就挂。这时候清理一下 IDE 的缓存索引，确保它指向 /opt/rocm 才是正解。

链接器哭诉：符号未定义与库的“张冠李戴”

解决了头文件，接下来就是链接阶段的“连环撞车”。最典型的报错是 undefined reference to 'hipLaunchKernelGGL' 或者更诡异的 cannot find -lcublas。这时候千万别顺手去装 NVIDIA 的 cuBLAS，那是火上浇油。

现象：编译通过，链接失败，提示找不到 HIP 运行时符号，或者错误地尝试链接 CUDA 专属库。
原因：这是典型的“混合依赖”事故。Python 生态里很多 wheel 包默认绑定 CUDA 版本的 torch 或 tensorflow。当你试图在 ROCm 环境下链接它们时，链接器会去寻找 libcudart.so 而不是 libhiprtc.so。另外，有些项目在 LD_LIBRARY_PATH 里残留了旧环境的 CUDA 路径，优先级高于 ROCm 库路径，导致链接器“看花眼”。
修复方案：
第一步，彻底隔离环境。强烈建议用 Conda 新建一个纯净环境，并且只安装带有 rocm 标签的 PyTorch：

conda install pytorch torchvision torchaudio pytorch-cuda=11.8 # 绝对不要运行这条！
# 正确做法：
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm6.0

第二步，检查链接参数。如果在编译 C++ 扩展，确保 LDFLAGS 里没有 -lcuda 或 -lcublas，取而代之的应该是 -lhipblas 或 -lrocblas。
我曾在一个深度学习项目的 setup.py 里发现这样一行硬编码：

extra_link_args = ['-lcublas', '-lcudnn'] 

直接改成：

extra_link_args = ['-lhipblas', '-lmiopen']

问题瞬间解决。记住，ROCm 的库命名通常把 cu 换成 roc 或 hip，但也不完全绝对，比如 cudnn 对应的是 MIOpen，这种映射关系得记在小本本上。

SGLang 启动时的“后端迷失”与显存玄学

代码迁移完了，到了真正跑大模型推理的时候，麻烦才刚刚开始。using SGLang 部署时，我经常遇到服务启动即崩溃，或者显存占用异常飙升的情况。

现象：运行 python -m sglang.launch_server 时，报错 Backend backend is not supported，或者进程卡住不动，hip-smi 查看显存却被占满。
原因：SGLang 默认可能尝试加载 CUDA 后端，或者在初始化 KV Cache 时使用了不兼容的内存分配策略。AMD GPU 的显存管理机制和 NVIDIA 略有不同，特别是在多卡通信时，如果没指定正确的后端，它会试图调用不存在的 NCCL 接口。
修复方案：
启动时必须显式声明后端。不要依赖自动检测，直接在命令行加上：

python -m sglang.launch_server --model-path meta-llama/Llama-3-8B-Instruct --port 30000 --device cuda --mem-fraction-static 0.8

等等，这里有个陷阱！虽然参数叫 --device cuda（为了兼容代码逻辑），但在 ROCm 环境下，你需要确保环境变量 HIP_VISIBLE_DEVICES 设置正确，并且安装的是支持 ROCm 的 SGLang 分支。如果官方源还没合并 PR，可能需要从特定的 fork 版本安装。

关于显存暴涨，通常是 Continuous Batching 的配置问题。尝试调整 --schedule-conservativeness 参数，AMD 架构下可能需要更保守的策略来避免 OOM。我还遇到过一次因为 flash_attention 算子未适配导致的静默失败，后来通过引入 TileLang 重写了关键的 Attention 内核，不仅解决了崩溃，吞吐量还提升了 20%。这说明通用算子在特定硬件上真的不能“拿来就用”。

微调时的梯度爆炸与 LLaMA-Factory 的适配坑

最后一步是用 LLaMA-Factory 做微调验证。本以为有了前面的铺垫，这里会一帆风顺，结果训练 Loss 直接变成 NaN，或者报 RuntimeError: CUDA error: an illegal memory access was encountered（哪怕我是在 AMD 卡上跑的，报错信息有时候依然写着 CUDA，这是因为 PyTorch 底层抽象没完全剥离）。

现象：训练开始后几步 Loss 变为 NaN，或者随机出现非法内存访问错误导致中断。
原因：这多半是混合精度训练（AMP）在 ROCm 下的数值稳定性问题。AMD 的 FP16 计算单元在某些边界条件下与 NVIDIA 表现不一致，导致梯度溢出。此外，DeepSpeed 的 ZeRO 阶段如果在 RCCL（ROCm 版 NCCL）未正确初始化时强行开启，也会引发通信死锁。
修复方案：
首先，尝试关闭 AMP，使用纯 FP32 训练看看是否稳定。如果正常，再逐步开启 BF16（如果显卡支持）代替 FP16。在 LLaMA-Factory 的配置文件 ds_config.json 中，明确指定：

"fp16": {
    "enabled": false
},
"bf16": {
    "enabled": true
}

其次，检查分布式后端。确保 torch.distributed 使用的是 gloo 或 rccl 而不是 nccl。可以通过设置环境变量强制指定：

export TORCH_DISTRIBUTED_DEBUG=DETAIL
export HCCL_HOME=/opt/rocm/hccl

如果在多卡环境下遇到 hangs，试着增加超时阈值：export NCCL_TIMEOUT=3600（是的，变量名还是 NCCL，但实际指向 RCCL）。

这一路踩坑下来，最大的感悟是：迁移不是简单的“查找替换”，而是一次对底层原理的重新审视。把这些报错现象、日志片段和对应的“土办法”记录下来，下次再遇到类似的“鬼打墙”，至少能少掉几根头发。希望这份错题本能帮你避开这些暗礁，让你的 AMD 显卡早日火力全开。

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