vLLM 推理服务

vLLM 是由加州大学伯克利分校开发的高性能大语言模型推理和服务框架。它通过 PagedAttention 等创新技术显著提升了推理吞吐量，相比传统方案可获得数倍的性能提升。vLLM 原生提供兼容 OpenAI API 的 HTTP 服务，适合在生产环境中部署高并发的 AI 推理服务。

系统要求

CentOS Stream 9 & 10 / AlmaLinux 9.x & 10.x / Rocky Linux 9.x & 10.x
Python 3.10 - 3.14（EL 10 默认为 Python 3.12；以 vLLM 当前版本的 requires-python 为准）
NVIDIA GPU（支持的算力等级随 vLLM 版本变化：不要假定 V100/SM70 一定被默认轮子支持，装前查官方安装页的架构列表）
NVIDIA 驱动：按所选 vLLM 版本的 CUDA 变体反推——默认预编译包的 CUDA 版本会随版本切换（例如曾从 cu129 切到 cu130），驱动最低版本应查该变体对应的 CUDA 兼容表；Blackwell 显卡至少需要 CUDA 12.8。参考 NVIDIA 驱动与 CUDA
至少 16 GB GPU 显存（运行 7B 模型）

安装前准备

安装系统依赖

sudo dnf install -y python3.12 python3.12-devel python3.12-pip gcc gcc-c++ make

如果系统默认没有 Python 3.12（主要是 EL 9），可以从 CRB 仓库安装：

sudo dnf install -y epel-release
sudo dnf config-manager --set-enabled crb
sudo dnf install -y python3.12 python3.12-devel python3.12-pip

确认 GPU 环境

# 确认 NVIDIA 驱动工作正常
nvidia-smi

# 确认 CUDA 版本
nvcc --version

创建 Python 虚拟环境

强烈建议在虚拟环境中安装 vLLM，避免与系统 Python 包冲突：

# 创建项目目录
sudo mkdir -p /opt/vllm
sudo chown $(whoami):$(whoami) /opt/vllm

# 创建虚拟环境
python3.12 -m venv /opt/vllm/venv

# 激活虚拟环境
source /opt/vllm/venv/bin/activate

# 升级 pip
pip install --upgrade pip setuptools wheel

安装 vLLM

使用 pip 安装（推荐）

source /opt/vllm/venv/bin/activate
pip install vllm

安装过程会自动拉取 PyTorch、Triton 等依赖，可能需要几分钟。

验证安装

source /opt/vllm/venv/bin/activate
python -c "import vllm; print(vllm.__version__)"

下载模型

vLLM 使用 Hugging Face 格式的模型。你可以提前下载模型，也可以让 vLLM 在启动时自动下载。

source /opt/vllm/venv/bin/activate
pip install huggingface_hub[cli]

# 下载 Qwen2.5-7B-Instruct 到指定目录
hf download Qwen/Qwen2.5-7B-Instruct \
  --local-dir /opt/vllm/models/Qwen2.5-7B-Instruct

# 或下载 Meta-Llama-3.1-8B-Instruct（gated 模型，需先在 HF 上申请授权并登录）
hf download meta-llama/Meta-Llama-3.1-8B-Instruct \
  --local-dir /opt/vllm/models/Meta-Llama-3.1-8B-Instruct

像 Meta-Llama 这类 gated（受限）模型，除了在 Hugging Face 网页上申请到访问权限外，下载时还必须提供访问令牌，否则会报 401/403 错误。先在 hf.co/settings/tokens 创建一个 read token，然后任选一种方式：

# 方式一：交互式登录（令牌写入 ~/.cache/huggingface）
hf auth login

# 方式二：通过环境变量（适合脚本/服务）
export HF_TOKEN=hf_xxxxxxxxxxxxxxxx

vLLM 在启动时自动下载 gated 模型也依赖同样的令牌。

如果访问 Hugging Face 较慢，可以设置镜像：

export HF_ENDPOINT=https://hf-mirror.com
hf download Qwen/Qwen2.5-7B-Instruct \
  --local-dir /opt/vllm/models/Qwen2.5-7B-Instruct

运行 OpenAI 兼容 API 服务

vLLM 内置了兼容 OpenAI API 的 HTTP 服务器：

source /opt/vllm/venv/bin/activate

vllm serve /opt/vllm/models/Qwen2.5-7B-Instruct \
  --host 0.0.0.0 \
  --port 8000 \
  --served-model-name qwen2.5-7b

服务启动后，你可以使用标准的 OpenAI API 格式调用：

