vllm 学习笔记

Appearance

API服务与部署 — 概念 ​

服务架构 ​

前端模式 ​

vLLM 现在支持三种前端模式：

模式实现触发条件适用场景
Python FastAPIAPIServerProcessManager默认通用场景
Rust FrontendRustFrontendProcessManagerVLLM_RUST_FRONTEND_PATH 环境变量高性能低延迟
DP Supervisordp_supervisor.py--data-parallel-multi-port-external-lb多 GPU 数据并行

OpenAI 兼容 API ​

Chat Completions ​

bash
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama/Llama-3-8B",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ],
    "temperature": 0.7,
    "max_tokens": 256,
    "stream": true
  }'

Text Completions ​

bash
curl http://localhost:8000/v1/completions \
  -d '{
    "model": "meta-llama/Llama-3-8B",
    "prompt": "Once upon a time",
    "max_tokens": 100
  }'

Embeddings ​

bash
curl http://localhost:8000/v1/embeddings \
  -d '{
    "model": "BAAI/bge-large-en",
    "input": "Hello world"
  }'

支持的参数 ​

参数说明默认值
temperature采样温度1.0
top_p核采样概率1.0
top_kTop-k 采样-1
max_tokens最大生成 token 数模型最大
stop停止 token 列表[]
stream是否流式输出false
n生成候选数1
presence_penalty存在惩罚0.0
frequency_penalty频率惩罚0.0
logprobs返回 logprobsfalse
response_format结构化输出格式null
guided_jsonJSON Schema 约束null

离线 LLM 类 ​

python
from vllm import LLM, SamplingParams

llm = LLM(model="meta-llama/Llama-3-8B")
params = SamplingParams(temperature=0.7, max_tokens=256)

# 单个推理
output = llm.generate("Hello, world!", params)

# 批量推理
outputs = llm.generate(["prompt1", "prompt2", "prompt3"], params)

for output in outputs:
    print(output.outputs[0].text)

Mixin 架构 ​

LLM 类从单一庞大类重构为 Mixin 组合架构：

LLM(BeamSearchOfflineMixin, PoolingOfflineMixin, OfflineInferenceMixin)
  • OfflineInferenceMixin (entrypoints/offline_utils.py): 核心推理逻辑 — 预处理、参数广播、引擎运行
  • BeamSearchOfflineMixin (entrypoints/generate/beam_search/offline.py): 离线 beam search
  • PoolingOfflineMixin: 池化操作（embeddings 等）

推测解码快捷参数 ​

python
# 之前：需要传递完整的 JSON 配置
llm = LLM(model="...", speculative_config='{"method":"ngram","num_speculative_tokens":5}')

# 现在：直接通过 CLI 参数设置
llm = LLM(model="...", spec_method="ngram", spec_tokens=5)

LLM 类参数 ​

参数说明
model模型名称或路径
tensor_parallel_size张量并行数
gpu_memory_utilizationGPU 显存利用率 (0-1)
max_model_len最大序列长度
quantization量化方法
dtype数据类型
trust_remote_code是否信任远程代码
spec_method推测解码方法
spec_model推测解码草稿模型
spec_tokens推测解码候选 token 数

中间件 ​

CORS ​

python
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"],
)

限流 ​

python
# 通过 --rate-limit-interval 和 --rate-limit-token 配置

健康检查 ​

GET /health    → 200 OK (引擎就绪)
GET /ready     → 200 OK (服务就绪)
GET /v1/models → 返回可用模型列表

性能调优 ​

关键配置参数 ​

参数影响建议值
--max-num-seqs最大并发请求数128-512
--max-num-batched-tokens每步最大 token 数8192-32768
--gpu-memory-utilizationGPU 显存利用率0.85-0.95
--block-sizeKV 缓存块大小16
--enable-prefix-caching启用前缀缓存建议开启
--enable-chunked-prefill启用分块 prefill建议开启

性能指标 ​

指标含义优化方向
TTFT首 token 延迟降低 prefill 时间
TPOT每 token 延迟减少 decode 开销
Throughput吞吐量 (tokens/s)增加批处理量
GPU UtilizationGPU 利用率平衡 prefill/decode

部署方式 ​

Docker ​

bash
docker run --gpus all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -p 8000:8000 \
  vllm/vllm-openai:latest \
  --model meta-llama/Llama-3-8B

多 GPU ​

bash
vllm serve meta-llama/Llama-3-70B \
  --tensor-parallel-size 4 \
  --gpu-memory-utilization 0.9

Rust Frontend（高性能） ​

bash
# 设置 Rust 前端路径
export VLLM_RUST_FRONTEND_PATH=/path/to/vllm-rs
vllm serve meta-llama/Llama-3-8B

Rust 前端与 Python API Server 共享相同的 ZMQ EngineCore 协议，通过 RustFrontendProcessManager 管理。它以子进程方式启动 vllm-rs 二进制文件，通过管道和 ZMQ 进行通信。

DP Supervisor（多端口数据并行） ​

bash
vllm serve meta-llama/Llama-3-8B \
  --data-parallel-size 4 \
  --data-parallel-multi-port-external-lb

DP Supervisor 是一个节点本地管理进程：

  • 为每个数据并行 rank 生成独立的 vLLM API Server（使用不同端口）
  • 提供聚合的健康检查端点（/health、/health/liveness、/health/readiness）
  • 自动为子进程设置 CUDA_VISIBLE_DEVICES
  • 支持可配置的探测间隔和失败阈值

相关概念 ​

反向链接

出链