serving-llms-vllm

vLLM - 高性能 LLM 服务

快速开始

vLLM 通过 PagedAttention（基于块的 KV 缓存）和连续批处理（混合预填充/解码请求）实现了比标准 transformers 高 24 倍的吞吐量。

安装：

pip install vllm

基本离线推理：

from vllm import LLM, SamplingParams

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

outputs = llm.generate(["Explain quantum computing"], sampling)
print(outputs[0].outputs[0].text)

OpenAI 兼容服务：

vllm serve meta-llama/Llama-3-8B-Instruct

# Query with OpenAI SDK
python -c "
from openai import OpenAI
client = OpenAI(base_url='http://localhost:8000/v1', api_key='EMPTY')
print(client.chat.completions.create(
    model='meta-llama/Llama-3-8B-Instruct',
    messages=[{'role': 'user', 'content': 'Hello!'}]
).choices[0].message.content)
"

常见工作流

工作流 1：生产 API 部署

复制此清单并跟踪进度：

Deployment Progress:
- [ ] Step 1: Configure server settings
- [ ] Step 2: Test with limited traffic
- [ ] Step 3: Enable monitoring
- [ ] Step 4: Deploy to production
- [ ] Step 5: Verify performance metrics

步骤 1：配置服务设置

根据模型大小选择配置：

# For 7B-13B models on single GPU
vllm serve meta-llama/Llama-3-8B-Instruct \
  --gpu-memory-utilization 0.9 \
  --max-model-len 8192 \
  --port 8000

# For 30B-70B models with tensor parallelism
vllm serve meta-llama/Llama-2-70b-hf \
  --tensor-parallel-size 4 \
  --gpu-memory-utilization 0.9 \
  --quantization awq \
  --port 8000

# For production with caching and metrics
vllm serve meta-llama/Llama-3-8B-Instruct \
  --gpu-memory-utilization 0.9 \
  --enable-prefix-caching \
  --enable-metrics \
  --metrics-port 9090 \
  --port 8000 \
  --host 0.0.0.0

步骤 2：使用有限流量进行测试

在生产前运行负载测试：

# Install load testing tool
pip install locust

# Create test_load.py with sample requests
# Run: locust -f test_load.py --host http://localhost:8000

验证 TTFT（首 token 时间）< 500ms 且吞吐量 > 100 req/sec。

步骤 3：启用监控

vLLM 在端口 9090 上暴露 Prometheus 指标：

curl http://localhost:9090/metrics | grep vllm

需要监控的关键指标：

• vllm:time_to_first_token_seconds - 延迟
• vllm:num_requests_running - 活跃请求
• vllm:gpu_cache_usage_perc - KV 缓存利用率

步骤 4：部署到生产环境

使用 Docker 进行一致的部署：

# Run vLLM in Docker
docker run --gpus all -p 8000:8000 \
  vllm/vllm-openai:latest \
  --model meta-llama/Llama-3-8B-Instruct \
  --gpu-memory-utilization 0.9 \
  --enable-prefix-caching

步骤 5：验证性能指标

检查部署是否达到目标：

• TTFT < 500ms（对于短提示词）
• 吞吐量 > 目标 req/sec
• GPU 利用率 > 80%
• 日志中无 OOM 错误

工作流 2：离线批量推理

用于处理大型数据集，无需服务开销。

复制此清单：

Batch Processing:
- [ ] Step 1: Prepare input data
- [ ] Step 2: Configure LLM engine
- [ ] Step 3: Run batch inference
- [ ] Step 4: Process results

步骤 1：准备输入数据

# Load prompts from file
prompts = []
with open("prompts.txt") as f:
    prompts = [line.strip() for line in f]

print(f"Loaded {len(prompts)} prompts")

步骤 2：配置 LLM 引擎

from vllm import LLM, SamplingParams

llm = LLM(
    model="meta-llama/Llama-3-8B-Instruct",
    tensor_parallel_size=2,  # Use 2 GPUs
    gpu_memory_utilization=0.9,
    max_model_len=4096
)

sampling = SamplingParams(
    temperature=0.7,
    top_p=0.95,
    max_tokens=512,
    stop=["</s>", "\n\n"]
)

步骤 3：运行批量推理

vLLM 自动批处理请求以提高效率：

# Process all prompts in one call
outputs = llm.generate(prompts, sampling)

# vLLM handles batching internally
# No need to manually chunk prompts

步骤 4：处理结果

# Extract generated text
results = []
for output in outputs:
    prompt = output.prompt
    generated = output.outputs[0].text
    results.append({
        "prompt": prompt,
        "generated": generated,
        "tokens": len(output.outputs[0].token_ids)
    })

# Save to file
import json
with open("results.jsonl", "w") as f:
    for result in results:
        f.write(json.dumps(result) + "\n")

print(f"Processed {len(results)} prompts")

工作流 3：量化模型服务

在有限的 GPU 内存中运行大型模型。

Quantization Setup:
- [ ] Step 1: Choose quantization method
- [ ] Step 2: Find or create quantized model
- [ ] Step 3: Launch with quantization flag
- [ ] Step 4: Verify accuracy

步骤 1：选择量化方法

