vLLM 高性能推理部署指南 / 02 - 安装与环境配置

02 - 安装与环境配置

从零搭建 vLLM 运行环境，涵盖多种安装方式和常见问题处理。

2.1 系统要求总览

在安装 vLLM 之前，请确认满足以下硬件和软件要求：

2.1.1 硬件要求

组件	最低要求	推荐配置
GPU	NVIDIA GPU（Compute Capability ≥ 7.0）	A100 80GB / H100 / H200
GPU 显存	8 GB（小模型）	24 GB+（7B 模型）/ 80 GB+（70B 模型）
系统内存	16 GB	64 GB+
磁盘	50 GB 可用空间	SSD，200 GB+（存放模型）
网络	无特殊要求	高带宽（下载模型、分布式推理）

2.1.2 支持的 GPU 型号

GPU 型号	Compute Capability	FP16	BF16	FP8	INT8	推荐场景
RTX 3090	8.6	✅	❌	❌	✅	开发测试
RTX 4090	8.9	✅	✅	❌	✅	中等规模
A100 40GB	8.0	✅	✅	❌	✅	生产环境
A100 80GB	8.0	✅	✅	❌	✅	生产首选
H100	9.0	✅	✅	✅	✅	高性能生产
H200	9.0	✅	✅	✅	✅	最大模型
L40S	8.9	✅	✅	✅	✅	性价比之选
A10	8.6	✅	❌	❌	✅	入门生产

注意：FP8 量化仅在 H100/H200/L40S 等 Hopper 架构 GPU 上可用。

2.1.3 软件要求

软件	版本要求	说明
操作系统	Ubuntu 20.04+ / CentOS 8+	推荐 Ubuntu 22.04
Python	3.9 - 3.12	推荐 3.10 或 3.11
CUDA	11.8+ / 12.1+	推荐 CUDA 12.4
NVIDIA 驱动	525.60+	需匹配 CUDA 版本
pip	23.0+	用于包管理
Git	2.0+	源码安装时需要

2.2 环境检查

2.2.1 检查 NVIDIA 驱动和 GPU

# 检查 NVIDIA 驱动版本
nvidia-smi

# 预期输出示例：
# +-----------------------------------------------------------------------------+
# | NVIDIA-SMI 535.129.03   Driver Version: 535.129.03   CUDA Version: 12.2     |
# |-------------------------------+----------------------+----------------------+
# | GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
# | Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
# |===============================+======================+======================|
# |   0  NVIDIA A100 80GB...  Off  | 00000000:00:04.0 Off |                    0 |
# | N/A   35C    P0    62W / 300W |      0MiB / 81920MiB |      0%      Default |
# +-------------------------------+----------------------+----------------------+

# 查看 GPU 详细信息
nvidia-smi --query-gpu=name,compute_cap,memory.total --format=csv

# 检查 GPU Compute Capability
nvidia-smi --query-gpu=compute_cap --format=csv,noheader
# 输出: 8.0（A100）

2.2.2 检查 CUDA 版本

# 方法一：通过 nvcc
nvcc --version

# 方法二：通过 nvidia-smi
nvidia-smi | grep "CUDA Version"

# 方法三：检查 CUDA 安装路径
ls /usr/local/cuda/version.txt
cat /usr/local/cuda/version.txt

2.2.3 检查 Python 版本

python3 --version
# Python 3.10.12

# 确认 pip 版本
pip --version
# pip 23.3.1 from ...

2.3 安装方式一：pip 安装（推荐）

2.3.1 创建虚拟环境

# 使用 venv
python3 -m venv vllm-env
source vllm-env/bin/activate

# 或使用 conda
conda create -n vllm python=3.10 -y
conda activate vllm

2.3.2 安装 vLLM

# 最新稳定版（推荐）
pip install vllm

# 指定版本安装
pip install vllm==0.6.6

# 使用国内镜像加速
pip install vllm -i https://pypi.tuna.tsinghua.edu.cn/simple

2.3.3 安装特定 CUDA 版本

如果默认安装的 CUDA 版本不匹配，可以指定：