# 测试 Chat Completions 接口
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5-7b",
    "messages": [
      {"role": "system", "content": "你是一个有用的助手。"},
      {"role": "user", "content": "CentOS Stream 和 AlmaLinux 有什么区别？"}
    ],
    "temperature": 0.7,
    "max_tokens": 512
  }'

# 查看可用模型
curl http://localhost:8000/v1/models

# 测试 Completions 接口
curl http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5-7b",
    "prompt": "Linux 的优势在于",
    "max_tokens": 128
  }'

性能调优

关键启动参数

vllm serve /opt/vllm/models/Qwen2.5-7B-Instruct \
  --host 0.0.0.0 \
  --port 8000 \
  --served-model-name qwen2.5-7b \
  --tensor-parallel-size 2 \
  --gpu-memory-utilization 0.90 \
  --max-model-len 8192 \
  --max-num-seqs 64 \
  --enable-prefix-caching \
  --dtype auto

参数说明：

参数	说明
`--tensor-parallel-size`	张量并行数，设为 GPU 数量。多卡时使用
`--gpu-memory-utilization`	GPU 显存利用率，默认 0.9，最大不超过 0.95
`--max-model-len`	最大上下文长度，降低此值可减少显存占用
`--max-num-seqs`	最大并发序列数
`--enable-prefix-caching`	启用前缀缓存，对相似请求有显著加速
`--dtype`	数据类型，`auto` 会自动选择，也可指定 `float16` 或 `bfloat16`
`--quantization`	量化方式，支持 `awq`、`gptq` 等（SqueezeLLM 已被 vLLM 移除，旧教程里的 `squeezellm` 不再可用）

使用量化模型减少显存占用

# 使用 AWQ 量化模型
vllm serve Qwen/Qwen2.5-7B-Instruct-AWQ \
  --quantization awq \
  --host 0.0.0.0 \
  --port 8000

多 GPU 推理

# 使用 2 块 GPU 进行张量并行
vllm serve /opt/vllm/models/Qwen2.5-7B-Instruct \
  --tensor-parallel-size 2 \
  --host 0.0.0.0 \
  --port 8000

systemd 服务

创建 systemd 服务文件以实现开机自启和进程管理：

sudo tee /etc/systemd/system/vllm.service > /dev/null <<'EOF'
[Unit]
Description=vLLM OpenAI Compatible API Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=root
Group=root
WorkingDirectory=/opt/vllm
ExecStart=/opt/vllm/venv/bin/vllm serve /opt/vllm/models/Qwen2.5-7B-Instruct \
  --host 0.0.0.0 \
  --port 8000 \
  --served-model-name qwen2.5-7b \
  --gpu-memory-utilization 0.90 \
  --max-model-len 8192
Restart=on-failure
RestartSec=10
Environment="CUDA_VISIBLE_DEVICES=0"
Environment="HF_HOME=/opt/vllm/hf_cache"

# 资源限制
LimitNOFILE=65536
LimitNPROC=65536

[Install]
WantedBy=multi-user.target
EOF

启用并启动服务：

sudo systemctl daemon-reload
sudo systemctl enable --now vllm

管理服务：

# 查看状态
sudo systemctl status vllm

# 查看日志
sudo journalctl -u vllm -f

# 重启
sudo systemctl restart vllm

防火墙配置

sudo firewall-cmd --permanent --add-port=8000/tcp
sudo firewall-cmd --reload

使用 Python 客户端调用

由于 vLLM 兼容 OpenAI API，你可以直接使用 OpenAI 的 Python 客户端：

pip install openai

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed",  # vLLM 默认不需要 API key
)

response = client.chat.completions.create(
    model="qwen2.5-7b",
    messages=[
        {"role": "system", "content": "你是一个 Linux 专家。"},
        {"role": "user", "content": "如何在 AlmaLinux 9 上配置防火墙？"},
    ],
    temperature=0.7,
    max_tokens=1024,
)

print(response.choices[0].message.content)

常见问题

CUDA 内存不足

如果遇到 CUDA out of memory 错误：

# 减小最大上下文长度
vllm serve /opt/vllm/models/Qwen2.5-7B-Instruct --max-model-len 4096

# 或降低 GPU 显存利用率
vllm serve /opt/vllm/models/Qwen2.5-7B-Instruct --gpu-memory-utilization 0.80

# 或使用量化模型
vllm serve Qwen/Qwen2.5-7B-Instruct-AWQ --quantization awq

模型下载超时

设置 Hugging Face 镜像环境变量：

sudo systemctl edit vllm

[Service]
Environment="HF_ENDPOINT=https://hf-mirror.com"

查看 GPU 使用情况

在服务运行时监控 GPU：

watch -n 1 nvidia-smi