环境准备：硬件要求与软件依赖

vLLM 是一个依赖 GPU 高性能计算、显存带宽与批量调度能力的推理引擎。它的性能上限并非由模型参数量单独决定，而是由“显存容量 + 显存带宽 + 计算单元 + 主机内存/PCIe 通道”共同构成。在部署前，先厘清硬件边界与软件栈的匹配关系，能避免大量“能跑但跑不快”的隐性故障。

2.1 硬件要求：GPU、CPU 与内存

GPU 是 vLLM 的核心算力来源。vLLM 的 PagedAttention 机制将 KV Cache 划分为固定大小的块（默认 16 个 token 一块），因此显存利用率远高于传统静态缓存方案，但显存总量仍然决定了可服务的最大并发数与序列长度。选择 GPU 时，需关注以下指标：

  • 显存容量：至少为“模型权重 + 激活值 + KV Cache 峰值”预留 1.2～1.5 倍余量。以 7B 模型 FP16 为例，权重约 14 GB，加上 KV Cache 与运行时开销，建议使用 24 GB 以上显存（如 RTX 3090/4090、A10G、L4）。
  • 显存带宽：决定 decode 阶段（逐 token 生成）的吞吐上限。H100/A100 的 HBM 带宽（2 TB/s 以上）远优于消费级显卡，对长序列生成影响显著。
  • 计算精度支持：FP16/BF16 是 vLLM 默认推理精度。若 GPU 不支持 BF16（如部分 Turing 架构），需回退到 FP16 或开启自动混合精度。
  • 多卡互联：多卡部署时，NVLink/NVSwitch 带宽决定张量并行的通信效率。PCIe 4.0 x16 仅约 32 GB/s，远低于 NVLink 的 600 GB/s，因此跨卡并行优先选择 NVLink 互联。

CPU 与内存的角色常被低估。vLLM 的调度器、tokenizer、采样器运行在 CPU 侧；当请求并发高时，CPU 需要快速完成 preemption、KV Cache 块分配与调度决策。若 CPU 核数过少或主频过低，GPU 会因等待调度指令而出现“饥饿”。内存方面，vLLM 会将模型权重从 CPU 内存加载到显存，同时需要为每个请求保留临时激活缓冲区。建议内存容量至少为显存总量的 2 倍，且使用双通道 DDR4/DDR5 以上配置。

实操建议：在采购或分配资源前，先运行 nvidia-smi 查看 GPU 型号、显存总量与当前占用；再使用 lscpu 确认核数与架构；最后用 free -h 检查可用内存。三者共同决定 vLLM 的 --tensor-parallel-size 与 --max-num-seqs 参数上限。
vLLM 硬件资源需求总览 GPU（核心计算单元） 显存容量：≥ 权重 + KV Cache × 1.2 显存带宽：HBM ≥ 2 TB/s（长序列关键） 精度支持：FP16 / BF16 / FP8 多卡互联 NVLink 600 GB/s ≫ PCIe 4.0 32 GB/s CPU（调度与预处理） 核心数 ≥ 16（高并发时建议 ≥ 32） 主频 ≥ 3.0 GHz（调度延迟敏感） 主机内存（数据中转与缓冲） 容量 ≥ 显存总量 × 2 通道：双通道 DDR4/DDR5 以上 调度 加载权重 PCIe / NVLink 数据传输 典型配置参考（7B 模型，FP16） 单卡入门 RTX 4090 24GB / 32GB 内存 生产标准 A100 80GB × 2 / 256GB 内存 高并发优化 H100 × 4 / 512GB 内存

2.2 软件依赖：CUDA、Python 与 PyTorch

vLLM 的软件栈可视为三层：驱动层（NVIDIA Driver）→ 计算平台层（CUDA Toolkit）→ 深度学习框架层（PyTorch）。vLLM 通过 CUDA 直接管理显存与 kernel 执行，同时依赖 PyTorch 的算子库与自动微分基础设施。版本不匹配是部署初期最常见的故障来源。

软件组件 推荐版本 说明
NVIDIA Driver ≥ 535.104（Linux） 驱动版本决定 CUDA 运行时兼容上限
CUDA Toolkit 12.1 / 12.4 vLLM 0.6+ 默认基于 CUDA 12 构建
Python 3.10 / 3.11 3.12 部分依赖需编译，不建议生产使用
PyTorch 2.3+（CUDA 12.1 配套） 需与 CUDA 版本严格对应
vLLM ≥ 0.6.0 建议使用官方预编译 wheel

安装前先验证驱动与 CUDA 的兼容性。运行 nvidia-smi 查看右上角的 CUDA Version，这是驱动支持的最高 CUDA 版本，而非当前激活的版本。随后用 nvcc --version 确认实际安装的 CUDA Toolkit 版本。两者关系为：驱动版本 ≥ 所需 CUDA 版本，否则即使安装了 CUDA 也无法调用 GPU。

