vLLM 是一个高性能、高吞吐量的大语言模型（LLM）推理和服务引擎

vLLM 是一个高性能、高吞吐量的大语言模型（LLM）推理和服务引擎，支持多种硬件平台和模型架构。

本教程将覆盖从基础安装、模型加载到生产环境部署的多种方式。

📥 第一步：环境准备与安装

在部署之前，请确保你的系统满足要求并安装了必要的依赖。

基本要求：
- 操作系统：Linux（推荐）。vLLM 也支持通过插件在 AMD GPU、Intel GPU、Google TPU、Apple Silicon 等硬件上运行。
- Python 版本：3.10 — 3.13。
- GPU：对于 NVIDIA GPU，需要 CUDA 11.8 或 12.1+ 和对应的 NVIDIA 驱动。推荐使用显存至少 16GB（如 T4）的 GPU，24GB（如 RTX 3090/4090）可流畅运行 7B-13B 模型。

安装 vLLM：

使用 uv（推荐）：uv 是一个快速的 Python 包管理器，可以自动选择适配的 PyTorch 版本。

# 安装 uv 后，创建环境并安装 vLLM
uv venv --python 3.12
source .venv/bin/activate
uv pip install vllm --torch-backend=auto

使用 pip：
1
pip install vllm

安装特定版本或每日构建版：

1 2	# 安装最新的 nightly 构建版 pip install vllm --pre --extra-index-url https://wheels.vllm.ai/nightly

🚀 第二步：离线批量推理

安装完成后，你可以直接使用 vLLM 的 Python API 进行离线批量推理。

from vllm import LLM, SamplingParams

# 定义提示词列表和采样参数
prompts = [
    "Hello, my name is",
    "The capital of France is",
]
sampling_params = SamplingParams(temperature=0.8, top_p=0.95)

# 初始化模型（会自动从 Hugging Face 下载）
# 也可以指定本地路径，如 model="/path/to/your/model"
llm = LLM(model="facebook/opt-125m")

# 生成输出
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 text: {generated_text!r}")

🌐 第三步：部署 OpenAI 兼容的 API 服务

vLLM 可以启动一个与 OpenAI API 完全兼容的服务器，方便现有应用无缝接入。

启动服务：

# 启动服务，加载模型并监听端口
vllm serve Qwen/Qwen2-7B-Instruct \
    --host 0.0.0.0 \
    --port 8000 \
    --gpu-memory-utilization 0.9

--model：指定 Hugging Face 模型 ID 或本地路径。
--gpu-memory-utilization：设置 GPU 显存使用比例，建议 0.85-0.95。

测试 API：
服务启动后，可以用 curl 测试：

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2-7B-Instruct",
    "messages": [{"role": "user", "content": "你好！"}]
  }'

🐳 第四步：使用 Docker 部署（生产推荐）

Docker 方式能提供更好的环境隔离和依赖管理，是生产环境的推荐选项。

直接运行：

docker run --runtime nvidia --gpus all \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai:latest \
    --model meta-llama/Llama-2-7b-chat-hf

--gpus all：将宿主机所有 GPU 传递给容器。
vllm/vllm-openai:latest：官方 Docker 镜像，已包含 vLLM 和 CUDA 环境。

使用 Docker Compose（进阶）：
对于更复杂的生产场景，可以使用 Docker Compose 进行编排。创建一个 docker-compose.yml 文件：

version: '3.8'
services:
  vllm:
    image: vllm/vllm-openai:latest
    ports:
      - "8000:8000"
    volumes:
      - /data/models:/models  # 挂载本地模型目录
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    command: ["--model", "/models/your-model-path", "--gpu-memory-utilization", "0.9"]

然后运行 docker compose up -d 启动服务。

☸️ 第五步：Kubernetes 生产级部署

对于大规模集群，可以使用 vLLM Production Stack 在 Kubernetes 上部署，它集成了自动扩缩容、前缀缓存路由和监控等功能。

核心步骤：
- 准备一个支持 GPU 的 K8s 集群，并安装 NVIDIA/AMD GPU Device Plugin。
- 为模型存储创建 PersistentVolumeClaim (PVC)。
- 创建 Deployment 和 Service 来运行和暴露 vLLM 服务。
- 一键部署 Production Stack（推荐）：
  1
  2
  helm repo add llmstack-repo https://lmcache.github.io/helm/
  helm install llmstack llmstack-repo/vllm-stack
  这会安装一个包含路由、缓存、自动缩放和监控的完整推理栈。
注意事项：
- 确保 Deployment 的 failureThreshold 足够大，给大模型下载和加载留足时间，避免被 K8s 误杀。
- 对于生产环境，建议使用 gRPC 协议并配置 Kubernetes 原生 gRPC 探针。