第2章环境准备

环境准备：安装vLLM

好，咱们正式开始动手了。这一章我带你把环境搭起来。说实话，很多同学卡在第一步——装了半天跑不起来，最后发现是CUDA版本不对。我当年也踩过这个坑，所以咱们一步步来，稳一点。

1. 安装vLLM：一行命令搞定？没那么简单

官方文档说 pip install vllm 就行。嗯，这话没毛病，但前提是你的环境得对。我个人习惯先创建一个干净的虚拟环境，避免跟其他项目打架。

# 创建虚拟环境（Python 3.8 - 3.11 都行，我推荐 3.10）
conda create -n vllm_env python=3.10 -y
conda activate vllm_env

# 安装 vLLM
pip install vllm

你可能会问：为什么不用 pip install vllm==0.4.0 指定版本？我的建议是：第一次装用最新版，踩坑少。等后面项目稳定了再锁定版本。

小提示： 如果你在公司的内网环境，记得先配好镜像源。我一般用清华源：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple vllm

2. CUDA与PyTorch版本兼容性检查——这步最容易被忽略

vLLM 对 CUDA 版本有硬性要求。说白了，它底层调用了很多 CUDA 核函数，版本不对直接报错。我见过最惨的案例：一个同事装了三天，最后发现 CUDA 11.7 跟 PyTorch 2.0 不匹配。

先看看你当前的环境：

# 检查 CUDA 版本
nvcc --version

# 检查 PyTorch 版本及 CUDA 是否可用
python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())"

这里有个关键点：vLLM 要求 CUDA >= 11.8。如果你看到 CUDA 11.7 或更低，那就得升级了。我自己的机器是 CUDA 12.1，跑 vLLM 0.4.0 很稳。

注意： 千万别以为 nvidia-smi 显示的版本就是 CUDA 版本。那个是驱动支持的最高版本。真正的 CUDA 版本要看 nvcc --version。我曾经就被这个坑过，查了半天才发现是两码事。

如果版本不匹配，我建议你直接用 PyTorch 官方提供的安装命令，它会自动匹配对应的 CUDA 版本：

# 以 CUDA 12.1 为例
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

3. 验证安装是否成功——跑个小模型试试

装完了别急着高兴，先验证一下。我习惯写个简单的 Python 脚本来测试：

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)

如果能看到输出文本，恭喜你，环境搭好了！如果报错，别慌。最常见的错误是 CUDA out of memory。嗯，这时候你想想看，是不是显存不够？0.5B 模型大概需要 2GB 显存，如果你的显卡只有 4GB，建议换个更小的模型，比如 Qwen2-0.5B 其实已经很小了。

  验证清单：
  ✅ vLLM 安装成功（无 ImportError）
✅ CUDA 版本 >= 11.8
✅ PyTorch 能调用 GPU（torch.cuda.is_available() 返回 True）
✅ 小模型推理能跑通

4. 知识体系总览

下面这张图帮你理清整个环境准备的核心逻辑：

5. 避坑指南——我踩过的那些坑

坑一：CUDA版本不一致 —— 我曾经在服务器上装了 vLLM，结果报错说找不到 CUDA 库。查了半天发现系统里装了三个 CUDA 版本，PATH 指向了 11.7。解决方案：用 export CUDA_HOME=/usr/local/cuda-12.1 指定版本。
坑二：显存不够 —— 有同学拿 4GB 显存的卡跑 7B 模型，那肯定 OOM。我的建议：先跑 0.5B 或 1.5B 模型验证环境，确认没问题再上大模型。
坑三：PyTorch 和 vLLM 版本不匹配 —— vLLM 0.4.0 要求 PyTorch >= 2.0。如果你用 PyTorch 1.13，装完 vLLM 会直接报 ImportError。解决办法：升级 PyTorch。

我的小技巧： 装完 vLLM 后，运行 python -c "from vllm import LLM; print('OK')" 快速验证。如果没报错，说明导入没问题。然后再跑推理测试。

好了，环境准备就到这里。记住一句话：环境搭好了，后面就顺了。如果遇到问题，别硬扛，检查一下 CUDA 版本和显存，八成是这两个原因。

📚 课程目录

环境准备：安装vLLM

1. 安装vLLM：一行命令搞定？没那么简单

2. CUDA与PyTorch版本兼容性检查——这步最容易被忽略

3. 验证安装是否成功——跑个小模型试试

4. 知识体系总览

5. 避坑指南——我踩过的那些坑