Github 协作规范，如何让 ROCm 相关的代码提交更专业

写好 PR 描述：让硬件差异透明化

在 ROCm 生态中提交代码，最大的挑战往往不是算法逻辑本身，而是隐蔽的硬件环境差异。作为维护者，我最怕看到的 PR 描述只有一句"Fix bug on AMD GPU"。AMD 的架构迭代快，MI250、MI300X 以及未来的 Instinct 系列在 Wavefront 尺寸、内存层级上都有显著区别，驱动版本（如 ROCm 6.1 vs 6.2）对算子的支持度也截然不同。

一份专业的 PR 描述，本质上是一份可复现的测试报告。在涉及SGLang推理后端或TileLang算子优化时，务必在描述中明确列出以下元数据：

  • 硬件型号：具体到 GPU SKU（例如AMD Instinct MI300X），而非笼统的"AMD GPU"。
  • 软件栈版本：精确到ROCm小版本号、HIP编译器版本以及容器镜像的 Tag。
  • 操作系统内核：某些底层通信库（如 RCCL）的行为受内核参数影响较大。
  • 测试场景：说明是在单卡调试还是多卡分布式环境下验证，若是多卡，需注明互联拓扑（PCIe 或 Infinity Fabric）。

例如，当你修复了LLaMA-Factory在特定精度下的收敛问题时，不要只说“修复了数值误差”，而应表述为：“在 ROCm 6.2 + MI300X 环境下，针对 BF16 混合精度训练进行了验证，对比 FP32 基准，Loss 曲线偏差小于 1e-4"。这种透明度能极大减少维护者的沟通成本，让他们一眼就能判断你的补丁是否覆盖了目标用户群。

避坑指南：代码审查中的高频驳回点

很多来自 CUDA 背景的贡献者，代码逻辑完美，却在 Code Review 环节被反复打回。究其原因，往往是忽略了 ROCm 特有的编程范式或引入了隐式依赖。以下是几个最容易“踩雷”的区域：

首先是硬编码的线程配置。在 NVIDIA 生态中，Warp Size 固定为 32，许多开发者习惯将blockDim.x写死为 32 的倍数。但在 AMD 架构中，Wavefront Size 虽然通常也是 64，但不同代际架构可能存在差异，且最佳性能配置往往需要匹配具体的 Compute Unit 数量。如果在TileLang生成的内核或手动编写的 HIP 代码中硬编码了线程数，而未使用hipGetDeviceProperties动态查询，这类代码通常会被直接驳回。

其次是隐式的 CUDA 依赖残留。这是最隐蔽的问题。有时候hipify-perl能转换大部分 API，但会漏掉一些第三方库的路径引用。比如在 CMakeLists.txt 中显式链接了cudart而非hiprt，或者在 Python 脚本中通过os.environ强制注入了CUDA_VISIBLE_DEVICES。审查时，我们会重点检查是否有平台特定的硬编码路径，确保代码在非 NVIDIA 环境下能干净地编译和运行。

最后是缺乏回退机制。ROCm 生态仍在快速演进，某些新特性（如特定的 FP8 格式支持）可能在旧版驱动上不可用。高质量的贡献应当包含版本检测逻辑，当检测到不支持的硬件特性时，优雅地降级到通用实现，而不是直接抛出异常导致程序崩溃。

搭建跨平台 CI：用自动化守住质量底线

人工测试总有疏漏，尤其是在多卡集群资源紧张的情况下。利用 GitHub Actions 构建自动化的 CI/CD 流水线，是确保 ROCm 相关代码稳定性的最后一道防线。对于开源项目而言，我们不一定能在 CI 环境中接入真实的昂贵 GPU 实例，但可以通过策略组合来最大化测试覆盖率。

一个典型的跨平台 CI 配置应包含三个阶段：

  1. 静态检查与编译验证：在无 GPU 的 Runner 上，使用 ROCm 官方提供的 Docker 镜像进行语法检查和编译测试。这一步能快速发现头文件缺失、API 拼写错误等基础问题。
  2. 单元测试模拟：利用 CPU 模式的 HIP 运行时或 Mock 对象，运行核心逻辑的单元测试。虽然无法测试性能，但能确保逻辑正确性。
  3. 夜间集成测试（Nightly Build）：如果项目拥有自建的 GPU 集群，可以配置 Self-hosted Runner，在夜间闲时触发全量集成测试。这一步专门用于运行SGLang的端到端推理测试或LLaMA-Factory的微调流程，捕捉那些只有在真实硬件上才会暴露的竞态条件或显存泄漏问题。

在配置.github/workflows/rocm_test.yml时，建议矩阵化测试不同的 ROCm 版本。例如，同时覆盖当前稳定的 6.x 版本和最新的 nightly 构建，确保代码既兼容现有用户，又不会阻碍未来的升级。通过这种自动化的“安全网”，贡献者可以在提交 PR 前就获得反馈，维护者也能放心地合并代码，共同推动 ROCm 大模型生态的成熟。

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