PyTorch如何正确启用CUDA并验证GPU可用性？

Question

**常见技术问题：** 在PyTorch项目中，调用 `torch.cuda.is_available()` 返回 `False`，或模型/张量无法通过 `.cuda()` 或 `.to('cuda')` 迁移到GPU，但系统已安装NVIDIA驱动和CUDA Toolkit。可能原因包括：① PyTorch安装的是CPU-only版本（如通过`pip install torch`未指定CUDA版本）；② PyTorch编译时链接的CUDA运行时版本与系统`nvidia-smi`显示的驱动支持的CUDA版本不兼容（如驱动仅支持CUDA 12.2，却安装了CUDA 12.4版PyTorch）；③ 环境变量`CUDA_VISIBLE_DEVICES`被错误设为空或无效值；④ 多Python环境（conda/virtualenv）中混用了不同CUDA配置的PyTorch。如何系统性排查并确保PyTorch正确识别、启用并稳定使用GPU？

Answer 1

```html

一、现象确认：验证GPU可用性基础状态

首先排除误判，执行最小化诊断脚本：

import torch
print("PyTorch版本:", torch.__version__)
print("CUDA是否可用:", torch.cuda.is_available())
print("CUDA版本（PyTorch编译时）:", torch.version.cuda)
print("cuDNN版本:", torch.backends.cudnn.version() if torch.cuda.is_available() else "N/A")
print("可见GPU设备数:", torch.cuda.device_count())
if torch.cuda.is_available():
    for i in range(torch.cuda.device_count()):
        print(f"  GPU-{i}: {torch.cuda.get_device_name(i)} (计算能力: {torch.cuda.get_device_capability(i)})")

⚠️ 注意：torch.version.cuda 是PyTorch二进制包编译所链接的CUDA Toolkit版本，不等于系统驱动支持的最高CUDA版本，也不等于nvidia-smi显示的CUDA版本（该值为驱动向后兼容的运行时上限）。

二、驱动与CUDA生态对齐：理解nvidia-smi vs nvcc的语义鸿沟

命令	输出含义	典型误区
nvidia-smi	显示当前NVIDIA驱动版本及其支持的最高CUDA运行时版本（右上角）	误认为该数字是已安装的CUDA Toolkit版本
nvcc --version	显示本地安装的CUDA Toolkit编译器版本（需PATH包含/usr/local/cuda/bin）	未安装CUDA Toolkit时此命令不存在，但PyTorch仍可运行（因自带精简runtime）

✅ 正确逻辑链：Driver Version ≥ CUDA Toolkit Version → PyTorch CUDA Build Version ≤ Driver's Max Supported CUDA。例如：驱动470.82支持CUDA 11.4，而PyTorch 2.1.0+cu118要求CUDA 11.8 → ❌ 不兼容；应选用torch==2.1.0+cu117或升级驱动。

三、环境隔离审计：多Python环境下的CUDA配置污染检测

使用以下命令交叉验证环境一致性：

• which python & python -c "import sys; print(sys.executable)"
• pip show torch 或 conda list pytorch（注意channel来源）
• python -c "import torch; print(torch._C._cuda_getCurrentRawStream(0))"（仅CUDA版有此属性）

常见陷阱：conda activate myenv 后仍运行系统Python（PATH未切换），或Jupyter Kernel绑定错误环境。建议统一用python -m pip install ...避免pip/conda混装。

四、CUDA_VISIBLE_DEVICES深度调试：从静默失效到显式诊断

该变量影响torch.cuda.device_count()和设备索引映射。执行以下测试：

import os
os.environ["CUDA_VISIBLE_DEVICES"] = "0"  # 显式设置
import torch
print("CUDA_VISIBLE_DEVICES='0' → device_count:", torch.cuda.device_count())  # 应为1

os.environ["CUDA_VISIBLE_DEVICES"] = "-1"  # 强制禁用
print("CUDA_VISIBLE_DEVICES='-1' → is_available:", torch.cuda.is_available())  # 应为False

# 检查是否被父进程继承污染
print("继承自环境:", os.environ.get("CUDA_VISIBLE_DEVICES", "NOT SET"))

💡 进阶技巧：在Slurm/PBS等调度系统中，常因--gres=gpu:0导致该变量为空字符串（""），触发PyTorch内部设备枚举异常——需在代码开头强制重置为"0"。

五、终极验证与稳定性加固：端到端GPU工作流压测

构建不可绕过的黄金验证流程（含错误捕获）：

def gpu_health_check():
    assert torch.cuda.is_available(), "CUDA不可用，请检查安装"
    device = torch.device("cuda")
    x = torch.randn(1000, 1000, device=device)
    y = torch.randn(1000, 1000, device=device)
    z = torch.mm(x, y)  # 触发实际GPU计算
    assert z.device.type == "cuda", "张量未驻留GPU"
    assert z.dtype == torch.float32, "精度异常"
    torch.cuda.synchronize()  # 确保kernel完成
    print("✅ GPU计算流通过，显存占用:", torch.cuda.memory_allocated()/1024**2, "MB")

gpu_health_check()

六、版本矩阵决策树（Mermaid流程图）

graph TD A[torch.cuda.is_available() == False?] -->|Yes| B{检查PyTorch CUDA构建} B --> C["pip show torch
查看Version字段是否含'+cu118'等后缀"] C -->|不含| D[重新安装CUDA版：pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118] C -->|含| E{对比驱动支持CUDA版本} E --> F["nvidia-smi → 右上角CUDA Version"] F -->|PyTorch CUDA版本 > 驱动支持版本| G[升级驱动 或 降级PyTorch] F -->|兼容| H{检查CUDA_VISIBLE_DEVICES} H -->|为空/非法| I[unset CUDA_VISIBLE_DEVICES 或 设为有效ID] H -->|正常| J[检查多环境冲突 → 重装隔离环境]

```