【从零走向AGI】旨在深入了解通用人工智能（AGI）的发展路径，从最基础的概念起，逐步构建完整的知识体系。

项目地址🔗：https://ai-mzq.github.io/From-Zero-to-AGI/^[1]

上一篇我们介绍了 vLLM V1 的核心架构，以及 API Server、EngineCore、Scheduler 和 GPU Worker 如何协作。这一次，我们转向参数配置，具体看看显存怎么分、请求怎样组批，以及缓存和调度会受到哪些参数影响。

本文聚焦于 vLLM v0.31.0 的显存、批处理、并行、缓存与调度参数。读完后，你会知道这些参数分别控制什么、设得不合适会出现什么现象，以及怎样用固定负载和运行指标验证调整是否有效。

往期推荐：

• 一文讲透 AI 算力平台 8 个核心概念：GPU、显存、NVLink、InfiniBand、调度、存储、容器、监控
• 一文详解大模型 12 个核心机制：Token、Embedding、Attention、Transformer、MoE、预训练、后训练、对齐、RAG、工具调用、推理、评测
• 一文讲透大模型推理服务 8 个核心指标：TTFT、TPOT、ITL、端到端延迟、吞吐、并发、请求率与 Goodput

• 一文讲透 vLLM 核心架构：API Server、EngineCore、Scheduler、GPU Worker 如何协作

vLLM 参数控制的不只是某一个性能数字，它们共同划定了模型权重、KV Cache、每轮计算规模和多卡通信的资源边界。同一个参数调大以后，吞吐可能上升，TTFT、TPOT、显存余量和运行稳定性也可能随之变化。

版本说明：本文基于 vLLM v0.31.0，以 vllm serve 启动的 V1 在线文本生成服务为主。vLLM 迭代较快，其他版本的参数名称、默认值和行为可能不同，应以对应版本的官方文档和源码为准。

假设我们为了让一项 vLLM 服务“多吃显存、多跑并发”，写下这样一条启动命令：

vllm serve <model> \
  --gpu-memory-utilization <value> \
  --max-model-len <value> \
  --max-num-batched-tokens <value> \
  --max-num-seqs <value> \
  --tensor-parallel-size <value>

直觉上，这几个值调大以后，服务应该能够装下更长的上下文、同时处理更多请求，并用更多 GPU 得到更高吞吐。

然而，实际结果可能并不是这样：模型能够加载，却在 warm-up 或首轮执行时 OOM；GPU 显存几乎占满，KV Cache 仍然不够；吞吐有所提高，首 token 却来得更慢；四张 GPU 都在工作，单请求延迟反而高于单卡。

问题在于，这几个值会互相影响。

gpu-memory-utilization 影响当前实例的显存预算，max-model-len 改变单条请求可能占用的 KV Cache，max-num-batched-tokens 和 max-num-seqs 共同限制每轮计算规模，TP、PP、DP 则决定模型怎样分布以及 GPU 之间怎样通信。

一个值发生变化，容量、延迟、吞吐和运行风险将可能会跟着一起变。

图 1：一条在线请求从 API Server 进入 EngineCore 和 Scheduler，再由 Executor 分发到 GPU Worker；显存、批处理、并行、缓存和调度参数分别作用于不同环节。

01 核心参数地图：五组参数分别控制什么

在 vLLM 的请求链上，参数是在为各组件设置资源边界和执行规则。

我们来看下上面表格中的五组参数，其实在共同回答四个问题：模型和缓存是否能装下，一轮允许处理多少工作，多张 GPU 怎样协作，以及请求以什么顺序获得有限资源。

其中，批处理还涉及三个容易混淆的层次：

一百个 HTTP 请求同时连接，不等于某一轮就有一百条 sequence 一起执行；max-num-seqs=128 也不表示接口最多只能维持 128 个连接。

02 显存参数：权重、执行空间和 KV Cache 要同时放得下

很多 vLLM 配置从 gpu-memory-utilization 开始，但这个名字很容易让人误解。

gpu-memory-utilization 控制的是当前实例的设备显存预算，不是 GPU 计算利用率。

按照 vLLM v0.31.0 的 CacheConfig^[2]，该参数的默认值为 0.92。它描述 vLLM 实例可以使用多大比例的设备内存，并不表示 GPU 有多少时间在执行计算。

