PyTorch 安装与验证

PyTorch 安装与验证

系列第 2 篇。上一篇 GPU 底座打完，本篇装本地 AI 的核心框架 PyTorch。重点解决四个问题：去 pytorch.org 选择器怎么选 pip 命令；cu124 / cu118 / cpu 三种 wheel 怎么选；国内怎么加速；装完用哪三步验证"真的上卡了"。读完你能装出一个torch.cuda.is_available()返回True的环境，并避开 32 位 Python、CPU 版装成默认这两类最阴的坑。

一、为什么需要它

PyTorch 是本地 AI 的事实标准底座：跑大模型推理、微调、图像生成（Stable Diffusion 全家桶）、Whisper 语音识别，底层几乎都是它。本篇的"验证三步"会成为后面 28 篇的公共检查点——以后任何一篇报 GPU 相关的错，第一反应都是回到这三步查环境。

装 PyTorch 的坑不在命令本身（一条 pip 的事），而在选版本：pytorch.org 的选择器会按操作系统、语言、包管理器和 CUDA 版本四个条件生成一条完整命令，四个条件里任何一个选错，装出来的东西就和预期不一致。

第二层坑在wheel。同一份 PyTorch 会按不同 CUDA 版本编译出不同安装包：cu124 版带 CUDA 12.4 运行时，cu118 版带 11.8，cpu 版干脆不带。选错组合的典型症状是torch.cuda.is_available()返回False，或者驱动太老时报CUDA driver version is insufficient for CUDA runtime version。这两个报错的修法方向完全相反，本篇后面会拆开讲。

第二个高频坑是装成 CPU 版而不自知：很多教程里的pip install torch默认拉的是 CPU 版（或按本机环境推了 cpu wheel），装完 import 成功、跑 CPU 推理也没报错，唯独 GPU 一点不上。所以本篇把"验证"写成和"安装"同等重要的部分，而且验证不止看is_available()，还要真把一张量扔到 GPU 上算一遍。

第三个坑更隐蔽：教程里的命令本身可能过时。PyTorch 的版本组合几个月就迭代一轮，一年前文章里的命令，照着敲可能拉到已经下架的 cuXXX 变体，或者一个和现有驱动不搭的旧版本。这就是本篇第一步坚持"去官网选择器生成命令"、而不是直接甩一条让你复制的原因——命令本身不值钱，能随时生成最新正确命令才值钱。

前置条件：驱动已装好（nvidia-smi能出表，记下了驱动版本和 CUDA 支持上限）。如果还没装，先回《AI-01 CUDA 与 N 卡驱动安装》。本篇全程在虚拟环境里操作，不碰全局环境——这条纪律比任何一条安装命令都重要，它决定了你以后会不会在"明明装过 torch 却找不到"这种问题上反复消耗时间。

二、环境要求

Python 版本这里强调两点。其一，必须是 64 位：32 位 Python 拿到的只能是不带 GPU 支持的包，且 Windows 下 32 位环境装 VC 运行库 x64 也对不上。其二，3.11 是当前兼容性最稳的选择，3.13 的新生态还有兼容风险，不建议拿它当第一环境。

三、安装与部署

3.1 第一步：pytorch.org 选择器选 pip 命令

不要手抄任何教程里的安装命令——PyTorch 的 wheel 组合迭代快，唯一可靠的命令生成器是官网Get Started页面（pytorch.org）。进去后按四栏选：

1. 操作系统：Windows 或 Linux（WSL2 里选 Linux，别选 Windows）；
2. 语言：Python（本篇主线；选 Conda 的话命令是conda install形式，同样以页面生成结果为准）；
3. 包管理器：pip；
4. CUDA 版本：这里对照nvidia-smi右上角的支持上限选（如 12.4 就选 12.4；上限只有 11.x 就选 11.8）。上限够新却选了偏旧的 wheel 也能跑，只是放弃了一部分新特性；上限不够却硬选新的，就是后面故障排查里那条 insufficient 报错。

页面生成的命令长这样（cu124 为例）：

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

3.2 cu124 / cu118 / cpu 三种 wheel 怎么选

选择原则一条：PyTorch 编译所用的 CUDA 版本 ≤ 驱动支持的 CUDA 版本（这是"上限原则"，不是"必须相等"）。

• cu124（CUDA 12.4 运行时）：nvidia-smi 支持上限 ≥ 12.4 时的默认选择，绝大多数 2023 年后的卡 + 新驱动都落在这个区间；
• cu118（CUDA 11.8 运行时）：驱动上限只有 11.x（老驱动、老卡）时用它。老架构显卡（如 Maxwell、Pascal 这一代）对 cu118 的覆盖比更新版本更好，太新的 CUDA 编译在老架构上会直接报CUDA error: no kernel image is available for execution on the device；
• cpu：没有 N 卡、或显存/驱动实在没戏时的兜底。cpu 版体积小、装得快，验证代码逻辑和跑小模型够用，但 GPU 相关功能全部缺失，命令：

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

怎么选不纠结：先nvidia-smi看支持上限，再用 pytorch.org 选择器按上限选——选择器给出的就是"当前 PyTorch 版本下"与你的驱动最匹配的组合，以它为准。

3.3 国内加速方案

两个层面分开处理：

wheel 本身从官方源download.pytorch.org拉，这个源国内直连通常可用但不快，慢就换时段。多说一句：torch 的 wheel 带捆绑的 CUDA 运行时，单个包就有好几 GB，别把它指到不熟的第三方镜像——体积大、校验麻烦，来路不明的源比“慢”更坑。

其余依赖一律走清华源，速度快一个量级：

pip install <pkg> -i https://pypi.tuna.tsinghua.edu.cn/simple

阿里源可作备份：-i https://mirrors.aliyun.com/pypi/simple。

