CUDA 环境安装与版本匹配

CUDA 环境安装与版本匹配

版本链路是这样的：显卡驱动决定支持的最高 CUDA runtime，CUDA 版本决定能装哪个 Toolkit，Toolkit 决定编译出的二进制能跑在哪些架构上。装之前先看驱动能支持到哪一档，按官方兼容性表选 Toolkit 版本，不要盲目装最新。

1. 查驱动与算力：

   nvidia-smi
   nvidia-smi --query-gpu=name,driver_version,compute_cap --format=csv

2. 安装 Toolkit，三条路线按需选：发行版仓库（apt / dnf，方便但可能顺带升级驱动）、官方 runfile（可精细挑组件、不动驱动）、conda（只做 Python 侧隔离环境）。

   # 以官方 runfile 为例，版本按兼容性表选择
   sudo sh cuda_<版本>_linux.run --silent --toolkit --no-opengl-libs

3. 配置环境变量：

   export CUDA_HOME=/usr/local/cuda
   export PATH=$CUDA_HOME/bin:$PATH
   export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH

   注意运行时库路径与编译期路径要指向同一个版本，机器上装了多个 CUDA 时最容易出错。
4. 容器方案（生产推荐）：

   # 宿主机先装 nvidia-container-toolkit
   docker run --gpus all -it --rm \
     -v $(pwd):/workspace \
     nvidia/cuda:<版本>-devel-ubuntu22.04

   容器内不需要再装驱动，驱动由宿主机透传，所以容器里的 CUDA 版本不能高于驱动支持的上限。
5. 验证：

   nvcc --version
   nvidia-smi
   deviceQuery   # 来自 cuda-samples，输出设备属性与算力

常见报错：nvcc: command not found，PATH 没配；no CUDA-capable device is detected，驱动没装、容器没加 --gpus，或者虚拟机里没做直通；CUDA driver version is insufficient for CUDA runtime version，驱动太旧，降 CUDA 或升驱动；unsupported gpu architecture，编译时指定的算力与 Toolkit 不匹配，用 -arch=native 或按 compute_cap 显式指定；no kernel image is available for execution on the device，编译时没有把目标架构的 SASS 打进二进制，检查 -gencode 参数。WSL2 下可以跑，但显存管理与性能表现与原生 Linux 有差异，生产环境不推荐。