一张 GPU 的显存大致由这些部分共同占用：

GPU 显存
├── 模型权重
├── KV Cache
├── 激活值与临时张量
├── CUDA Graph / 通信缓冲区
└── 运行时安全余量

vLLM 会先加载模型权重，通过 profiling 估算模型执行的峰值占用，再根据剩余空间建立 KV Cache。即使一张卡有 80 GB 显存，把参数设为 0.9，也不能简单理解为 KV Cache 固定获得 72 GB。

调高该参数，通常能把更多显存留给当前实例，KV Cache 容量可能随之增加。但运行时余量也会缩小。如果 profiling 没有覆盖真实负载中的峰值，或者同一张卡还有其他进程，服务可能在启动后才出现 OOM。

调低它能给其他进程和异常峰值留出空间，代价是 KV Cache 可能更早成为并发和长上下文的限制。

因此，0.92 是 v0.31.0 的版本默认值，不是所有模型和 GPU 的推荐答案。

kv-cache-memory-bytes 直接指定每张 GPU 的 KV Cache 大小。

在 v0.31.0 中，显式设置该参数后，KV Cache 大小不再由 gpu-memory-utilization 自动推导。两者的层次不同：前者直接设置缓存预算，后者给当前实例设置整体设备显存预算。

显式指定缓存大小也不会取消物理显存约束。模型权重、执行空间、KV Cache 和运行时开销加起来超过设备容量，仍然会 OOM。

max-model-len 同时定义能力上限和资源上限。

它限制 prompt 与生成结果合计的最大长度。未显式设置时，vLLM 可以从模型配置推导；auto 或 -1 可根据可用显存选择能够容纳的长度，具体行为以 vllm serve v0.31.0 文档^[3]为准。

KV Cache 会随着已处理 token 数增长。一条接近 128K 的请求，可能长时间占用大量缓存，留给其他请求的空间随之减少。模型声明支持 128K，并不意味着线上服务必须默认开放 128K。

KV Cache 每个 token 的占用可以用一个简化公式建立直觉：

KV bytes/token ≈ 2 × 层数 × KV heads × head dimension × 每元素字节数

其中的 2 对应 Key 和 Value。实际占用还受 TP 分片、GQA/MQA、混合注意力、block 对齐和实现方式影响，最终容量仍要看启动阶段的 profile 结果。

dtype 和权重量化主要改变模型权重占用，kv-cache-dtype 改变的则是缓存表示。cpu-offload-gb 也面向模型权重，通过主机内存换取模型可加载性，但每轮前向可能产生 CPU 与 GPU 之间的数据访问。它能减轻显存压力，却可能把瓶颈转移到 PCIe、CPU 内存带宽和 NUMA。

排查显存问题时，顺序应当是：

图 2：单张 GPU 的显存需要同时容纳模型权重、KV Cache、激活与临时张量、CUDA Graph、通信缓冲区和运行时安全余量。

03 批处理参数：token budget 与 sequence 上限

传统推理框架常用一个 batch size 表示一批样本的数量。LLM 在线服务很难只靠一个数字描述 batch，因为 Prefill 和 Decode 的形态差别很大。

一条 8K Prompt 正在做 Prefill 时，本轮可能处理数千个 token，却只有一条 sequence。另一边，一百多条请求都进入 Decode 后，每条请求本轮可能只推进一个 token，sequence 很多，token 总量却不一定大。

这就是 vLLM 同时需要 max-num-batched-tokens 和 max-num-seqs 的原因。

max-num-batched-tokens 限制一次迭代最多处理多少 token。

根据 SchedulerConfig^[4]，它是一轮执行的 token budget，不是单条请求允许的最大长度。这份预算里既可能有 Decode token，也可能有 chunked prefill 拆出来的一段 Prompt token。

本轮 token budget = 2048（仅作示意）

请求 A：Decode，推进 1 token
请求 B：Decode，推进 1 token
请求 C：Prefill，处理 2046 token

增大 token budget，通常能让一轮容纳更多工作，长 Prompt 的 Prefill 也可能更快完成。代价是单轮执行时间可能变长，正在流式输出的 Decode 请求要等待更久，TPOT 或 ITL 可能上升。

