CUDA 开发排查思路总结

2025-11-19 分类：CS

基于我们刚才从环境配置到最终跑通 RMSNorm 的全过程，整理了一套系统化的 CUDA/HPC 问题排查方法论。这套方法论不仅适用于本项目，也适用于未来所有的 AI Infra 工作。

🛠️ HPC/CUDA 开发通用排查框架 (Troubleshooting Framework)

我们将排查过程分为四个层级：环境层 -> 编译层 -> 运行层 -> 逻辑层。

第一层：环境与配置层 (Environment Layer)

症状：找不到 nvcc，找不到显卡，CMake 报错，路径混淆。

  1. 硬件可见性检查：
    • 核心动作：nvidia-smi
    • 判定：如果没有输出或报错，驱动未安装或 WSL 直通未配置。
  2. 工具链一致性：
    • 核心动作：nvcc --version vs cmake .. 输出的检测信息。
    • 判定：确保编译器版本与 PyTorch/系统版本兼容。
  3. 文件系统隔离 (WSL特有)：
    • 核心动作：检查当前路径 pwd。
    • 判定：严禁在 /mnt/d/... (Windows挂载盘) 下编译 Linux 项目，必须迁移到 ~/... (Linux原生盘)，避免 IO 性能差和缓存路径冲突。
  4. 脏环境清理：
    • 核心动作：rm -rf build && mkdir build
    • 原理：CMake 的缓存机制导致旧的环境变量污染新配置，环境变动后必须全量重构。

第二层：编译构建层 (Build Layer)

症状：Unsupported gpu architecture，变量未定义，链接错误。

  1. 架构匹配 (Arch Matching)：
    • 核心动作：检查显卡算力代号 (Pascal 6.1, Ampere 8.6) -> 修改 CMakeLists.txt 中的 CMAKE_CUDA_ARCHITECTURES。
    • 原理：编译器不知道目标硬件特性（如是否支持 TensorCore），需显式指定。
  2. 语法与作用域：
    • 核心动作：检查报错行号及周边变量定义（如 idx 是否被意外删除）。
    • 原则：CUDA Kernel 对变量作用域要求严格，尤其是 __shared__ 内存和寄存器变量。

第三层：内核启动层 (Kernel Launch Layer)

症状：程序不报错但结果全为 0，结果部分正确部分全 0。

  1. 显式错误捕获 (The Silent Killer)：
    • 核心动作：必加代码 cudaError_t err = cudaGetLastError();。
    • 原理：CUDA Kernel 的启动是异步的，且默认不抛出异常。如果不主动检查，Kernel 挂了 CPU 根本不知道，只会读回一堆 0。
  2. 开箱验货 (Sanity Check)：
    • 核心动作：打印前 5 个数据 (CPU First 5 vs GPU First 5)。
    • 判定：
      • 全是 0 -> Kernel 没启动或参数传错。
      • 全是 nan -> 除以 0 或显存越界。
      • 部分对部分错 -> 线程索引/Block 偏移量逻辑错误。

第四层：数值逻辑层 (Numerical Logic Layer)

症状：Max Diff 很大 (4.65)，Max Diff 接近 1.0。

  1. 建立基准 (Ground Truth)：
    • 核心动作：必须先写一个 cpu_rmsnorm 或使用 torch.nn 的结果作为标准答案。
    • 原则：永远不要觉得“我看代码是对的”，必须用数据验证。
  2. 维度与边界分析：
    • 案例回顾：
      • Diff ≈ 4.65 -> 归一化严重错误 -> Warp 规约逻辑与 Block Size 不匹配（只规约了32个，却启动了1024个）。
      • Diff ≈ 1.0 -> 一行对，一行错 -> Grid 索引缺失（忘了加 offset = blockIdx.x * hidden_dim）。
  3. 最小化复现 (Minimal Working Example)：
    • 核心动作：将 Block Size 从 1024 降为 32，将数据量 rows 降为 1。
    • 原理：先确保一个 Warp、一行数据是对的，再扩展到整个 Grid。

🧠 核心思维模型 (Mental Model)

在解决这个问题时，我们实际上遵循了**“控制变量法”**的工程思维：

  1. Fix the Platform: 先确保舞台（环境）是稳的（WSL迁移）。
  2. Fix the Config: 再确保剧本（CMake）是读得懂的（架构号修改）。
  3. Fix the Communication: 确保导演（CPU）能联系上演员（GPU）（cudaGetLastError）。
  4. Fix the Logic: 最后调整演员的动作（Offset与规约算法）。