Skip to content

troubleshooting.md

Latest commit

 

History

History
457 lines (348 loc) · 8.72 KB

troubleshooting.md

File metadata and controls

457 lines (348 loc) · 8.72 KB

故障排除指南

本指南涵盖了构建和使用 HPC-AI-Optimization-Lab 时的常见问题和解决方案。

目录

编译问题

CMake 配置错误

"Could not find CUDA"

症状：

CMake Error: Could not find CUDA

解决方案：

  1. 验证 CUDA Toolkit 已安装： 
    nvcc --version  # 应显示 CUDA 12.4+
  2. 显式设置 CUDA 路径： 
    export CUDA_HOME=/usr/local/cuda
cmake -S . -B build -DCUDA_TOOLKIT_ROOT_DIR=$CUDA_HOME
  3. 检查 PATH 是否包含 CUDA： 
    echo $PATH  # 应包含 /usr/local/cuda/bin

"CMake version too old"

症状：

CMake Error: CMake was unable to find a build program corresponding to "Unix Makefiles"

解决方案：

  1. 安装 CMake 3.24+： 
    # Ubuntu/Debian
wget https://github.com/Kitware/CMake/releases/download/v3.28.0/cmake-3.28.0-linux-x86_64.sh
chmod +x cmake-*.sh
sudo ./cmake-*.sh --prefix=/usr/local
  2. 或使用 pip： 
    pip install cmake --upgrade

"Compiler doesn't support C++20"

症状：

error: unrecognized command line option '-std=c++20'

解决方案：

  1. 升级 GCC 到 11+： 
    # Ubuntu 22.04+
sudo apt install g++-11
export CXX=g++-11
  2. 或使用 Clang 14+： 
    sudo apt install clang-14
export CXX=clang++-14

编译错误

"Tensor Core requires SM 7.0+"

症状：

error: identifier "wmma::load_matrix_sync" is undefined

解决方案：

  1. 显式指定 GPU 架构： 
    cmake -S . -B build -DCMAKE_CUDA_ARCHITECTURES="80;90"
  2. 或检查您的 GPU： 
    nvidia-smi --query-gpu=compute_cap --format=csv

"Shared memory size exceeds limit"

症状：

error: shared memory array size exceeds maximum

解决方案：

  1. 减小内核配置中的 tile 大小
  2. 使用动态共享内存： 
    extern __shared__ float smem[];
  3. 检查 GPU 共享内存限制： 
    nvidia-smi -q -d MEMORY | grep "Shared"

运行时问题

"Invalid device ordinal"

症状：

CUDA error: invalid device ordinal

解决方案：

  1. 检查可用的 GPU： 
    nvidia-smi -L
  2. 设置可见设备： 
    export CUDA_VISIBLE_DEVICES=0

"Out of memory"

症状：

CUDA error: out of memory

解决方案：

  1. 减小 batch/tensor 大小
  2. 检查 GPU 内存： 
    nvidia-smi
  3. 使用内存池（CUDA 11.2+）： 
    cudaMemPool_t pool;
cudaDeviceGetDefaultMemPool(&pool, 0);

内核启动失败

"Launch out of resources"

解决方案：

  1. 减小 block 大小： 
    // 不用 1024 线程
dim3 block(256);  // 使用更小的 block
  2. 检查寄存器使用： 
    nvcc --ptxas-options=-v kernel.cu

性能问题

Tensor Core 内核性能低

症状： TFLOPS 远低于预期

解决方案：

  1. 确保维度是 16 的倍数： 
    // Tensor Core 要求 M, N, K 能被 16 整除
int M = ((M + 15) / 16) * 16;  // 填充到 16 的倍数
  2. 验证 FP16 输入： 
    // Tensor Core 需要 __half 输入
hpc::Tensor<__half> A(M * K);  // 不是 float
  3. 检查占用率： 
    nvprof --metrics achieved_occupancy ./program

Bank Conflicts

症状： 共享内存操作意外减速

解决方案：

  1. 为共享内存数组添加填充： 
    __shared__ float tile[32][33];  // +1 避免 bank conflict
  2. 使用 Nsight Compute 分析： 
    ncu --metrics l1tex__data_bank_conflicts_pipe_lsu_mem_shared_op_ld ./program

Python 绑定问题

"No module named 'hpc_ai_opt'"

解决方案：

  1. 使用 Python 绑定构建： 
    cmake -S . -B build -DBUILD_PYTHON_BINDINGS=ON
cmake --build build
  2. 设置 PYTHONPATH： 
    export PYTHONPATH="$(pwd)/build/python:${PYTHONPATH}"
  3. 验证： 
    import hpc_ai_opt
