CUDA / PyTorch 自检

平台不在创建响应里写死「本机 CUDA = x.y」。版本由所选系统镜像 + 驱动 + 你安装的框架 wheel共同决定。本页给可复现的检查命令与分层排障。

镜像选型见 系统镜像与 CUDA。

#分层模型

应用框架 (PyTorch / TensorFlow)
        ↑  需匹配的 CUDA runtime(wheel 自带或系统)
CUDA Toolkit / nvcc(可选,镜像未必有)
        ↑
NVIDIA 驱动 (nvidia-smi)
        ↑
GPU 硬件 (nvidia-smi -L)

nvidia-smi 右上角 CUDA Version = 驱动支持的最高 CUDA,不是 nvcc --version,也不是 torch.version.cuda。

#硬件与驱动

nvidia-smi
nvidia-smi -L
nvidia-smi --query-gpu=name,memory.total,driver_version,pci.bus_id --format=csv
cat /proc/driver/nvidia/version 2>/dev/null
现象处理
nvidia-smi: command not found 或失败确认选了 CUDA 类镜像、实例为运行中;仍失败带平台实例编号提单
卡数少于下单对照配置卡数;附 nvidia-smi -L 输出提单
驱动正常但无 nvcc正常:许多运行镜像只带驱动 + CUDA runtime,不含完整 toolkit

#CUDA Toolkit(若有)

nvcc --version
which nvcc
echo $CUDA_HOME
ls /usr/local/cuda*/version.json 2>/dev/null
ls /usr/local/cuda/lib64/libcudart.so* 2>/dev/null

需要编译自定义 CUDA 扩展时,应选择带对应 toolkit 的镜像,或按 NVIDIA 文档自行安装,并注意与驱动上限兼容。

#PyTorch

python3 - <<'PY'
import torch
print("torch:", torch.__version__)
print("cuda available:", torch.cuda.is_available())
print("torch.version.cuda:", torch.version.cuda)
print("device_count:", torch.cuda.device_count())
if torch.cuda.is_available():
    print("device0:", torch.cuda.get_device_name(0))
    print("capability:", torch.cuda.get_device_capability(0))
    x = torch.randn(1024, 1024, device="cuda")
    print("matmul ok:", float((x @ x).sum()))
PY

torch.cuda.is_available() == False 但 nvidia-smi 正常时:

  1. 1. 是否装了 CPU 版 wheel
  2. 2. 当前 venv / conda 是否指对
  3. 3. wheel 的 CUDA 标签是否高于驱动支持上限

安装示例(版本号自行替换为与镜像匹配的组合,以 PyTorch 官方矩阵为准):

python3 -m pip install torch --index-url https://download.pytorch.org/whl/cu128

#Docker + GPU(镜像带 Docker 时)

docker version
docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu22.04 nvidia-smi

容器内再装框架时,同样要满足「驱动 ≥ 容器 CUDA」关系。

#显存与进程

nvidia-smi
# 结束占用:kill <pid> 或在训练代码中释放
python3 - <<'PY'
import torch
torch.cuda.empty_cache()
print(torch.cuda.memory_summary())
PY

OOM 时优先减 batch、开 gradient checkpoint、清残留进程,再考虑换更大显存规格。

#多卡

nvidia-smi -L
echo $CUDA_VISIBLE_DEVICES
检查期望
device_count等于下单卡数(未设置 CUDA_VISIBLE_DEVICES 时)
NCCL / 分布式按框架文档设置;先单机 all_reduce 小测

#仍异常时提供给工单

  • - 平台实例编号、区域、镜像展示名
  • - nvidia-smi 全文
  • - python3 -c "import torch; ..." 输出或报错
  • - /etc/os-release 前几行

基础设施类问题由平台跟进;先完成上述自检可缩短定位时间。

#相关文档