环境搭建：GPU驱动与CUDA安装、Docker环境配置、vLLM源码编译与pip安装、验证安装是否成功

说实话，很多同学学vLLM卡在第一步——环境装不上。我见过太多人花了两天装驱动，结果发现CUDA版本对不上，心态直接崩了。这一章，咱们就把这些坑一个个填平。

1. GPU驱动与CUDA安装

先说说驱动。你想想看，GPU就像一台高性能跑车，驱动就是它的发动机管理系统。没有驱动，GPU就是个摆设。

第一步：确认你的GPU型号

我个人习惯先用这个命令看看机器上有什么卡：

lspci | grep -i nvidia

如果是云服务器，通常能看到类似 NVIDIA A100 或 NVIDIA V100 这样的输出。嗯，这里要注意，有些云厂商的实例默认没装驱动，得自己装。

第二步：安装NVIDIA驱动

我建议用官方推荐的方式，干净利落：

# 先卸载旧驱动（如果有）
sudo apt-get purge nvidia*

# 添加官方驱动仓库
sudo add-apt-repository ppa:graphics-drivers/ppa
sudo apt-get update

# 安装推荐版本（我一般选最新的稳定版）
sudo apt-get install nvidia-driver-535

# 重启机器
sudo reboot

# 验证驱动
nvidia-smi

第三步：安装CUDA Toolkit

驱动和CUDA是什么关系？驱动是底层，CUDA是上层。驱动让操作系统认识GPU，CUDA让程序能用GPU算东西。vLLM需要CUDA 11.8及以上版本。

我曾经踩过一个坑：装了驱动但没装CUDA Toolkit，结果编译vLLM时报错说找不到CUDA。后来学乖了，直接用NVIDIA官方提供的runfile安装：

# 下载CUDA 12.1（推荐）
wget https://developer.download.nvidia.com/compute/cuda/12.1.0/local_installers/cuda_12.1.0_530.30.02_linux.run

# 执行安装（注意：不要装驱动，只装Toolkit）
sudo sh cuda_12.1.0_530.30.02_linux.run --toolkit --silent

# 配置环境变量
echo 'export PATH=/usr/local/cuda-12.1/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.1/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

# 验证CUDA
nvcc --version

2. Docker环境配置

说实话，Docker是部署vLLM最省心的方式。你想想看，不用管依赖冲突，拉个镜像就能跑，多爽。

安装Docker Engine

# 安装依赖
sudo apt-get update
sudo apt-get install ca-certificates curl gnupg

# 添加Docker官方GPG密钥
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 添加仓库
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装Docker
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io

# 启动并设置开机自启
sudo systemctl start docker
sudo systemctl enable docker

# 验证
sudo docker run hello-world

安装NVIDIA Container Toolkit

这一步很多人会忘。Docker默认看不到GPU，得装这个工具才能让容器里用上显卡。

# 添加NVIDIA容器工具包仓库
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

# 安装
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

# 重启Docker
sudo systemctl restart docker

# 验证：在容器里跑nvidia-smi
sudo docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

3. vLLM安装：pip vs 源码编译

这里有两个选择，我分别说说。

方式一：pip安装（推荐新手）

说白了就是一行命令的事：

pip install vllm

但要注意，pip安装的是预编译的wheel包，它只支持特定的CUDA版本。我建议用Python 3.10 + CUDA 12.1的组合，兼容性最好。

方式二：源码编译（适合定制需求）

我个人习惯用源码编译，因为可以加一些自定义的优化。比如我想用FlashAttention的某个实验性特性，就得自己编译。

# 克隆源码
git clone https://github.com/vllm-project/vllm.git
cd vllm

# 创建虚拟环境（强烈推荐）
python3 -m venv vllm_env
source vllm_env/bin/activate

# 安装编译依赖
pip install -r requirements-build.txt

# 编译安装（这一步比较慢，大概10-20分钟）
pip install -e .

# 验证
python -c "import vllm; print(vllm.__version__)"

编译时你会看到一堆C++和CUDA代码在编译，风扇呼呼转。别慌，这是正常的。我曾经在编译时去泡了杯咖啡，回来刚好编译完。

4. 验证安装是否成功

装完了，怎么知道能不能用？跑个最简单的例子试试。

测试脚本：

from vllm import LLM, SamplingParams

# 加载一个小的模型（比如Qwen2-0.5B）
llm = LLM(model="Qwen/Qwen2-0.5B-Instruct")

# 设置采样参数
sampling_params = SamplingParams(temperature=0.7, top_p=0.9)

# 推理
outputs = llm.generate(["Hello, how are you?"], sampling_params)

# 打印结果
for output in outputs:
    print(output.outputs[0].text)

如果看到模型输出了内容，恭喜你，环境搭建成功了！

嗯，到这里环境就搭好了。你可能会问，为什么我推荐用Docker？说白了，Docker能让你在不同机器上复现一模一样的环境。我见过太多人因为环境不一致，在开发机上跑得好好的，部署到生产就崩了。用Docker，这种问题直接消失。

下一章，咱们开始写第一个API接口，让vLLM真正跑起来提供服务。

---