7.2 核心参数详解：每个旋钮背后是哪个机制
7.2 核心参数详解：每个旋钮背后是哪个机制
本节摘要：vLLM 的启动参数数以百计，但决定生产形态的核心只有十来个。本节按机制归属逐个拆解：显存水位、上下文上限、并发上限、调度与交换、缓存与精度、量化并行——每个参数讲清默认值的由来、该动它的时机，以及它与前六章哪个机制对应。读完本节，调参从背配置变成讲道理。
把 vLLM 的参数文档从头读到尾是低效的——绝大多数参数是边缘场景的微调，真正决定服务形态的核心旋钮，恰好与前六章的机制一一对应。本节按"机制归属"组织参数清单：你在调的不是一行配置，而是第 2 章的显存账、第 3 章的块池、第 4 章的调度器。
显存水位：gpu_memory_utilization 为什么默认 0.9
这是被问得最多的参数：引擎启动时按"总显存 × 0.9"预占自己的用池（权重、KV Cache 块池、激活都从这里出），留下一成余量。默认值的逻辑有三层：
- 块表设计需要稳定的大池：第 3 章的物理块在启动时一次性切好，运行中不再向 CUDA 动态申请——碎片化管理的前提是池子先固定下来。
- 一成余量是安全垫：CUDA 上下文、通信缓冲、监控探针等都要在引擎池外占一些显存；不留余量的服务，起得来、死得快。
- 预留不等于浪费：池内没用到的块池空间会被前缀缓存（第 5 章）自动利用，"预占 0.9"与第 2 章批评的"预留浪费"是两回事——前者是池子固定，后者是块内空转。
该动它的时机：与其他进程共享一张卡时下调（0.5 到 0.7，给邻居留空间）；独占卡且监控确认无外部占用时，一般不必动。上调到 0.95 换取更大块池是激进打法，先确认卡上真的没有别的租户。
上下文上限：max-model-len 是预留峰值的总闸
第 2 章讲过预留浪费的根源是"按最长序列预留"——max-model-len 就是这个"最长序列"的用户侧总闸。它钳制单条请求允许的最大 token 数（输入加输出），块池按它做最坏情况的可行性检查。
显存联动公式（回顾）： 单请求 KV 峰值 = 2 × 层数 × KV 头数 × head_dim × 字节数 × max-model-len max-model-len 从模型默认（比如 32K）降到 8K： 单请求峰值缓存降为四分之一 → 同样块池能容纳四倍并发， 或同等并发下缓存可以降到 FP8 之外再留出更多余量。
该动它的时机：业务的最大输入加输出明确小于模型上限时（比如客服对话最多四千 token），果断下调——这是花一分钟就能拿到的最大并发增益。反过来，盲目设满模型上限是新手最常见的翻车姿势：上限设得越大，长请求的峰值显存越凶，洪峰时越容易触发第 4.2 节的抢占风暴。
并发与调度：max-num-seqs、swap-space 与 prefill 配额
max-num-seqs 限制同时运行的序列数（默认值较大，常见部署会显式收敛）。它与第 4 章调度器的联动是：这个数字 × max-model-len 对应的峰值缓存，必须小于块池容量，否则洪峰必抢占。健康的配置让常态并发贴着它跑、洪峰偶发抢占；常态就抢占说明容量不足，调参救不了。
swap-space 是第 4.2 节"交换"路线的每卡主存配额（GB）。被抢占请求的 KV Cache 换出到这里；主存充裕、抢占频繁的负载适当调大，让"换出"替代"重算"。
max-num-batched-tokens 控制单个迭代里 prefill 能吞多少 token（大输入会被切成多次迭代分摊）。它决定 prefill 与 decode 混批时的相互干扰程度：调小让对话请求的 TBT 更平稳，调大让长输入的 TTFT 更好——按你更在乎哪个指标来定。
缓存与精度：prefix caching 与 kv-cache-dtype
--enable-prefix-caching 打开第 5 章的前缀缓存（新版本默认开启）；--kv-cache-dtype fp8 把块池的缓存精度降到 8 位（第 6 章），长上下文场景的独立收益点。两者可以叠加：缓存共享的是块，精度决定每块的字节数，互不冲突。默认值之外唯一要记的纪律是：改精度必须跑回归评测（第 6.2 节的四步验证），精度旋钮不接受"感觉没问题"。
量化与并行：第 6 章的三行投影
--quantization awq / gptq / fp8、--tensor-parallel-size、--pipeline-parallel-size 分别是量化路线与两种并行的开关，机制细节已在第 6 章展开。组合时的检查顺序固定为：先量化（能不能装进更少卡）→ 再单机 tp（吃满 NVLink）→ 最后跨机 pp（网络扛得住吗）。
一张速查表：参数、机制与调参时机
| 参数 | 背后的机制 | 默认口径 | 什么时候动它 |
|---|---|---|---|
| gpu-memory-utilization | 第 3 章块池预占 | 0.9 | 共享卡下调；独占卡一般不动 |
| max-model-len | 第 2 章预留峰值 | 模型上限 | 业务长度明确时果断下调 |
| max-num-seqs | 第 4 章批容量 | 较大 | 与块池对账后显式收敛 |
| swap-space | 第 4.2 节交换路线 | 数 GB | 主存充裕且抢占频繁时调大 |
| max-num-batched-tokens | prefill 分摊 | 按硬件 | 平衡 TTFT 与 TBT 时微调 |
| enable-prefix-caching | 第 5 章前缀缓存 | 新版默认开 | 前缀各异的负载可关 |
| kv-cache-dtype | 第 6 章缓存精度 | 模型精度 | 长上下文省显存，需回归验证 |
| quantization | 第 6 章权重量化 | 无 | 单卡装不下或想提速时 |
| tensor-parallel-size | 第 6 章层内并行 | 1 | 单卡装不下时，吃满单机 |
| pipeline-parallel-size | 第 6 章层间并行 | 1 | 跨机扩展时 |
一份可以直接抄的起步配置
把本节参数组装成一条常见生产配置（8B 模型、单卡 80 GB、对话业务）：
vllm serve 模型名称 \ --max-model-len 8192 \ --gpu-memory-utilization 0.9 \ --max-num-seqs 128 \ --enable-prefix-caching \ --port 8000
这份配置的每行都能说出为什么：上下文钳到业务上限换并发、水位保持默认、并发与块池对过账、缓存默认开启。你的业务如果是长上下文，把第一行放大并同时把并发调小；如果是 70B 模型，先加量化与并行参数——变化的是参数，不变的是"从机制倒推配置"的方法。
💡 调参的检验标准永远在第 8 章：任何参数改动都要过同一套压测口径（吞吐、TTFT、TBT 的分位数），改前改后各跑一轮。没有前后对比的调参，等于没有调过。
本节要点回顾
- 参数是机制的投影：显存水位对应块池预占，上下文上限对应预留峰值，并发上限对应调度容量，量化并行对应第 6 章。
- gpu_memory_utilization 默认 0.9 的三层逻辑：池子固定、安全垫、缓存自动消化余量。
- max-model-len 是性价比最高的旋钮：按业务真实长度下调，一分钟换数倍并发。
- 并发上限必须与块池对账，常态抢占说明容量不足，不是调参能救的。
- 任何调参过压测口径：改前改后的吞吐与分位延迟对比是唯一验收标准。
部署与参数都就位了。最后一章建立闭环：压测怎么说数、监控看什么、调优按什么顺序下手。