vLLM V1¶
公告
我们已开始弃用 V0 版本。请参阅 RFC #18571 获取更多详情。
V1 现已在所有受支持的用例中默认启用，我们将逐步为计划支持的每个用例启用它。请在 GitHub 或 vLLM Slack 中分享您的任何反馈。
要禁用 V1，请将环境变量设置为：VLLM_USE_V1=0，并通过 GitHub issue 告诉我们原因！
为何选择 vLLM V1？¶
vLLM V0 成功支持了广泛的模型和硬件，但随着新功能独立开发，系统变得日益复杂。这种复杂性使得集成新功能变得更加困难，并引入了技术债，揭示了对更精简和统一设计的需求。
在 V0 成功的基础上，vLLM V1 保留了 V0 中稳定且经过验证的组件（例如模型、GPU 内核和实用程序）。同时，它显著地重新架构了核心系统，包括调度器、KV 缓存管理器、工作器、采样器和 API 服务器，以提供一个更具内聚性、可维护的框架，更好地适应持续的增长和创新。
具体而言，V1 旨在
- 提供一个**简单、模块化且易于修改的代码库**。
- 确保**高性能**，同时 CPU 开销接近于零。
- 将**关键优化**整合到统一架构中。
- 通过默认启用功能/优化，实现**零配置**。
我们看到升级到 V1 核心引擎带来了显著的性能提升，尤其是在长上下文场景中。请参阅性能基准（待添加）。
欲了解更多详情，请查阅 vLLM V1 博客文章 《vLLM V1：vLLM 核心架构的重大升级》（发布于 2025 年 1 月 27 日）。
本用户指南概述了 vLLM V1 引入的一些已知**重要变更和限制**。团队一直在积极努力将 V1 作为默认引擎，因此本指南将随着 vLLM V1 支持更多功能而不断更新。
当前状态¶
对于每个项目，我们对 V1 支持的进展状态分为以下几类：
- 🚀 **已优化**：接近完全优化，目前没有进一步的工作计划。
- 🟢 **功能完备**：完全可操作，并持续进行优化。
- 🚧 **WIP (开发中)**：正在积极开发中。
- 🟡 **已计划**：计划未来实施（部分可能有已开放的 PR/RFC）。
- 🟠 **已延迟**：在 V1 中暂时移除，但计划稍后重新引入。
- 🔴 **已弃用**：未计划在 V1 中支持，除非有强烈需求。
注意
vLLM V1 的统一调度器通过使用一个简单的字典（例如 `{request_id: num_tokens}`）来动态分配每个请求的固定令牌预算，从而以相同的方式处理提示和输出令牌，实现了分块预填充、前缀缓存和推测解码等功能，而无需严格区分预填充和解码阶段。
V1 调度器支持多种调度策略，包括先到先服务（FCFS）和基于优先级的调度（请求根据分配的优先级处理，FCFS 作为平局决胜者），可通过 `--scheduling-policy` 参数进行配置。
硬件¶
| 硬件 | 状态 |
|---|---|
| NVIDIA | |
| AMD | |
| TPU | |
| CPU |
模型¶
| 模型类型 | 状态 |
|---|---|
| 仅解码器模型 | |
| 编码器-解码器模型 | |
| 嵌入模型 | |
| Mamba 模型 | |
| 多模态模型 |
vLLM V1 目前排除了具有 SupportsV0Only 协议的模型架构。
提示
这对应于我们支持的模型列表中的 V1 列。
请参阅下文，了解尚未支持或在 V1 中有更多功能计划的模型状态。
嵌入模型¶
最初的基本支持现已可用。
随后，我们将考虑使用基于 全局 logits 处理器的 隐藏状态处理器，以实现在 V1 中使用相同引擎实例同时进行生成和嵌入。
Mamba 模型¶
使用选择性状态空间机制而非标准 Transformer 注意力机制的模型已部分支持。使用 Mamba-2 层（例如 Mamba2ForCausalLM）的模型已受支持，但使用较旧 Mamba-1 层（例如 MambaForCausalLM、JambaForCausalLM）的模型尚未支持。请注意，这些模型目前在 V1 中需要禁用前缀缓存。
结合了 Mamba-2 层和标准注意力层的模型也受支持（例如 BambaForCausalLM、Zamba2ForCausalLM、NemotronHForCausalLM、FalconH1ForCausalLM 和 GraniteMoeHybridForCausalLM）。请注意，这些模型目前在 V1 中需要禁用前缀缓存并使用 FlashInfer 注意力后端。
编码器-解码器模型¶
需要独立编码器和解码器之间交叉注意力的模型（例如 BartForConditionalGeneration、MllamaForConditionalGeneration）尚未支持。
功能¶
| 功能 | 状态 |
|---|---|
| 前缀缓存 | |
| 分块预填充 | |
| LoRA | |
| Logprobs 计算 | |
| FP8 KV 缓存 | |
| 推测解码 | |
| 带前缀缓存的提示 Logprobs | |
| 结构化输出备选后端 | |
| 请求级结构化输出后端 | |
| best_of | |
| 按请求 Logits 处理器 | |
| GPU <> CPU KV 缓存交换 |
注意
vLLM V1 的统一调度器通过使用一个简单的字典（例如 `{request_id: num_tokens}`）来动态分配每个请求的固定令牌预算，从而以相同的方式处理提示和输出令牌，实现了分块预填充、前缀缓存和推测解码等功能，而无需严格区分预填充和解码阶段。
Logprobs 的语义变更¶
vLLM V1 支持 logprobs 和提示 logprobs。然而，与 V0 相比，存在一些重要的语义差异：
Logprobs 计算
V1 中的 Logprobs 现在从模型原始输出计算后立即返回（即在应用任何 logits 后处理，如温度缩放或惩罚调整之前）。因此，返回的 logprobs 不反映采样过程中使用的最终调整概率。
支持带采样后调整的 logprobs 正在开发中，并将在未来更新中添加。
带前缀缓存的提示 Logprobs
目前，提示 logprobs 仅在通过 --no-enable-prefix-caching 关闭前缀缓存时才受支持。在未来的版本中，提示 logprobs 将与前缀缓存兼容，但即使命中前缀缓存，也会触发重新计算以恢复完整的提示 logprobs。详情请参阅 RFC #13414。
已弃用的功能¶
作为 vLLM V1 核心架构重大重构的一部分，一些遗留功能已被弃用。
采样功能
- **best_of**：此功能因使用率有限已被弃用。详情请参阅 RFC #13361。
- **按请求 Logits 处理器**：在 V0 中，用户可以传递自定义处理函数以按请求调整 logits。在 vLLM V1 中，此功能已弃用。相反，设计正朝着支持**全局 logits 处理器**的方向发展，这是团队正在积极为未来版本开发的功能。详情请参阅 RFC #13360。
KV 缓存功能
- **GPU <> CPU KV 缓存交换**：随着新的简化核心架构，vLLM V1 不再需要 KV 缓存交换来处理请求抢占。
结构化输出功能
- **请求级结构化输出后端**：已弃用，现在支持带回退机制的替代后端（outlines, guidance）。