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）。
有關支援模型的完整列表，請參閱支援的模型列表。