减小它可以缩短每轮粒度，让不同请求更频繁地得到调度。但预算过小会把长 Prompt 拆成更多轮，增加调度和 kernel 启动开销，GPU 也可能吃不满。

max-num-seqs 限制一次迭代最多处理多少条 sequence。

在 Decode 为主的负载中，每条请求本轮通常只推进少量 token。这时即使 token budget 还有余量，但 sequence 数可能已达到上限。

例如，一轮允许处理 4096 个 token，但 max-num-seqs 只有 64。当 64 条请求都处于 Decode，每条推进 1 个 token 时，实际只使用约 64 个 token 的预算，剩余预算不能自动变成第 65 条 sequence 的执行资格。

可以把单轮 batch 画在一个二维坐标上：横轴是 sequence 数，纵轴是本轮 token 数。

max-num-seqs 给横轴设置边界，max-num-batched-tokens 给纵轴设置边界。Scheduler 只有同时满足两类约束，才能把请求放入这一轮。

图 3：max-num-seqs 限制单轮 sequence 数，max-num-batched-tokens 限制单轮 token 总量，两者共同划定一次迭代能够处理的工作范围。

低并发时 GPU 吃不满，先确认有没有足够的请求供给。高并发、短输出时吞吐受限，sequence 上限可能先成为瓶颈；长 Prompt 多、ITL 抖动明显，则更应该检查 token budget 和 chunked prefill。

参数调大后 preemption 增加，往往意味着更多请求进入运行态，但 KV Cache 无法支撑它们持续执行。

04 并行参数：TP、PP、DP

一张 GPU 装不下模型，或者单个模型副本无法支撑请求量时，就要考虑多卡部署。但 TP、PP、DP 分别改变权重放置、执行方式和服务副本数量，不能当作三个可以互换的数字。

TP：让多张 GPU 一起执行一个模型副本。

Tensor Parallel 把单层中的权重和计算切分到多张 GPU。每个 rank 只保存一部分权重，多张卡通过 collective communication 合作完成同一层的计算。

TP 最直接的作用，是降低单张 GPU 需要承载的权重，使单卡放不下的模型能够运行。代价是通信进入每轮模型执行的关键路径，一个慢 rank 会拖住整组。

低并发、小 batch 或互联较弱时，新增 GPU 带来的计算收益可能抵不过 collective 开销。因此，tensor-parallel-size=4 表示四张 GPU 共同服务一份模型，并不是得到四份可以独立处理请求的模型。

PP：把不同模型层分到多个流水线阶段。

Pipeline Parallel 让前面的 GPU 负责较早的网络层，后面的 GPU 负责后续层，激活值在阶段之间传递。

PP 同样能够分摊模型权重，但在线自回归生成还会受到 microbatch 数量、阶段平衡和流水线气泡影响。它适合模型跨更多设备放置，不等于无条件降低单请求延迟。

DP：复制模型副本，让不同请求分开执行。

Data Parallel 建立多套 EngineCore 和 Worker 组，每个副本拥有自己的权重和 KV Cache，不同请求被分配到不同副本。

如果单个副本的延迟已经达标，只是总请求容量不足，DP 或多个独立实例通常更接近问题本身。代价是每个副本都要重新存放权重，并维护自己的缓存。

长短请求差异很大时，负载均衡也不能只看请求数量。一个副本可能正在处理少量超长 Prompt，另一个副本虽然请求更多，实际工作量却更小。

选择并行方式，先看单卡能否装下权重和目标 KV Cache，再看节点内互联、模型是否需要跨更多设备，以及单副本的延迟是否已经达标。关键是先分清当前缺的是模型容量，还是请求容量。

具体部署方式可参考 vLLM Parallelism and Scaling^[5]。MoE 模型的 Expert Parallel 涉及专家分布和 all-to-all，应单独评估，不直接套用 Dense 模型的结论。

图 4：同样使用 8 张 GPU，TP、PP 和 DP 的组合不同，模型副本数、权重切分方式和通信位置也会随之改变。

05 缓存参数：容量、精度、复用和 offload

“缓存优化”听起来都在节省显存，但几类参数改变的是不同环节。