# CUDA 12.1 版本
pip install vllm --extra-index-url https://download.pytorch.org/whl/cu121

# CUDA 11.8 版本
pip install vllm --extra-index-url https://download.pytorch.org/whl/cu118

2.3.4 安装可选依赖

# 安装全部可选依赖
pip install vllm[all]

# 仅安装推理相关
pip install vllm[inference]

# 安装 OpenAI 兼容客户端（用于测试）
pip install openai

# 安装性能分析工具
pip install vllm[metrics]

# 安装 Ray（分布式推理）
pip install ray[default]

2.3.5 验证安装

# verify_install.py
import vllm

print(f"vLLM version: {vllm.__version__}")

# 检查 CUDA 是否可用
import torch
print(f"CUDA available: {torch.cuda.is_available()}")
print(f"CUDA version: {torch.version.cuda}")
print(f"GPU count: {torch.cuda.device_count()}")
print(f"GPU name: {torch.cuda.get_device_name(0)}")
print(f"GPU memory: {torch.cuda.get_device_properties(0).total_mem / 1e9:.1f} GB")

python verify_install.py

# 预期输出：
# vLLM version: 0.6.6
# CUDA available: True
# CUDA version: 12.4
# GPU count: 1
# GPU name: NVIDIA A100 80GB PCIe
# GPU memory: 80.0 GB

2.4 安装方式二：Docker 安装

2.4.1 准备 Docker 和 NVIDIA Container Toolkit

# 安装 Docker（如果未安装）
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

# 安装 NVIDIA Container Toolkit
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | \
    sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
    sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
    sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

# 配置 Docker 使用 NVIDIA runtime
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

# 验证
docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi

2.4.2 使用官方 Docker 镜像

# 拉取官方镜像
docker pull vllm/vllm-openai:latest

# 运行容器（基本用法）
docker run -d \
    --name vllm-server \
    --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai:latest \
    --model Qwen/Qwen2.5-7B-Instruct

# 运行容器（完整参数）
docker run -d \
    --name vllm-server \
    --gpus '"device=0"' \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    -v /data/models:/models \
    -p 8000:8000 \
    --ipc=host \
    --ulimit memlock=-1:-1 \
    --shm-size=16g \
    -e HUGGING_FACE_HUB_TOKEN=$HF_TOKEN \
    vllm/vllm-openai:latest \
    --model /models/Qwen2.5-72B-Instruct \
    --tensor-parallel-size 4 \
    --max-model-len 8192 \
    --gpu-memory-utilization 0.9 \
    --served-model-name qwen-72b

2.4.3 Docker 参数说明

参数	说明
`--gpus all`	使用所有 GPU
`--gpus '"device=0,1"'`	使用指定 GPU
`--ipc=host`	共享主机 IPC 命名空间（必需，用于共享内存）
`--shm-size=16g`	设置共享内存大小（推荐 ≥ 16GB）
`--ulimit memlock=-1:-1`	解除内存锁定限制
`-v ~/.cache/huggingface:/root/.cache/huggingface`	挂载模型缓存
`-p 8000:8000`	映射端口

关键：--ipc=host 是必需参数，vLLM 需要大量共享内存用于进程间通信。

2.5 安装方式三：源码安装

适用于需要修改源码或使用最新开发特性的场景。

2.5.1 克隆和编译

# 克隆仓库
git clone https://github.com/vllm-project/vllm.git
cd vllm

# 切换到特定版本（可选）
git checkout v0.6.6

# 安装编译依赖
pip install -r requirements-build.txt

# 编译安装（耗时较长，需要 CUDA 编译器）
pip install -e .

# 以开发模式安装（可编辑）
pip install -e ".[all]"

2.5.2 源码安装注意事项

编译时间：首次编译可能需要 30-60 分钟，取决于 CPU 性能。

内存需求：编译过程需要大量系统内存，建议 32 GB+。

CUDA Toolkit：需要完整安装 CUDA Toolkit（不仅是 runtime）。

2.6 安装方式四：conda 安装

# 创建环境
conda create -n vllm python=3.10 -y
conda activate vllm

