环境准备：Python环境、CUDA、PyTorch安装，以及vLLM的安装与验证

vLLM 是一个高度依赖底层硬件与运行时环境的推理引擎。它的性能优势建立在 CUDA 生态、PyTorch 张量库以及 Python 解释器三者紧密协作的基础之上。如果环境版本不匹配，轻则安装失败，重则出现推理结果错误或显存访问异常。本节将按照“Python → CUDA → PyTorch → vLLM”的顺序，梳理一套经过验证的环境搭建路径，并给出每一步的验证方法。

核心原理：版本匹配是环境搭建的第一原则

vLLM 通过 PyTorch 的 CUDA 扩展接口调用 GPU 算子，而 PyTorch 的 CUDA 支持版本必须与驱动提供的 CUDA 运行时兼容。这里需要区分两个概念：驱动版本（NVIDIA Driver）与CUDA Toolkit 版本。驱动是操作系统与 GPU 之间的底层桥梁，而 CUDA Toolkit 是编译和运行 CUDA 程序所需的库集合。PyTorch 在安装时会捆绑自己的 CUDA 运行时库（如 cu121、cu124），只要驱动版本足够新，就能兼容这些捆绑库，无需单独安装完整的 CUDA Toolkit。

关键判断依据：在终端执行 nvidia-smi，右上角显示的 CUDA Version 是驱动支持的最高 CUDA 版本，而非系统已安装的 Toolkit 版本。PyTorch 安装时选择的 CUDA 版本必须 ≤ 该值。

下图展示了从硬件驱动到 vLLM 推理的完整依赖链，以及各层之间的版本约束关系：

NVIDIA GPU 硬件（如 A100 / H100 / RTX 4090） 显存容量与计算能力（Compute Capability）决定可运行的模型规模 NVIDIA 驱动（nvidia-smi 可查看） 驱动版本决定支持的最高 CUDA 版本，例如 535.104 支持 CUDA 12.2 CUDA 运行时（随 PyTorch 捆绑，如 cu121 / cu124） 无需单独安装 Toolkit，但版本必须 ≤ 驱动支持的最高版本 PyTorch（2.x + CUDA 版本匹配） vLLM 依赖 PyTorch 的 CUDA 扩展机制，需使用官方预编译包 vLLM 推理引擎 通过 PagedAttention 与 CUDA 算子实现高效推理 ≥ 535.104 ≤ 驱动支持 2.1+ 推荐 0.6+ 推荐

方法流程：四步完成环境搭建

第一步：Python 虚拟环境

强烈建议使用 conda 或 python -m venv 创建独立环境，避免与系统 Python 或其它项目产生依赖冲突。vLLM 对 Python 版本要求为 3.9 ~ 3.12，推荐使用 3.10 或 3.11，这两个版本在算子编译和第三方库兼容性上表现最稳定。

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

# 验证 Python 版本
python --version
# 输出示例：Python 3.11.9

第二步：确认 CUDA 驱动与安装 PyTorch

首先执行 nvidia-smi 查看驱动支持的 CUDA 版本。假设输出显示 CUDA Version: 12.4，则可以选择 PyTorch 的 cu124 或更低版本（如 cu121）。然后前往 PyTorch 官网 获取对应安装命令。

# 以 CUDA 12.4 为例（驱动需 ≥ 550.54.14）
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

# 验证 PyTorch 是否可用 GPU
python -c "import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))"
# 期望输出：
# 2.4.0+cu124
# True
# NVIDIA A100-SXM4-40GB

常见误区：不要使用 pip install torch 默认安装 CPU 版本。默认 PyPI 源中的 torch 不包含 CUDA 支持，会导致 vLLM 启动时报 CUDA unavailable 错误。务必使用指定 --index-url 的安装方式。

第三步：安装 vLLM

vLLM 提供了预编译的 wheel 包，安装过程会自动检测 PyTorch 版本并拉取匹配的依赖。推荐使用 pip 直接安装，避免从源码编译（源码编译需要额外的 GCC、Ninja 等工具链，且耗时较长）。

# 安装 vLLM（自动匹配已安装的 PyTorch CUDA 版本）
pip install vllm

# 验证安装
python -c "import vllm; print(vllm.__version__)"
# 输出示例：0.6.3

第四步：端到端验证

使用一个小型模型验证 vLLM 能否正常完成推理。这里以 facebook/opt-125m 为例，该模型约 250MB，下载和推理都很快，适合作为冒烟测试。

# 创建测试脚本 test_vllm.py
from vllm import LLM, SamplingParams

llm = LLM(model="facebook/opt-125m", gpu_memory_utilization=0.4)
prompts = ["什么是深度学习？", "请用一句话解释注意力机制。"]
outputs = llm.generate(prompts, SamplingParams(temperature=0.8, max_tokens=64))

for output in outputs:
    print(output.prompt)
    print(output.outputs[0].text)
    print("-" * 40)
# 运行测试
python test_vllm.py
# 期望看到模型加载日志、GPU 显存分配信息，以及生成的文本输出

案例场景：典型环境配置参考

下表列出了三种常见的生产环境配置组合，供不同硬件条件下的部署参考。请根据实际 GPU 型号和驱动版本选择最接近的一组。

GPU 型号 驱动版本 PyTorch CUDA 版本 vLLM 版本 备注
A100 / H100 ≥ 550.54.14 cu124 ≥ 0.6.0 生产环境首选，支持全精度与 FP8
RTX 4090 / 3090 ≥ 535.104 cu121 ≥ 0.5.0 消费级显卡，注意显存限制
L40S / A10 ≥ 525.60 cu118 ≥ 0.4.0 数据中心推理卡，性价比高

误区与复盘：环境问题排查清单

在实际部署中，以下三类问题出现频率最高，建议在遇到异常时按顺序排查：

  • CUDA 不可用（torch.cuda.is_available() 返回 False）：首先检查驱动是否正常（nvidia-smi），然后确认 PyTorch 安装的是 CUDA 版本而非 CPU 版本。可通过 pip list | grep torch 查看安装来源。
  • vLLM 导入时报 CUDA 扩展编译错误：通常是因为 PyTorch 版本过旧或过新，与 vLLM 预编译包不匹配。解决方案是升级 PyTorch 到 2.1 以上，或降级 vLLM 到与当前 PyTorch 兼容的版本。
  • 显存不足（CUDA out of memory）：vLLM 默认会占用约 90% 的显存。如果同时运行其他任务，可通过 gpu_memory_utilization 参数调低占用比例，例如设置为 0.6。

快速诊断命令：将以下命令组合成一行，可快速判断环境是否就绪：

python -c "import torch, vllm; print('PyTorch:', torch.__version__, '| CUDA:', torch.version.cuda, '| Available:', torch.cuda.is_available()); print('vLLM:', vllm.__version__)"

如果输出中 Available: True 且 vLLM 版本号正常显示，则环境基本可用。

最后需要强调的是，环境搭建虽然步骤简单，但版本匹配的细节决定了后续所有工作的稳定性。建议在完成安装后，将 nvidia-smi 的输出、torch.__version__ 和 vllm.__version__ 三个信息记录在项目文档中，作为团队协作和问题复现的基础依据。这样当模型推理出现性能异常或结果错误时，可以快速排除环境因素，将精力集中在模型配置和推理参数调优上。

← 上一章 📖 返回目录 下一章 →