第3章：vLLM安装与验证

好，咱们进入实操环节。这一章我带你亲手把vLLM装起来，并且验证它能不能跑。安装这事儿，说简单也简单，说坑也多。我这些年装过不下几十次，踩过的坑能写个小本本。今天我把最稳的两种方式都告诉你。

3.1 pip安装：最快上手的方式

如果你只是想快速体验vLLM，或者你的环境比较干净，那用pip是最省事的。我个人习惯在干净的虚拟环境里装，避免跟其他项目打架。

# 创建一个干净的虚拟环境（我推荐Python 3.10+）
python3 -m venv vllm_env
source vllm_env/bin/activate

# 直接安装
pip install vllm

嗯，就这么简单。但这里有个坑——CUDA版本必须匹配。vLLM对CUDA的依赖很敏感。我建议你装之前先看一眼自己的CUDA版本：

nvidia-smi
# 或者
nvcc --version

vLLM 0.4.0之后的版本，要求CUDA >= 11.8。如果你用的是老卡（比如T4、V100），CUDA 11.8完全够用。如果是H100、A100这种新卡，建议上CUDA 12.x。

3.2 从源码编译安装：定制化需求

为什么要从源码编译？说白了，就两个场景：

• 你想改vLLM的代码，比如加个自定义算子
• 你的硬件比较特殊，pip包没覆盖到

我从源码编译过大概七八次，每次都得等20-30分钟。你想想看，编译过程中如果报错，那才叫一个酸爽。所以我把步骤拆细了：

# 第一步：拉代码
git clone https://github.com/vllm-project/vllm.git
cd vllm

# 第二步：安装编译依赖
pip install -r requirements-build.txt

# 第三步：编译安装
pip install -e .

这里有个关键点——GCC版本。vLLM的C++代码需要GCC >= 9.0。我曾在CentOS 7上栽过跟头，默认GCC才4.8，编译到一半直接崩了。解决办法是手动升级：

# 查看当前GCC版本
gcc --version

# 如果版本太低，用scl或者直接装新版本
sudo yum install centos-release-scl
sudo yum install devtoolset-9-gcc*
scl enable devtoolset-9 bash

3.3 验证安装是否成功

装完了，怎么知道它能不能用？别急着跑大模型，先来个快速验证：

# 检查vLLM是否能正常导入
python -c "import vllm; print(vllm.__version__)"

# 如果能打印出版本号，比如 0.4.2，说明安装成功
# 如果报错，看下一节的排查指南

我个人习惯再跑一个最小推理测试，确保CUDA和GPU都正常：

from vllm import LLM, SamplingParams

# 用一个小模型测试，比如facebook/opt-125m
llm = LLM(model="facebook/opt-125m")
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)

如果能看到输出文本，恭喜你，vLLM已经跑起来了。如果报错，别慌，往下看。

3.4 常见安装问题排查

我整理了一份「踩坑清单」，都是我在项目中真实遇到过的：

错误信息	原因	解决办法
CUDA error: no kernel image is available	CUDA版本与显卡架构不匹配	升级CUDA或重新编译时指定架构
ImportError: libcudart.so.11.0: cannot open shared object file	CUDA运行时库没找到	检查LD_LIBRARY_PATH是否包含CUDA路径
RuntimeError: NCCL error	多卡通信库问题	重新安装nccl或检查驱动版本
OutOfMemoryError	显存不够	换小模型或减少batch size

关于NVIDIA驱动兼容性，我多说两句。vLLM依赖CUDA，而CUDA又依赖驱动。驱动版本太低，CUDA 12.x根本装不上。我的经验是：

• 驱动版本 >= 525.60.13，才能支持CUDA 12.x
• 驱动版本 >= 450.80.02，支持CUDA 11.x
• 用 nvidia-smi 查看驱动版本，用 nvcc --version 查看CUDA版本

3.5 知识体系总览

这一章的内容，我用一张图帮你理清思路：

这张图把安装流程分成了三条线。你走哪条线，取决于你的场景。但不管走哪条，最后都要落到「验证」这一步。我见过太多人装完就跑，结果上线才发现问题。所以，验证这步千万别省。