# 检查驱动与 CUDA 版本
nvidia-smi
# 输出示例：
# +-----------------------------------------------------------------------------+
# | NVIDIA-SMI 535.154.05   Driver Version: 535.154.05   CUDA Version: 12.2     |
# +-----------------------------------------------------------------------------+

nvcc --version
# 输出示例：
# Cuda compilation tools, release 12.1, V12.1.105
常见误区：不要将 nvidia-smi 显示的 CUDA Version 误认为已安装的 CUDA Toolkit。前者是驱动支持的“上限”，后者才是编译和运行 PyTorch/vLLM 实际使用的版本。若两者不一致，优先以 PyTorch 官方安装命令中指定的 CUDA 版本为准。

2.3 虚拟环境配置：隔离与复现

vLLM 依赖的包较多且版本敏感，直接安装到系统 Python 会导致依赖冲突。推荐使用 conda 或 venv 创建独立环境。生产环境建议使用 conda，因为它能同时管理 Python 版本与 CUDA 相关的非 Python 依赖。

方法流程：conda 环境创建与安装

# 1. 创建独立环境，指定 Python 版本
conda create -n vllm-env python=3.11 -y

# 2. 激活环境
conda activate vllm-env

# 3. 安装 PyTorch（以 CUDA 12.1 为例）
pip install torch==2.3.1 torchvision==0.18.1 --index-url https://download.pytorch.org/whl/cu121

# 4. 安装 vLLM（官方预编译包）
pip install vllm==0.6.3

# 5. 验证安装
python -c "import vllm; print(vllm.__version__)"

安装完成后，务必执行一次 GPU 连通性测试，确认 PyTorch 能正确识别 CUDA 设备：

python -c "import torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))"
# 期望输出：
# True
# NVIDIA A100-SXM4-80GB

若输出 False，按以下顺序排查：

  1. 驱动是否正常加载：lsmod | grep nvidia 或重新安装驱动。
  2. PyTorch 的 CUDA 版本是否与驱动匹配：python -c "import torch; print(torch.version.cuda)"。
  3. 是否在正确的 conda 环境中：which python 应指向 ~/anaconda3/envs/vllm-env/bin/python。

案例：多项目环境隔离的典型场景

假设一台服务器同时运行三个推理项目：项目 A 使用 vLLM 0.5.4（依赖 PyTorch 2.1），项目 B 使用 vLLM 0.6.3（依赖 PyTorch 2.3），项目 C 使用 TensorRT-LLM。若共用系统 Python，版本冲突不可避免。通过 conda 创建三个独立环境，每个环境拥有各自的 PyTorch 与 CUDA 运行时，互不干扰。启动服务时，只需在 systemd 或 Docker 启动脚本中显式激活对应环境即可。

生产部署建议：使用 conda env export > environment.yml 导出环境配置，并纳入 Git 版本管理。这样新机器上可通过 conda env create -f environment.yml 一键复现，避免“在我机器上能跑”的尴尬。

2.4 误区与复盘：环境准备阶段的常见陷阱

根据社区反馈与生产事故复盘，以下三类问题出现频率最高：

  • 误区一：盲目追求最新版本。vLLM 的 master 分支或最新 PyTorch 版本可能引入未充分测试的变更。生产环境应锁定已验证的版本组合，例如 vLLM 0.6.3 + PyTorch 2.3.1 + CUDA 12.1，而非使用 pip install vllm 直接拉取最新。
  • 误区二：忽略 CPU 与内存瓶颈。部分团队只关注 GPU 型号，却使用 4 核 CPU 和 16 GB 内存的机器运行 70B 模型。结果 GPU 利用率长期低于 30%，请求排队时间远超生成时间。复盘发现，CPU 调度延迟与内存换页成为瓶颈。
  • 误区三：多卡环境未检查 NVLink 拓扑。使用 nvidia-smi topo -m 可查看 GPU 间互联方式。若两张卡通过 PCIe 而非 NVLink 连接，张量并行通信开销会显著增加，此时应优先使用数据并行或调整并行策略。

一次典型的故障复盘记录如下：某团队在 4×A100 服务器上部署 vLLM，启动时设置 --tensor-parallel-size 4，但运行后吞吐仅为预期的 40%。排查过程：

  1. 先检查 GPU 利用率：nvidia-smi dmon -s puc，发现 4 张卡利用率均低于 50%。
  2. 再检查通信拓扑：nvidia-smi topo -m，发现 GPU0 与 GPU2 之间为 PCIe 连接（无 NVLink）。
  3. 改用 --tensor-parallel-size 2 并配合数据并行，吞吐提升至预期的 85%。

复盘结论：环境准备不仅是“装好驱动”，更需理解硬件拓扑与软件并行策略的匹配关系。建议在部署前将硬件信息、驱动版本、CUDA 版本、Python 版本、PyTorch 版本、vLLM 版本记录为一份环境清单，随服务发布文档一同归档。

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