后续下载模型才是真正的大流量场景，届时用 hf-mirror 或 ModelScope：

set HF_ENDPOINT=https://hf-mirror.com

（Linux 下用export HF_ENDPOINT=https://hf-mirror.com），或pip install modelscope后走 ModelScope 下载，完整方案详见《AI-06 模型下载全攻略》。

3.4 执行安装

确认虚拟环境已激活（python -c "import sys; print(sys.executable)"打印的路径指向你的 .venv/conda 环境），然后跑 3.1 生成的命令。安装过程会显示一个个Collecting/Downloading，torch 本体加捆绑的 CUDA 运行时加起来好几 GB，耐心等。出现Successfully installed torch-2.x.x+cu124 ...即成功——注意看版本号里的+cu124后缀，这是它装成了 GPU 版的第一证据。如果发现装出来的是torch-2.x.x或+cpu而没有+cuXXX，说明安装命令没带对--index-url，先卸载再重装，别在错误版本上继续搭后面的东西。

四、验证

三步，逐层确认，分别回答三个问题：框架看不看得到卡、认不认得出卡是什么、真算算得动吗。任何一步单过都不算数——is_available()为True但小张量算不动，说明中间某层（驱动架构、wheel 组合）还有问题；只做到前两步就收工，是最常见的"假成功"，往往到后面跑模型时才爆出来，排查时间翻几倍。

第一步，确认 GPU 可见（框架层探针）：

python -c "import torch; print(torch.__version__, torch.cuda.is_available())"

期望输出：2.x.x+cu124 True。返回False直接跳"六、故障排查"第一条。

第二步，看 PyTorch 自己认到几张卡、什么卡：

python -c "import torch; print(torch.cuda.device_count()); print(torch.cuda.get_device_name(0))"

期望：张数 ≥ 1，设备名是你的显卡型号（如NVIDIA GeForce RTX 4060）。

第三步，真把一张量扔到 GPU 上算——这步治"能 import、is_available 为 True、实际算不动"的隐性故障：

python -c "import torch; x = torch.randn(1024, 1024, device='cuda'); y = x @ x; print('GPU OK', y.sum().item())"

期望：打印GPU OK加一个数字，且几秒内返回。报no kernel image是 wheel 与卡架构不匹配；报OutOfMemoryError才说明显存层有问题（1024×1024 的 float32 矩阵才 4 MB，这一步 OOM 基本是别的进程把显存占满了，nvidia-smi查占用）。

三步全过，PyTorch 环境即交付。我个人的习惯是把第三步的小张量存成一个check_gpu.py，以后每换一个环境先跑它，30 秒定位环境层问题。

五、进阶技巧

多版本共存怎么避免：一个项目一个虚拟环境，环境名直接带用途（llama、diffusion）。同一台机器要跑不同 torch 版本时，venv 或 conda（conda create -n ai python=3.11 -y）天然隔离，互相不污染。千万别在一个全局环境里反复pip install torch==2.0.1、torch==2.2.0来回折腾——残留的 CUDA 库和PATH污染是 Windows 上Error 126: Unknown error的头号来源。

验证 torch 用的 CUDA 版本：python -c "import torch; print(torch.version.cuda)"，对照 nvidia-smi 的 CUDA 支持上限，前者必须 ≤ 后者。这条命令在排查"驱动够不够"时是框架层的第二探针。看到版本号是+cu126而 nvidia-smi 只给到 12.4，问题只是还没爆发，跑 GPU 操作时必现——升驱动或降 wheel 二选一，别拖。

装前先看上限再选 wheel：nvidia-smi 只支持到 11.8、而选择器里一堆 12.x，不代表卡不行，只是驱动老。先升驱动再看上限，然后做选择。升驱动是一次性动作，降到旧 wheel 跑旧运行时则是一笔长期债。

WSL2 用户：WSL 里直接按 Linux 流程装，不需要在 WSL 内装 NVIDIA 驱动——Windows 侧驱动透传即可，装完nvidia-smi在 WSL 内也能跑，详见《AI-04 WSL2 部署 AI 开发环境》。

显存预算先算账：装完框架别急着拉大模型，先按"参数量 × 每参数字节数"估算你的卡装得下什么（7B fp16 约 14-15 GB，Q4 量化约 4-5 GB，再加 10-20% 开销），详见《AI-05 显存计算与模型选择》。

六、故障排查

分层定位：网络层 → 驱动层 → 框架层 → 显存层 → 应用层。装 PyTorch 的问题 90% 落在框架层和环境依赖层。

30 秒探针顺序：where python（环境对不对）→torch.__version__后缀（wheel 对不对）→torch.cuda.is_available()（框架认不认卡）→ 小张量上 GPU（真算得动吗）→nvidia-smi（显存谁占了）。从上往下，一步一个结论。

七、本篇自检清单

• 会用 pytorch.org 选择器生成 pip 命令，没手抄过时命令
• 能解释 cu124 / cu118 / cpu 三种 wheel 的适用场景（上限原则）
• 安装成功，torch.__version__带+cuXXX后缀
• 验证三步全过：is_available()为True、get_device_name(0)报出卡名、小张量上 GPU 返回GPU OK
• 知道 32 位 Python / VC 运行库缺失各自对应的报错长什么样
• 多项目用虚拟环境隔离，全局环境不装 torch

参考

• PyTorch 官网 Get Started（安装命令生成器）：https://pytorch.org/get-started/locally/
• PyTorch 官方文档（CUDA 支持说明）：https://docs.pytorch.org/docs/stable/notes/cuda.html
• 清华 PyPI 镜像：https://pypi.tuna.tsinghua.edu.cn
• HuggingFace 国内镜像：https://hf-mirror.com