环境准备：操作系统要求、Python版本选择、虚拟环境创建与激活

在部署 vLLM 之前，必须先搭建一个干净、可控、可复现的运行环境。vLLM 依赖 CUDA、PyTorch 和编译工具链，任何一层版本不匹配都可能导致导入失败、显存分配异常甚至非法指令错误。本节从操作系统、Python 版本和虚拟环境三个层面，梳理部署前必须完成的环境准备工作。

操作系统要求

vLLM 官方对操作系统的支持范围明确，核心约束在于 CUDA 运行库与 GCC 编译工具链的可用性。推荐使用 Linux 系操作系统，尤其是 Ubuntu 20.04 或 22.04 LTS，这两者在驱动兼容性、库依赖完整度和社区排障资料方面表现最佳。

操作系统 支持级别 说明
Ubuntu 20.04 / 22.04 LTS ✅ 官方推荐 驱动与 CUDA 兼容性最好，社区案例最多
CentOS 7 / Rocky Linux 8 ⚠️ 可用但需注意 需手动安装较新的 GCC（≥10）和 Python 3.10+
Windows (WSL2) ⚠️ 实验性支持 仅限 WSL2 的 Ubuntu 发行版，原生 Windows 不支持
macOS ❌ 不支持 无 NVIDIA GPU 驱动，无法运行 CUDA 加速

在 Linux 上，建议先确认 GPU 驱动与 CUDA 版本。执行 nvidia-smi 查看驱动版本，并确认其支持的最高 CUDA 版本。vLLM 要求 CUDA 11.8 或 12.1+，推荐直接使用 CUDA 12.1 及以上版本，以获得更好的算子兼容性。

# 检查 GPU 驱动与 CUDA 版本
nvidia-smi

# 输出示例（关键行）
# CUDA Version: 12.2
# Driver Version: 535.104.05

如果驱动版本过旧，需要先升级 NVIDIA 驱动，再安装对应版本的 CUDA toolkit。注意：驱动版本决定可用的最高 CUDA 版本，而 PyTorch 和 vLLM 的编译产物则依赖具体的 CUDA 运行时。

Python 版本选择

vLLM 对 Python 版本有明确要求：Python 3.9 至 3.12。其中 3.10 和 3.11 是当前社区使用最广泛、兼容性最稳定的版本。Python 3.12 虽然受支持，但部分依赖库（如 flash-attention）的预编译轮子可能尚未完全跟上，建议在正式部署前做一次导入测试。

选择 Python 版本时，还需考虑 PyTorch 的版本约束。vLLM 0.6.x 系列要求 PyTorch ≥ 2.1，而 PyTorch 2.1 至 2.3 对 Python 3.12 的支持存在细微差异。为避免不必要的编译问题，推荐组合如下：

  • 稳定组合：Python 3.10 + PyTorch 2.1.2 + CUDA 12.1
  • 性能组合：Python 3.11 + PyTorch 2.3.0 + CUDA 12.1
  • 保守组合：Python 3.9 + PyTorch 2.0.1 + CUDA 11.8

检查当前 Python 版本：

python3 --version
# 期望输出：Python 3.10.x 或 3.11.x

如果系统自带的 Python 版本过低，建议通过 apt 或源码编译安装新版本，但不要覆盖系统默认的 python3 软链接，以免破坏系统工具链。

版本选择建议：如果服务器上已有多个 Python 版本，使用 update-alternatives 或 pyenv 管理版本切换，避免直接修改 /usr/bin/python3 的指向。

虚拟环境创建与激活

虚拟环境是隔离 Python 依赖的必备手段。vLLM 的依赖项较多且版本敏感，直接安装到系统环境极易与现有包冲突。推荐使用 python3 -m venv 创建虚拟环境，这是 Python 3.3+ 内置的轻量级方案，无需额外安装。

创建虚拟环境的完整流程如下：

# 1. 创建虚拟环境目录（命名为 vllm-env）
python3 -m venv vllm-env

# 2. 激活虚拟环境
source vllm-env/bin/activate

# 3. 确认当前 Python 路径已指向虚拟环境
which python
# 输出：/path/to/vllm-env/bin/python

# 4. 升级 pip 并安装 vLLM
pip install --upgrade pip
pip install vllm

激活后，命令行提示符前会出现 (vllm-env) 前缀，表示当前 shell 已进入虚拟环境。此时所有 pip install 和 python 命令都指向虚拟环境内的解释器，不会污染系统环境。

如果需要退出虚拟环境，直接执行 deactivate 即可。在编写 systemd 服务或 Docker 启动脚本时，务必使用虚拟环境内 Python 的绝对路径，例如：

/opt/vllm-env/bin/python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-2-7b-chat-hf

这样可以确保服务启动时加载的是虚拟环境中的依赖，而不是系统 Python 的包。

环境验证与常见误区

环境配置完成后，不要急于启动服务，先做一次快速验证。以下命令可以确认 vLLM 是否能正确导入并识别 GPU：

# 在虚拟环境中执行
python -c "import vllm; print(vllm.__version__)"
# 期望输出：0.6.3.post1 或类似版本号

python -c "import torch; print(torch.cuda.is_available())"
# 期望输出：True

如果 torch.cuda.is_available() 返回 False，说明 PyTorch 与 CUDA 的匹配有问题。常见原因包括：

  • 安装了 CPU 版本的 PyTorch（pip install torch 默认可能安装 CPU 版）
  • CUDA 驱动版本过低，无法支持 PyTorch 所需的 CUDA 运行时
  • 虚拟环境中存在多个 PyTorch 版本冲突

正确的 PyTorch 安装方式应指定 CUDA 版本，例如：

# 安装 CUDA 12.1 对应的 PyTorch
pip install torch==2.1.2 torchvision==0.16.2 torchaudio==2.1.2 \
  --index-url https://download.pytorch.org/whl/cu121
常见误区：不要直接使用 pip install vllm 后才发现 PyTorch 版本不对。vLLM 安装时不会自动替换已存在的 PyTorch，如果系统环境中已有 CPU 版 PyTorch，vLLM 会报出 torch.cuda.is_available() is False 的错误。务必在安装 vLLM 之前，先确认虚拟环境中的 PyTorch 是 CUDA 版本。

另一个高频问题是 GCC 版本过低。vLLM 在安装时会编译部分自定义算子，需要 GCC ≥ 10。如果编译过程中出现 internal compiler error 或 undefined reference，请先检查编译器版本：

gcc --version
# 期望输出：gcc (Ubuntu 11.4.0-1ubuntu1~22.04) 11.4.0

如果 GCC 版本过低，可以通过 apt install gcc-11 g++-11 安装新版本，并使用 update-alternatives 切换默认编译器。

环境配置复盘清单

为了帮助你在部署前快速自查，以下是一份精简的环境准备清单：

  1. 操作系统为 Ubuntu 20.04/22.04 或兼容 Linux 发行版
  2. NVIDIA 驱动已安装，nvidia-smi 显示 CUDA 版本 ≥ 12.1
  3. Python 版本为 3.10 或 3.11（python3 --version 确认）
  4. 已创建独立虚拟环境并激活（source vllm-env/bin/activate）
  5. PyTorch 为 CUDA 版本（torch.cuda.is_available() 返回 True）
  6. GCC 版本 ≥ 10（gcc --version 确认）
  7. vLLM 安装成功（import vllm 无报错）

完成以上步骤后，你的环境就具备了运行 vLLM 的基本条件。接下来可以着手准备模型权重文件，并启动推理服务进行验证。

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