• AWQ：最适合 70B 模型，精度损失最小
• GPTQ：广泛支持模型，压缩效果好
• FP8：在 H100 GPU 上最快

步骤 2：查找或创建量化模型

使用 HuggingFace 上预量化的模型：

# Search for AWQ models
# Example: TheBloke/Llama-2-70B-AWQ

步骤 3：使用量化标志启动

# Using pre-quantized model
vllm serve TheBloke/Llama-2-70B-AWQ \
  --quantization awq \
  --tensor-parallel-size 1 \
  --gpu-memory-utilization 0.95

# Results: 70B model in ~40GB VRAM

步骤 4：验证精度

测试输出是否符合预期质量：

# Compare quantized vs non-quantized responses
# Verify task-specific performance unchanged

何时使用及替代方案

在以下情况使用 vLLM：

• 部署生产 LLM API（100+ req/sec）
• 提供 OpenAI 兼容端点
• GPU 内存有限但需要大型模型
• 多用户应用（聊天机器人、助手）
• 需要低延迟和高吞吐量

在以下情况使用替代方案：

• llama.cpp：CPU/边缘推理，单用户
• HuggingFace transformers：研究、原型设计、一次性生成
• TensorRT-LLM：仅限 NVIDIA，需要绝对最大性能
• Text-Generation-Inference：已在 HuggingFace 生态系统中

常见问题

问题：模型加载期间内存不足

减少内存使用：

vllm serve MODEL \
  --gpu-memory-utilization 0.7 \
  --max-model-len 4096

或使用量化：

vllm serve MODEL --quantization awq

问题：首 token 缓慢（TTFT > 1 秒）

为重复的提示词启用前缀缓存：

vllm serve MODEL --enable-prefix-caching

对于长提示词，启用分块预填充：

vllm serve MODEL --enable-chunked-prefill

问题：模型未找到错误

对于自定义模型使用 --trust-remote-code：

vllm serve MODEL --trust-remote-code

问题：吞吐量低（<50 req/sec）

增加并发序列数：

vllm serve MODEL --max-num-seqs 512

使用 nvidia-smi 检查 GPU 利用率 - 应 >80%。

问题：推理比预期慢

验证张量并行使用 2 的幂次方数量的 GPU：

vllm serve MODEL --tensor-parallel-size 4  # Not 3

启用推测解码以加快生成：

vllm serve MODEL --speculative-model DRAFT_MODEL

高级主题

服务部署模式：参见 references/server-deployment.md 了解 Docker、Kubernetes 和负载均衡配置。

性能优化：参见 references/optimization.md 了解 PagedAttention 调优、连续批处理详情和基准测试结果。

量化指南：参见 references/quantization.md 了解 AWQ/GPTQ/FP8 设置、模型准备和精度比较。

故障排除：参见 references/troubleshooting.md 了解详细错误消息、调试步骤和性能诊断。

硬件要求

• 小型模型（7B-13B）：1 张 A10（24GB）或 A100（40GB）
• 中型模型（30B-40B）：2 张 A100（40GB），使用张量并行
• 大型模型（70B+）：4 张 A100（40GB）或 2 张 A100（80GB），使用 AWQ/GPTQ

支持的平台：NVIDIA（主要）、AMD ROCm、Intel GPU、TPU

资源

• 官方文档：https://docs.vllm.ai
• GitHub：https://github.com/vllm-project/vllm
• 论文：《使用 PagedAttention 高效管理大语言模型服务的内存》（SOSP 2023）
• 社区：https://discuss.vllm.ai

Agent 操作流程

1. 检查环境。 确认硬件、框架和服务版本、模型格式以及预期负载。
2. 明确输入。 从数据或用户处确认格式、标识符和参数。任何可能影响结果的值都应询问，而不是猜测。
3. 先运行小规模版本。 先提供或记录单个请求，或端到端运行一次，再扩大规模。
4. 使用以上说明和参考资料执行完整任务。
5. 验证结果。 对照参考值测量延迟、吞吐量和输出正确性；检查资源使用情况和成本。
6. 汇报。 说明运行了什么（版本、命令、参数）、检查了什么，以及还有哪些不确定之处。

如果发生这种情况	请这样做
服务无法启动或发生 OOM	检查模型大小与内存是否匹配，并检查量化和并行设置。
这些说明中的函数、标志或端点在已安装版本中不存在	查阅已安装版本自身的文档（help()、--help、官方文档），进行调整并告知用户。切勿编造 API。
必需的输入、标识符或参数含义不明确	询问用户，或在运行前明确说明所采用的假设。

诚信准则

• 切勿捏造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请如实说明。
• 不要公开服务或凭据；在配置资源前确认云成本。
• 此处与特定版本相关的细节可能已经过时：请对照已安装版本的官方文档进行确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，必须先征得同意。

相关技能

• tensorrt-llm：使用 NVIDIA TensorRT 优化 LLM 推理，实现最高吞吐量和最低延迟。
• awq-quantization：采用激活感知权重量化，将 LLM 压缩至 4 位，提速 3 倍且精度损失极小。
• gptq：通过 AutoGPTQ 和 transformers 使用 GPTQ 进行分组量化（默认分组大小为 128），将 LLM 量化至 4 位（也支持 3 位）。