CUDA 安装理解

经常部署或安装一些模型、程序等，少不了要使用cuda，由于不了解经常被版本问题折磨，看一些资料看完也觉得不太明白，下面谈一下自己的理解，不对之处望指出。

GPU驱动是必须要装的，它负责和显卡去打交道。

英伟达发明了一种编程语言，你可以理解成是一种对C++ 的增强语言，它的源码文件扩展名一般是 .cu , 例如这些 .cu 文件都是这种编程语言写的程序。

既然是程序，那就有编译器和运行时，

nvcc 命令是编译器，安装cuda-toolkit后才有nvcc命令，如果你要运行的程序中没有 .cu 的源码，一般不需要安装cuda-toolkit。

cuda runtime是程序的运行环境，用来运行 .cu 代码编译出来的程序（只运行，不编译）。

一，GPU驱动、cuda runtime、cuda-toolkit 三者关系的理解

1.GPU驱动

驱动是直接安装在系统层面的（非虚拟环境），所有程序共用一个驱动，它决定了能运行的cuda版本上限；

通过nvidia-smi 可查看驱动版本 和 最高能运行的cuda版本

610.62 是驱动版本

13.3 是最高支持的CUDA版本

2.cuda runtime

cuda rutime 仅为cuda程序的运行环境，

cuda toolkit不仅包含运行环境也包含cuda程序编译器（nvcc）和一些其他工具。

二者关系可以理解为cuda rutime 是JRE，cuda toolkit 是JDK。

cuda runtime可以在系统层面安装，也可以每个虚拟python环境安装一个。

一般你在安装gpu 版pytorch时都会自动给你安装cuda runtime，比如执行如下命令它就会安装pytorch及cuda runtime 12.8 ，其中cu128指的就是cuda runtime 12.8

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

但完成上述安装后，仅安装了cuda runtime，是没有nvcc命令的（即不能用nvcc -V查看版本），但可以用如下命令看到相关的runtime依赖：

 pip list | grep nvidia 

上述组件的作用解释如下：

3. cuda-toolkit

cuda toolkit 可以在系统层面安装，也可以每个虚拟python环境安装一个.

大多数情况下并不需要安装它，因为大多数情况下你只是在跑别人编译好的程序，比如用vllm部署模型就不需要安装它，因为vllm已经是别人编译好的程序，安装cuda runtime就够了，但如果要运行的程序中包含 .cu 的cuda源码程序，就需要安装cuda-toolkit，安装cuda-toolkit后才有nvcc命令，才可用nvcc命令编译程序。

推荐采用conda 在虚拟环境安装 cuda-toolkit，命令：

conda install -c nvidia cuda-toolkit=12.8  -y

但是不建议通过 pip / uv pip 安装cuda-toolkit， 因为它们安装的很可能功能不全，有的甚至没有nvcc编译器，安装12.x的cuda-toolkit 需要执行 pip install cuda-toolkitall 才完整，但如果是13.x的cuda-toolkit需要单独安装nvcc

4. 注意

4.1 假设别人的 .cu 的程序是用 cuda-toolkit 高版本编译的（高版本的nvcc），你装一个低版本的 cuda runtime来运行，很可能会运行不了。

4.2 虚拟环境中可能已经被某个程序如pytorch自动安装了某个版本的cuda runtime，但是你又安装其他版本的cuda tookit 也可能造成版本混乱不兼容。

二，经常踩坑点

1. 安装GPU版pytorch+cuda12.8

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

或者

#torch相关的依赖使用--index-url地址
#torch依赖的其他组件（如 filelock）使用 --extra-index-url地址（清华源加速）
pip install torch \
--index-url https://download.pytorch.org/whl/cu128 \
--extra-index-url https://pypi.tuna.tsinghua.edu.cn/simple

2.安装CPU版pytorch

pip install torch

#加清华源也是CPU版本
pip install torch -i https://pypi.tuna.tsinghua.edu.cn/simple

这里是最坑的，我们经常认为上面2条命令就把torch安装好了，pytorch就可以调用GPU了，但实际上这个命令安装的是CPU版的pytorch。

3. 验证安装的pytorch能否用GPU

#切换到对应的虚拟环境后执行
python -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available())"

输出True证明是GPU版的pytorch

4. vllm 与 cuda runtime

vllm非常特殊，vllm是不会用虚拟环境中的cuda runtime的，vllm固定使用系统级的cuda runtime。

如何证明？

如果你已经安装了vllm，可以用ldd命令查看当前虚拟环境中vllm的这个扩展文件_C_stable_libtorch.abi3.so的依赖关系：

ldd /data/qwen35-4b/venv/lib/python3.11/site-packages/vllm/_C_stable_libtorch.abi3.so

其中libcudart.so.13 指向的是系统的cuda runtime(简写为cudart, rt就是runtime简写)，写死了，没法配置或修改。

也就是说，如果用vllm跑大模型，你不仅需要在虚拟环境中安装cuda runtime供pytorch使用，还要在系统中安装cuda runtime供vllm使用。

而sglang可以通过环境变量配置cuda runtime路径，即sglang可以使用虚拟环境中的cuda runtime 。

5. 系统层面安装cuda runtime

以ubuntu系统安装cuda runtime为例，如下：

# 下载并安装密钥环

wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb

sudo dpkg -i cuda-keyring_1.1-1_all.deb


# 更新软件包列表

sudo apt update


# 上面两部一定要执行，否则找不到安装包，执行后可以安装 CUDA 13 runtime了

sudo apt install cuda-runtime-13-0

6.系统层面安装cuda toolkit

有时候runtime装了可能还会缺失一些工具比如监控的，这时直接装toolkit可能更省事

# 下载并安装密钥环

wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb

sudo dpkg -i cuda-keyring_1.1-1_all.deb


# 更新软件包列表

sudo apt update


# 上面两步一定要执行，否则找不到安装包，执行后可以安装 CUDA 13 toolkit了

sudo apt install cuda-toolkit-13-0

三，vllm部署Qwen3.5-4B实战

采用的机器 驱动版本及支持的最大的cuda版本如下：

安装命令如下：

#conda创建虚拟环境并激活
conda create -p /data/qwen35-4b/venv python=3.11 -y
conda activate /data/qwen35-4b/venv

#在虚拟环境安装uv
pip install uv


#用uv在虚拟环境安装vllm, uv会自动分析显卡驱动，选择合适版本
uv pip install vllm \
  --extra-index-url https://wheels.vllm.ai/nightly/cu130 \
  --extra-index-url https://download.pytorch.org/whl/cu130 \
  --index-strategy unsafe-best-match

#检查虚拟环境pytorch可用GPU
python -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available())"


#在系统层面直接安装cuda-toolkit（这里安装cuda runtime就行，但为了省事直接装cuda toolkit）
# 下载并安装密钥环
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb

# 更新软件包列表
sudo apt update

# 有时候runtime装了可能还会缺失一些工具比如监控的，这时直接装toolkit可能更省事
sudo apt install cuda-toolkit-13-0

#检查toolkit是否可用
nvcc -V

#启动服务
vllm serve /data/qwen35-4b/Qwen3.5-4B \
  --served-model-name qwen35-4b \
  --trust-remote-code \
  --max-model-len 8096 \
  --gpu-memory-utilization 0.85 \
  --max-num-seqs 10 \
  --port 8000

curl测试
  curl http://127.0.0.1:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen35-4b",
    "messages": [{"role": "user", "content": "你好"}],
    "max_tokens": 1024,
    "temperature": 0.6,
    "stream": true,
	"chat_template_kwargs": {"enable_thinking": false}
  }'