跳到主要内容

环境配置

本章将指导你完成 vLLM 的安装和环境配置。vLLM 支持多种安装方式，你可以根据自己的硬件环境和使用场景选择最适合的方案。

系统要求​

硬件要求​

vLLM 主要面向 GPU 推理优化，以下是推荐的硬件配置：

NVIDIA GPU（推荐）

  • 计算能力 7.0 及以上的 NVIDIA GPU
  • 最低 8GB 显存（运行 7B 模型）
  • 推荐 24GB 显存（运行 13B 及以上模型）
  • CUDA 12.1 或更高版本

AMD GPU

  • AMD Radeon Instinct 系列
  • ROCm 5.7 或更高版本

CPU 模式（实验性）

  • 支持 x86_64 和 ARM64 架构
  • 需要大量内存（建议模型参数的 2 倍以上）
  • 推理速度较慢，适合测试和开发

软件要求​

  • Python 3.9 - 3.12
  • CUDA 12.1+（NVIDIA GPU）或 ROCm 5.7+（AMD GPU）
  • Linux 操作系统（推荐 Ubuntu 20.04+）
  • Windows 10/11（通过 WSL2）

安装方式​

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

pip 安装是最简单直接的方式，适合大多数用户。

创建虚拟环境

推荐使用 conda 或 venv 创建独立的 Python 环境：

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

# 或使用 venv
python -m venv vllm-env
source vllm-env/bin/activate  # Linux/Mac
# 或
vllm-env\Scripts\activate  # Windows

安装 vLLM

# 安装稳定版本
pip install vllm

# 安装最新开发版本
pip install vllm --pre --extra-index-url https://wheels.vllm.ai/nightly

验证安装

python -c "import vllm; print(vllm.__version__)"

方式二：Docker 安装​

Docker 安装可以确保环境一致性，特别适合生产部署。

拉取官方镜像

# 最新稳定版本
docker pull vllm/vllm-openai:latest

# 指定版本
docker pull vllm/vllm-openai:v0.5.0

运行容器

docker run --runtime nvidia --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    -p 8000:8000 \
    vllm/vllm-openai:latest \
    --model meta-llama/Llama-2-7b-chat-hf

参数说明：

  • --runtime nvidia：启用 NVIDIA Docker 运行时
  • --gpus all：允许容器访问所有 GPU
  • -v：挂载 Hugging Face 缓存目录，避免重复下载模型
  • -p 8000:8000：映射端口

方式三：从源码安装​

如果你需要修改 vLLM 源码或参与开发，可以选择从源码安装。

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

# 安装依赖
pip install -e .

# 或安装开发依赖
pip install -e ".[dev]"

CUDA 环境配置​

检查 CUDA 版本​

nvcc --version
nvidia-smi

CUDA 版本不匹配处理​

如果系统 CUDA 版本与 vLLM 要求不匹配，可以通过以下方式解决：

方案一：安装兼容的 PyTorch 版本

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

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

方案二：使用 conda 安装 CUDA 工具包

conda install -c nvidia cuda-toolkit=12.1

模型下载配置​

vLLM 使用 Hugging Face 的 transformers 库加载模型。首次使用某个模型时会自动下载。

配置镜像（国内用户）​

由于网络原因，国内用户可能需要配置镜像源：

# 设置 Hugging Face 镜像
export HF_ENDPOINT=https://hf-mirror.com

# 或在 Python 中设置
import os
os.environ['HF_ENDPOINT'] = 'https://hf-mirror.com'

手动下载模型​

如果自动下载失败，可以手动下载模型：

# 安装 huggingface-cli
pip install huggingface-hub

# 下载模型
huggingface-cli download --resume-download meta-llama/Llama-2-7b-chat-hf --local-dir ./models/llama-2-7b

使用 ModelScope（国内替代）​

# 安装 ModelScope
pip install modelscope

# 在代码中使用
from modelscope import snapshot_download
model_dir = snapshot_download("modelscope/Llama-2-7b-chat-ms")

开发环境配置​

IDE 配置​

推荐使用 VS Code 或 PyCharm 进行开发。

VS Code 推荐插件：

  • Python
  • Pylance
  • autoDocstring
  • GitLens

Python 代码格式化：

pip install black isort

# 格式化代码
black .
isort .

类型检查​

vLLM 使用类型提示，建议开启类型检查：

pip install mypy
mypy your_script.py

常见问题​

问题一：ImportError: libcudart.so.11.0: cannot open shared object file​

原因：CUDA 运行时库未找到

解决方案：

# 添加 CUDA 到 LD_LIBRARY_PATH
export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH

# 永久生效（添加到 ~/.bashrc）
echo 'export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc

问题二：OutOfMemoryError: CUDA out of memory​

原因：GPU 显存不足

解决方案：

  1. 使用更小的模型
  2. 降低 max_model_len 参数
  3. 使用量化模型
  4. 减少 gpu_memory_utilization（默认 0.9，可尝试 0.8）
llm = LLM(
    model="meta-llama/Llama-2-7b-chat-hf",
    gpu_memory_utilization=0.8,
    max_model_len=2048
)

问题三：模型下载超时​

解决方案：

# 增加超时时间
export HF_HUB_DOWNLOAD_TIMEOUT=300

# 或使用代理
export HTTPS_PROXY=http://your-proxy:port

问题四：Windows 安装失败​

vLLM 官方主要支持 Linux。Windows 用户建议：

  1. 使用 WSL2（Windows Subsystem for Linux）
  2. 使用 Docker Desktop

WSL2 安装步骤：

# 在 PowerShell 中启用 WSL
wsl --install

# 安装 Ubuntu
wsl --install -d Ubuntu-22.04

# 进入 WSL
wsl

# 后续安装步骤与 Linux 相同

验证环境​

创建一个测试脚本来验证环境是否配置正确：

# test_env.py
from vllm import LLM, SamplingParams

# 测试模型加载（使用小模型）
print("正在加载模型...")
llm = LLM(model="facebook/opt-125m")

# 测试推理
prompts = [
    "你好，",
    "今天天气",
]
sampling_params = SamplingParams(temperature=0.8, top_p=0.95, max_tokens=50)

print("正在生成...")
outputs = llm.generate(prompts, sampling_params)

for output in outputs:
    prompt = output.prompt
    generated_text = output.outputs[0].text
    print(f"Prompt: {prompt!r}, Generated: {generated_text!r}")

print("环境验证成功！")

运行测试：

python test_env.py

下一步​

环境配置完成后，你可以进入快速开始章节，学习如何使用 vLLM 进行模型推理。

参考资源​