第3章 vLLM安装与基础使用

3、vLLM安装与基础使用：pip安装、源码编译、单GPU推理测试

好，咱们直接进入正题。这一章我带你亲手把vLLM装起来，跑通第一个推理任务。说实话，安装这一步看着简单，但坑不少。我在不同集群上部署过几十次，踩过的雷能写满一页A4纸。今天我把最稳的两种方式都给你捋清楚。

3.1 环境准备：先把地基打牢

在动手装vLLM之前，有几样东西你得先确认好。我见过太多人上来就pip install，结果报一堆错，回头一看CUDA版本不对——白忙活半天。

⚠️ 硬件与驱动检查清单

GPU型号：vLLM要求计算能力7.0+，说白了就是V100、A100、H100、RTX 3090/4090这些。T4勉强能用，但别指望多快。
CUDA版本：建议11.8或12.1。我个人习惯用12.1，兼容性最好。
PyTorch版本：2.0以上是必须的。我建议直接用2.1或2.2，省事。
Python版本：3.9 - 3.11。别用3.12，有些依赖还没跟上。

怎么快速检查？敲几行命令就清楚了：

nvidia-smi                     # 看驱动和CUDA版本
python -c "import torch; print(torch.__version__)"  # 看PyTorch版本
python --version               # 看Python版本

嗯，这里要注意：nvidia-smi显示的CUDA版本是驱动支持的版本，不代表PyTorch用的那个。你最好用torch.version.cuda再确认一下。

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

这是最省心的方式。vLLM官方在PyPI上提供了预编译的wheel包，直接装就行。我在测试环境里基本都是这么干的。

pip install vllm

就这么一行？对，就这么一行。但有个前提——你的CUDA环境得对得上。vLLM的pip包目前只支持CUDA 11.8和12.1。如果你用的是其他版本，那就得走源码编译了。

💡 我的习惯：装之前先建个虚拟环境，别污染全局。我用conda：

conda create -n vllm_env python=3.10
conda activate vllm_env
pip install vllm

装完之后验证一下：

python -c "from vllm import LLM; print('vLLM installed successfully')"

没报错？恭喜，你可以直接跳到3.4节了。

3.3 方式二：源码编译（进阶玩家）

为什么要源码编译？说白了就两个原因：一是你想用最新的特性，pip包可能滞后一两周；二是你的CUDA版本不在官方支持列表里。我曾经在CUDA 11.6的老集群上部署，没办法，只能自己编译。

编译前先把依赖装好：

# 安装编译工具
sudo apt-get update
sudo apt-get install -y build-essential cmake

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

# 安装Python依赖
pip install -e .

这个过程大概要10-20分钟，取决于你的机器性能。编译时会自动检测CUDA版本，生成对应的算子库。我第一次编译时等了快半小时，还以为卡死了——其实它在编译FlashAttention，那个确实慢。

⚠️ 避坑指南：我曾经在编译时遇到nvcc fatal: unsupported option '--generate-code'的错误。原因是GCC版本太高，跟CUDA不兼容。解决办法是降级GCC到9或10：

sudo apt-get install gcc-9 g++-9
export CC=/usr/bin/gcc-9
export CXX=/usr/bin/g++-9

编译完成后，同样验证一下：

python -c "from vllm import LLM; print('Source build successful')"

3.4 单GPU推理测试：跑通第一个模型

装好了，咱们来点真格的。单GPU测试是检验安装是否成功的最好方式。我用一个7B的模型做演示，你换成自己的模型也行。

from vllm import LLM, SamplingParams

# 加载模型
llm = LLM(model="facebook/opt-125m")  # 小模型，下载快

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

# 准备输入
prompts = [
    "什么是深度学习？",
    "请用Python写一个快速排序算法。"
]

# 执行推理
outputs = llm.generate(prompts, sampling_params)

# 打印结果
for output in outputs:
    prompt = output.prompt
    generated_text = output.outputs[0].text
    print(f"Prompt: {prompt}")
    print(f"Generated: {generated_text}")
    print("-" * 50)

跑这个代码，你会看到vLLM先加载模型，然后开始推理。第一次加载会慢一些，因为要编译CUDA kernel。之后就好了。

  🔑 关键参数说明：
  temperature：控制随机性。0是确定性输出，1是最大随机。我一般设0.7。
top_p：核采样，只从概率和超过p的token里选。0.9是个好起点。
max_tokens：生成的最大token数。别设太大，显存会爆。

3.5 性能基准：看看你的GPU有多快

跑通了？那咱们测个速。我习惯用这个简单脚本看吞吐量：

import time
from vllm import LLM, SamplingParams

llm = LLM(model="facebook/opt-125m")
params = SamplingParams(max_tokens=64)

# 构造100个请求
prompts = ["你好"] * 100

start = time.time()
outputs = llm.generate(prompts, params)
end = time.time()

total_tokens = sum(len(o.outputs[0].token_ids) for o in outputs)
elapsed = end - start

print(f"总耗时: {elapsed:.2f}秒")
print(f"生成token数: {total_tokens}")
print(f"吞吐量: {total_tokens/elapsed:.2f} tokens/秒")

这个数据能帮你判断部署环境是否正常。比如在A100上跑7B模型，吞吐量通常在1000+ tokens/s。如果差太多，可能是显存带宽瓶颈或者CPU预处理拖了后腿。

3.6 常见问题速查

问题	原因	解决办法
ImportError: libcuda.so.1 not found	CUDA驱动没装或路径不对	检查`ldconfig -p \| grep libcuda`，设置`LD_LIBRARY_PATH`
RuntimeError: CUDA out of memory	模型太大，显存不够	换小模型，或设置`max_num_seqs`降低并发
ValueError: The model's max seq length is too small	模型上下文窗口太小	用`--max-model-len`参数调大，但别超过模型上限

嗯，基本上装好、跑通、测速，这三步走完，你的vLLM环境就算搭好了。下一章咱们会聊多GPU部署，那才是vLLM真正发力的地方。不过今天先把单机单卡玩熟，地基打牢了，后面才稳当。

📌 我的建议：把刚才的测试脚本保存成test_vllm.py，以后换机器或更新版本后，跑一遍就知道环境有没有问题。我在每个部署环境里都留了这么个脚本，省了不少排查时间。

公众号:蓝海资料掘金营，微信deep3321

📚 课程目录

3、vLLM安装与基础使用：pip安装、源码编译、单GPU推理测试

3.1 环境准备：先把地基打牢

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

3.3 方式二：源码编译（进阶玩家）

3.4 单GPU推理测试：跑通第一个模型

3.5 性能基准：看看你的GPU有多快

3.6 常见问题速查