kv-cache-dtype 用更低精度换取更多 KV token 容量。

auto 会按照模型与平台能力选择缓存类型。在受支持的硬件和后端上，FP8 等低精度 KV Cache 可以减少每个 token 的缓存占用，使同样显存容纳更多上下文或活动请求。

缓存更小不代表服务一定更快。量化与反量化可能引入额外计算，实际表现取决于 kernel 支持。KV 精度还会参与后续注意力计算，因此必须验证生成质量。

Quantized KV Cache^[6]列出了相应的硬件、格式和 scaling 配置。线上启用前至少要覆盖长文本、事实问答和真实业务样本，不能把“成功启动”当成质量验收。

Prefix caching 复用的是重复 token 前缀。

Automatic Prefix Caching 会复用不同请求之间相同前缀所对应的 KV block，省掉这部分 Prompt 的重复 Prefill 计算。

它更适合固定长 system prompt、多轮对话历史、共享长文档和模板稳定的 RAG 请求。如果每个请求在开头加入不同的用户信息、时间戳或随机 ID，即使后面的文档相同，可复用前缀也可能很短。

开启 enable-prefix-caching 后，需要把 prefix cache queries/hits 与 TTFT 一起看。命中率低，功能开启本身不会产生明显收益；命中率高，还要确认复用块是否长期占用 KV Cache，挤压当前活动请求。具体机制可参考 Automatic Prefix Caching^[7]。

block-size 决定分页粒度，但通常不是首轮调参项。

block 较小可能减少尾部内部浪费，却增加元数据和管理粒度；block 较大则相反。实际支持范围与性能还受平台和后端影响。除非正在复现缓存碎片、后端限制或开展源码实验，普通部署不必优先扫描该参数。

KV offloading 与权重 offloading 移动的数据不同。

kv-offloading-size 面向 KV Cache，将部分缓存块放到主机内存等更大但更慢的层级；cpu-offload-gb 面向模型权重。两者都可能增加 CPU 内存与传输压力，但移动的数据、触发时机和性能后果不同。

KV offload 是否合适，取决于缓存工作集、复用间隔和 CPU 与 GPU 之间的互联能力，具体路径可参考 KV Offloading Usage Guide^[8]。

版本变化也要单独核对。vLLM V1 已移除旧式 GPU↔CPU KV Cache swapping 路径，早期教程中的 swap-space 和 swapped requests 不能直接套到 v0.31.0 的默认机制上。

图 5：KV Cache 可以从容量预算、缓存精度、重复前缀复用和分层 offload 四个方向调整，但每种方式解决的问题并不相同。

06 调度参数：长 Prefill 与 Decode 怎样分享每轮预算

Prefill 和 Decode 会争用同一组 GPU。Prefill 一次处理一段 Prompt，单次计算量大；Decode 每轮只推进少量 token，却直接影响流式输出是否顺畅。

如果一个长 Prompt 一次占满整轮，正在 Decode 的请求就要等待。反过来，如果每轮只给长 Prompt 很少预算，它的首 token 又会迟迟到来。

enable-chunked-prefill 会把长 Prompt 拆成多个 chunk。

开启后，Scheduler 可以根据剩余的 max-num-batched-tokens，把长 Prefill 分到多次迭代，并与 Decode 请求穿插。

未分块：
第 1 轮  [长 Prefill ........................]
第 2 轮  [Decode A][Decode B][Decode C]

分块后：
第 1 轮  [Prefill chunk][Decode A][Decode B]
第 2 轮  [Prefill chunk][Decode A][Decode B][Decode C]
第 3 轮  [Prefill chunk][Decode A][Decode B][Decode C]

分块能减少长 Prefill 连续独占计算资源的机会，让 Decode 更平滑地推进。但 chunk 太小会增加迭代次数和调度开销；token budget 太大时，单个 Prefill chunk 仍可能让一次迭代变得很长。

Chunked prefill 要与 max-num-batched-tokens 一起看：前者决定长 Prompt 能否拆分，后者决定一轮总共能放多少工作。

long-prefill-token-threshold 用于识别需要限制的长 Prefill。

