vLLM V1 用户指南#
V1 现在已默认启用，适用于所有支持的用例，我们将逐步为计划支持的每个用例启用它。请在 GitHub 或 vLLM Slack 中分享任何反馈。
要禁用 V1，请设置环境变量为：VLLM_USE_V1=0，并向我们发送 GitHub issue 分享原因！
为何选择 vLLM V1？#
vLLM V0 成功支持了广泛的模型和硬件，但随着新特性的独立开发，系统变得越来越复杂。这种复杂性使得集成新功能变得更加困难，并引入了技术债务，揭示了对更精简和统一设计的需求。
在 V0 成功的基础上，vLLM V1 保留了 V0 中稳定且经过验证的组件（例如模型、GPU 内核和实用程序）。与此同时，它对核心系统进行了重大架构重构，涵盖了调度器、KV 缓存管理器、worker、采样器和 API 服务器，以提供一个有凝聚力、可维护的框架，更好地适应持续增长和创新。
具体来说，V1 旨在
提供一个简单、模块化且易于 hack 的代码库。
确保高性能，接近零 CPU 开销。
将关键优化整合到一个统一的架构中。
通过默认启用特性/优化，实现 零配置。
我们看到升级到 V1 核心引擎带来了显著的性能提升，尤其是在长上下文场景中。请参阅性能基准（待添加）。
有关更多详细信息，请查看 vLLM V1 博客文章 vLLM V1：vLLM 核心架构的重大升级（发布于 2025 年 1 月 27 日）。
这份活生生的用户指南概述了 vLLM V1 引入的一些已知的重要更改和限制。团队一直在积极工作，使 V1 成为默认引擎，因此本指南将随着更多特性在 vLLM V1 上得到支持而不断更新。
支持概览#
硬件#
硬件 |
状态 |
|---|---|
NVIDIA |
|
AMD |
|
TPU |
特性 / 模型#
特性 / 模型 |
状态 |
|---|---|
前缀缓存 |
|
分块预填充 |
|
Logprobs 计算 |
|
LoRA |
|
多模态模型 |
|
FP8 KV 缓存 |
|
推测解码 |
|
带前缀缓存的 Prompt Logprobs |
|
结构化输出备用后端 |
|
嵌入模型 |
|
Mamba 模型 |
|
编码器-解码器模型 |
|
请求级结构化输出后端 |
|
best_of |
|
按请求 Logits 处理器 |
|
GPU <> CPU KV 缓存交换 |
🚀 已优化：接近完全优化，目前没有进一步工作计划。
🟢 功能正常：功能齐全，正在进行优化。
🚧 开发中：正在积极开发中。
🟡 计划中：计划在未来实施（有些可能已开启 PR/RFC）。
🔴 已弃用：除非有强烈需求，否则不计划在 v1 中支持。
注意：vLLM V1 的统一调度器通过使用简单的字典（例如，{request_id: num_tokens}）动态分配每个请求的固定令牌预算，从而以相同的方式处理 prompt 和输出令牌，从而实现分块预填充、前缀缓存和推测解码等功能，而无需严格区分预填充和解码阶段。
语义更改和已弃用特性#
Logprobs#
vLLM V1 支持 logprobs 和 prompt logprobs。但是，与 V0 相比，存在一些重要的语义差异
Logprobs 计算
V1 中的 Logprobs 现在在从模型的原始输出计算出来后立即返回（即，在应用任何 logits 后处理（例如温度缩放或惩罚调整）之前）。因此，返回的 logprobs 不反映采样期间使用的最终调整后的概率。
对带有后采样调整的 logprobs 的支持正在进行中，将在未来的更新中添加。
带前缀缓存的 Prompt Logprobs
目前，仅当通过 --no-enable-prefix-caching 关闭前缀缓存时，才支持 prompt logprobs。在未来的版本中，prompt logprobs 将与前缀缓存兼容，但即使在前缀缓存命中时，也会触发重新计算以恢复完整的 prompt 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）正在开发中。
正在进行的特性和模型支持#
尽管我们已经在 vLLM V1 中重新实现并部分优化了 V0 中的许多特性和模型，但某些特性的优化工作仍在进行中，其他特性仍不受支持。
待优化的特性#
这些特性已在 vLLM V1 中支持，但其优化仍在进行中。
待支持的特性#
结构化输出备用后端：计划支持结构化输出备用后端（outlines、guidance）。V1 目前仅支持
xgrammar:no_fallback模式，这意味着如果 xgrammar 不支持输出模式，则会报错。有关结构化输出的详细信息，请访问此处。
待支持的模型#
vLLM V1 目前排除了具有 SupportsV0Only 协议的模型架构，并且大多数属于以下类别。最终将添加对这些模型的 V1 支持。
嵌入模型
不再使用单独的模型运行器、隐藏状态处理器 RFC #12249，而是提出了基于全局 logits 处理器 RFC #13360 的方案，以在 V1 中使用相同的引擎实例同时进行生成和嵌入。它仍处于计划阶段。
Mamba 模型
尚不支持使用选择性状态空间机制（而不是标准 Transformer 注意力机制）的模型（例如，MambaForCausalLM, JambaForCausalLM）。
编码器-解码器模型
vLLM V1 目前针对仅解码器 Transformer 进行了优化。尚不支持需要在单独的编码器和解码器之间进行交叉注意力的模型（例如，BartForConditionalGeneration, MllamaForConditionalGeneration）。
有关支持模型的完整列表，请参阅支持的模型列表。