环境搭建：CUDA与PyTorch版本选择、vLLM pip安装、Docker镜像部署、验证安装是否成功
说实话，环境搭建这块，我见过太多人卡在这里了。
明明代码写对了，跑起来就是报错。为什么？说白了就是版本没对齐。vLLM 对 CUDA 和 PyTorch 的版本要求非常严格，差一个小版本都可能翻车。今天我就把我在项目中踩过的坑、总结的经验，一次性给你讲清楚。
CUDA 与 PyTorch 版本选择
先讲核心原则：vLLM 依赖 PyTorch，PyTorch 依赖 CUDA，CUDA 依赖显卡驱动。这条链上任何一个环节出问题，后面全白搭。
我个人习惯，第一步先看显卡驱动支持的 CUDA 版本。在终端跑一下：
nvidia-smi看右上角的 "CUDA Version"，比如显示 12.1，那你就只能选 ≤12.1 的 CUDA 工具包。别想着装 12.2，驱动不支持，装上去也是废的。
接下来选 PyTorch 版本。我建议直接上 PyTorch 2.1 或 2.2，配合 CUDA 12.1。为什么？因为 vLLM 官方测试最多的就是这套组合。你想想看，官方都帮你踩过坑了，咱就别自己再去踩一遍了。
具体对应关系，我整理了一张表：
| CUDA 版本 | PyTorch 版本 | vLLM 版本 | 我的评价 |
|---|---|---|---|
| 11.8 | 2.0.x / 2.1.0 | 0.2.x | 老项目在用，新项目别碰 |
| 12.1 | 2.1.x / 2.2.0 | 0.3.x - 0.4.x | ✅ 推荐组合，稳得很 |
| 12.4 | 2.3.0+ | 0.5.x+ | 新特性多，但坑也多 |
vLLM pip 安装
环境确认好了，安装就简单了。我个人习惯用虚拟环境，避免污染全局 Python。
# 创建虚拟环境
python -m venv vllm_env
source vllm_env/bin/activate
# 安装 PyTorch（以 CUDA 12.1 为例）
pip install torch==2.1.2 torchvision==0.16.2 torchaudio==2.1.2 --index-url https://download.pytorch.org/whl/cu121
# 安装 vLLM
pip install vllm==0.4.2嗯，这里要注意一点。vLLM 安装时会自动编译一些 CUDA 扩展，这个过程可能持续 5-10 分钟。别以为卡住了，其实它在干活。你可以去泡杯咖啡。
如果安装过程中报错 "nvcc not found"，说明你的 CUDA 工具包没装全。我建议直接装完整的 CUDA Toolkit，别只装 driver。命令如下：
# Ubuntu 系统
sudo apt install nvidia-cuda-toolkit
# 或者去 NVIDIA 官网下载 runfile 安装
wget https://developer.download.nvidia.com/compute/cuda/12.1.0/local_installers/cuda_12.1.0_530.30.02_linux.run
sudo sh cuda_12.1.0_530.30.02_linux.runpip install -i https://pypi.tuna.tsinghua.edu.cn/simple vllm==0.4.2
Docker 镜像部署
说实话，pip 安装虽然方便，但生产环境我强烈推荐用 Docker。为什么？因为环境一致性。你在笔记本上装好了，到服务器上可能又是另一番景象。
vLLM 官方提供了 Docker 镜像，直接拉下来就能用：
# 拉取官方镜像
docker pull vllm/vllm-openai:latest
# 或者指定版本
docker pull vllm/vllm-openai:v0.4.2拉下来之后，启动容器：
docker run --gpus all \
-v /path/to/models:/models \
-p 8000:8000 \
vllm/vllm-openai:latest \
--model /models/llama-2-7b-chat-hf \
--served-model-name llama2-7b这里我解释一下参数：
--gpus all：让容器访问所有 GPU-v：挂载模型目录，这样容器里就能读到你的模型文件-p 8000:8000：把容器的 8000 端口映射到宿主机
--gpus all 参数，容器默认只认 CPU。所以这个参数千万别漏。
验证安装是否成功
环境搭好了，怎么知道能不能用？我一般跑一个简单的推理测试。
先写一个 Python 脚本：
from vllm import LLM, SamplingParams
# 加载模型
llm = LLM(model="facebook/opt-125m")
# 设置采样参数
sampling_params = SamplingParams(temperature=0.8, top_p=0.95)
# 推理
outputs = llm.generate(["Hello, how are you?"], sampling_params)
# 打印结果
for output in outputs:
print(output.outputs[0].text)跑这个脚本，如果正常输出文本，说明安装成功。如果报错，别慌，看错误信息。常见的错误有：
- CUDA out of memory：显存不够，换个更小的模型，或者调低
max-model-len - ModuleNotFoundError：某个依赖没装，pip install 补上就行
- RuntimeError: CUDA error：驱动或 CUDA 版本不对，回头检查第一步
--dtype float16 参数，显存占用直接减半。我测试过，精度损失几乎可以忽略。
本章知识体系
下面这张图，帮你理清环境搭建的完整流程：
说白了，环境搭建就三步：选对版本 → 装好软件 → 跑通测试。每一步都有坑，但只要你按照我上面说的来，基本不会出大问题。
好了，这一章就到这里。环境搭好了，下一章我们就可以开始真正的批量推理了。