# 安装 PyTorch（先安装 PyTorch 确保 CUDA 版本匹配）
conda install pytorch pytorch-cuda=12.1 -c pytorch -c nvidia

# 安装 vLLM
pip install vllm

2.7 模型下载与缓存

2.7.1 HuggingFace 模型缓存

vLLM 从 HuggingFace Hub 下载模型，缓存默认位置：

# 默认缓存路径
~/.cache/huggingface/hub/

# 自定义缓存路径
export HF_HOME=/data/huggingface
export HUGGING_FACE_HUB_TOKEN=hf_xxxxxxxxxxxxx  # 访问 gated 模型

2.7.2 提前下载模型

# 方法一：使用 huggingface-cli
pip install huggingface_hub
huggingface-cli download Qwen/Qwen2.5-7B-Instruct

# 方法二：使用 Python
python -c "
from huggingface_hub import snapshot_download
snapshot_download(
    'Qwen/Qwen2.5-7B-Instruct',
    local_dir='/data/models/qwen2.5-7b'
)
"

# 方法三：使用 modelscope（国内加速）
pip install modelscope
modelscope download --model Qwen/Qwen2.5-7B-Instruct --local_dir /data/models/qwen2.5-7b

2.7.3 使用本地模型

# 本地模型路径
vllm serve /data/models/qwen2.5-7b --served-model-name qwen-7b

# 或设置环境变量
export HF_HOME=/data/models
vllm serve Qwen/Qwen2.5-7B-Instruct  # 从缓存加载

2.7.4 HuggingFace 镜像加速

# 设置 HuggingFace 镜像（国内用户）
export HF_ENDPOINT=https://hf-mirror.com

# 验证镜像
curl -I https://hf-mirror.com

# 之后所有 huggingface 操作自动使用镜像
huggingface-cli download Qwen/Qwen2.5-7B-Instruct

2.8 多 GPU 环境配置

2.8.1 指定可见 GPU

# 使用所有 GPU
export CUDA_VISIBLE_DEVICES=0,1,2,3

# 使用指定 GPU
export CUDA_VISIBLE_DEVICES=0,1

# 在 Python 中指定
import os
os.environ["CUDA_VISIBLE_DEVICES"] = "0,1,2,3"

2.8.2 GPU 持久化模式

# 启用 GPU 持久化模式（减少初始化延迟）
sudo nvidia-smi -pm 1

# 设置 GPU 功率限制（可选，降低功耗）
sudo nvidia-smi -pl 300  # 设置为 300W

# 设置 GPU 计算模式
sudo nvidia-smi -c EXCLUSIVE_PROCESS  # 独占进程模式（生产推荐）

2.9 环境变量配置

以下是 vLLM 相关的重要环境变量：

# ~/.bashrc 或 ~/.profile

# === 模型相关 ===
export HF_HOME=/data/huggingface               # HuggingFace 缓存目录
export HUGGING_FACE_HUB_TOKEN=hf_xxx           # HF Token（gated 模型需要）
export HF_ENDPOINT=https://hf-mirror.com       # HF 镜像（国内加速）

# === vLLM 相关 ===
export VLLM_WORKER_MULTIPROC_METHOD=spawn       # 多进程启动方式
export VLLM_ATTENTION_BACKEND=FLASH_ATTN        # Attention 后端
export VLLM_USE_MODELSCOPE=False                # 是否使用 ModelScope

# === CUDA 相关 ===
export CUDA_VISIBLE_DEVICES=0,1,2,3            # 可见 GPU
export CUDA_DEVICE_ORDER=PCI_BUS_ID             # GPU 编号顺序

# === 性能相关 ===
export NCCL_P2P_DISABLE=0                       # P2P 通信开关
export NCCL_IB_DISABLE=0                        # InfiniBand 开关
export OMP_NUM_THREADS=8                        # OpenMP 线程数

2.10 安装问题排查

常见问题一：CUDA 版本不匹配

错误信息：

RuntimeError: CUDA error: no kernel image is available for execution on the device

解决方案：

