编译期报错：依赖冲突与路径指向的“硬骨头”

在将 CUDA 代码迁移至 ROCm 平台的过程中，编译期往往是我们遇到的第一道“拦路虎”。很多开发者习惯性地认为只要安装了驱动就能直接编译，结果却在 cmake 或 pip install 阶段被各种找不到符号、版本不匹配的报错劝退。这类问题最典型的特征是：系统里明明装了 ROCm，编译器却还在死磕 CUDA 的头文件。

记得有一次团队在编译自定义算子时，终端疯狂抛出 fatal error: cuda_runtime.h: No such file or directory。乍一看以为是环境没配好，仔细检查才发现是构建脚本中硬编码了 CUDA 的路径，或者环境变量 ROCM_PATH 未被正确识别。更隐蔽的情况是混用了不同版本的 wheel 包——比如 PyTorch 是 ROCm 版，但底层的 flash-attention 却是基于 CUDA 编译的，这种“混搭”必然导致链接错误。

排查与修复实录：
遇到这类问题，第一步永远是“隔离环境”。我们强烈建议使用 Conda 或 Docker 容器，确保内部纯净。

1. 检查环境变量：在编译前，务必显式导出关键变量。

   export ROCM_PATH=/opt/rocm
   export HIP_VISIBLE_DEVICES=0
   

2. 清理缓存：很多时候旧的构建缓存会干扰新配置。执行 rm -rf build/ 和 pip cache purge 是基本操作。
3. 验证工具链：使用 hipcc --version 确认当前调用的确实是 HIP 编译器，而不是系统的 gcc 或 nvcc。

如果报错信息中提到 undefined reference to 'hipMalloc'，这通常意味着链接器没有找到 ROCm 的动态库。此时需要在 CMakeLists.txt 中明确指定 hip::host 和 hip::device 目标，而不是手动去拼凑 -L 和 -l 参数。把这些坑填平后，90% 的编译报错都能迎刃而解。

运行时崩溃：Kernel 启动配置与显存管理的陷阱

代码能编译通过，不代表能跑起来。运行时错误往往更加晦涩，程序可能直接 Segmentation Fault，或者静默地输出错误结果。在 ROCm 环境下，最常见的问题集中在 Kernel 启动配置无效以及显存管理差异上。

AMD GPU 的线程束（Wavefront）尺寸通常是 64，而 NVIDIA 是 32。如果直接沿用 CUDA 代码中的 Block 和 Grid 配置，可能会导致资源分配超出硬件限制，触发 HIP_ERROR_INVALID_CONFIGURATION。我们就曾在一个 Attention 算子上栽过跟头，代码在 NVIDIA 卡上跑得飞起，一到 MI250 上就崩溃，日志里只有一行冷冰冰的 Kernel launch configuration invalid。

典型故障复盘：

• 现象：程序启动瞬间崩溃，日志显示 HIP runtime error: hipErrorInvalidConfiguration。
• 根因：原有的 CUDA 代码假设 Block Size 为 1024 且未检查 Wavefront 对齐，或者共享内存（LDS）用量超过了单块上限。
• 修复步骤：
  1. 动态查询属性：不要硬编码线程数。使用 hipGetDeviceProperties 获取 warpSize 和 sharedMemPerBlock。
  2. 调整启动参数：将 Block Size 调整为 64 的倍数，并确保总共享内存用量在安全范围内。

  // 错误示范：硬编码
  // myKernel<<<gridDim, 1024>>>(...); 
  
  // 正确做法：根据设备属性动态计算
  int warpSize = props.warpSize;
  int blockSize = 256; // 确保是 warpSize 的整数倍
  myKernel<<<gridDim, blockSize>>>(...);
  

  3. 显存监控：利用 rocm-smi 实时监控显存占用。如果发现显存泄漏或未释放，检查是否有 hipMalloc 后遗漏了 hipFree，特别是在异常处理分支中。

此外，多卡环境下的通信死锁也是运行时的高发区。在使用 RCCL 进行分布式训练时，如果网络拓扑配置不当，容易卡在 allReduce 阶段。这时需要检查 MASTER_ADDR 和 MASTER_PORT 是否正确设置，并尝试调整 RCCL 的超时阈值环境变量 NCCL_TIMEOUT（ROCm 中兼容该变量名）来避免误判。

性能异常：算子效率低下与精度偏差的优化

当程序能稳定运行后，接下来的挑战就是性能。很多团队在迁移后发现，虽然功能正常，但推理延迟比预期高了 30%，或者训练吞吐量上不去。这通常是因为通用算子未能充分利用 AMD 架构的特性，或者是数值精度处理不当。

我们在测试 SGLang 部署时发现，默认的矩阵乘法算子在长序列场景下效率不佳。这是因为数据在全局内存和共享内存之间的搬运策略没有针对 CDNA 架构优化。引入 TileLang 进行算子重写后，通过精细控制分块（Tiling）策略，让数据更好地驻留在 LDS 中，显著减少了内存访问延迟。

优化实战笔记：

• 算子级调优：对于计算密集型的 MatMul 或 Conv 操作，不要盲目相信默认实现。使用 TileLang 描述数据流动，手动指定分块大小以匹配 Wavefront 尺寸。实测表明，针对特定形状定制的内核，性能可提升 20% 以上。
• 精度对齐：在微调大模型时，偶尔会遇到损失曲线震荡或不收敛的情况。这往往是混合精度训练（AMP）中缩放因子（Scale Factor）在 ROCm 后端表现不同导致的。
  • 对策：尝试关闭 AMP，使用纯 FP32 进行短步数测试，观察收敛情况。如果确认是精度问题，可以调整 Loss Scaler 的初始值，或者在关键算子中强制使用 FP32 累加。
• 量化适配：SGLang 支持 INT8/FP8 量化，但在 ROCm 上需要确保底层内核已适配。如果开启量化后速度反而变慢，可能是触发了软件模拟路径。此时应检查是否加载了正确的量化库，并确认显卡架构是否原生支持该数据类型。

建立团队共享的“错题本”机制

技术迁移不是一锤子买卖，而是一个持续踩坑、填坑的过程。为了避免同一个错误被不同成员重复排查，我们建立了一套共享的“错题本”机制。这份文档不是简单的报错截图集合，而是按照“编译期”、“运行时”、“性能异常”分类的结构化知识库。

每个条目都包含三个核心要素：错误日志片段（脱敏后）、触发条件分析（如特定驱动版本、特定模型结构）以及具体修复步骤。例如，针对前面提到的 Kernel 启动配置问题，文档里不仅记录了修改后的代码，还附上了 rocm-gdb 的调试命令和分析思路。

我们建议团队定期更新这份手册，并将其纳入新人入职的培训材料。每当解决一个疑难杂症，就花 10 分钟整理成文档推送到共享仓库。久而久之，这套沉淀下来的经验将成为团队最宝贵的资产，让新成员在面对复杂环境时不再手足无措，也能让大家把更多精力投入到真正的业务创新中去。毕竟，在异构计算的道路上，少走弯路就是最快的捷径。

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