vLLM 启动报最大模型长度超过 KV cache 容量

模型权重加载完成后，vLLM 在初始化缓存时退出，日志里出现：

The model's max seq len (131072) is larger than the maximum number of tokens that can be stored in KV cache (30880).

这里比较的是本次配置的最大序列长度与可分配的 GPU KV cache 容量。权重能放进显存，并不代表还剩下足够空间容纳这个长度的请求。下面按 vLLM 0.6.5 的 CUDA、普通 attention 模型路径说明；其他版本的日志、默认 prefill 策略和内存计算可能不同。

先读容量数字，不把模型文件大小当成运行预算

vLLM 的显存还要容纳权重以外的激活、运行时分配和 KV cache。0.6.5 会先做内存 profiling，从当前实例的显存预算中扣除非 KV 部分，再按缓存块大小计算容量。报错里的 30880 是那次启动得到的容量，不能当成这张卡永远支持的长度。

保留完整启动参数与日志，重点看模型 dtype、gpu_memory_utilization、激活峰值、缓存块数及 max_model_len。确认没有另一任务同时改变显存占用。记录中的模型名和量化格式也要一致，不能拿 AWQ 权重大小解释实际启动的 GPTQ 模型。

业务只需要短上下文时，限制实际服务长度

max_model_len 约束单个请求的总序列长度，输入与计划生成的 token 都要留在这个范围内。例如实际需求是 8192 token，并且本次 profiling 支持该长度，可以在原来的启动配置中加入下面的参数片段：

--max-model-len 8192

这不是完整启动命令，模型、认证和其他已批准参数继续保留。8192 只是示例，不应超过该模型受支持的上下文长度或当前缓存容量。缩短上限会影响长请求的接收，调用方也要调整输入和生成预算；它不会自动将所有超长输入变成可用的短输入。

修改后重新读取本次启动的容量，而不是沿用上一次日志。缓存检查通过后，在隔离验证环境中用实际长度的请求检查生成与资源用量，再更新服务配置。保留原配置，失败时恢复，并确认原配置所需资源仍然可用。

长度缩短后，缓存反而变小

旧版 vLLM 的默认策略可能随上下文长度变化。0.6.5 在满足若干条件的长上下文 CUDA 场景中自动启用 chunked prefill；将长度降到 32K 以下，可能不再走这条默认路径，profiling 的激活峰值随之改变。因此，缓存容量不一定随着长度参数单调变化。

对支持 chunked prefill 的模型与功能组合，可以在测试配置中显式加入：

--enable-chunked-prefill

它把 prefill 分块，可能减少这一阶段的激活压力，但仍要看新日志中的实际缓存容量。该版本对多模态、滑动窗口、推测解码、LoRA 等组合有条件或限制，不能把这个开关当成所有模型的通用修复。新版本也不能直接照搬 0.6.5 的默认阈值判断。

显存预算确实偏低，再考虑提高利用比例

gpu_memory_utilization 是当前实例的显存预算比例，包含模型执行所需部分，不是只分给 KV cache，也不会协调同卡上的其他实例。确认卡上其他任务、模型开销和资源余量后，再小幅调整并重新 profiling。

不要直接设为 1 就认定缓存一定够用：预算比例不能创造显存，也不能消除权重与激活开销。量化权重、不同并行方案和 KV cache dtype 对容量的作用不同，涉及兼容性和输出质量，应分别核对，不为通过启动强行拼接参数。

如果连 PyTorch 都看不到 GPU，先沿CUDA 可用性检查处理。已经进入上述缓存容量比较时，应继续核对服务长度和内存预算；训练阶段的梯度、优化器显存问题不属于这条路径。