它应该根据真实 Prompt 长度分布和 TTFT/ITL 目标设置，不能照抄模型最大上下文。大部分请求很短、少量请求突然达到数万 token 时，阈值有助于限制长请求单轮占用的份额；如果请求普遍很长，过严限制又会让所有 Prefill 都需要更多轮。

scheduling-policy 决定谁先获得有限资源。

fcfs 按到达顺序处理。priority 允许请求优先级参与排序，适合交互式请求与离线任务共用资源的场景。

但参数不会替产品定义优先级规则。谁能提交高优先级、同级请求怎样排序、低优先级如何避免长期饥饿，都需要在服务层明确。系统持续超载时，调度策略只能改变等待顺序，无法增加总容量。

scheduler-reserve-full-isl、watermark 和 async-scheduling 用于进一步控制请求接纳、缓存水位和 CPU 调度空隙。只有确认问题出在这些环节后再调整，具体语义和兼容性以 SchedulerConfig^[4]为准。

图 6：chunked prefill 将长 Prompt 拆成多个计算片段，与 Decode 请求穿插执行，从而改变 TTFT、ITL 和单轮执行时间之间的取舍。

07 参数之间怎样互相影响

服务表现通常由几组参数共同决定。

显存预算 × 上下文上限 × 活动请求数

gpu-memory-utilization 影响设备内存预算，max-model-len 决定单条请求最坏情况下可能增长到多长，max-num-seqs 限制一轮希望同时推进多少条 sequence。

显存预算不变，却同时提高最大上下文和活动请求上限，KV Cache 可能更快接近上限。得到的未必是更高吞吐，也可能是更多 preemption、更长 TTFT 和更差的尾延迟。

Token budget × chunked prefill

max-num-batched-tokens 决定单轮总预算，chunked prefill 决定长 Prompt 怎样占用这份预算。预算增大可能提高 Prefill 吞吐，却让单轮变重；预算减小可以让 Decode 更频繁地获得机会，也会让长 Prompt 经过更多轮。

判断结果时，要把 Prefill TTFT、Decode TPOT、iteration tokens 与整体吞吐放在一起看。

TP × batch 规模 × GPU 互联

TP 增加参与一个模型副本计算的 GPU 数，也增加 collective 通信。batch 较大时，更多计算有机会摊薄通信和 kernel 启动成本；低并发、小 batch 时，通信占比会更突出。

同样是 TP=4，四张卡在同一节点通过 NVLink/NVSwitch 连接，和跨节点通信相比，结果可能相差很大。TP 数值脱离硬件拓扑没有可比性。

Prefix caching × 前缀重复率 × KV 容量

共享前缀越长、复用次数越多，省下的 Prefill 计算越可观。但复用块也占用缓存，而且只有在再次访问前仍然驻留，复用才会发生。

Prefix cache hit rate 不能单独代表收益，还要结合 TTFT、KV usage 和缓存块驻留情况判断。

图 7：显存、上下文、批处理、并行、缓存与调度参数会共同影响 TTFT、TPOT、吞吐、preemption 和 OOM 风险，不能脱离其他参数单独判断。

08 不同负载，调参重点也不同

调参顺序取决于请求形态。

短对话、高并发，模型单卡能够装下

先保持 TP=1 建立单卡基线，重点评估 max-num-seqs、max-num-batched-tokens 与 KV Cache 容量。观察 queue time、TPOT、iteration tokens、KV usage 和 preemption。

如果请求供给不足，GPU 利用率低并不是 batch 参数的问题。

长 Prompt 较多，TTFT 是主要目标

按产品真实需求设置 max-model-len，再观察长 Prefill 是否让 Decode 出现明显停顿。重点调整 chunked prefill、token budget 和 long prefill threshold。只有长前缀确实重复时，prefix caching 才是优先项。

RAG 或固定长 system prompt，前缀重复率高

先确认重复发生在实际 token 前缀上，再开启 prefix caching，并对比命中率和 TTFT。如果 KV usage 长期接近上限，还要确认被缓存的前缀是否挤压活动请求。

模型单卡装不下

先核算权重精度、目标上下文和 KV Cache，再根据 GPU 拓扑选择 TP。跨节点 TP 必须实测 NCCL 与尾延迟。TP 仍无法合理放置模型时，再评估 PP 或权重 offload。