print(hpc_ai_opt.__doc__)

"PyTorch tensors must be on CUDA"

症状：

ValueError: Tensors must be on CUDA device

解决方案：

# 错误
x = torch.randn(1024)  # CPU tensor

# 正确
x = torch.randn(1024, device="cuda")  # GPU tensor

NaN 或错误结果

解决方案：

  1. 检查 tensor dtypes 是否匹配： 
    x = torch.randn(1024, device="cuda", dtype=torch.float32)
y = torch.empty_like(x)  # 相同的 dtype 和 device
  2. 验证维度： 
    # FlashAttention 要求 head_dim=64
config = {
    'head_dim': 64,  # 必须是 64
    ...
}

CUDA 错误

错误代码参考

错误代码 描述 常见原因
1 无效值 参数错误
2 内存不足 GPU 内存耗尽
8 无效设备序号 错误的 GPU ID
9 无效内核镜像 架构不匹配
30 未知错误 通常是驱动问题

"CUDA driver version is insufficient"

解决方案：

  1. 检查驱动版本： 
    nvidia-smi  # 查看 "Driver Version"
  2. 更新驱动： 
    # Ubuntu
sudo apt install nvidia-driver-535
  3. 匹配 CUDA 版本：
    CUDA 最低驱动
    12.4 550.54+
    12.3 545.23+
    12.2 535.54+

"CUDA capability not supported"

解决方案：

  1. 检查 GPU 架构： 
    nvidia-smi --query-gpu=compute_cap --format=csv
  2. 为正确的架构构建： 
    # A100 (SM 8.0)
cmake -S . -B build -DCMAKE_CUDA_ARCHITECTURES="80"

# H100 (SM 9.0)
cmake -S . -B build -DCMAKE_CUDA_ARCHITECTURES="90"

调试技巧

启用 CUDA 错误检查

#define CUDA_CHECK(call) \
    do { \
        cudaError_t err = call; \
        if (err != cudaSuccess) { \
            fprintf(stderr, "CUDA error at %s:%d: %s\n", \
                    __FILE__, __LINE__, cudaGetErrorString(err)); \
            exit(EXIT_FAILURE); \
        } \
    } while (0)

// 内核启动后使用
kernel<<<grid, block>>>(args);
CUDA_CHECK(cudaGetLastError());
CUDA_CHECK(cudaDeviceSynchronize());

使用 Compute Sanitizer

# 检查内存错误
compute-sanitizer ./build/tests/gemm/test_gemm

# 检查竞态条件
compute-sanitizer --tool racecheck ./program

# 检查内存泄漏
compute-sanitizer --tool memcheck ./program

使用 Nsight Compute 进行分析

# 详细内核分析
ncu --set full -o profile ./program

# 关注特定指标
ncu --metrics gpu__time_duration.sum ./program

# 比较内核
ncu --set basic ./program

使用 Nsight Systems 查看时间线

# 系统级分析
nsys profile -o timeline ./program

# 查看结果
nsys-ui timeline.nsys-rep

获取帮助

如果您的问题未在此处涵盖：

  1. 搜索现有问题：GitHub Issues
  2. 查阅文档：文档
  3. 在讨论中提问：GitHub Discussions
  4. 报告 bug：使用 Bug 报告模板

报告时请包含：

  • 操作系统和版本
  • CUDA 版本（nvcc --version）
  • GPU 型号和驱动（nvidia-smi）
  • CMake 配置输出
  • 完整的错误信息
  • 最小复现代码

常见问题

问：我可以在没有 GPU 的情况下使用吗？

答：不可以。本库需要具有 Compute Capability 7.0+ 的 NVIDIA GPU。所有内核都在 GPU 上执行。

问：为什么我的内核比预期的慢？

答：常见原因：

  • GPU 架构错误（为您的 GPU 编译）
  • 非最佳维度（为 Tensor Core 填充到 16 的倍数）
  • 低占用率（减少寄存器使用）
  • Bank conflicts（添加填充）

问：这在 Windows 上可用吗？

答：可以，需要 Visual Studio 2022+ 和 CUDA 12.4+。使用 CMake GUI 或 Developer Command Prompt。

问：我可以与 PyTorch 一起使用吗？

答：可以！构建 Python 绑定并直接传递 PyTorch CUDA tensors：

import torch
import hpc_ai_opt

x = torch.randn(1024, device="cuda")
y = torch.empty_like(x)
hpc_ai_opt.elementwise.relu(x, y)

还有问题？提交一个 issue，我们会帮助您！