{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}

Serving Llms Vllm

vLLM：高吞吐 LLM 服务、OpenAI API、量化。

Skill 元数据
来源可选 — 通过 hermes skills install official/mlops/serving-llms-vllm 安装
路径optional-skills/mlops/inference/serving-llms-vllm
版本1.0.1
作者Orchestra Research
许可证MIT
依赖项vllm, torch, transformers
平台linux, macos
标签vLLM, Inference Serving, PagedAttention, Continuous Batching, High Throughput, Production, OpenAI API, Quantization, Tensor Parallelism

参考：完整 SKILL.md

INFO

以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。

vLLM - 高性能 LLM 服务

何时使用

在部署生产级 LLM API、优化推理延迟/吞吐，或在 GPU 显存有限时服务模型时使用。支持 OpenAI 兼容端点、量化（GPTQ/AWQ/FP8）和张量并行。

快速开始

vLLM 通过 PagedAttention（基于块的 KV 缓存）和连续批处理（混合 prefill/decode 请求），比标准 transformers 吞吐高 24 倍。

安装：

pip install vllm

基本离线推理：

from vllm import LLM, SamplingParams

llm = LLM(model="meta-llama/Meta-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/Meta-Llama-3-8B-Instruct

# 用 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/Meta-Llama-3-8B-Instruct',
    messages=[{'role': 'user', 'content': 'Hello!'}]
).choices[0].message.content)
"

常用工作流

工作流 1：生产 API 部署

复制此清单并跟踪进度：

部署进度：
- [ ] 第 1 步：配置服务器设置
- [ ] 第 2 步：用有限流量测试
- [ ] 第 3 步：启用监控
- [ ] 第 4 步：部署到生产
- [ ] 第 5 步：验证性能指标

第 1 步：配置服务器设置

根据模型大小选择配置：

# 单 GPU 上的 7B-13B 模型
vllm serve meta-llama/Meta-Llama-3-8B-Instruct \
  --gpu-memory-utilization 0.9 \
  --max-model-len 8192 \
  --port 8000

# 用张量并行的 30B-70B 模型
vllm serve meta-llama/Meta-Llama-3-70B-Instruct \
  --tensor-parallel-size 4 \
  --gpu-memory-utilization 0.9 \
  --quantization awq \
  --port 8000

# 带缓存的生产环境（Prometheus 指标自动暴露在 API 端口的 /metrics）
vllm serve meta-llama/Meta-Llama-3-8B-Instruct \
  --gpu-memory-utilization 0.9 \
  --enable-prefix-caching \
  --port 8000 \
  --host 0.0.0.0

第 2 步：用有限流量测试

生产前跑负载测试：

# 安装压测工具
pip install locust

# 创建带示例请求的 test_load.py
# 运行：locust -f test_load.py --host http://localhost:8000

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

第 3 步：启用监控

vLLM 在 API 端口（默认 8000）的 /metrics 暴露 Prometheus 指标：

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

关键监控指标：

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

第 4 步：部署到生产

用 Docker 保证部署一致：

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

第 5 步：验证性能指标

检查部署是否达标：

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

工作流 2：离线批量推理

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

复制此清单：

批量处理：
- [ ] 第 1 步：准备输入数据
- [ ] 第 2 步：配置 LLM 引擎
- [ ] 第 3 步：运行批量推理
- [ ] 第 4 步：处理结果

第 1 步：准备输入数据

# 从文件加载提示
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/Meta-Llama-3-8B-Instruct",
    tensor_parallel_size=2,  # 用 2 张 GPU
    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 自动批处理请求以提升效率：

# 一次调用处理所有提示
outputs = llm.generate(prompts, sampling)

# vLLM 内部处理批处理
# 无需手动切分提示

第 4 步：处理结果

# 提取生成文本
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)
    })

# 保存到文件
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 显存。

量化设置：
- [ ] 第 1 步：选择量化方法
- [ ] 第 2 步：找或创建量化模型
- [ ] 第 3 步：带量化标志启动
- [ ] 第 4 步：验证精度

第 1 步：选择量化方法

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

第 2 步：找或创建量化模型

用 HuggingFace 上的预量化模型：

# 搜索 AWQ 模型
# 示例：TheBloke/Llama-2-70B-AWQ

第 3 步：带量化标志启动

# 使用预量化模型
vllm serve TheBloke/Llama-2-70B-AWQ \
  --quantization awq \
  --tensor-parallel-size 1 \
  --gpu-memory-utilization 0.95

# 结果：70B 模型约 40GB VRAM

第 4 步：验证精度

测试输出符合预期质量：

# 对比量化 vs 非量化回答
# 验证特定任务性能不变

与替代方案的取舍

以下情况用 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

对长提示，启用分块 prefill：

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  # 不是 3

启用投机解码以加快生成（配置以 JSON 传入；--speculative-model 已移除，改用 --speculative-config）：

vllm serve MODEL \
  --speculative-config '{"model": "DRAFT_MODEL", "num_speculative_tokens": 5, "method": "draft_model"}'

进阶话题

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

性能优化：PagedAttention 调优、连续批处理细节、基准结果见 references/optimization.md。

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

故障排查：详细错误信息、调试步骤、性能诊断见 references/troubleshooting.md。

硬件需求

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

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

资源