# 检查 PyTorch CUDA 版本
python -c "import torch; print(torch.version.cuda)"

# 检查系统 CUDA 版本
nvcc --version

# 确保两者匹配，重新安装 PyTorch
pip install torch --index-url https://download.pytorch.org/whl/cu124

常见问题二：共享内存不足

错误信息：

torch.multiprocessing.spawn: Process exited with error: bus error

解决方案：

# Docker 中增加共享内存
docker run --shm-size=16g ...

# 系统中增加 /dev/shm
sudo mount -o remount,size=16G /dev/shm

常见问题三：编译失败

错误信息：

nvcc fatal: Unsupported gpu architecture 'compute_XX'

解决方案：

# 确保 CUDA Toolkit 版本支持目标 GPU
# CUDA 11.8 支持 compute_89（RTX 4090）
# CUDA 12.1+ 支持 compute_90（H100）

# 使用预编译的 wheel（推荐）
pip install vllm

常见问题四：内存不足

错误信息：

OutOfMemoryError: CUDA out of memory

解决方案：

# 1. 减小 GPU 内存利用率（默认 0.9）
vllm serve model --gpu-memory-utilization 0.85

# 2. 减小最大序列长度
vllm serve model --max-model-len 2048

# 3. 使用量化模型
vllm serve model --quantization awq

2.11 安装验证全流程

完成安装后，运行以下完整验证脚本：

# full_verify.py
"""vLLM 安装完整验证脚本"""

import sys

def check_imports():
    """检查关键模块导入"""
    modules = ["vllm", "torch", "transformers"]
    for mod in modules:
        try:
            m = __import__(mod)
            version = getattr(m, "__version__", "unknown")
            print(f"  ✅ {mod}: {version}")
        except ImportError as e:
            print(f"  ❌ {mod}: {e}")
            return False
    return True

def check_cuda():
    """检查 CUDA 环境"""
    import torch
    if not torch.cuda.is_available():
        print("  ❌ CUDA 不可用")
        return False
    
    print(f"  ✅ CUDA: {torch.version.cuda}")
    print(f"  ✅ cuDNN: {torch.backends.cudnn.version()}")
    print(f"  ✅ GPU 数量: {torch.cuda.device_count()}")
    
    for i in range(torch.cuda.device_count()):
        props = torch.cuda.get_device_properties(i)
        print(f"  ✅ GPU {i}: {props.name}, {props.total_mem / 1e9:.1f} GB, CC {props.major}.{props.minor}")
    return True

def check_vllm():
    """检查 vLLM 功能"""
    from vllm import LLM, SamplingParams
    
    print("  尝试加载小模型进行测试...")
    try:
        llm = LLM(
            model="Qwen/Qwen2.5-0.5B-Instruct",
            max_model_len=512,
            gpu_memory_utilization=0.5,
        )
        outputs = llm.generate(["Hello, how are you?"], SamplingParams(max_tokens=10))
        print(f"  ✅ 推理成功: {outputs[0].outputs[0].text[:50]}")
        return True
    except Exception as e:
        print(f"  ❌ vLLM 测试失败: {e}")
        return False

if __name__ == "__main__":
    print("=== vLLM 安装验证 ===\n")
    
    print("1. 检查模块导入:")
    check_imports()
    
    print("\n2. 检查 CUDA 环境:")
    check_cuda()
    
    print("\n3. 检查 vLLM 功能:")
    check_vllm()
    
    print("\n=== 验证完成 ===")

2.12 注意事项

驱动兼容性：NVIDIA 驱动版本必须高于 CUDA 版本要求的最低版本。详见 CUDA 兼容性矩阵。

Docker 共享内存：使用 Docker 运行 vLLM 时，--ipc=host 是必需参数，否则会出现段错误（segfault）。

防火墙：如果需要从外部访问 API 服务，确保开放 8000 端口（或自定义端口）。

模型许可证：下载模型前请确认许可证允许您的使用场景，尤其是商业用途。

2.13 扩展阅读

上一章：01 - vLLM 概述与技术原理 | 下一章：03 - 快速开始