单副本延迟达标，总请求容量不足

优先增加 DP 或独立实例副本，不必继续扩大单副本 TP。负载均衡应结合每个副本的 waiting queue、KV usage 和健康状态，避免长短请求造成工作量失衡。

09 一套可复现的调参流程

同时修改多个值，很难判断哪项改动真正起了作用。更稳妥的办法是固定测试条件，一次只改一个主要变量。

第一步：固定版本、模型和硬件。

记录 vLLM 版本或 commit、模型 revision、权重精度、GPU 型号与互联拓扑、TP/PP/DP 组合，以及 CPU、NUMA、主机内存和网络。

第二步：固定工作负载。

至少准备短输入短输出、短输入长输出、长输入短输出、长输入长输出四类请求。固定到达率、并发方式、共享前缀、采样参数和 warm-up 流程。

第三步：先让模型稳定装下。

确认权重精度、max-model-len、TP/PP 和显存余量，再检查启动日志中的 KV Cache 容量。在目标最长输入和持续并发下验证运行期 OOM 与 preemption，不要看到服务启动就开始追吞吐。

第四步：调整 token 与 sequence 预算。

一次只修改 max-num-batched-tokens 或 max-num-seqs。前者重点观察 TTFT、TPOT、单轮时间和吞吐，后者重点观察 running/waiting、KV usage、preemption 和 P95/P99。

第五步：按负载启用缓存和调度策略。

有稳定重复前缀再测试 prefix caching；有长 Prompt 干扰再调整 chunked prefill；确有业务等级再考虑 priority scheduling。每项功能都要用对应指标验证，不能只看启动参数是否生效。

第六步：最后扩展并行和副本数。

先得到单副本基线，再测试 TP/PP 的扩展效率。单副本延迟达标后，通过 DP 或实例副本扩大总容量。多卡实验还要记录各 rank 执行时间和通信开销。

调优至少要保留这些指标：

具体指标可查阅 vLLM Production Metrics^[9]，压测入口可参考 vllm bench^[10]。

达到目标 SLO 后，不必为了少量峰值吞吐继续压缩安全余量。平均吞吐提高，却让 P99、错误率、OOM 风险或成本明显恶化，也不能算作优化成功。

图 8：调优从固定版本、硬件和负载开始，先保证模型稳定运行，再依次验证二维 batch、缓存与调度策略，以及并行和副本扩展。

10 调参时最容易混淆的十个概念

这些判断都能在运行数据中找到证据。参数名只是入口，启动日志、Scheduler 状态、KV Cache 指标和固定负载下的延迟分布，才决定配置是否合适。

最后，参数要从负载开始设置

回到开头那条启动命令。

把几个值一起调大，并不会自动换来更高吞吐。

如果模型和目标上下文本身放不下，先处理权重、显存和并行方式。请求已经排队，但 KV Cache 和算力还有余量，再检查 token budget 与 sequence 上限。长 Prompt 让流式输出频繁停顿，就看 chunked prefill。只有实际请求中存在大量相同前缀，prefix caching 才可能发挥作用。

每个选择都有代价。增大 max-num-batched-tokens 可能提高离线吞吐，也可能让交互式服务的 ITL 变差。增加 TP 能让模型分布到更多 GPU，却会把跨卡通信带进每轮计算。显存预算调高后可以多放一些 KV block，留给运行时波动的空间也会减少。

服务顺利启动，只能证明这套参数暂时跑得起来。它是否合适，还要在同一批请求下比较 TTFT、TPOT、吞吐、Goodput 和 P99，并观察持续运行时有没有 preemption、OOM 或延迟抖动。

调参到最后，做的其实是两件事：先用真实负载找出限制服务的那一环，再只改对应参数。改完以后，用同一批请求重新测一遍。

欢迎关注【魔方AI空间】👇

AIGC技术交流社区（涵盖AI绘画、AI视频、大模型、AI多模态、数字人、具身智能等AIGC干货资源及教程）

► 从零走向 AGI 系列

► 技术专栏： 多模态大模型最新技术解读专栏 | AI 视频最新技术解读专栏 | 大模型基础入门系列专栏 | 视频内容理解技术专栏 |