环境搭建：Python环境、CUDA、PyTorch、vLLM安装与验证

核心原理：为什么环境顺序如此重要

vLLM 是一个依赖 GPU 加速的高性能推理引擎，其运行链路涉及 CUDA 驱动 → CUDA Toolkit → PyTorch → vLLM 的层层依赖关系。每一层都向下兼容特定版本范围，如果底层版本不匹配，上层组件可能无法识别 GPU 或出现算子编译错误。例如，PyTorch 在编译时绑定了特定的 CUDA 运行时版本，而 vLLM 又依赖 PyTorch 的特定 API 和算子扩展。因此，安装顺序必须遵循“先底层驱动、再中间库、最后应用层”的原则，避免因版本错位导致推理时出现 CUDA error: no kernel image is available 或 AssertionError 等难以排查的问题。

方法流程：从零搭建可运行的 vLLM 环境

以下流程以 Ubuntu 22.04 + Python 3.10 + 单张 NVIDIA GPU 为例，适用于大多数生产环境。请根据实际 GPU 型号（如 A100、H100、RTX 4090）微调 CUDA 版本。

第一步：确认 GPU 与驱动

# 检查 GPU 是否被系统识别
lspci | grep -i nvidia

# 查看当前驱动版本与 CUDA 可用版本
nvidia-smi

如果 nvidia-smi 无法运行，说明驱动未安装或未正确加载。此时需要先安装 NVIDIA 驱动：

sudo apt update
sudo apt install -y nvidia-driver-535
# 安装完成后重启
sudo reboot

第二步：创建独立的 Python 虚拟环境

强烈推荐使用 conda 或 python -m venv 隔离环境，避免系统 Python 被污染。

# 使用 conda 创建 Python 3.10 环境
conda create -n vllm-env python=3.10 -y
conda activate vllm-env

# 或使用 venv
python3.10 -m venv ~/vllm-venv
source ~/vllm-venv/bin/activate

第三步：安装 PyTorch（CUDA 版）

访问 PyTorch 官网 获取对应 CUDA 版本的安装命令。以 CUDA 12.1 为例：

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

安装完成后，立即验证 GPU 是否可用：

python -c "import torch; print('PyTorch版本:', torch.__version__); print('CUDA可用:', torch.cuda.is_available()); print('GPU名称:', torch.cuda.get_device_name(0))"

预期输出示例：

PyTorch版本: 2.4.0+cu121
CUDA可用: True
GPU名称: NVIDIA A100-SXM4-40GB

第四步：安装 vLLM

pip install vllm

vLLM 会自动检测当前环境中的 PyTorch 和 CUDA 版本，并编译对应的算子。如果安装过程中出现编译错误，通常是因为 PyTorch 与 CUDA 版本不匹配。

第五步：验证 vLLM 是否正常工作

# 检查 vLLM 版本
vllm --version

# 运行一个最小推理测试（使用内置的 TinyLlama 模型）
python -c "
from vllm import LLM, SamplingParams
llm = LLM(model='facebook/opt-125m', gpu_memory_utilization=0.4)
output = llm.generate(['Hello, my name is'], SamplingParams(max_tokens=20))
print(output[0].outputs[0].text)
"

如果能够正常输出文本，说明环境搭建成功。若出现 CUDA out of memory，可降低 gpu_memory_utilization 参数。

案例：一次完整的安装过程与验证日志

以下是一个实际安装案例的完整日志，展示了从环境检查到推理验证的全过程：

$ nvidia-smi
+-----------------------------------------------------------------------------+
| NVIDIA-SMI 535.154.05   Driver Version: 535.154.05   CUDA Version: 12.2     |
+-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
|   0  NVIDIA A100-SXM4-40GB   On | 00000000:00:04.0 Off |                    0 |
+-------------------------------+----------------------+----------------------+

$ conda create -n vllm-env python=3.10 -y
$ conda activate vllm-env

$ pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
Successfully installed torch-2.4.0+cu121 torchvision-0.19.0+cu121 torchaudio-2.4.0+cu121

$ python -c "import torch; print(torch.cuda.is_available())"
True

$ pip install vllm
Successfully installed vllm-0.6.3.post1

$ vllm --version
vLLM version: 0.6.3.post1

$ python -c "
from vllm import LLM, SamplingParams
llm = LLM(model='facebook/opt-125m', gpu_memory_utilization=0.4)
output = llm.generate(['Hello, my name is'], SamplingParams(max_tokens=20))
print(output[0].outputs[0].text)
"
Processed prompts: 100%|████████████████████| 1/1 [00:02<00:00,  2.34s/it]
Hello, my name is John and I am a software engineer.

环境配置速查表

误区与复盘：环境搭建中的典型陷阱

• 误区一：盲目追求最新 CUDA 版本。vLLM 和 PyTorch 的官方预编译包通常滞后于最新 CUDA 版本。使用 CUDA 12.4 而非 13.0，能获得更好的兼容性。
• 误区二：忽略驱动与 CUDA Toolkit 的区别。驱动是系统级组件，决定 GPU 的可用性；CUDA Toolkit 是用户级开发库。两者版本可以不同，但驱动版本必须 ≥ Toolkit 所需的最低版本。
• 误区三：在系统 Python 中直接安装。系统 Python 往往被多个项目共享，安装 vLLM 可能破坏其他依赖。务必使用虚拟环境。
• 误区四：安装后不验证就运行大模型。建议先用 125M 参数的小模型做冒烟测试，确认推理链路通畅后再加载大模型，避免浪费时间和显存。