模型部署与推理优化

vLLM 参数级配置与调优

kp-022核心30 分钟06-推理服务

一句话定义

vLLM 的部署质量由十余个参数共同决定，核心是三件事：把显存账（gpu-memory-utilization × 卡容量 = 权重 + KV 池）算对、把并发上限（max-num-seqs）与 TPOT SLO 对齐、把前缀缓存与量化等开关按负载画像打开。

为什么重要

同一模型同一硬件，默认参数与调优参数的吞吐差距常达 2–3 倍；而 OOM 与"吞吐上不去"两类事故几乎都能定位到 2–3 个参数。这是从"会启动引擎"到"能对生产负责"之间最实用的一课。

前置知识

核心概念：核心参数与启动示例

vllm serve Qwen/Qwen2.5-7B-Instruct-AWQ \
  --served-model-name qwen7b-awq \
  --gpu-memory-utilization 0.90 \
  --max-model-len 8192 \
  --max-num-seqs 64 \
  --tensor-parallel-size 1 \
  --enable-prefix-caching \
  --block-size 16 \
  --quantization awq_marlin
  • gpu-memory-utilization（默认 0.9）：给引擎的显存比例；扣掉权重后余量即 KV 池。KV 池 = util × 卡容量 − 权重 − 开销，这是排错时的第一算式（kp-004）。
  • max-model-len：单请求最大上下文；按业务真实需要设，不要默认放最大——KV 池被"最坏情况"挤占。
  • max-num-seqs：并发上限；与 KV 池、TPOT SLO 三者互相约束，不是越大越好。
  • tensor-parallel-size：张量并行卡数；多卡时权重与 KV 池按卡切分。
  • enable-prefix-caching：开启前缀块复用，多轮对话/共享 system prompt 必开。
  • enforce-eager（未写即默认 CUDA Graph）：图捕获省 launch 开销但占额外显存；显存极限时可打开换稳定。
  • --quantization：通常从模型 config 自动推断，显式写可避免误判。

原理与机制

vLLM 的参数之间是约束链而非独立旋钮：gpu-memory-utilization 决定 KV 池总量，max-model-len 决定单请求的最坏 KV 占用，两者相除给出理论并发上限；max-num-seqs 是在这个上限之内、由 TPOT SLO 截出的实际值。理解这条链后，调参顺序自然是从显存 → 并发 → SLO——倒过来调必然返工，因为下游参数的合法区间由上游决定。

实践步骤（可执行操作）

  1. 按 kp-004 账本算清：权重（AWQ 后 3.5–4.5GB）+ 目标 KV 池 + 约 10% 开销，反推 util 与 max-model-len。
  1. 压测定 max-num-seqs：从 32 起步，观察 P99 TPOT 触线（如 50ms）即停——这条线就是你的并发容量（kp-002 方法）。
  1. 打开 prefix caching，用真实多轮对话流量复测 TTFT 改善与 KV 命中率（vLLM /metrics 暴露 num_requests_*、cache 指标）。
  1. 长输入场景评估 chunked prefill（分块预填充，让长 prefill 与 decode 交错）以压 TTFT 长尾。
  1. 固化配置到部署清单，与压测数字一起归档（kp-009 的留痕纪律）。

实例或案例

一台 A100-80G 部署 AWQ 7B 的完整推演：util=0.90 → 约 72GB 归引擎，扣权重约 4GB 与开销后 KV 池约 65GB；max-model-len=8192 时单请求 KV 峰值约 1GB（GQA），理论并发上限约 60；压测发现并发 48 处 TPOT P99 越过 50ms 红线，最终 max-num-seqs=48。三个数字全部可由账本与压测复算——"配置可审计"就是本知识点要训练的能力。

排错清单（症状 → 核查 → 处置）

  • 启动即 OOM：重算 util×容量−权重 是否为负 → 降 util 或 max-model-len → 仍不够则 tensor-parallel-size+1。
  • 运行中抢占频繁/OOM：max-num-seqs 超 KV 池承载力 → 降并发或缩上下文（对照 kp-027）。
  • 吞吐不达预期：看 /metrics 的 running/waiting——waiting 长期高说明容量不足；running 低说明压测并发不够。
  • TTFT 长尾：多为长 prefill 阻塞 decode → 开 chunked prefill / 加大 max-num-batched-tokens。
  • 多卡后吞吐没线性涨：先查是否卡在 prefill 或调度，再看通信开销；TP 不是线性扩展，2 卡常见 1.6–1.8 倍。

常见误区

  • "util 拉满 0.98 更好"：不留余量会在显存碎片与 CUDA Graph 上翻车，0.90 是稳妥起点。
  • "max-num-seqs 默认 256 就该用满"：TPOT 与 KV 池会先爆，容量必须由 SLO 压测得出。
  • "prefix caching 万能"：前缀不重复的负载（如长尾独立文档）命中率趋零，白占管理开销——先看流量画像。

自测题

  1. 80GB 卡、AWQ 7B（权重约 4GB）、util=0.9，KV 池大约多少？

要点：72 − 4 − 约 5 开销 ≈ 60GB 量级（精确值以引擎日志为准）。

  1. 为什么 max-model-len 要按业务设而非越大越好？

要点：调度与 KV 预留按最坏情况计，过大挤占 KV 池、降低可接纳并发。

  1. running 高且 waiting 高，说明什么？

要点：容量不足，已饱和——加副本/降并发/缩上下文，而不是调 kernel。

与其他知识点的关系

参数语义全部落在 kp-004/kp-014/kp-021 上；压测方法来自 kp-002；跨副本后的路由与扩缩容见 kp-023；系统级排错见 kp-027。

延伸阅读

vLLM 官方文档的 "Optimizing vLLM" 与 metrics 页面（与本页参数一一对应，按需查阅最新参数名）。

#vLLM#配置#gpu-memory-utilization#max-num-seqs#调优#tensor-parallel