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（计算能力 7.0 以上，即 V100/T4/A100/RTX 20 系列及更新）
NVIDIA 驱动：建议 R570 以上 + CUDA 12.8 以上（当前默认预编译包基于 CUDA 12.9；CUDA 13 需要 R580+ 驱动，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 到指定目录
huggingface-cli download Qwen/Qwen2.5-7B-Instruct \
  --local-dir /opt/vllm/models/Qwen2.5-7B-Instruct

# 或下载 Meta-Llama-3.1-8B-Instruct（gated 模型，需先在 HF 上申请授权并登录）
huggingface-cli 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）
huggingface-cli login

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

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

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

export HF_ENDPOINT=https://hf-mirror.com
huggingface-cli 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` 等

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

# 使用 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