上一章我們建立了 vLLM v1 的分層心智模型，知道請求從 API Server 出發，穿過 EngineCore，最終抵達 Worker 執行。但一個 HTTP 請求體裡的 JSON 字符串，是如何變成引擎內部可以調度、可以追蹤、可以中斷的對象的？這就是 Request 類要回答的問題。

KV Cache 的規格體系：從 KVCacheSpec 到註冊表

Request 解決了「誰要計算」的問題，而KVCacheSpec解決的是「在哪裡計算」的問題。在 PagedAttention 的世界裡，每個模型層的 KV cache 都需要被精確地描述：它有多少個 head、每個 head 多大、一個 block 能存多少 token、是否需要量化。這些信息被編碼在KVCacheSpec的繼承體系中。

直覺模型：KVCacheSpec 是顯存的「戶型圖」

沒有這套規格體系，KV cache 的分配就只能靠硬編碼的假設，無法支持從標準 MHA 到 MLA、從全注意力到滑動窗口、從 FP16 到 FP8 量化的多樣化模型需求。

數據結構：KVCacheSpec 的繼承樹與關鍵字段

KVCacheSpec是所有規格的基類，它是一個@dataclass(frozen=True) 📎 vllm/v1/kv_cache_interface.py:150-152。frozen 意味著規格對象一旦創建就不可變——這保證了多個組件（調度器、Worker、KV Cache Manager）看到的是同一份規格，不會因為某處修改而導致不一致。

基類定義了三個必須由子類實現的抽象屬性：num_heads、tokens_per_state、state_content_size_bytes 📎 vllm/v1/kv_cache_interface.py:182-183。這三個屬性共同決定了page_size_bytes——即一個 block 佔用的字節數。

AttentionSpec是最核心的子類，它引入了num_kv_heads、head_size、dtype、kv_quant_mode等字段📎 vllm/v1/kv_cache_interface.py:485-498。其中tokens_per_state字段的設計尤為精妙：默認值為 1，表示一個 state 對應一個 token；但可以設為大於 1 的整數（如 DeepSeek-V4 的稀疏 MLA 將多個 token 壓縮為一個 state），或小於 1 的分數（如 Whisper 的 block pooling 用Fraction(1, block_pool_size)表示一個 token 對應多個 state）📎 vllm/v1/kv_cache_interface.py:501-501。

FullAttentionSpec在AttentionSpec基礎上增加了sliding_window和attention_chunk_size 📎 vllm/v1/kv_cache_interface.py:566-566。注意它的文檔字符串解釋了一個重要的設計決策：當混合分配器被禁用時，滑動窗口注意力層在 KV Cache Manager 中被當作全注意力處理（為所有 token 分配 block），但在模型運行時仍按滑動窗口計算📎 vllm/v1/kv_cache_interface.py:540-545。這是一種保守分配、精確計算的策略。

MLAAttentionSpec是 DeepSeek 系列模型的關鍵規格。它將head_size_v默認設為 0📎 vllm/v1/kv_cache_interface.py:670，因為 MLA 只存儲一個 latent vector，沒有獨立的 V。alignment字段用於頁對齊填充📎 vllm/v1/kv_cache_interface.py:646-652，這對 FlashMLA 等需要特定對齊的後端至關重要。

MambaSpec則完全不走 attention 的路線。它用shapes和dtypes元組描述狀態張量的形狀📎 vllm/v1/kv_cache_interface.py:1027-1028，state_content_size_bytes是所有狀態張量大小的總和📎 vllm/v1/kv_cache_interface.py:1048-1052。Mamba 的max_memory_usage_bytes根據mamba_cache_mode有三種不同的計算方式📎 vllm/v1/kv_cache_interface.py:1073-1084，這反映了 Mamba 狀態管理的複雜性——它不像 attention 那樣線性增長，而是有固定的狀態大小。

場景驅動：從規格到顯存佈局的轉換

當引擎啟動時，它需要將所有層的KVCacheSpec轉換為實際的顯存佈局。這個過程由KVCacheTensor和create_kv_cache_views完成。

KVCacheTensor描述了一組同形狀層在 KV cache 分配中的位置📎 vllm/v1/kv_cache_interface.py:1406-1427。它的核心字段是layer_stride和block_stride：前者是相鄰層之間的字節距離，後者是相鄰 block 之間的字節距離。文檔字符串詳細解釋了兩種佈局模式：層外層佈局（layer-outermost）給每層一個連續區域，塊外層佈局（block-outermost）讓每個 block 包含所有層的 page📎 vllm/v1/kv_cache_interface.py:1416-1416。

flowchart LR
    subgraph spec["KVCacheSpec 层"]
        fas["FullAttentionSpec<br/>num_kv_heads=32<br/>head_size=128<br/>block_size=16"]
    end
    subgraph tensor["KVCacheTensor 层"]
        kt["KVCacheTensor<br/>size=2GB<br/>layer_stride=page*num_blocks<br/>block_stride=page"]
    end
    subgraph view["torch.Tensor 视图"]
        v1["layer_0: [B, H, N, C]"]
        v2["layer_1: [B, H, N, C]"]
        v3["layer_N: [B, H, N, C]"]
    end
    fas -->|"compute_layer_kv_cache_shape_bytes()"| kt
    kt -->|"create_kv_cache_views()"| v1
    kt -->|"create_kv_cache_views()"| v2
    kt -->|"create_kv_cache_views()"| v3

create_kv_cache_views函數是這個過程的核心📎 vllm/v1/kv_cache_interface.py:353-417。它接收一個扁平的 int8 buffer，通過torch.as_strided為每一層創建一個 4D 視圖[B, H, N, C]。關鍵參數是strides，它由compute_layout_strides計算得出📎 vllm/v1/kv_cache_interface.py:314-350。這個函數按照layout.stride_order指定的維度順序，從最內層維度開始反向計算每個維度的字節步長。

這裡有一個值得注意的邊界檢查：當 kernel_block_size 小於 spec.block_size 時（即一個 manager block 被拆分為多個 kernel block），代碼會驗證 block_stride 是否等於 dense_page_size📎 vllm/v1/kv_cache_interface.py:381-382。如果不等於，說明佈局中存在 padding，無法均勻拆分，此時會拋出帶有明確修復建議的 ValueError。

設計思考：註冊表模式與可擴展性

KVCacheSpecRegistry是 vLLM 可擴展性的關鍵設計📎 vllm/v1/kv_cache_spec_registry.py:39-40。它維護了兩個全局字典：_REGISTRY_KVCACHESPEC_LIST存儲 spec 類到元數據的映射，_REGISTRY_ROLE_MANAGERS存儲角色到管理器的映射📎 vllm/v1/kv_cache_spec_registry.py:35-36。

get_manager_class方法展示了註冊表的核心查找邏輯：它沿著 spec 類的 MRO（方法解析順序）向上遍歷，找到第一個已註冊的基類📎 vllm/v1/kv_cache_spec_registry.py:129-130。這意味著一個自定義的CustomFullAttentionSpec如果沒有單獨註冊，會自動繼承FullAttentionSpec的管理器。這種基於繼承的查找使得新增 spec 類型時只需註冊差異部分。

check_kv_cache_spec_registry方法在啟動時驗證所有層的 spec 都已註冊📎 vllm/v1/kv_cache_spec_registry.py:165-174。注意它使用raise ValueError而非assert，註釋明確說明這是為了在生產環境中也生效📎 vllm/v1/kv_cache_spec_registry.py:165-174。這是一個重要的工程決策：Python 的-O標誌會移除 assert，但生產環境中的配置錯誤必須在啟動時就暴露，而不是在運行時才崩潰。

本章小結

本章剖析了 vLLM v1 的兩個核心資料結構。Request是請求在引擎內部的生命週期載體，它透過雙 token 列表、非同步排程計數器和 block hash 機制，支撐了連續批次處理和前綴快取兩大核心功能。KVCacheSpec及其繼承體系則定義了 KV cache 的顯存佈局規格，從標準的FullAttentionSpec到MLAAttentionSpec、MambaSpec，涵蓋了多樣化的模型架構需求。註冊表模式使得新增 spec 類型無需修改核心程式碼，保證了系統的可擴展性。

至此，我們已經看清了 Request 如何從 EngineCoreRequest 轉換而來，以及它如何透過狀態計數器、block hash 等機制支撐排程決策。但一個外部請求究竟如何穿越 API Server、chat template 與多模態處理，最終變成 EngineCoreRequest？下一章將進入請求入口層，完整追蹤這條從 HTTP/CLI 到 EngineCore 的鏈路。

上一章我們剖析了 Request 與 KVCacheSpec 這兩個引擎內部的核心資料結構，理解了邏輯序列與物理顯存塊如何解耦。但一個 HTTP 請求體或一個 Python 字串，究竟如何穿越 API Server、chat template 與多模態處理，最終變成 EngineCoreRequest？本章將完整追蹤這條鏈路，並揭示同步 CLI、非同步 API 與離線 LLM 類三條入口路徑如何匯聚到同一引擎核心。

3.1 三條入口路徑的收斂點：AsyncLLMEngine 與 LLMEngine

在深入請求解析之前，必須先看清三條入口路徑的拓撲結構。vLLM 提供了三種使用方式：vllm serve啟動的 OpenAI 相容 HTTP 服務、命令列vllm工具、以及 Python 中直接實例化LLM類做離線推理。它們看似獨立，實則共享同一套引擎核心。

先看非同步 API 路徑的別名機制。

📎 vllm/engine/async_llm_engine.py:7-7

這個檔案短得幾乎不像一個模組——它只做了一件事：把AsyncLLMEngine別名指向vllm.v1.engine.async_llm.AsyncLLM。這是一個典型的架構遷移痕跡。vLLM v0 時代的AsyncLLMEngine是一個龐大而複雜的類，v1 架構重寫後，新的AsyncLLM承擔了相同職責。為了不破壞既有使用者程式碼，vLLM 保留了舊模組路徑作為相容層。

再看離線路徑的入口。

📎 vllm/entrypoints/llm.py:344-346

LLM.__init__最終呼叫LLMEngine.from_engine_args，傳入UsageContext.LLM_CLASS。這個UsageContext枚舉是區分入口路徑的關鍵——它讓引擎知道自己是運行在離線批次處理模式還是在線服務模式，從而調整日誌、指標和資源管理策略。

📎 vllm/entrypoints/llm.py:357-359

注意這裡self.renderer = self.llm_engine.renderer和self.input_processor = self.llm_engine.input_processor的賦值。離線LLM類並不自己實現 chat template 渲染，而是複用引擎內部的renderer。這意味著 chat template 的解析邏輯在離線與在線路徑上是同一份程式碼，只是呼叫時機不同。

三條路徑的收斂關係可以用下面的資料流圖表示。

flowchart LR
    subgraph entry["入口层"]
        http["HTTP 请求体<br/>ChatCompletionRequest"]
        cli["CLI 参数<br/>vllm serve / vllm chat"]
        offline["Python 调用<br/>LLM.chat(messages)"]
    end

    subgraph parse["解析层"]
        chat_utils["chat_utils.parse_chat_messages<br/>-> ConversationMessage + mm_data"]
        renderer["renderer<br/>apply_chat_template -> token_ids"]
    end

    subgraph engine["引擎层"]
        async_llm["AsyncLLM<br/>add_request()"]
        llm_engine["LLMEngine<br/>add_request()"]
        core["EngineCore<br/>input_queue"]
    end

    http --> chat_utils
    cli --> chat_utils
    offline --> chat_utils
    chat_utils --> renderer
    renderer --> async_llm
    renderer --> llm_engine
    async_llm --> core
    llm_engine --> core

這張圖揭示了一個關鍵設計：無論請求來自 HTTP、CLI 還是 Python，chat_utils都是多模態與 chat template 處理的唯一入口。它把異構的輸入格式統一為ConversationMessage列表加MultiModalDataDict，再交給 renderer 生成 token 序列。

3.2 chat_utils：從異構訊息到統一對話結構

chat_utils.py是整個請求入口層最複雜的模組，2264 行程式碼處理了 OpenAI 相容格式、自訂擴展、多模態嵌入、工具呼叫等所有輸入形態。它的核心職責可以用一句話概括：把使用者傳來的任意訊息列表，規範化為 chat template 能理解的ConversationMessage列表，同時把多模態資料抽取到獨立的MultiModalDataDict中。

直覺模型：翻譯官與行李分揀員

把chat_utils想像成機場的翻譯官兼行李分揀員。旅客（使用者）來自不同國家（OpenAI 格式、自訂格式、Harmony 格式），說著不同的語言。翻譯官先把所有人的話翻譯成統一的工作語言（ConversationMessage），同時把旅客託運的行李（圖片、音訊、影片）分揀到獨立的傳送帶上（MultiModalDataDict），貼上標籤（UUID），最後把人和行李分別送上同一架飛機（引擎）。

如果沒有這一層，引擎就必須理解每一種輸入格式的細節，多模態資料的提取邏輯會散落在各個入口中，任何新格式的加入都要改動引擎核心。

資料結構：追蹤器與解析器的雙類協作

chat_utils的核心是兩組類的協作：BaseMultiModalItemTracker及其子類負責「追蹤」多模態項，BaseMultiModalContentParser及其子類負責「解析」內容部分。

先看追蹤器的欄位佈局。

📎 vllm/entrypoints/chat_utils.py:598-601

_items_by_modality是一個defaultdict[str, list[_T]]，按模態（image、audio、video 等）分組儲存待處理的項。_modality_order則專門為vision_chunk模態記錄每個 chunk 的原始模態（image 還是 video），因為統一視覺 chunk 模型會把兩者都映射到vision_chunk，但後續處理需要知道原始類型。

📎 vllm/entrypoints/chat_utils.py:613-615

use_unified_vision_chunk_modality是一個cached_property，從 HuggingFace 配置中讀取use_unified_vision_chunk標誌。使用cached_property而非普通屬性，是因為這個檢查在每次add呼叫時都會觸發，快取可以避免重複的getattr開銷。

追蹤器的add方法是核心入口。

📎 vllm/entrypoints/chat_utils.py:656-684

add方法先呼叫_validate_add做校驗，然後根據是否使用統一視覺 chunk 模態，把項存入不同的鍵下。注意prompt_embeds的特殊處理：它直接追加到_items_by_modality["prompt_embeds"]並返回None，因為預計算嵌入不經過 HF processor，沒有佔位符字串。

_validate_add中的校驗邏輯值得細看。

📎 vllm/entrypoints/chat_utils.py:686-721

這裡有一個微妙的分支：當enable_mm_embeds=True且該模態的每 prompt 限制為 0 且原始模態以_embeds結尾時，跳過數量校驗。這是為了允許嵌入輸入繞過原始模態的數量限制——嵌入是預計算的，不佔用原始模態的處理資源。

場景驅動：一次帶圖片的 chat 請求如何被解析

假設使用者發送一個包含圖片 URL 和文字的 chat 請求。parse_chat_messages是同步路徑的入口。

📎 vllm/entrypoints/chat_utils.py:2161-2197

parse_chat_messages建立MultiModalItemTracker，遍歷每條訊息呼叫_parse_chat_message_content，最後呼叫_postprocess_messages處理工具呼叫參數，再透過mm_tracker.resolve_items()物化多模態資料。

_parse_chat_message_content負責單條訊息的解析。

📎 vllm/entrypoints/chat_utils.py:2007-2029

它先規範化 content：None變成空列表，字串變成單個文字 part。然後呼叫_parse_chat_message_content_parts，其中wrap_dicts參數由content_format == "openai"決定——這決定了輸出是結構化字典列表還是拼接後的字串。

_parse_chat_message_content_parts遍歷每個 part。

📎 vllm/entrypoints/chat_utils.py:1814-1853

每個 part 經過_parse_chat_message_content_part處理。如果wrap_dicts=False，最終會把文字和佔位符拼接成單個字串；如果wrap_dicts=True，則返回結構化字典列表。

_parse_chat_message_content_part是分發的核心。

📎 vllm/entrypoints/chat_utils.py:1875-1884

對於純文字 part，先做保留佔位符檢查，再根據wrap_dicts決定返回格式。對於結構化 part，呼叫_parse_chat_message_content_mm_part提取類型和內容。

📎 vllm/entrypoints/chat_utils.py:1690-1723

_parse_chat_message_content_mm_part透過MM_PARSER_MAP查找對應的解析函式。注意uuid is None的條件——如果使用者提供了 UUID，說明媒體資料可能不在請求體中（已透過其他方式上傳），此時走下面的直接 URL 欄位分支。

📎 vllm/entrypoints/chat_utils.py:1731-1733

當part_type is None或uuid is not None時，程式碼嘗試從 part 中直接提取 URL 欄位。這種「寬鬆解析」是為了相容那些不嚴格遵循 OpenAI 格式的客戶端。

回到_parse_chat_message_content_part，媒體類型的 part 會被分發到對應的mm_parser方法。

📎 vllm/entrypoints/chat_utils.py:1923-1968

每個媒體類型呼叫對應的parse_*方法，這些方法內部會呼叫tracker.add把項加入追蹤器，並返回佔位符字串。最後根據interleave_strings決定返回佔位符還是None。

📎 vllm/entrypoints/chat_utils.py:1984-1999

prompt_embeds的處理是特殊的：無論interleave_strings如何，都返回PROMPT_EMBEDS_PLACEHOLDER_TOKEN。註解解釋了原因——prompt_embeds 在 token 偏移處拼接，位置很重要，如果走missing_placeholders的前置填充邏輯會打亂順序。

非同步路徑的差異

非同步路徑使用AsyncMultiModalItemTracker和AsyncMultiModalContentParser。核心差異在resolve_items。

📎 vllm/entrypoints/chat_utils.py:906-952

非同步版本用asyncio.gather並發等待所有模態項。註解明確指出：每個追蹤項已經是獨立的 awaitable，非同步連接器會把阻塞的解碼工作卸載到執行緒池，所以串行等待一個模態再等下一个會無謂地增加延遲。return_exceptions=True讓所有任務都完成或失敗後再統一拋出，避免第一個失敗就放棄仍在進行中的網路請求。

設計思考：為什麼追蹤器與解析器分離

3.3 從訊息到 token：renderer 與 EngineCore 的交接

chat_utils產出的ConversationMessage列表和MultiModalDataDict還需要經過 chat template 渲染才能變成 token 序列。這一步由 renderer 完成，之後請求才真正進入引擎。

場景驅動：chat template 渲染與請求投遞

parse_chat_messages返回後，呼叫方（如OpenAIServingChat）會把conversation和mm_data傳給 renderer。renderer 應用 chat template，把ConversationMessage列表渲染成文本，再 tokenize 成 token ID 序列。多模態佔位符（如<##IMAGE##>）在 tokenize 後會被替換為模型特定的佔位符 token。

渲染完成後，請求被封裝為EngineCoreRequest，透過AsyncLLM.add_request()或LLMEngine.add_request()投遞到 EngineCore 的輸入佇列。

📎 vllm/entrypoints/llm.py:420-484

離線LLM.generate方法展示了這條鏈路：它先校驗runner_type，取得預設取樣參數，然後呼叫_run_completion。_run_completion內部會呼叫 renderer 渲染 prompt，再透過llm_engine投遞請求。

📎 vllm/entrypoints/llm.py:615-708

LLM.chat方法則展示了 chat 路徑：它接收messages列表，呼叫_run_chat，後者內部會呼叫parse_chat_messages和 renderer。

設計思考：為什麼 renderer 在引擎內部

錯誤恢復與生產踩坑

_postprocess_messages中的工具呼叫參數處理是一個典型的生產環境陷阱。

📎 vllm/entrypoints/chat_utils.py:2118-2158

當 assistant 訊息包含tool_calls時，arguments欄位可能是 JSON 字串、字典或無效 JSON。程式碼嘗試解析 JSON 字串，如果失敗則記錄警告並強制轉為空物件。註解解釋了原因：格式錯誤的arguments存在於對話歷史中，如果在這裡讓請求失敗，後續每一輪都會失敗，對話將無法恢復。這是一個深思熟慮的容錯設計——寧可讓模型看到空的工具參數，也不讓整個對話卡死。

另一個陷阱是保留佔位符的注入防護。

📎 vllm/entrypoints/chat_utils.py:1856-1872

當enable_prompt_embeds開啟時，PROMPT_EMBEDS_PLACEHOLDER_TOKEN被註冊為不可分割的特殊 token。如果使用者文本中恰好包含這個字面序列，tokenizer 會把它編碼為同一個 token ID，renderer 會誤認為這是拼接點，允許呼叫者透過純文字內容移動或注入拼接位置。_reject_reserved_placeholder_in_text在文本 part 解析時拒絕這種輸入，堵住了這個安全漏洞。

📎 vllm/entrypoints/chat_utils.py:1889-1892

注意這個檢查在isinstance(part, str)分支和結構化文本分支中都有呼叫，確保所有文本路徑都經過防護。

本章小結

本章追蹤了請求從外部進入系統的第一段鏈路。三條入口路徑——HTTP API、CLI 和離線LLM類——最終都匯聚到chat_utils的多模態解析層。BaseMultiModalItemTracker負責狀態管理，BaseMultiModalContentParser負責內容提取，兩者分離使得同步和非同步路徑可以共享追蹤邏輯。parse_chat_messages把異構訊息規範化為ConversationMessage列表和MultiModalDataDict，再交給引擎內部的 renderer 完成 chat template 渲染和 tokenize。最終，請求被封裝為EngineCoreRequest投遞到 EngineCore 的輸入佇列。

本章思考與自測

下一章將進入排程器，看 EngineCore 如何用連續批次處理與顯存感知策略編排這些請求。

至此，請求已經完成從外部輸入到 EngineCoreRequest 的規範化轉換，並抵達引擎核心的入口。但請求進入之後並不會立即執行——引擎需要決定在每一步中處理哪些請求、如何分配有限的顯存資源。下一章將深入 EngineCore 的排程迴圈，剖析 Scheduler 如何在連續批次處理中權衡吞吐與延遲，以及 chunked prefill、prefix caching 與 KV block 分配如何協同工作。

請求進入 EngineCore 的輸入佇列後，並不會立即被執行。每一步處理哪些請求、為每個請求分配多少 token 預算、顯存不足時優先犧牲誰，這些決策都集中在Scheduler.schedule()方法中。本章從排程器的資料結構入手，追蹤一次schedule()呼叫如何將 waiting 佇列、running 列表和 KV cache 池組織成一個可執行的批次。

4.1 排程器的資料結構：三個佇列與一個顯存池

排程器要回答的核心問題是：在有限的 token 預算和 KV block 預算下，這一步該讓哪些請求前進多少 token？要理解它，先要看清它手裡握著哪些狀態。

排程器維護三類請求容器。self.requests是全域字典，req_id -> Request，所有活躍請求的唯一真相來源📎 vllm/v1/core/sched/scheduler.py:208-209。self.waiting和self.skipped_waiting是兩個優先級佇列，前者放正常等待排程的請求，後者放因非同步依賴或約束暫時無法排程的請求（如等待遠端 KV、等待結構化輸出語法編譯）📎 vllm/v1/core/sched/scheduler.py:208-209。self.running是一個普通列表，存放已經進入運行態、持有 KV block 的請求📎 vllm/v1/core/sched/scheduler.py:208-209。

這裡有一個容易被忽略的設計：max_num_running_reqs與max_num_active_reqs是兩個不同的上限。前者來自max_num_seqs，決定 model runner 的槽位數；後者來自max_num_active_seqs，只限制能進入 RUNNING 的請求數，預設等於前者📎 vllm/v1/core/sched/scheduler.py:123-131。這個分離允許在不縮小 CUDA graph 捕獲容量的前提下，壓低實際並行解碼批次大小。

顯存側由KVCacheManager統一管理，它內部持有BlockPool。BlockPool的核心是self.blocks（全部KVCacheBlock的列表）和free_block_queue（一個按驅逐順序排列的空閒塊雙向鏈結串列）📎 vllm/v1/core/block_pool.py:171-177。注意null_block的存在：它是從空閒佇列頭部彈出的第一個塊，is_null=True，引用計數不參與常規維護，專門用作佔位符📎 vllm/v1/core/block_pool.py:183-187。當請求的某個 token 位置不需要真實 KV block（例如被滑動視窗跳過的位置）時，block table 裡就填這個 null block。

前綴快取的索引結構是BlockHashToBlockMap，它把BlockHashWithGroupId映射到一個KVCacheBlock或一個{block_id: KVCacheBlock}字典📎 vllm/v1/core/block_pool.py:56-59。為什麼要用聯合類型？註解給出了答案：大多數雜湊只對應一個塊，用字典會產生不必要的 GC 開銷；只有當同一個雜湊被多個塊共享時才升級為字典📎 vllm/v1/core/block_pool.py:56-59。這是一個典型的用類型複雜度換執行時開銷的取捨。

KVCacheBlocks是排程器與 KV cache 管理器之間的介面物件，它把內部資料結構隱藏起來。它的blocks欄位是tuple[Sequence[KVCacheBlock], ...]，外層維度是 KV cache group，內層是塊序列📎 vllm/v1/core/kv_cache_manager.py:41-54。註解明確解釋了為什麼不用塊作為外層維度：那會假設所有 group 的塊數相同，而未來可能給不同 group 配置不同的 block size📎 vllm/v1/core/kv_cache_manager.py:43-48。

flowchart LR
    subgraph Sched["Scheduler 状态"]
        W["waiting<br/>RequestQueue"]
        SW["skipped_waiting<br/>RequestQueue"]
        R["running<br/>list[Request]"]
        REQ["requests<br/>dict[str, Request]"]
    end
    subgraph KV["KVCacheManager"]
        BP["BlockPool.blocks<br/>list[KVCacheBlock]"]
        FQ["free_block_queue<br/>FreeKVCacheBlockQueue"]
        MAP["cached_block_hash_to_block<br/>BlockHashToBlockMap"]
    end
    W -->|"admit + allocate_slots"| R
    R -->|"preempt"| W
    R -->|"free / pop_blocks_for_free"| FQ
    FQ -->|"get_new_blocks"| BP
    BP -->|"cache_full_blocks"| MAP
    MAP -->|"get_cached_block"| W

這張圖錨定了排程器與顯存池之間的資料流：waiting 佇列的請求透過allocate_slots進入 running，running 的請求被搶佔時回到 waiting，釋放的塊回到空閒佇列，而前綴快取雜湊表是 waiting 請求命中快取的入口。

4.2 schedule() 主流程：running 優先、waiting 補充、搶佔兜底

schedule()是整個排程器的核心方法，它回傳一個SchedulerOutput，描述這一步要執行什麼。方法開頭的註解點明了設計哲學：排程器裡沒有「解碼階段」和「預填充階段」的區分，每個請求只有num_computed_tokens和num_tokens_with_spec，排程器的任務就是讓前者追上後者📎 vllm/v1/core/sched/scheduler.py:559-568。這個統一視角是 chunked prefill、prefix caching、投機解碼能共存的基礎。

4.2.1 預算初始化與閾值計算

進入主迴圈前，排程器先設定兩個預算：token_budget初始化為max_num_scheduled_tokens，input_budget初始化為max_num_batched_tokens 📎 vllm/v1/core/sched/scheduler.py:577-580。兩者通常相等，但當模型可能在批次中追加 token（如投機解碼）時，max_num_scheduled_tokens會小於max_num_batched_tokens，差值就是留給 draft token 的空間。

long_prefill_token_threshold的處理值得單獨看。它的作用是防止一個長 prefill 餓死其他請求，但如果當前只有一個請求，就沒有人會被餓死，所以閾值被置零📎 vllm/v1/core/sched/scheduler.py:606-616。當adaptive_long_prefill_threshold開啟時，閾值還會被抬高到input_budget // num_eligible_reqs，保證不會把單個請求的預算壓到公平份額以下📎 vllm/v1/core/sched/scheduler.py:617-622。

4.2.2 running 請求的排程迴圈

主迴圈從self.running的頭部開始遍歷，req_index是游標📎 vllm/v1/core/sched/scheduler.py:624-627。對每個請求，先做一系列跳過判斷：

• 非同步排程下，如果請求的輸出佔位符表明它已經達到max_tokens，跳過以避免多跑一步📎 vllm/v1/core/sched/scheduler.py:631-645。
• V2 + PP + 非同步場景下，如果當前步還沒到next_decode_eligible_step，跳過以匹配 worker 側的取樣 token 廣播節奏📎 vllm/v1/core/sched/scheduler.py:647-651。
• DP prefill 均衡開啟時，非節奏對齊步上的 prefill chunk 被推遲📎 vllm/v1/core/sched/scheduler.py:653-657。

透過跳過判斷後，計算這個請求本步能前進多少 token：

num_new_tokens = request.num_tokens_with_spec
               + request.num_output_placeholders
               - request.num_computed_tokens

然後依次被long_prefill_token_threshold、token_budget、input_budget - draft_slots和max_model_len約束📎 vllm/v1/core/sched/scheduler.py:670-688。如果請求帶編碼器輸入，還要經過_try_schedule_encoder_inputs調整📎 vllm/v1/core/sched/scheduler.py:700-712。

接下來是最關鍵的一步：分配 KV block。allocate_slots被包在一個while True迴圈裡📎 vllm/v1/core/sched/scheduler.py:742-747。如果回傳None，說明顯存不夠，排程器開始搶佔：按策略選出犧牲者（PRIORITY 策略選優先級最低的，FCFS 策略選 running 列表末尾的）📎 vllm/v1/core/sched/scheduler.py:761-767，呼叫_preempt_request把它踢回 waiting 佇列，然後重試分配📎 vllm/v1/core/sched/scheduler.py:801-806。如果犧牲者就是當前請求自己，說明已經沒有可搶佔的對象，跳出迴圈，當前請求也無法排程📎 vllm/v1/core/sched/scheduler.py:807-813。

搶佔邏輯裡有一個精妙的細節：PRIORITY 策略下，如果被搶佔的請求已經在scheduled_running_reqs裡（即本步已經為它分配過資源），需要把它的 token 預算、block、投機 token、編碼器預算全部歸還📎 vllm/v1/core/sched/scheduler.py:779-797。這保證了預算帳本的一致性。

分配成功後，請求被加入scheduled_running_reqs，記錄 block 和 token 數，扣減預算📎 vllm/v1/core/sched/scheduler.py:815-823。投機解碼相關的 token 在這裡被裁剪並記錄📎 vllm/v1/core/sched/scheduler.py:825-841。

4.2.3 waiting 請求的准入

running 迴圈結束後，如果本步沒有發生搶佔且排程器未暫停，開始處理 waiting 佇列📎 vllm/v1/core/sched/scheduler.py:868-872。准入前先檢查兩個上限：max_num_active_reqs和input_budget 📎 vllm/v1/core/sched/scheduler.py:873-879。

waiting 請求的排程比 running 多了一個前綴快取查找步驟。當request.num_computed_tokens == 0時，呼叫_get_local_prefix_cache_hit查找本地快取命中📎 vllm/v1/core/sched/scheduler.py:932-939。如果配置了 KV connector，還會查詢遠端快取命中📎 vllm/v1/core/sched/scheduler.py:942-954。

這裡有一個處理本地與遠端命中衝突的精細邏輯。本地命中可能不是塊對齊的（partial_tail），而遠端命中如果嚴格超過本地完整命中，就丟棄本地的子塊尾部，讓遠端載入覆蓋它，避免寫時複製📎 vllm/v1/core/sched/scheduler.py:977-988。反之則保留本地尾部，不載入外部📎 vllm/v1/core/sched/scheduler.py:989-995。

准入成功後，請求從 waiting 佇列彈出，狀態設為 RUNNING，加入 running 列表📎 vllm/v1/core/sched/scheduler.py:1263-1319。如果本步之後它仍在 prefill 中（num_computed_tokens + num_new_tokens < request.num_tokens），加入_inflight_prefills集合📎 vllm/v1/core/sched/scheduler.py:1326-1328。

flowchart TD
    start["schedule() 开始"] --> init["初始化 token_budget / input_budget"]
    init --> run_loop{"running 循环<br/>req_index < len(running)<br/>且 token_budget > 0?"}
    run_loop -->|是| skip_check{"跳过条件?<br/>max_tokens 已达 /<br/>decode_eligible / defer_prefills"}
    skip_check -->|跳过| run_inc["req_index += 1"]
    run_inc --> run_loop
    skip_check -->|不跳过| calc["计算 num_new_tokens<br/>受多约束裁剪"]
    calc --> alloc{"allocate_slots<br/>返回 None?"}
    alloc -->|成功| admit_run["加入 scheduled_running_reqs<br/>扣减预算"]
    admit_run --> run_inc
    alloc -->|失败| can_preempt{"有可抢占请求?<br/>_request_blocks_can_be_freed"}
    can_preempt -->|否| break_run["跳出 running 循环"]
    can_preempt -->|是| preempt["_preempt_request<br/>踢回 waiting"]
    preempt --> alloc
    break_run --> wait_loop{"无抢占且未暂停?<br/>waiting 非空且 token_budget > 0?"}
    run_loop -->|否| wait_loop
    wait_loop -->|是| blocked{"blocked 状态?<br/>_is_blocked_waiting_status"}
    blocked -->|是且无法提升| skip_wait["移入 skipped_waiting"]
    skip_wait --> wait_loop
    blocked -->|否| prefix{"num_computed_tokens == 0?<br/>查找前缀缓存"}
    prefix -->|命中| alloc_wait["allocate_slots<br/>带 new_computed_blocks"]
    prefix -->|未命中| alloc_wait
    alloc_wait --> wait_ok{"分配成功?"}
    wait_ok -->|是| admit_wait["加入 running<br/>状态设为 RUNNING"]
    admit_wait --> wait_loop
    wait_ok -->|否| break_wait["跳出 waiting 循环"]
    wait_loop -->|否| build["构建 SchedulerOutput"]
    break_wait --> build

這張控制流圖覆蓋了schedule()的兩大迴圈和搶佔分支。注意 running 迴圈中allocate_slots失敗後的搶佔重試路徑，以及 waiting 迴圈中 blocked 狀態請求被移入skipped_waiting的旁路。

4.3 顯存感知的核心：allocate_slots 與搶佔

allocate_slots是排程器與顯存之間的閘門。它的參數列表本身就是一份顯存帳本：num_new_tokens是要新計算的 token 數，num_new_computed_tokens是前綴快取新命中的 token 數，num_external_computed_tokens是 connector 提供的外部命中數，num_lookahead_tokens是投機解碼預留的槽位📎 vllm/v1/core/kv_cache_manager.py:371-383。

方法開頭的註解用一張 ASCII 圖精確描述了塊佈局📎 vllm/v1/core/kv_cache_manager.py:417-438：

| < comp > | < new_comp > | < ext_comp >  | < new >  | < lookahead > |
                                          |   < to be computed >     |
                        |            < to be allocated >           |

comp是已計算 token，new_comp是前綴快取命中，ext_comp是外部命中，new是本步新計算，lookahead是投機預留。分配分三個階段：先釋放不需要的塊並檢查是否有足夠空閒塊，再處理前綴 token，最後為新計算 token 分配塊📎 vllm/v1/core/kv_cache_manager.py:458-461。

4.3.1 水位線與准入控制

allocate_slots裡有兩個准入閘門。第一個是full_sequence_must_fit：當開啟時，先檢查整個請求序列（而非僅第一個 chunk）能否裝下，裝不下直接返回None 📎 vllm/v1/core/kv_cache_manager.py:515-531。這防止 chunked prefill 下過度准入導致 KV cache 抖動。

第二個是水位線。watermark_blocks只在請求狀態為 WAITING 或 PREEMPTED 且已有請求被排程時生效📎 vllm/v1/core/kv_cache_manager.py:506-513。它要求分配後至少保留一定比例的空閒塊，避免頻繁驅逐和搶佔。reserved_blocks則用於非同步 KV 載入場景，確保在途 prefill 的預留塊不被新請求吃掉📎 vllm/v1/core/kv_cache_manager.py:564-570。

4.3.2 搶佔的代價與恢復

搶佔還處理了非同步排程下的「陳舊輸出」問題。num_stale_output_tokens被設為num_in_flight_tokens，標記所有在途輸出為陳舊📎 vllm/v1/core/sched/scheduler.py:1571-1574。這些 token 仍會被交付（丟棄會擾動投機解碼接受率），但不會修改重置後的計數器。drop_stale_output標誌決定是丟棄還是交付📎 vllm/v1/core/sched/scheduler.py:1539-1547。

4.3.3 延遲釋放：非同步連接器的寫後讀風險

當使用 KV connector 且存在多個在途批次時，defer_block_free被設為True 📎 vllm/v1/core/sched/scheduler.py:175-181。原因是：一個步驟可能仍在寫入已釋放請求的 KV 塊，而消費者 connector 可能透過一個未與該寫入排序的載入重新分配並填充這些塊。

延遲釋放透過deferred_frees雙端佇列實現，每個條目是(fence_seq, blocks) 📎 vllm/v1/core/sched/scheduler.py:388-390。_free_request_blocks檢查_request_blocks_can_be_freed，如果請求的最後排程步還沒被處理完，就把塊放入延遲佇列📎 vllm/v1/core/sched/scheduler.py:2679-2688。_drain_deferred_frees在update_from_output中推進processed_step_seq後調用，釋放 fence 已滿足的塊📎 vllm/v1/core/sched/scheduler.py:2701-2706。

4.4 前綴快取命中判定與塊生命週期

前綴快取的查找入口是KVCacheManager.get_computed_blocks。它先檢查是否啟用快取且請求未標記跳過讀取📎 vllm/v1/core/kv_cache_manager.py:286-287。然後調用coordinator.find_longest_cache_hit，傳入request.block_hashes和max_cache_hit_length = request.num_tokens - 1 📎 vllm/v1/core/kv_cache_manager.py:295-300。

為什麼是num_tokens - 1？註解解釋了：當所有 token 都命中快取時，必須重算最後一個 token 才能獲得 logits📎 vllm/v1/core/kv_cache_manager.py:289-294。這是一個容易被忽略的邊界：即使前綴完全命中，也至少要計算一個 token。

塊的生命週期由BlockPool管理。get_new_blocks從空閒佇列頭部彈出塊，如果啟用快取，先調用_maybe_evict_cached_block清除其雜湊元資料，然後增加引用計數📎 vllm/v1/core/block_pool.py:683-702。free_blocks則根據塊是否有雜湊決定放回佇列頭還是尾：無雜湊的塊 LIFO 複用（更好的 GPU 局部性），有雜湊的塊 FIFO 複用（LRU 驅逐行為）📎 vllm/v1/core/block_pool.py:785-805。

cache_full_blocks是塊被寫入前綴快取雜湊表的時刻。它遍歷新滿的塊，跳過 null 塊和被 mask 的塊，為每個塊計算雜湊並插入cached_block_hash_to_block 📎 vllm/v1/core/block_pool.py:272-300。如果塊已經有雜湊（部分塊升級為滿塊的場景），先移除舊雜湊再插入新雜湊📎 vllm/v1/core/block_pool.py:285-293。

touch方法處理快取命中時的引用計數：如果塊在空閒佇列中（ref_cnt == 0），先把它從佇列移除，再增加引用計數📎 vllm/v1/core/block_pool.py:754-770。這保證了被命中的塊不會被驅逐。

設計思考

本章小結

排程器的核心是schedule()方法中的兩個迴圈：running 迴圈優先保證已運行請求前進，waiting 迴圈在預算允許時准入新請求。顯存不足時透過搶佔 running 列表中優先級最低的請求來騰出空間，被搶佔請求的num_computed_tokens重置為 0，但前綴快取能抵消部分重算代價。allocate_slots是顯存閘門，透過full_sequence_must_fit、水位線和reserved_blocks三層准入控制防止過度分配。前綴快取透過塊雜湊索引實現跨請求共享，命中判定以num_tokens - 1為上限以保證至少計算一個 token 獲得 logits。

本章思考與自測

排程器輸出的SchedulerOutput明確了這一步的執行內容：新請求的塊 ID、快取請求的 token 數、投機 token、編碼器輸入等。下一章將追蹤這個輸出如何被 ModelRunner 消費，從SchedulerOutput一路走到 GPU 前向傳播。

上一章我們看到，Scheduler 在每一步的排程迴圈中決定了哪些請求進入 running 佇列、哪些被搶佔、哪些因顯存不足而等待，並最終產出一份 SchedulerOutput——它描述了本步該算什麼：哪些請求、各算多少 token、用哪些 KV block。但這份清單只是邏輯意圖，GPU 需要的是物理張量。本章追蹤 SchedulerOutput 如何被 Executor 分發到 Worker，再由 GPUModelRunner 翻譯成 input_ids、positions、slot_mapping 和 block table 等 GPU 可執行的輸入，最終透過 forward_context 把跨層共享的批描述注入模型每一層，完成從排程決策到前向傳播的跨越。

5.1 Executor：把排程結果送到每一張卡

直覺模型

Executor是 EngineCore 與 GPU Worker 之間的「傳令官」。若沒有它，EngineCore 就得自己知道叢集裡有幾張卡、每張卡在哪個行程、如何把SchedulerOutput序列化過去——排程邏輯會和分散式拓撲糾纏在一起。Executor把這個職責抽出來：EngineCore 只管呼叫execute_model(scheduler_output)，剩下的「發給誰、怎麼發、收幾個結果」由 Executor 決定。

類別階層與欄位

Executor是一個抽象基底類別，其類別層級欄位直接編碼了後端能力📎 vllm/v1/executor/abstract.py:48-49：

uses_ray: bool = False  # whether the executor uses Ray for orchestration.
supports_pp: bool = False  # whether the executor supports PP

這兩個旗標不是裝飾性的——上層程式碼會讀取它們來決定是否啟用某些最佳化路徑。__init__中初始化了sleeping_tags、kv_output_aggregator、ec_output_aggregator三個狀態欄位📎 vllm/v1/executor/abstract.py:119-120，分別用於睡眠模式標籤追蹤、KV 連接器輸出聚合、編碼器連接器輸出聚合。

後端選擇：get_class的分支路由

get_class是一個靜態工廠，根據distributed_executor_backend配置回傳具體 Executor 類別📎 vllm/v1/executor/abstract.py:51-96。它的分支結構值得細看：

• 若配置本身是一個type，驗證其是否為Executor子類別後直接使用📎 vllm/v1/executor/abstract.py:52-61；
• "ray"分支下還有二級分支：VLLM_USE_RAY_V2_EXECUTOR_BACKEND為真時用RayExecutorV2，否則用RayDistributedExecutor 📎 vllm/v1/executor/abstract.py:64-72；
• "mp"映射到MultiprocExecutor，"uni"映射到UniProcExecutor 📎 vllm/v1/executor/abstract.py:73-80；
• 字串形式的自訂後端透過resolve_obj_by_qualname動態解析📎 vllm/v1/executor/abstract.py:85-90。

flowchart TD
    start["Executor.get_class(vllm_config)"] --> check_type{"backend 是 type?"}
    check_type -->|是| verify_sub{"issubclass(Executor)?"}
    verify_sub -->|否| err_type["raise TypeError"]
    verify_sub -->|是| use_direct["executor_class = backend"]
    check_type -->|否| check_ray{"backend == 'ray'?"}
    check_ray -->|是| ray_v2{"VLLM_USE_RAY_V2?"}
    ray_v2 -->|是| use_rayv2["RayExecutorV2"]
    ray_v2 -->|否| use_ray["RayDistributedExecutor"]
    check_ray -->|否| check_mp{"backend == 'mp'?"}
    check_mp -->|是| use_mp["MultiprocExecutor"]
    check_mp -->|否| check_uni{"backend == 'uni'?"}
    check_uni -->|是| use_uni["UniProcExecutor"]
    check_uni -->|否| check_ext{"backend == 'external_launcher'?"}
    check_ext -->|是| use_ext["ExecutorWithExternalLauncher"]
    check_ext -->|否| check_str{"backend 是 str?"}
    check_str -->|是| resolve["resolve_obj_by_qualname"]
    check_str -->|否| err_unknown["raise ValueError"]

Step-by-Step：一次execute_model的呼叫流

代入場景：EngineCore 完成一步排程，拿到SchedulerOutput，呼叫executor.execute_model(scheduler_output)。

Executor.execute_model的實作極簡📎 vllm/v1/executor/abstract.py:237-238：

def execute_model(
    self, scheduler_output: SchedulerOutput, non_block: bool = False
) -> ModelRunnerOutput | None | Future[ModelRunnerOutput | None]:
    output = self.collective_rpc(
        "execute_model", args=(scheduler_output,), non_block=non_block
    )
    return output[0]

sample_tokens走同樣的模式📎 vllm/v1/executor/abstract.py:257-258，但回傳型別不含None——取樣必然產出結果。這兩個方法的分工對應了 vLLM v1 的「執行-取樣分離」設計：execute_model可能回傳None（表示前向已提交但取樣延後），此時狀態被暫存在ExecuteModelState中。

設計思考

collective_rpc被宣告為@abstractmethod 📎 vllm/v1/executor/abstract.py:186-192，意味著不同後端必須自己實作「如何把 RPC 發到 Worker」。MultiprocExecutor用共享記憶體佇列，RayDistributedExecutor用 Ray actor 呼叫，UniProcExecutor直接本地呼叫。這種抽象讓上層程式碼完全不需要關心分散式細節。

一個容易忽略的細節：supported_tasks被標記為@cached_property 📎 vllm/v1/executor/abstract.py:306-309，註解直言「避免不必要的 RPC 呼叫」。因為get_supported_tasks需要跨行程通訊，而任務列表在模型生命週期內不變，快取是正確且必要的優化。

5.2 GPUModelRunner：從 SchedulerOutput 到輸入張量

直覺模型

GPUModelRunner是「翻譯官」：它把SchedulerOutput裡的邏輯描述（請求 ID、token 數、塊 ID）翻譯成 GPU 能直接消費的物理張量。若沒有它，模型層就得自己處理「第 3 個請求的第 7 個 token 在哪個 KV 槽位」這種問題——這是災難性的關注點洩漏。

核心狀態與記憶體佈局

GPUModelRunner繼承自三個 Mixin📎 vllm/v1/worker/gpu_model_runner.py:479-480：LoRAModelRunnerMixin、KVConnectorModelRunnerMixin、ECConnectorModelRunnerMixin，分別提供 LoRA 適配、KV 連接器、編碼器連接器能力。

__init__中快取了全部配置物件📎 vllm/v1/worker/gpu_model_runner.py:488-498，並初始化了幾個關鍵旗標：

• check_ep_fault：僅當資料平行 > 1 且是 MoE 模型時，查詢 EP all2all 管理器是否支援容錯📎 vllm/v1/worker/gpu_model_runner.py:507-509；
• is_pooling_model：由runner_type == "pooling"決定📎 vllm/v1/worker/gpu_model_runner.py:515；
• enable_prompt_embeds：是否啟用 prompt embedding 輸入📎 vllm/v1/worker/gpu_model_runner.py:516。

ExecuteModelState是一個NamedTuple，承載execute_model()與sample_tokens()之間的臨時狀態📎 vllm/v1/worker/gpu_model_runner.py:463-476。它的欄位設計揭示了執行-取樣分離的本質：logits、hidden_states、sample_hidden_states是前向產物，spec_decode_metadata、slot_mappings是取樣階段仍需的元資料。註解明確說這是「在 execute_model() 回傳 None 後傳遞的臨時快取狀態」📎 vllm/v1/worker/gpu_model_runner.py:464-464。

Step-by-Step：_update_states如何同步快取狀態

代入場景：排程器決定本步處理請求 A（新請求）、B（上一步的 decode 繼續）、C（被搶佔後恢復），同時請求 D 已完成。

第一步：清理已完成請求。遍歷finished_req_ids，從self.requests字典彈出狀態，從input_batch移除📎 vllm/v1/worker/gpu_model_runner.py:1202-1217。注意註解指出的邊界情況：finished_req_ids和scheduled_req_ids可能重疊——當請求被中止後又以相同 ID 重新提交時，它們被視為兩個不同請求📎 vllm/v1/worker/gpu_model_runner.py:1211-1215。

第二步：清零新分配的 KV 塊。若new_block_ids_to_zero非空，呼叫_zero_block_ids清零顯存，防止陳舊 NaN 污染注意力或 SSM 計算📎 vllm/v1/worker/gpu_model_runner.py:1219-1222。這是 PagedAttention 塊重用的安全前提。

第三步：計算未排程請求集合。這是最容易出錯的一步📎 vllm/v1/worker/gpu_model_runner.py:1238-1247：

scheduled_req_ids = scheduler_output.num_scheduled_tokens.keys()
cached_req_ids = self.input_batch.req_id_to_index.keys()
resumed_req_ids = scheduler_output.scheduled_cached_reqs.resumed_req_ids
unscheduled_req_ids = cached_req_ids - (scheduled_req_ids - resumed_req_ids)

註解解釋了為什麼是scheduled_req_ids - resumed_req_ids而非直接scheduled_req_ids：通常cached_req_ids和resumed_req_ids不相交，但在reset_prefix_cache觸發的強制搶佔場景下，恢復的請求需要先從持久批中清除再重新加入📎 vllm/v1/worker/gpu_model_runner.py:1241-1246。

第四步：處理新請求。對每個scheduled_new_reqs，建構CachedRequestState 📎 vllm/v1/worker/gpu_model_runner.py:1295-1308。若取樣類型是RANDOM_SEED，建立帶種子的torch.Generator 📎 vllm/v1/worker/gpu_model_runner.py:1277-1284。若模型使用 M-RoPE，呼叫_init_mrope_positions預計算位置📎 vllm/v1/worker/gpu_model_runner.py:1319-1321。

第五步：更新執行中請求。對每個scheduled_cached_reqs，更新num_computed_tokens 📎 vllm/v1/worker/gpu_model_runner.py:1402，處理塊 ID 追加或替換📎 vllm/v1/worker/gpu_model_runner.py:1437-1448。若請求不在持久批中（req_index is None），加入reqs_to_add 📎 vllm/v1/worker/gpu_model_runner.py:1450-1465。

第六步：壓縮與重排。 condense()填補移除請求留下的空洞📎 vllm/v1/worker/gpu_model_runner.py:1511-1512，_may_reorder_batch讓注意力後端按需重排📎 vllm/v1/worker/gpu_model_runner.py:1513-1514，refresh_metadata()刷新批元數據📎 vllm/v1/worker/gpu_model_runner.py:1515-1516。

輸入張量準備：_prepare_input_ids的異步快路徑

_prepare_input_ids處理一個微妙問題：異步調度下，上一步的採樣 token 還在 GPU 上，本步的input_ids需要把它們填進去📎 vllm/v1/worker/gpu_model_runner.py:1767-1772。

正常路徑（prev_sampled_token_ids is None）直接拷貝 CPU 張量到 GPU📎 vllm/v1/worker/gpu_model_runner.py:1788-1794。異步路徑則遍歷請求，計算每個請求最後一個 token 在扁平化input_ids中的索引📎 vllm/v1/worker/gpu_model_runner.py:1809-1836。註釋給出了具體例子：cu_num_tokens = [2, 5, 8]、draft_tokens = [1, 2, 2]時，sample_flattened_indices = [0, 2, 5]，spec_flattened_indices = [1, 3, 4, 6, 7] 📎 vllm/v1/worker/gpu_model_runner.py:1820-1822。

有一個關鍵優化📎 vllm/v1/worker/gpu_model_runner.py:1859-1868：

if common_indices_match and max_flattened_index == (num_common_tokens - 1):
    self.input_ids.gpu[:num_common_tokens].copy_(
        self.input_batch.prev_sampled_token_ids[:num_common_tokens, 0],
        non_blocking=True,
    )
    return

當批未變且無重排時，索引是0..N-1的同一排列，可直接用單次切片拷貝，避免 scatter 開銷。這是持久批優化的直接體現。

slot_mapping與 block table

_get_slot_mappings返回兩種格式📎 vllm/v1/worker/gpu_model_runner.py:4078-4078：按 KV cache group 索引的dict[int, torch.Tensor]供注意力元數據使用，按層名索引的dict[str, torch.Tensor]供ForwardContext使用。對 encoder-only 的 KV cache group，slot mapping 是全零張量📎 vllm/v1/worker/gpu_model_runner.py:4096-4115；否則從block_table.slot_mapping.gpu切片📎 vllm/v1/worker/gpu_model_runner.py:4107-4109。未使用的尾部填充-1，註釋說明這是reshape_and_cache在全 CUDA graph 模式下的需要📎 vllm/v1/worker/gpu_model_runner.py:4118-4122。

_get_block_table對每個 KV cache group 獲取設備張量📎 vllm/v1/worker/gpu_model_runner.py:2319-2335，並用NULL_BLOCK_ID填充 CUDAGraph padding 行——塊 0 被保留作 padding📎 vllm/v1/worker/gpu_model_runner.py:2332-2334。

5.3 forward_context：跨層共享的批描述

直覺模型

forward_context是貼在教室前方的「統一通知板」：每個模型層抬頭就能看到本場考試的座位安排（attention metadata）和規則（slot mapping），不必各自去問。若沒有它，每個注意力層都得從參數裡接收這些信息——而模型層的forward簽名是固定的，無法為每層單獨傳參。

數據結構

ForwardContext是一個@dataclass 📎 vllm/forward_context.py:141-202，核心字段：

• no_compile_layers：從static_forward_context拷貝，標記不參與編譯的層📎 vllm/forward_context.py:132-137；
• attn_metadata：層名到注意力元數據的映射，DBO 模式下是長度為 2 的列表（每個 microbatch 一個）📎 vllm/forward_context.py:144-152；
• slot_mapping：層名到 slot mapping 張量的映射📎 vllm/forward_context.py:145；
• cudagraph_runtime_mode：運行時 CUDA graph 模式，默認NONE 📎 vllm/forward_context.py:155-157；
• batch_descriptor：批描述符，用於 CUDA graph 分發📎 vllm/forward_context.py:158；
• is_padding：token 軸上的布爾掩碼，True表示 padding 行📎 vllm/forward_context.py:162-165。

BatchDescriptor是另一個@dataclass(frozen=True) 📎 vllm/forward_context.py:30-57，字段設計遵循「最小化描述項」原則：num_tokens、num_reqs（PIECEWISE 模式下可為 None）、uniform（所有請求 token 數相同）、has_lora、num_active_loras。註釋解釋了num_active_loras的存在原因：當cudagraph_specialize_lora_count啟用時，每個 LoRA 數量值捕獲獨立 CUDA graph，因為fused_moe_lora等內核的 grid size 依賴此值📎 vllm/forward_context.py:60-64。

全局單例與上下文管理

_forward_context是一個模塊級全局變量📎 vllm/forward_context.py:199-201，通過override_forward_context上下文管理器在進入時保存舊值、退出時恢復📎 vllm/forward_context.py:263-274。set_forward_context是更高層的封裝📎 vllm/forward_context.py:277-394，它額外處理 DP 元數據構造、batch descriptor 自動創建、平台特定 kwargs 注入。

Step-by-Step：從execute_model到模型前向

代入場景：GPUModelRunner.execute_model已準備好所有輸入張量，即將調用模型。

在execute_model中，set_forward_context被調用📎 vllm/v1/worker/gpu_model_runner.py:4408-4420：

with (
    set_forward_context(
        attn_metadata,
        self.vllm_config,
        num_tokens=num_tokens_padded,
        num_tokens_across_dp=num_tokens_across_dp,
        cudagraph_runtime_mode=cudagraph_mode,
        batch_descriptor=batch_desc,
        ubatch_slices=ubatch_slices_padded,
        slot_mapping=slot_mappings,
        skip_compiled=has_encoder_input,
        is_padding=is_padding,
    ),
    ...
):
    model_output = self._model_forward(...)

set_forward_context內部先構造DPMetadata（若啟用 DP 或序列並行 MoE）📎 vllm/forward_context.py:299-328，再調用create_forward_context構造ForwardContext實例📎 vllm/forward_context.py:347-358，最後通過override_forward_context設置全局變量📎 vllm/forward_context.py:361-362。

模型層通過get_forward_context()讀取📎 vllm/forward_context.py:208-214。若未設置，斷言失敗並提示使用set_forward_context。

sequenceDiagram
    participant EC as EngineCore
    participant EX as Executor
    participant W as Worker
    participant MR as GPUModelRunner
    participant FC as ForwardContext
    participant M as Model Layers

    EC->>EX: execute_model(SchedulerOutput)
    EX->>W: collective_rpc("execute_model", args)
    W->>MR: execute_model(scheduler_output)
    MR->>MR: _update_states(scheduler_output)
    MR->>MR: _prepare_inputs(...)
    MR->>MR: _get_slot_mappings(...)
    MR->>FC: set_forward_context(attn_metadata, slot_mapping, ...)
    FC-->>MR: context manager entered
    MR->>M: _model_forward(input_ids, positions, ...)
    M->>FC: get_forward_context()
    FC-->>M: ForwardContext
    M-->>MR: hidden_states
    MR->>MR: compute_logits(sample_hidden_states)
    MR-->>W: ExecuteModelState / None
    W-->>EX: ModelRunnerOutput
    EX-->>EC: output[0]

設計思考

is_padding字段的設計值得注意📎 vllm/forward_context.py:162-165：註釋說「消費者可用它跳過 padding token 的工作」。這是 CUDA graph 場景下的優化——padding 行參與了圖捕獲但不應產生實際計算。

all_moe_layers與moe_layer_index是一對巧妙的 workaround📎 vllm/forward_context.py:170-195。註釋詳細解釋了問題：vllm.moe_forward自定義算子會把層名字符串硬編碼進圖，導致 torch.compile 冷啟動時間過長。解決方案是把層名列表存在ForwardContext中，自定義算子按順序彈出字符串並遞增計數器。註釋也坦承這依賴「自定義算子按順序執行且 torch.compile 不會重排」的假設📎 vllm/forward_context.py:182-184。

設計思考與生產踩坑

異步調度的狀態一致性。 _update_states在異步投機解碼下採用「樂觀假設」策略：假設上一步所有 draft token 都被接受，先擴展output_token_ids，然後註冊一個延遲修正函數📎 vllm/v1/worker/gpu_model_runner.py:1376-1384。修正函數在模型前向啟動後調用📎 vllm/v1/worker/gpu_model_runner.py:1509-1510，從 GPU 讀取實際接受數並回退num_computed_tokens 📎 vllm/v1/worker/gpu_model_runner.py:1547-1558。這個設計的精妙之處在於：修正發生在「批已啟動」之後，不阻塞前向，保持了異步流水線的連續性。

_may_reorder_batch的觸發條件。該方法首先檢查kv_cache_groups是否為空📎 vllm/v1/worker/gpu_model_runner.py:1131-1132。註釋解釋了為什麼不能簡單檢查is_attention_free：Mamba 模型也是 attention-free 的，但它用 KV cache 保存內部狀態📎 vllm/v1/worker/gpu_model_runner.py:1116-1139。只有真正沒有 KV cache group 的模型才跳過重排。

_prepare_input_ids的索引計算陷阱。當批中既有上一步的 decode 請求又有新請求時，num_common_tokens < total_without_spec，需要先拷貝 CPU 張量再 scatter📎 vllm/v1/worker/gpu_model_runner.py:1849-1854。若num_common_tokens == 0，說明沒有任何請求與上一步重疊，直接返回📎 vllm/v1/worker/gpu_model_runner.py:1855-1858。這兩個分支的區分至關重要——漏掉任何一個都會導致input_ids部分未初始化。

AsyncGPUModelRunnerOutput的流同步。輸出拷貝在獨立 CUDA stream 上進行📎 vllm/v1/worker/gpu_model_runner.py:308-328，使用blocking=True的 Event 避免忙輪詢 CUDA 驅動鎖📎 vllm/v1/worker/gpu_model_runner.py:296-298。get_output()中先 synchronize 再釋放設備張量引用📎 vllm/v1/worker/gpu_model_runner.py:336-340，順序不能顛倒——否則張量可能在拷貝完成前被回收。

本章小結

本章追蹤了SchedulerOutput從 EngineCore 到 GPU 前向的完整路徑。Executor透過collective_rpc把調度結果廣播到所有 Worker，GPUModelRunner的_update_states同步緩存狀態、_prepare_inputs構造輸入張量、_get_slot_mappings生成 KV 槽位映射，最後set_forward_context把批描述注入全局上下文供模型各層消費。異步調度路徑透過樂觀假設 + 延遲修正保持了流水線連續性，而ForwardContext的全局單例設計解決了模型層簽名固定與跨層元數據注入之間的矛盾。

本章思考與自測

至此，我們走完了從 SchedulerOutput 到 GPU 前向傳播的完整路徑：Executor 分發、Worker 執行、GPUModelRunner 將邏輯清單翻譯為物理張量，並透過 forward_context 將批描述注入每一層。然而，模型前向傳播中最耗時的部分——注意力計算——尚未展開。下一章將深入注意力後端，看 attn_metadata 中的 block table 和 slot mapping 如何被 PagedAttention 內核消費，以及 FlashAttention、FlashInfer、Triton 等不同後端如何透過統一接口被選擇和調度。

上一章我們看到 GPUModelRunner 如何把調度結果翻譯成 input_ids、slot_mapping 和 block_table 等物理張量，並透過 forward_context 注入每一層。但真正消耗 GPU 時間的大頭——注意力計算——還懸在半空。attn_metadata 裡那些張量究竟被誰消費？FlashAttention、FlashInfer、Triton 這些實現憑什麼能在同一套模型程式碼下互換？答案在 AttentionBackend 抽象層。它把「注意力怎麼算」與「模型怎麼調」解耦：模型層只持有 AttentionImpl 引用，呼叫統一的 forward(query, key, value, kv_cache, attn_metadata, output)；而具體後端負責把 block_table、slot_mapping、seq_lens 翻譯成自家核心能吃的參數。本章以 FlashAttentionBackend 為主線，因為它同時覆蓋了 PagedAttention 的 gather 語意、CUDA Graph 相容、級聯注意力、DCP 分散式上下文等最豐富的分支。讀透它，其他後端只是參數映射的變體。這種「後端註冊 + 統一介面」的設計動機很直接：注意力核心演進極快（FA2→FA3→FA4，FlashInfer 迭代，Triton 自研），如果模型層直接依賴某個具體核心，每次核心升級都要改模型程式碼。抽象層把變化隔離在 get_impl_cls() 一個工廠方法後面。

後端選擇：能力宣告與元資料建構

直覺模型

把AttentionBackend想成招聘啟事：它不幹活，只宣告「我能處理哪些 dtype、哪些 head_size、哪些 KV cache 量化格式、哪些 attention 類型」。調度器拿著模型配置來匹配，匹配失敗就換下一個候選人。若沒有這層宣告，系統會在執行時才發現「這個 head_size 核心不支援」，直接崩潰。

能力矩陣：欄位即契約

FlashAttentionBackend的類別屬性就是它的能力邊界。supported_dtypes限定 fp16/bf16📎 vllm/v1/attention/backends/flash_attn.py:287-287；supported_kv_cache_dtypes額外允許 fp8 系列📎 vllm/v1/attention/backends/flash_attn.py:298-299。但「宣告支援」不等於「無條件支援」——supports_kv_cache_dtype對量化 KV 會進一步委託給flash_attn_supports_kv_cache_dtype做裝置相關判斷📎 vllm/v1/attention/backends/flash_attn.py:431-438。

更精細的是supports_combination：它接收 head_size、dtype、block_size、use_mla、has_sink 等一整套組合參數，回傳None表示可用，回傳字串表示拒絕原因📎 vllm/v1/attention/backends/flash_attn.py:454-507。例如 sink 在算力 < 9.0 上被拒📎 vllm/v1/attention/backends/flash_attn.py:467-468，SM90 上 FP8 KV 配 mm_prefix 必須走 Triton📎 vllm/v1/attention/backends/flash_attn.py:472-472。這種「回傳原因字串」的設計讓上層能給出可診斷的報錯，而非靜默回退。

block_size 的選擇同樣由能力驅動。預設回傳MultipleOf(16)，但 SM90 FP8-KV 強制 64📎 vllm/v1/attention/backends/flash_attn.py:297-324，FA4 的 head_size=256 核心強制FA4_HD256_PAGE_SIZE 📎 vllm/v1/attention/backends/flash_attn.py:326-352。這解釋了為什麼 KV cache 的 block 大小不是隨便定的——它被核心的 TMA tile 尺寸反向約束。

元資料結構：FlashAttentionMetadata 的欄位佈局

FlashAttentionMetadata是 dataclass，欄位分四組📎 vllm/v1/attention/backends/flash_attn.py:511-566：

第一組是基礎批描述：num_actual_tokens（去掉 padding 的真實 token 數）、max_query_len、query_start_loc（前綴和，用於 varlen 核心定位每條序列的起止）、seq_lens、block_table、slot_mapping 📎 vllm/v1/attention/backends/flash_attn.py:520-526。注意原始碼註解裡那張 ASCII 圖📎 vllm/v1/attention/backends/flash_attn.py:512-518，它精確區分了context_len（歷史 KV）、query_len（本次新增）、seq_len（兩者之和）——這是理解 varlen 核心參數的關鍵。

第二組是級聯注意力欄位：use_cascade、common_prefix_len、cu_prefix_query_lens等📎 vllm/v1/attention/backends/flash_attn.py:528-533。

第三組是 DCP（Decode Context Parallel）欄位：max_dcp_context_kv_len、dcp_context_kv_lens，以及區分 decode/prefill 請求數的計數器📎 vllm/v1/attention/backends/flash_attn.py:535-544。

第四組是可選調度與特殊遮罩：scheduler_metadata（FA3 AOT 調度用）、causal（可為 bool 或張量，支援逐序列因果）、mm_prefix_query_range_tensor（多模態雙向範圍）、R-SWA 相關欄位📎 vllm/v1/attention/backends/flash_attn.py:546-566。

build() 的 Step-by-Step

代入場景：一個混合批次，3 條 decode 序列 + 2 條 prefill 序列，無級聯、無 DCP。

第一步，從common_attn_metadata解包基礎張量📎 vllm/v1/attention/backends/flash_attn.py:824-832。第二步，決定是否啟用 AOT 排程：aot_schedule = self.aot_schedule and not fast_build and not envs.VLLM_BATCH_INVARIANT 📎 vllm/v1/attention/backends/flash_attn.py:836-838。self.aot_schedule在__init__裡由get_flash_attn_version() == 3決定📎 vllm/v1/attention/backends/flash_attn.py:709-709——只有 FA3 支援預計算排程中繼資料。第三步，首次 build 時惰性填充aot_sliding_window：遍歷所有FlashAttentionImpl層收集滑窗配置，若配置唯一則採用，若多於一種則關閉 AOT📎 vllm/v1/attention/backends/flash_attn.py:848-851。

第四步，計算max_num_splits。預設 0（讓 FA3 用啟發式），僅當啟用 full CUDA graph 且 token 數在捕獲範圍內時才設為self.max_num_splits 📎 vllm/v1/attention/backends/flash_attn.py:856-866。註解解釋了原因：num_splits > 1會分配[num_splits, num_heads, num_tokens, head_size]的中間緩衝，顯存代價高，只在 CUDA graph 場景值得📎 vllm/v1/attention/backends/flash_attn.py:862-865。

第五步，走非級聯非 DCP 分支，呼叫_get_scheduler_metadata生成 FA3 的排程中繼資料📎 vllm/v1/attention/backends/flash_attn.py:976-986。第六步，_store_scheduler_metadata處理 CUDA graph 場景：把新中繼資料拷進預分配緩衝，並把剩餘部分清零📎 vllm/v1/attention/backends/flash_attn.py:671-684。清零這一步至關重要——註解明確指出，否則某些 thread block 會讀到無效中繼資料並覆寫輸出緩衝📎 vllm/v1/attention/backends/flash_attn.py:671-672。

第七步，構造FlashAttentionMetadata並返回📎 vllm/v1/attention/backends/flash_attn.py:992-1015。

flowchart TD
    start["build(common_prefix_len, common_attn_metadata)"] --> unpack["解包 query_start_loc / seq_lens / block_table / slot_mapping"]
    unpack --> aot{"aot_schedule 且非 fast_build 且非 BATCH_INVARIANT?"}
    aot -->|是| sw_check{"aot_sliding_window 已初始化?"}
    aot -->|否| maxsplit
    sw_check -->|否, 首次| collect["_get_sliding_window_configs 收集层滑窗"]
    collect --> sw_unique{"配置数量 == 1?"}
    sw_unique -->|是| set_sw["设置 aot_sliding_window"]
    sw_unique -->|否, >1| disable_aot["self.aot_schedule = False"]
    set_sw --> maxsplit
    disable_aot --> maxsplit
    sw_check -->|是| maxsplit["计算 max_num_splits"]
    maxsplit --> cg_check{"use_full_cuda_graph 且 tokens <= max_cudagraph_size?"}
    cg_check -->|是| set_splits["max_num_splits = self.max_num_splits"]
    cg_check -->|否| zero_splits["max_num_splits = 0"]
    set_splits --> branch
    zero_splits --> branch
    branch{"dcp_world_size > 1?"}
    branch -->|是| dcp_path["计算 dcp_context_kv_lens, 可能 skip"]
    branch -->|否| cascade_check{"common_prefix_len > 0?"}
    cascade_check -->|是| cascade_path["构造 prefix/suffix 双份 scheduler_metadata"]
    cascade_check -->|否| normal_path["_get_scheduler_metadata 单份"]
    dcp_path --> store
    cascade_path --> store
    normal_path --> store
    store["_store_scheduler_metadata: CUDA graph 时拷入预分配缓冲并清零尾部"] --> build_meta["构造 FlashAttentionMetadata"]
    build_meta --> mm_check{"mm_req_doc_ranges 非空?"}
    mm_check -->|是| fill_mm["fill_mm_prefix_query_ranges + 拷贝到 GPU"]
    mm_check -->|否| rswa_check
    fill_mm --> rswa_check{"rswa_window 非空?"}
    rswa_check -->|是| copy_rswa["拷贝 prefix_lens 到持久缓冲"]
    rswa_check -->|否| done
    copy_rswa --> done["返回 attn_metadata"]

---

forward()：從中繼資料到核心呼叫的完整鏈路

直覺模型

forward()是後端的「總裝車間」：它拿到模型層算好的 Q/K/V、KV cache 張量、以及上一步構建的中繼資料，把 KV cache 的物理佈局調整成核心期望的形狀，然後分派到具體核心。若沒有這一步，核心會讀到錯誤的記憶體佈局，輸出靜默錯誤——比崩潰更難查。

KV cache 的記憶體佈局變換

vLLM 的 KV cache 物理形狀是[num_blocks, num_kv_heads, block_size, 2 * head_size]——K 和 V 拼在最後一維📎 vllm/v1/attention/backends/flash_attn.py:1246-1247。但 FlashAttention 核心期望 K 和 V 分開，且佈局為[num_blocks, block_size, num_kv_heads, head_size]。

變換發生在forward()開頭：kv_cache.transpose(1, 2).split(self.head_size, dim=-1) 📎 vllm/v1/attention/backends/flash_attn.py:1310-1310。transpose(1,2)把[blocks, heads, block_size, 2D]變成[blocks, block_size, heads, 2D]，split沿最後一維切成 K 和 V。注意transpose只改 stride 不搬資料，所以後續核心必須支援非連續存取。

緊接著是canonicalize_singleton_dim_strides 📎 vllm/v1/attention/backends/flash_attn.py:1310-1310。註解點明了動機：當num_kv_heads=1（TP 場景常見）時，size-1 維度的 stride 是退化的，而 FA3/FA4 在 H100+ 上用 TMA，要求 stride 至少 16 位元組對齊📎 vllm/v1/attention/backends/flash_attn.py:1310-1310。這是一個典型的「邏輯上等價、物理上不合法」的陷阱。

非級聯路徑的參數流轉

進入if not attn_metadata.use_cascade分支後，參數逐一映射📎 vllm/v1/attention/backends/flash_attn.py:1326-1342：cu_seqlens_q = query_start_loc，seqused_k = seq_lens，block_table = attn_metadata.block_table。descale_shape取(batch_size, num_kv_heads)，用於 FP8 量化的 scale 廣播——註解說明 flash-attn 期望 descale 形狀是(num_sequences, num_kv_heads)，用.expand()避免複製📎 vllm/v1/attention/backends/flash_attn.py:1258-1258。

然後是滑窗的對稱化處理。_maybe_symmetrize_window的邏輯：因果滑窗(w, 0)在非因果場景下要變成(w, w)，讓雙向 query 能往兩個方向看📎 vllm/v1/attention/backends/flash_attn.py:587-589。註解還強調「層自己的 window 優先於 group 的 window」，因為一個 KV cache group 可能同時容納視窗層和全局層（如 Gemma-3 關閉 hybrid KV cache manager 時）📎 vllm/v1/attention/backends/flash_attn.py:1362-1365。

遮罩分支：mm_prefix 與 R-SWA

當mm_prefix_query_ranges非空且滿足 FA4 + 靜態因果條件時，程式碼構造 CuTE-DSL 的mask_mod 📎 vllm/v1/attention/backends/flash_attn.py:1374-1407。關鍵動作是causal = False和sliding_window_size = None 📎 vllm/v1/attention/backends/flash_attn.py:1406-1407。註解解釋了原因：mm_prefix 的語義是(causal ∧ window) ∨ bidirectional-range，不是 causal 的子集；FA #155 之後設定 mask_mod 不再自動清除 causal/local，呼叫方必須顯式關閉，否則內建 causal 路徑會短路 mask_mod📎 vllm/v1/attention/backends/flash_attn.py:1402-1405。

_make_mm_prefix_mask_mod用functools.cache快取📎 vllm/v1/attention/backends/flash_attn.py:1793-1802。註解給出硬核理由：FA4 的hash_callable會把閉包單元的repr()混入編譯鍵，嵌套的_load_q_range每次呼叫位址不同，會導致每次 forward 都觸發完整 JIT 重編譯📎 vllm/v1/attention/backends/flash_attn.py:1793-1802。這是生產環境效能陷阱的典型樣本。

遮罩內部有個座標轉換細節：FA4 傳的是局部q_idx（當前 prefill chunk 內 0-based），而kv_idx是絕對位置。程式碼用q_abs = q_idx + seqlen_k - seqlen_q恢復絕對位置📎 vllm/v1/attention/backends/flash_attn.py:1859-1865。__vec_size__ = 1的設定也有講究：_load_q_range讀 lane 0，一次呼叫不能跨 query 行📎 vllm/v1/attention/backends/flash_attn.py:1897-1897。

R-SWA 的 mask_mod 類似，但語義是causal & (in_prefix | in_window) 📎 vllm/v1/attention/backends/flash_attn.py:1945-1948，且use_fast_sampling = True讓 FA4 跳過完全被遮罩的 KV block，不載入其資料📎 vllm/v1/attention/backends/flash_attn.py:1950-1950。

FA4 hd256 的特殊處理

當self.fa4_hd256為真時，程式碼強制 page 對齊：num_pages = cdiv(max_seqlen_k, FA4_HD256_PAGE_SIZE)，max_seqlen_k向上取整到頁邊界，block_table截斷到精確頁數，num_splits = 1 📎 vllm/v1/attention/backends/flash_attn.py:1442-1448。註解說明 hd256 核心要求頁對齊長度、精確寬度 block table、且不支援 SplitKV。

最終呼叫_FA4_DENSE_ATTENTION_KERNEL(...)，把 q、k、v、out、cu_seqlens_q、seqused_k、block_table、softcap、mask_mod、aux_tensors 等一併傳入📎 vllm/v1/attention/backends/flash_attn.py:1450-1475。

KV cache 寫入：do_kv_cache_update

forward()唯讀 KV cache，寫入由do_kv_cache_update完成。它呼叫reshape_and_cache_flash，用slot_mapping把新算出的 K/V 散射寫入 cache📎 vllm/v1/attention/backends/flash_attn.py:1532-1541。註解指出：key/value是 padded 的而slot_mapping不是，但不需要手動切片，因為 op 用slot_mapping的 shape 決定實際 token 數📎 vllm/v1/attention/backends/flash_attn.py:1527-1531。這裡不做 stride 規範化，因為沒有 TMA 內核參與📎 vllm/v1/attention/backends/flash_attn.py:1520-1521。

sequenceDiagram
    participant Model as 模型层 Attention
    participant Impl as FlashAttentionImpl
    participant KVC as kv_cache 张量
    participant Kernel as flash_attn_varlen_func
    Model->>Impl: forward(query, key, value, kv_cache, attn_metadata, output)
    Impl->>Impl: output_scale 非空? 抛 NotImplementedError
    Impl->>Impl: attn_metadata is None? 返回 output.fill_(0)
    Impl->>KVC: transpose(1,2).split(head_size)
    KVC-->>Impl: key_cache, value_cache
    Impl->>Impl: canonicalize_singleton_dim_strides(key_cache)
    Impl->>Impl: use_cascade?
    alt 非级联
        Impl->>Impl: 映射 cu_seqlens_q / seqused_k / block_table
        Impl->>Impl: _maybe_symmetrize_window
        Impl->>Impl: mm_prefix 或 R-SWA? 构造 mask_mod
        Impl->>Kernel: _FA4_DENSE_ATTENTION_KERNEL(q, k, v, out, ...)
        Kernel-->>Impl: output 就地写入
    else 级联
        Impl->>Kernel: cascade_attention(prefix + suffix 两次调用)
        Kernel-->>Impl: merge_attn_states 合并
    end
    Impl-->>Model: output

---

設計思考：為什麼這樣寫

CUDA Graph 兼容性是元數據設計的隱形約束。_store_scheduler_metadata的「拷入 + 清零尾部」模式📎 vllm/v1/attention/backends/flash_attn.py:671-684反覆出現在 R-SWA 持久緩衝📎 vllm/v1/attention/backends/flash_attn.py:787-798和 mm_prefix 暫存區📎 vllm/v1/attention/backends/flash_attn.py:800-813中。共同模式是：在__init__裡預分配最大尺寸的持久緩衝，build()裡只做拷貝不做分配。原因在註釋裡點明——CUDA graph 捕獲期間不能有分配操作📎 vllm/v1/attention/backends/flash_attn.py:1044-1046。

DCP 與 fused draft decode 的互斥。supports_draft_decode_metadata_update = self.dcp_world_size == 1 📎 vllm/v1/attention/backends/flash_attn.py:742-742。註釋解釋：fused draft decode 跨 draft 步複用捕獲的元數據對象，但 DCP 的 build-time 主機側決策（如skip_dcp_context_attention()）會改變元數據形狀，這些 Python 字段在 graph replay 之間不會原地刷新📎 vllm/v1/attention/backends/flash_attn.py:736-741。這是一個「性能優化與正確性衝突時選擇正確性」的典型取捨。

級聯注意力的啟發式門檻。use_cascade_attention用一串閾值過濾：common_prefix_len < 256 直接拒絕📎 vllm/v1/attention/backends/flash_attn.py:1967-1967，alibi/sliding_window/local_attention 不支持📎 vllm/v1/attention/backends/flash_attn.py:1978-1979，請求數 < 8 拒絕📎 vllm/v1/attention/backends/flash_attn.py:1982-1984，DCP 場景禁用📎 vllm/v1/attention/backends/flash_attn.py:1985-1987。通過後還要用粗略性能模型比較 cascade 與 FlashDecoding 的 CTA 數和 wave 數📎 vllm/v1/attention/backends/flash_attn.py:2011-2029。註釋坦承這個模型「very rough」📎 vllm/v1/attention/backends/flash_attn.py:2009-2010。

生產踩坑點：forward()裡有一段醒目註釋，警告 piece-wise CUDA graph 下此方法在 eager 模式執行，view/slice等看似無 GPU 操作的方法實際很慢，改動必須 benchmark📎 vllm/v1/attention/backends/flash_attn.py:1277-1284。這解釋了為什麼代碼裡大量使用[:num_actual_tokens]切片而非更「優雅」的寫法——每一處都是性能權衡的結果。

---

本章小結

本章沿FlashAttentionBackend走完了注意力後端的完整生命週期：能力聲明（supports_*系列）→ 元數據構建（build()把CommonAttentionMetadata翻譯成FlashAttentionMetadata）→ 內核調用（forward()變換 KV cache 佈局、構造掩碼、分派到 FA 內核）。核心機制包括：KV cache 的transpose+split佈局變換、退化 stride 的規範化、CUDA graph 下的持久緩衝模式、mm_prefix/R-SWA 的 CuTE-DSL 掩碼構造、以及級聯注意力的啟發式決策。

關鍵設計原則：能力聲明與實現分離、CUDA graph 兼容性驅動元數據預分配、性能優化與正確性衝突時優先正確性（DCP 禁用 fused draft decode）。

下一章將轉向採樣與輸出：logits如何經處理器鏈（溫度、top-p、懲罰項）變成 token，結構化輸出如何約束解碼，以及流式返回如何與調度器協作。

本章思考與自測

至此，注意力後端從抽象介面到核心實現的完整鏈路已經打通：模型層透過 AttentionImpl 統一呼叫，後端負責將 block_table、slot_mapping 等元資料翻譯為具體核心參數，而 FlashAttentionBackend 的 PagedAttention 實現則展示了分頁 KV Cache 下的 gather 語義與 CUDA Graph 相容策略。但注意力計算產出的只是隱藏狀態，模型最終要輸出的是下一個 token。這些隱藏狀態如何變成 logits，logits 又如何經過取樣與後處理，最終以串流文本返回給客戶端？下一章將追蹤這最後一公里。

上一章我們追蹤了注意力後端如何把 block table 翻譯成核心參數，在非連續顯存上完成 gather 式注意力計算。但注意力產出的只是隱藏狀態——模型真正要交付給使用者的是下一個 token 的文本。本章追蹤這最後一公里：隱藏狀態經 lm_head 投影為 logits 後，如何穿過一條精心排序的處理器鏈（溫度、懲罰、top-k/top-p、結構化約束），被取樣成 token id，再經 detokenizer 還原為文本並串流推送。這條鏈路上任何一步順序錯亂或狀態洩漏，都會讓輸出品質靜默劣化。

Sampler：處理器鏈的順序即正確性

直覺模型：Sampler 像一條裝配流水線，logits 是待加工的毛坯。流水線上每個工位（processor）都會修改毛坯，而工位的先後順序直接決定成品——先削再磨和先磨再削得到的是兩種東西。若沒有這條鏈，模型只能輸出原始機率分佈，使用者拿到的就是無法控制溫度、無法抑制重複、無法約束格式的「裸取樣」。

資料結構與記憶體佈局

Sampler 本身是nn.Module，但它的核心狀態極薄：只持有topk_topp_sampler子模組、logprobs_mode與use_fp64_gumbel標誌📎 vllm/v1/sample/sampler.py:61-64。真正的批級狀態全部封裝在SamplingMetadata中，由 forward 參數傳入。這種「無狀態 Sampler + 外部元資料」的設計是刻意的：Sampler 實例在引擎生命週期內只建立一次，而每個 decode step 的批組成都在變，把狀態外置才能讓 Sampler 被 CUDA Graph 捕獲後安全重放。

關鍵常量是_SAMPLING_EPS = 1e-5 📎 vllm/v1/sample/sampler.py:18。它同時充當兩個語義：溫度低於此值視為貪心，以及apply_temperature中防止除零的兜底。

Step-by-Step Walkthrough

代入場景：一個 batch 中混合了貪心請求與隨機取樣請求，部分請求還開了 logprobs。

第一步，快照原始 logprobs。在施加任何懲罰或溫度之前，若請求需要 logprobs，先按logprobs_mode決定快照內容📎 vllm/v1/sample/sampler.py:84-93。注意註解明確點出與 V0 的差異：V1 用原始 logits（懲罰與溫度之前）計算 top-k logprobs📎 vllm/v1/sample/sampler.py:72-77。這是語意契約——使用者看到的 logprob 應反映模型真實分佈，而非被懲罰扭曲後的分佈。

第二步，統一轉到 float32。 📎 vllm/v1/sample/sampler.py:95-96無論輸入是 bf16 還是 fp16，都上轉 float32。原因是後續的 log_softmax、top-k、累積機率在低精度下會累積誤差，尤其在 vocab 達 15 萬時。

第三步，非 argmax 不變處理器鏈。 apply_logits_processors依次施加：allowed token 白名單遮罩、bad words 排除、non_argmax_invariant處理器、懲罰項📎 vllm/v1/sample/sampler.py:391-404。這裡的分類是核心設計——non_argmax_invariant指那些會改變貪心結果的處理器（如 min_tokens、logit_bias），它們必須在貪心取樣之前生效；而argmax_invariant處理器（如 min_p）不改變 argmax，可以推遲到溫度之後。

第四步，取樣。 sample方法先判斷是否全隨機📎 vllm/v1/sample/sampler.py:256-271：若all_greedy，直接 argmax 返回；否則先算貪心結果備用，再施加溫度、argmax 不變處理器、top-k/top-p📎 vllm/v1/sample/sampler.py:275-291。最後用torch.where按溫度閾值在貪心與隨機結果間選擇📎 vllm/v1/sample/sampler.py:305-306，並複用greedy_sampled張量作為輸出緩衝，避免額外分配。

第五步，收集 logprobs 並封裝輸出。按num_logprobs分三種情況：None 只返回指定 token 的 logprobs；-1 返回全量未排序 logprobs；否則 top-k📎 vllm/v1/sample/sampler.py:120-131。最終 token id 轉 int32 壓縮體積，擴展為[num_requests, 1]的二維張量📎 vllm/v1/sample/sampler.py:138-148。

flowchart TD
    in_logits["logits (bf16/fp16)"] --> snap{"需要 logprobs?"}
    snap -->|是| raw["compute_logprobs / clone<br/>raw_logprobs 快照"]
    snap -->|否| f32
    raw --> f32["logits.to(float32)"]
    f32 --> proc["apply_logits_processors"]
    proc --> mask{"allowed_token_ids_mask?"}
    mask -->|是| fill["masked_fill_(-inf)"]
    mask -->|否| bad
    fill --> bad{"bad_words_token_ids?"}
    bad -->|是| apply_bad["apply_bad_words"]
    bad -->|否| noninv
    apply_bad --> noninv["non_argmax_invariant 处理器"]
    noninv --> pen["apply_penalties"]
    pen --> sample["sample()"]
    sample --> allg{"all_greedy?"}
    allg -->|是| greedy["greedy_sample (argmax)"]
    allg -->|否| temp["apply_temperature"]
    temp --> arginv["argmax_invariant 处理器"]
    arginv --> topp["topk_topp_sampler"]
    topp --> where["torch.where(temp < EPS)"]
    greedy --> out
    where --> out["SamplerOutput<br/>sampled_token_ids"]

設計思考與踩坑

為什麼懲罰項必須在溫度之前？溫度是對分佈的縮放，懲罰是對特定 token 的加減分。若先縮放再懲罰，懲罰的絕對幅度會被溫度放大或縮小，導致同一組懲罰參數在不同溫度下行為不一致。V1 把懲罰固定在溫度前，保證了參數語意的穩定性。

mark_unbacked的編譯陷阱。在gather_logprobs中，batched_count_greater_than被編譯，而 batch 維度從 1 變到 ≥2 時會觸發 dynamo 的 0/1 特化重編譯📎 vllm/v1/sample/sampler.py:345-348。mark_unbacked把該維度標記為完全符號化，避免這次重編譯。生產環境中若看到 decode 首個請求後突然卡頓一次，很可能就是這類重編譯。

gpu_sync_allowed的同步邊界。 batched_count_greater_than內部可能觸發 GPU 同步，vLLM 用gpu_sync_allowed(first_only=True)上下文顯式宣告「這裡允許同步，但只允許第一次」📎 vllm/v1/sample/sampler.py:345-348。若在 CUDA Graph 捕獲區內意外同步，會導致捕獲失敗——這是排查圖捕獲問題的關鍵線索。

結構化輸出：位元遮罩與語法的雙軌狀態機

直覺模型：結構化輸出像給取樣器戴上一副「語法眼鏡」——每一步只能看見符合 JSON schema 或文法的 token。若沒有它，模型可能生成語法錯誤的 JSON，下游解析器直接崩潰。vLLM 的實現精髓在於：語法狀態機在 CPU 側推進，而約束以位元遮罩形式傳給 GPU 側取樣。

資料結構與記憶體佈局

StructuredOutputManager是引擎級單例，持有backend（xgrammar/guidance/outlines/lm-format-enforcer 之一）、reasoner_cls與兩個執行緒池📎 vllm/v1/structured_output/__init__.py:39-98。

位元遮罩是核心資料結構：_grammar_bitmask是形狀為[max_batch_size * (1 + max_num_spec_tokens), vocab_size/32]的 int32 張量📎 vllm/v1/structured_output/__init__.py:327-336。每個 bit 對應一個 token 是否合法。_full_mask = torch.tensor(-1, dtype=torch.int32)表示「全 1」——所有 token 合法📎 vllm/v1/structured_output/__init__.py:59。

兩個執行緒池分工明確：executor負責語法編譯（CPU 密集，worker 數為 CPU 數一半）📎 vllm/v1/structured_output/__init__.py:71-78；executor_for_fillmask負責大 batch 位元遮罩並行填充，僅在 batch 超過 128 時啟用📎 vllm/v1/structured_output/__init__.py:62-69。

Step-by-Step Walkthrough

語法初始化。請求首次進入時grammar_init被呼叫📎 vllm/v1/structured_output/__init__.py:115-176。若 backend 未初始化則按配置選擇實現📎 vllm/v1/structured_output/__init__.py:130-165。隨後提交編譯任務：預設走非同步executor.submit，但在external_launcher模式下必須同步📎 vllm/v1/structured_output/__init__.py:167-176。

位元遮罩生成。每個 decode step，grammar_bitmask為批內所有結構化請求生成遮罩📎 vllm/v1/structured_output/__init__.py:314-442。大 batch 走並行路徑：按 16 個一批提交到執行緒池📎 vllm/v1/structured_output/__init__.py:346-373。小 batch 走串行路徑，逐 token 推進語法狀態📎 vllm/v1/structured_output/__init__.py:374-433。

投機解碼下的遮罩對齊。這是最精妙的部分。當有 draft token 時，每個請求需要1 + max_num_spec_tokens行遮罩。串行路徑逐 token 處理：若某 draft token 被語法拒絕，記錄failed_index，後續行直接複製該行的遮罩📎 vllm/v1/structured_output/__init__.py:396-418。這保證了「draft 被拒後，後續位置的約束狀態回退到拒絕點」。

狀態回滾。位元遮罩填充過程中語法狀態被推進了state_advancements步，但 draft token 尚未被真正接受，因此必須grammar.rollback(state_advancements)回退📎 vllm/v1/structured_output/__init__.py:422-430。真正接受發生在accept_tokens 📎 vllm/v1/structured_output/__init__.py:444-466。

sequenceDiagram
    participant Sched as Scheduler
    participant Mgr as StructuredOutputManager
    participant Pool as executor_for_fillmask
    participant Gram as StructuredOutputGrammar
    participant GPU as GPU Runner

    Sched->>Mgr: grammar_bitmask(requests, ids, spec_tokens)
    Mgr->>Mgr: allocate_token_bitmask(max_batch*(1+spec))
    alt batch > 128 且无投机
        Mgr->>Pool: _async_submit_fill_bitmask(batch)
        Pool->>Gram: fill_bitmask(bitmask, index)
        Gram-->>Pool: 写入合法 token 位
        Pool-->>Mgr: Future.result()
    else 小 batch 或含投机
        loop 每个 req 的每个 spec token
            Mgr->>Gram: fill_bitmask(bitmask, cumulative_index)
            Mgr->>Gram: accept_tokens(req_id, [token])
            Gram-->>Mgr: True/False
            Note over Mgr: 失败则记录 failed_index<br/>后续行复制该行
        end
        Mgr->>Gram: rollback(state_advancements)
    end
    Mgr-->>Sched: bitmask.numpy() (NDArray int32)
    Sched->>GPU: 传入采样内核

設計思考與踩坑

為什麼 external_launcher 必須同步編譯？註解給出了精確原因：非同步編譯會讓WAITING_FOR_STRUCTURED_OUTPUT_GRAMMAR → WAITING狀態轉換在不同 TP rank 上發生於不同時刻，破壞 external_launcher 依賴的確定性假設📎 vllm/v1/structured_output/__init__.py:47-56。這是分散式確定性與非同步優化衝突的典型案例。

推理模型下的約束起點。 _get_constraint_start決定從第幾個 token 開始施加語法約束📎 vllm/v1/structured_output/__init__.py:220-292。對於帶思維鏈的模型，reasoning 階段不應受 JSON 約束，只有 reasoning 結束後才啟動。enable_in_reasoning為 True 時直接返回 0（全程約束）📎 vllm/v1/structured_output/__init__.py:235-236。若 reasoner 支援find_reasoning_end_offset，用它精確定位📎 vllm/v1/structured_output/__init__.py:261-267；否則回退到逐 token 回退搜尋📎 vllm/v1/structured_output/__init__.py:287-291。

validate_tokens的前綴語義。投機解碼時 draft token 可能違反語法，validate_tokens返回「最長合法前綴」📎 vllm/v1/structured_output/__init__.py:294-312。注意它先剝離投機填充（-1），再計算約束起點，最後只對約束區間內的 token 做語法校驗。

Detokenizer：增量解碼與 stop string 的邊界博弈

直覺模型：detokenizer 像一位逐字謄抄的書記員，把 token id 翻譯成人類可讀文字。難點在於：token 與字元不是一一對應（一個 token 可能只對應半個 UTF-8 字元），且 stop string 可能橫跨多個 token。若沒有增量解碼，每步都要從頭解碼整個序列，O(n²) 的開銷會拖垮吞吐。

資料結構與記憶體佈局

IncrementalDetokenizer基類只持token_ids列表📎 vllm/v1/engine/detokenizer.py:32-33。BaseIncrementalDetokenizer增加了 stop 相關欄位：stop列表、min_tokens、include_stop_str_in_output、stop_buffer_length與_last_output_text_offset 📎 vllm/v1/engine/detokenizer.py:70-94。

stop_buffer_length是關鍵：當 stop string 不包含在輸出中時，它等於最長 stop string 長度減一📎 vllm/v1/engine/detokenizer.py:87-90。這個「回退緩衝」確保串流輸出不會提前吐出可能是 stop string 前綴的字元。

兩條實作路徑：FastIncrementalDetokenizer用 tokenizers 函式庫的DecodeStream 📎 vllm/v1/engine/detokenizer.py:166-246；SlowIncrementalDetokenizer用 Python 側detokenize_incrementally 📎 vllm/v1/engine/detokenizer.py:249-305。選擇依據是 tokenizers 版本 ≥ 0.22.0 且 tokenizer 類型匹配📎 vllm/v1/engine/detokenizer.py:32-33📎 vllm/v1/engine/detokenizer.py:61-63。

Step-by-Step Walkthrough

增量解碼。 update接收新 token ids 與stop_terminated標誌📎 vllm/v1/engine/detokenizer.py:96-142。若 stop 終止且不包含 stop string，則最後一個 token 被排除在解碼外📎 vllm/v1/engine/detokenizer.py:107-111。隨後逐 token 呼叫decode_next累積文字📎 vllm/v1/engine/detokenizer.py:117-122。

stop string 偵測。 check_stop_strings只在新增字元範圍內搜尋📎 vllm/v1/engine/detokenizer.py:308-360。搜尋起點是1 - new_char_count - stop_string_len 📎 vllm/v1/engine/detokenizer.py:338，這個偏移確保跨 token 邊界的 stop string 也能被捕獲。多個 stop string 同時匹配時，選擇最早完成的那個📎 vllm/v1/engine/detokenizer.py:342-347。

串流輸出切片。 get_next_output_text按delta參數決定返回全量還是增量📎 vllm/v1/engine/detokenizer.py:148-163。未完成時保留stop_buffer_length個字元不吐📎 vllm/v1/engine/detokenizer.py:145-146，用_last_output_text_offset記錄已發送位置📎 vllm/v1/engine/detokenizer.py:148-163。

異常恢復。 FastIncrementalDetokenizer._protected_step處理兩類異常：OverflowError/TypeError 記錄日誌返回 None📎 vllm/v1/engine/detokenizer.py:225-229；「Invalid prefix」錯誤則重建 DecodeStream並重試📎 vllm/v1/engine/detokenizer.py:222-246。後者應對 tokenizer 產生非單調 UTF-8 輸出的邊界情況。

設計思考與踩坑

stop_buffer_length 的權衡。緩衝越長，串流延遲越大（使用者看到文字的時間推後），但越不容易漏檢跨 token 的 stop string。取「最長 stop string 長度減一」是精確下界：任何 stop string 的前綴最多這麼長。

min_tokens 與 stop_check_offset。當輸出 token 數未達min_tokens時，stop_check_offset被持續推到文字末尾📎 vllm/v1/engine/detokenizer.py:120-122，意味著這段文字不會被 stop 偵測。這防止了模型在開頭就撞上 stop string 導致空輸出。

Fast 路徑的 added_token_ids 快取。當spaces_between_special_tokens為 False 時，需要抑制特殊 token 間的空格📎 vllm/v1/engine/detokenizer.py:192-207。程式碼把added_token_ids快取在 tokenizer 物件上📎 vllm/v1/engine/detokenizer.py:195-200，避免每次 decode 都重建字典。

設計思考

三個模組共享一條設計哲學：把狀態推進與約束檢查分離，讓 GPU 側只做無狀態的張量運算。Sampler 無狀態，狀態在SamplingMetadata；語法狀態機在 CPU 側推進，GPU 只消費位元遮罩；detokenizer 的_last_output_text_offset是唯一的串流游標。這種分離讓每個 GPU 側元件都能被 CUDA Graph 捕獲。

另一條主線是順序即語義。Sampler 的處理器鏈順序、結構化輸出的約束起點、detokenizer 的 stop 偵測偏移，任何一處順序錯誤都不會崩潰，只會靜默產出錯誤結果——這正是這類程式碼最難除錯之處。

本章小結

• Sampler 的處理器鏈嚴格排序：原始 logprobs 快照 → float32 → 白名單/bad words → non-argmax-invariant → 懲罰 → 溫度 → argmax-invariant → top-k/top-p。
• 結構化輸出用位元遮罩把 CPU 側語法狀態傳給 GPU，投機解碼下透過failed_index複製與rollback保證狀態一致。
• Detokenizer 用stop_buffer_length回退緩衝平衡串流延遲與 stop string 跨 token 偵測，Fast 路徑依賴 tokenizers ≥ 0.22.0 的DecodeStream。

本章思考與自測

至此，單機上的推理全鏈路已經打通：從注意力計算到取樣輸出，每個環節都直接影響最終交付的文本品質。但當模型規模超出單卡容量時，這條鏈路必須跨越多個裝置協同完成。下一章我們將離開單機，進入分散式並行：TP、PP、EP 如何切分模型，通訊原語如何在 rank 間同步這些取樣結果。

上一章我們走完了單次推理生命週期的最後一公里，從 logits 取樣到串流輸出。但當模型大到單卡放不下時，這條流水線就必須被切分到多個裝置上協同執行。分散式推理的第一性問題不是「怎麼切模型」，而是「切完之後，誰和誰說話、用什麼方式說話」。vLLM 把這兩個問題分別交給 parallel_state.py 的進程組拓撲和 custom_all_reduce.py 的通訊器實現。本章沿著「建組 → 切分 → 通訊 → 負載再平衡」這條鏈路，逐層拆開 TP、PP、EP 的並行策略與底層通訊原語。

8.1 進程組拓撲：一張 rank 網格如何切出 TP/PP/DP/EP

直覺模型

把 8 張 GPU 想成一張 8 個座位的長桌。張量並行（Tensor Parallelism，TP）要求「同桌的人必須同時舉杯」，流水線並行（Pipeline Parallelism，PP）要求「相鄰座位接力傳菜」，資料並行（Data Parallelism，DP）要求「不同桌各吃各的但最後對帳」，專家並行（Expert Parallelism，EP）要求「token 按科室分診」。若沒有統一的座位編排，每個模組各自new_group，就會出現「我以為你在 TP 組裡，其實你在 DP 組裡」的通信錯位——集合通信一旦有 rank 缺席，NCCL 會直接掛死而非報錯。

資料結構與記憶體佈局

GroupCoordinator是這一切的載體。它的欄位設計直接對應「一個行程在多個平行維度上的多重身份」：

• rank是全域 rank，ranks是組成員全域 rank 列表，world_size是組大小📎 vllm/distributed/parallel_state.py:434-436。
• local_rank用於綁定裝置，rank_in_group是組內序號——原始碼用一張表精確區分二者：跨兩節點的 4 卡組裡，rank 2 的local_rank是 0（它在節點 1 上是第一張卡），但rank_in_group是 2📎 vllm/distributed/parallel_state.py:437-445。
• cpu_group與device_group成對存在：前者走 gloo 做元資料/物件通信，後者走 NCCL 做張量通信📎 vllm/distributed/parallel_state.py:446-447。

這裡有個關鍵設計：為什麼每個組都要維護一個 CPU 組？因為broadcast_object、send_object這類操作傳輸的是 Python 物件（序列化後的位元組），走 NCCL 既浪費顯存又可能污染當前 CUDA 裝置。barrier()的註解把這一點說得很直白：NCCL 的 barrier 內部是一次 broadcast，會偷偷建立 GPU 張量，容易搞亂當前裝置，所以必須用 CPU 組📎 vllm/distributed/parallel_state.py:1355-1362。

Step-by-Step：initialize_model_parallel如何切網格

代入一個具體場景：8 卡、TP=2、PP=4、DP=1。核心是把一維 rank 序列 reshape 成多維網格，再沿每個維度切分。

第一步，建構 rank 網格。佈局順序被明確定義為ExternalDP x DP x PP x PCP x TP 📎 vllm/distributed/parallel_state.py:2045-2060：

all_ranks = torch.arange(world_size).reshape(
    -1, data_parallel_size, pipeline_model_parallel_size,
    prefill_context_model_parallel_size, tensor_model_parallel_size,
)

第二步，切 TP 組：把網格 view 成(-1, tp_size)後 unbind，得到[g0,g1],[g2,g3],... 📎 vllm/distributed/parallel_state.py:2065-2077。注意 TP 組額外傳了use_message_queue_broadcaster=True，因為 TP 組需要共享記憶體廣播來分發元資料。

第三步，切 PP 組：all_ranks.transpose(2, 4)把 PP 維換到最後一維再切，得到[g0,g2,g4,g6],[g1,g3,g5,g7] 📎 vllm/distributed/parallel_state.py:2175-2188。這正是文件字串裡給出的例子📎 vllm/distributed/parallel_state.py:1997-1997。

第四步，切 DP 組：transpose(1, 4)後切📎 vllm/distributed/parallel_state.py:2195-2202。

第五步，切 EP 組——這裡有個容易忽略的細節：EP 組只在 MoE 模型下建立，dense 模型直接跳過📎 vllm/distributed/parallel_state.py:2210-2241。EP 組的 rank 集合是DP x PCP x TP的乘積，意味著 EP 複用了 DP 和 TP 的物理卡，而不是獨立維度。

flowchart TD
    start["initialize_model_parallel()"] --> grid["all_ranks = arange(world_size).reshape(-1, DP, PP, PCP, TP)"]
    grid --> tp["TP: view(-1, tp_size).unbind(0)"]
    grid --> pp["PP: transpose(2,4).reshape(-1, pp_size)"]
    grid --> dp["DP: transpose(1,4).reshape(-1, dp_size)"]
    grid --> ep_check{"model_config.is_moe?"}
    ep_check -->|是| ep["EP: transpose(1,2).reshape(-1, DP*PCP*TP)"]
    ep_check -->|否| skip["_EP 保持 None"]
    ep --> eplb_check{"enable_eplb?"}
    eplb_check -->|是| eplb["EPLB: 与 EP 同 rank 集，独立 PG"]
    eplb_check -->|否| no_eplb["_EPLB 保持 None"]
    tp --> done["logger.info_once 打印各维度 rank"]
    pp --> done
    dp --> done
    ep --> done
    skip --> done
    eplb --> done
    no_eplb --> done

設計思考與踩坑

EPLB 為什麼要獨立行程組？註解給出了答案：把 EPLB 通信與 MoE 前向的集合通信隔離，防止「執行期的 torch.distributed」與「EPLB 的 torch.distributed」互相死鎖📎 vllm/distributed/parallel_state.py:2243-2246。這是一個典型的「用獨立通信域換確定性」的權衡——多一個 PG 的顯存開銷，換來的是不會在權重搬運時卡死前向。

DP 組的同步約束是生產環境最常踩的坑：同一 DP 組內所有 rank 必須同時呼叫generate，否則死鎖📎 vllm/distributed/parallel_state.py:2048-2051。因為 DP 組內會做梯度/取樣結果的 all-reduce，任何 rank 缺席都會讓集合通信永久阻塞。

銷毀順序同樣有講究。destroy()先銷毀 device communicator，再銷毀 device_group 和 cpu_group📎 vllm/distributed/parallel_state.py:1380-1393。註解解釋了原因：device communicator 可能持有依賴這些 PG 的集合通信工作區（如 FlashInfer PCIe IPC barrier），必須先釋放📎 vllm/distributed/parallel_state.py:1377-1377。

8.2 通信原語：自訂 all-reduce 如何繞過 NCCL

直覺模型

NCCL 的 all-reduce 是「通用貨車」，能拉任何貨、走任何路，但啟動開銷和協定開銷固定。當你要在 8 卡 NVLink 全互聯的機器上反覆做小張量 all-reduce（TP 的每個 attention/MLP 層都要做），通用貨車的「過路費」就變得不可忽視。自訂 all-reduce 是「專用小推車」：只在同機、NVLink 全互聯、張量大小合適的場景下啟用，用一次cudaMemcpy換掉 NCCL 的握手與協定開銷。

資料結構與記憶體佈局

CustomAllreduce的初始化是一場「能力探測 + 資源預分配」的組合。關鍵欄位：

• _SUPPORTED_WORLD_SIZES = [2, 4, 6, 8, 16]：只支援這些組大小📎 vllm/distributed/device_communicators/custom_all_reduce.py:113-129。
• meta_ptrs：同步元資料 + 中間結果緩衝區，大小ops.meta_size() + max_size 📎 vllm/distributed/device_communicators/custom_all_reduce.py:291-294。
• buffer_ptrs：預註冊的 IPC 緩衝區，eager 模式下輸入張量先拷進來再算📎 vllm/distributed/device_communicators/custom_all_reduce.py:298-305。
• rank_data：8MB 的 uint8 張量，存放所有 rank 的 IPC 緩衝區指標元組📎 vllm/distributed/device_communicators/custom_all_reduce.py:309-315。

為什麼緩衝區要預註冊？因為 CUDA Graph 捕獲要求所有位址在捕獲時固定。register_graph_buffers在捕獲結束時把所有用到的緩衝區位址廣播給所有 rank 並註冊📎 vllm/distributed/device_communicators/custom_all_reduce.py:474-491。

Step-by-Step：一次 all-reduce 的決策流

代入場景：TP 組內某層 MLP 輸出需要 all-reduce，輸入是 4MB 的 bf16 張量。

第一步，custom_all_reduce檢查是否禁用、是否滿足should_custom_ar 📎 vllm/distributed/device_communicators/custom_all_reduce.py:529-533。

第二步，should_custom_ar逐條過濾：world_size > 8 拒絕；dtype 必須是 fp32/fp16/bf16；位元組數必須是 16 的倍數；必須弱連續；world_size==2 或全互聯才繼續📎 vllm/distributed/device_communicators/custom_all_reduce.py:493-508。

第三步，根據是否在 CUDA Graph 捕獲中分流：捕獲中用registered=True（位址已固定），否則registered=False（需要先 memcpy 到預註冊緩衝區）📎 vllm/distributed/device_communicators/custom_all_reduce.py:529-545。

第四步，實際調用ops.all_reduce，傳入buffer_ptrs[rank]和max_size 📎 vllm/distributed/device_communicators/custom_all_reduce.py:519-527。

flowchart TD
    call["custom_all_reduce(input)"] --> disabled{"self.disabled?"}
    disabled -->|是| ret_none["return None → 回退 NCCL"]
    disabled -->|否| should{"should_custom_ar(input)?"}
    should -->|否| ret_none
    should -->|是| capturing{"self._IS_CAPTURING?"}
    capturing -->|是| stream_cap{"is_current_stream_capturing()?"}
    stream_cap -->|是| reg["all_reduce(registered=True)"]
    stream_cap -->|否| mimic["return empty_like(input) 模拟分配"]
    capturing -->|否| eager["all_reduce(registered=False) 先 memcpy"]
    reg --> out["返回 out 张量"]
    eager --> out

設計思考與踩坑

多機場景的降級路徑是這段程式碼最精妙的部分。same_node為假時，mnnvl_only置真📎 vllm/distributed/device_communicators/custom_all_reduce.py:198-199，隨後檢查 MNNVL（Multi-Node NVLink）能力。如果組內不是每張卡都支援 MNNVL，直接禁用自訂集合通訊📎 vllm/distributed/device_communicators/custom_all_reduce.py:228-233。_group_can_attempt_mnnvl用一次 CPU all-reduce（MIN 操作）確保所有 rank 走同一條控制流📎 vllm/distributed/device_communicators/custom_all_reduce.py:59-73——這是異構叢集裡避免「部分 rank 進 MNNVL 路徑、部分走 NCCL」導致掛死的關鍵防護。

P2P 檢查的代價：_can_p2p會遍歷所有 peer 做gpu_p2p_access_check，註解說首次計算很貴但會快取📎 vllm/distributed/device_communicators/custom_all_reduce.py:278-278。生產環境如果發現啟動慢，可以設VLLM_SKIP_P2P_CHECK跳過，直接信任驅動的 P2P 報告📎 vllm/distributed/device_communicators/custom_all_reduce.py:86-100。

reduce-scatter 的三級後端選擇值得單獨看：_select_reduce_scatter_backend按優先級返回mnnvl_multimem > mnnvl_lamport > legacy 📎 vllm/distributed/device_communicators/custom_all_reduce.py:601-636。multimem 路徑要求 world_size 在(2,4,8)且設備能力是 (10,0) 或 (10,3)（Blackwell 級）📎 vllm/distributed/device_communicators/custom_all_reduce.py:103-104。注意VLLM_BATCH_INVARIANT會禁用 multimem 路徑📎 vllm/distributed/device_communicators/custom_all_reduce.py:628——因為 multimem 的歸約順序不確定，會破壞批次不變性。

8.3 EPLB：專家負載再平衡的調度邏輯

直覺模型

MoE 模型裡，256 個邏輯專家分到 32 張卡上，每卡 8 個。但真實流量下，某些「熱門專家」（比如處理常見語法結構的）會被大量 token 路由到，導致持有它的卡成為瓶頸，其他卡空轉。EPLB（Expert Parallel Load Balancer）就是「給熱門專家加副本」：把熱門專家的權重複製到空閒卡上，讓 token 分流過去。若沒有它，MoE 的實際吞吐會被最慢的那張卡鎖死。

資料結構與記憶體佈局

EplbModelState用三張映射表描述「邏輯專家 ↔ 物理專家」的關係：

• physical_to_logical_map：形狀(num_moe_layers, num_physical_experts)，每個物理槽位存它承載的邏輯專家 id📎 vllm/distributed/eplb/eplb_state.py:105-120。
• logical_to_physical_map：形狀(num_moe_layers, num_logical_experts, max_replicas+1)，稀疏矩陣，-1 表示無映射📎 vllm/distributed/eplb/eplb_state.py:123-146。
• logical_replica_count：每個邏輯專家有幾個副本📎 vllm/distributed/eplb/eplb_state.py:147-161。

expert_load_window是滑動視窗，形狀(window_size, num_moe_layers, num_physical_experts) 📎 vllm/distributed/eplb/eplb_state.py:180-187。註解特別指出：現在記錄所有物理專家的負載而非僅本地專家，以保證不同 dispatch 方法（naive all-to-all、DeepEP）統計一致；naive all-to-all 下每個 DP rank 貢獻相同 token 集，負載會被乘以 dp_size📎 vllm/distributed/eplb/eplb_state.py:180-187。

Step-by-Step：一次重排的完整鏈路

代入場景：expert_rearrangement_step達到閾值，觸發rearrange()。

第一步，把物理負載映射回邏輯專家。用scatter_add_按physical_to_logical_map聚合，無效槽位（<0）填到invalid_idx桶裡最後丟棄📎 vllm/distributed/eplb/eplb_state.py:794-816。

第二步，跨 rank all-reduce 得到全局邏輯負載。_allreduce_list對多個模型的負載做拼接後一次 all-reduce 再拆開，避免多次通訊📎 vllm/distributed/eplb/eplb_state.py:1045-1068。

第三步，調用策略計算新映射。policy.rebalance_experts在 host 上運行，所以負載視窗和當前映射都要拷回 CPU📎 vllm/distributed/eplb/eplb_state.py:859-867。

第四步，ROCm 特化的「跳過重排」判斷：如果新映射帶來的 rank 負載不均衡改善小於 5%，就跳過這次重排📎 vllm/distributed/eplb/eplb_state.py:869-923。這是一個務實的優化——重排本身有通訊成本，收益不夠就不做。

第五步，執行權重搬運並提交新映射📎 vllm/distributed/eplb/eplb_state.py:925-942。

sequenceDiagram
    participant Main as 主线程 step()
    participant Policy as DefaultEplbPolicy
    participant Comm as EplbCommunicator
    participant Async as async_worker 线程
    Main->>Main: expert_rearrangement_step >= interval
    Main->>Main: scatter_add_ 物理负载→逻辑负载
    Main->>Main: _allreduce_list 跨 rank 聚合
    Main->>Policy: rebalance_experts(load, replicas, groups, nodes, gpus, map)
    Policy-->>Main: new_physical_to_logical_map
    alt 同步模式
        Main->>Comm: rearrange_expert_weights_inplace()
        Comm-->>Main: 权重搬运完成
        Main->>Main: _commit_eplb_maps()
    else 异步模式
        Main->>Main: eplb_stats = EplbStats(...); rebalanced = True
        Main->>Async: rearrange_event.record()
        Async->>Comm: 后台搬运权重到 expert_buffer
        Async-->>Main: pending_result 就绪
        Main->>Main: _move_to_workspace() 提交
    end

設計思考與踩坑

非同步模式的同步原語是這段程式碼最微妙的地方。rebalanced標誌依賴 GIL 在主執行緒和 async worker 之間同步📎 vllm/distributed/eplb/eplb_state.py:194-203。但註解警告：rebalanced必須在所有 rank 上保持一致，否則_all_ranks_result_ready裡的 all-reduce 會掛死📎 vllm/distributed/eplb/eplb_state.py:664-665。_all_ranks_result_ready優先使用 CPU 組做 all-reduce，因為 CPU 組更可靠📎 vllm/distributed/eplb/eplb_state.py:1024-1043。

滑動視窗的「提前錄製」優化：_should_record_current_step只在距離下次重排不超過window_size步時才開啟錄製📎 vllm/distributed/eplb/eplb_state.py:689-709。註解解釋：每個重排週期前step_interval - window_size步的資料會被滑動視窗覆蓋，錄了也白錄，浪費 GPU 計算📎 vllm/distributed/eplb/eplb_state.py:1196-1199。should_record_tensor是所有層共享的同一個純量張量，一次fill_更新所有層📎 vllm/distributed/eplb/eplb_state.py:272-278。

彈性 EP 的容量預留：enable_elastic_ep時，physical_expert_capacity按elastic_ep_max_dp_size預留，映射表用 -1 填充多餘槽位📎 vllm/distributed/eplb/eplb_state.py:375-386。這樣擴容時不需要重新分配顯存，只需把 -1 槽位填上真實專家。reconfigure_physical_expert_slots負責在擴容/縮容時刷新視圖📎 vllm/distributed/eplb/eplb_state.py:1135-1160。

_commit_eplb_maps的 pin memory 處理：當PIN_MEMORY開啟且源在 CPU 時，先拷到 pinned 記憶體再non_blocking=True非同步拷貝到 GPU📎 vllm/distributed/eplb/eplb_state.py:1392-1400。這是為了避免 H2D 拷貝阻塞主執行緒——映射表每層每輪都要更新，同步拷貝會成為瓶頸。

設計思考

三塊程式碼共享一個設計哲學：用能力探測換確定性降級。GroupCoordinator在world_size == 1時直接 bypass 所有集合通訊📎 vllm/distributed/parallel_state.py:736-738；CustomAllreduce在任一條件不滿足時返回None讓呼叫方回退 NCCL📎 vllm/distributed/device_communicators/custom_all_reduce.py:532-533；EPLB 在改善不足 5% 時跳過重排📎 vllm/distributed/eplb/eplb_state.py:916。這種「快速失敗 + 優雅降級」的模式，讓同一份程式碼能在從單卡到多機 MNNVL 的全譜系硬體上運行，而不需要為每種配置寫分支。

另一個共性是控制流一致性優先於效能。_group_can_attempt_mnnvl用 CPU all-reduce 強制所有 rank 走同一分支📎 vllm/distributed/device_communicators/custom_all_reduce.py:59-73，_all_ranks_result_ready同理📎 vllm/distributed/eplb/eplb_state.py:1024-1043。在分散式系統裡，「部分 rank 走了快路徑、部分走了慢路徑」比「所有 rank 都走慢路徑」危險得多——前者會掛死，後者只是慢。

本章小結

• GroupCoordinator把一維 rank 序列 reshape 成ExternalDP x DP x PP x PCP x TP網格，沿各維度切分出 TP/PP/DP/EP/EPLB 行程群組；每個群組同時維護 CPU（gloo）和 device（NCCL）兩個 PG。
• CustomAllreduce透過能力探測（同機、NVLink 全互聯、張量大小、dtype、16 位元組對齊）決定是否接管 all-reduce，多機場景降級到 MNNVL 或 NCCL。
• EPLB 用三張映射表描述邏輯/物理專家關係，透過滑動視窗統計負載、策略計算新映射、通訊器搬運權重，支援同步與非同步兩種模式。
• 三者的共同設計原則：能力探測 + 確定性降級 + 控制流一致性優先。

本章思考與自測

至此，我們釐清了卡間通訊的建組、切分與負載再平衡機制。但分散式推理的通訊挑戰不止於單實例內部——當 prefill 與 decode 被拆到不同實例上時，KV Cache 需要跨節點傳輸。下一章我們將離開「卡間通訊」，進入「實例間通訊」：KV Cache 如何在分離式部署的 prefill 與 decode 實例之間傳輸，KV Connector 抽象如何統一 NIXL、Mooncake 等傳輸後端。

上一章我們把視角鎖在單個推理實例內部：TP/PP/DP/EP 進程組如何建組，張量如何在卡間切分，EPLB 如何在 MoE 層做專家再平衡。但所有這些機制都建立在同一個前提上——prefill 和 decode 跑在同一個實例裡，KV Cache 從頭到尾待在本地顯存。分離式部署（Prefill-Decode Disaggregation，簡稱 PD 分離）打破了這個前提。它把 prefill 和 decode 拆成兩個獨立的 vLLM 實例：prefill 實例只做 prompt 的前向計算，產出 KV Cache 後交給 decode 實例；decode 實例拿著這份 KV Cache 繼續自迴歸生成。這樣做的好處是資源可以按階段特性獨立配置——prefill 是計算密集型，適合大 TP、大 batch；decode 是訪存密集型，適合小 batch、低延遲調度。兩者不再互相拖累。代價是：KV Cache 必須跨實例傳輸。這就是本章的主角——KV Connector。vllm/distributed/kv_transfer/kv_connector/v1/base.py 的檔案頭註解已經把整個抽象的核心原語列了出來：Scheduler 側負責綁定元數據、查詢遠端快取命中、決定是否異步釋放 block；Worker 側負責實際的 KV 載入與保存。這套介面的設計目標，是讓上層調度邏輯與底層傳輸後端（NIXL、Mooncake、MoRIIO）徹底解耦。從工程角度看，PD 分離最大的風險不是傳輸慢，而是狀態不一致：prefill 實例認為 KV 已經發出去了，decode 實例卻沒收到；或者 decode 實例提前釋放了 block，prefill 還在往裡寫。本章要探明的，正是這套連接器體系如何用握手協議、租約（lease）、心跳和失敗恢復機制來兜住這些邊界。

一、KVConnectorBase_V1：雙角色抽象與元數據契約

直覺模型

KV Connector 就像兩家分店之間的快遞系統。Prefill 店算好了半成品（KV Cache），打包寄給 Decode 店繼續加工。但快遞系統不能只有「發貨」這一個動作——它需要一張運單（metadata）說明寄什麼、寄到哪；需要一個簽收機制確認對方收到了；還需要一套超時規則，防止包裹永遠卡在路上佔著貨架。

如果沒有這套抽象，每個傳輸後端（NIXL、Mooncake）都要自己實現調度邏輯，vLLM 的 Scheduler 就得為每種後端寫一套適配代碼。KVConnectorBase_V1 的價值，就是把這套契約固定下來。

雙角色：Scheduler 側與 Worker 側

📎 vllm/distributed/kv_transfer/kv_connector/v1/base.py:137-142定義了連接器的兩種角色：

class KVConnectorRole(enum.Enum):
    # Connector running in the scheduler process
    SCHEDULER = 0
    # Connector running in the worker process
    WORKER = 1

這個劃分不是隨意的。Scheduler 進程負責全局調度決策——哪些請求需要傳輸、什麼時候可以釋放 block；Worker 進程負責實際的數據搬運。兩者通過KVConnectorMetadata通信。

📎 vllm/distributed/kv_transfer/kv_connector/v1/base.py:153-158定義了 Scheduler 到 Worker 方向的元數據基類：

class KVConnectorMetadata(ABC):  # noqa: B024
    """Abstract Metadata used to communicate
    Scheduler KVConnector -> Worker KVConnector.
    """
    pass

反向的 Worker 到 Scheduler 方向，📎 vllm/distributed/kv_transfer/kv_connector/v1/base.py:161-176定義了KVConnectorWorkerMetadata，它要求實現aggregate方法——因為一個 engine step 裡可能有多個 worker 各自返回元數據，需要聚合後再交給 Scheduler。

核心數據結構：KVConnectorTransferResults

📎 vllm/distributed/kv_transfer/kv_connector/v1/base.py:87-96定義了傳輸結果的快照結構：

@dataclass
class KVConnectorTransferResults:
    finished_sending: set[str] = field(default_factory=set)
    finished_recving: set[str] = field(default_factory=set)
    failed_recving: set[str] = field(default_factory=set)

注意註解裡的關鍵設計：失敗的接收也會出現在finished_recving裡。這是為了讓 Scheduler 能把請求從「等待傳輸」狀態中釋放出來——即使傳輸失敗了，請求也不能永遠卡著。失敗資訊透過failed_recving單獨傳遞，Scheduler 據此決定是重試還是降級。

生命週期鉤子：從請求到釋放

整個連接器的生命週期圍繞幾個關鍵鉤子展開。Scheduler 側：

• get_num_new_matched_tokens 📎 vllm/distributed/kv_transfer/kv_connector/v1/base.py:485-518：查詢遠端快取能命中多少 token。註解特別強調「應該只考慮實際可用的最大前綴」，如果某些 token 因為連線問題或驅逐拿不到，就不能算進去。
• update_state_after_alloc 📎 vllm/distributed/kv_transfer/kv_connector/v1/base.py:520-544：block 分配後更新狀態。註解裡有個容易踩的坑——判斷是否載入要看num_external_tokens，而不是blocks是否為空，因為 MultiConnector 的非選中子連接器也會收到真實 block。
• request_finished 📎 vllm/distributed/kv_transfer/kv_connector/v1/base.py:579-598：請求完成時呼叫，回傳True表示連接器接管 block 的非同步釋放責任。

Worker 側：

• start_load_kv / wait_for_layer_load：逐層載入，支援流水線。
• save_kv_layer / wait_for_save：逐層儲存。
• get_transfer_results 📎 vllm/distributed/kv_transfer/kv_connector/v1/base.py:396-397：回傳非同步傳輸的完成情況。

📎 vllm/distributed/kv_transfer/kv_connector/v1/base.py:192-201還有一個容易被忽略但很關鍵的設計——requires_kv_delivery屬性：

@property
def requires_kv_delivery(self) -> bool:
    """Whether this connector hands off KV that must be reliably delivered.
    ...
    """
    return self._kv_transfer_config.is_kv_producer

註解解釋了動機：如果請求在 KV 交接還沒完成時被搶占，應該重新計算而不是讓它完成並交接已經被搶占釋放的 block。只有 producer 角色才需要可靠交付，best-effort 快取丟了只是未來的一次 cache miss。

握手元資料

📎 vllm/distributed/kv_transfer/kv_connector/v1/base.py:145-150定義了握手元資料的基類：

class KVConnectorHandshakeMetadata(ABC):  # noqa: B024
    """Metadata used for out of band connector handshake between
    P/D workers. This needs to serializable.
    """
    pass

「out of band」意味著握手不走正常的請求路徑，而是 P/D worker 之間直接通訊。這為 NIXL 的 ZMQ 握手協議埋下了伏筆。

---

二、NIXL 連接器：握手、註冊與描述符構建

直覺模型

NIXL（NVIDIA Inference Xfer Library）是 NVIDIA 提供的底層傳輸庫，支援 UCX、GDS 等多種後端。NixlBaseConnectorWorker 的角色，就像快遞公司的分揀中心——它需要先和對方分揀中心建立專線（握手），登記自己的貨架佈局（註冊 KV Cache 記憶體區域），然後才能高效地按位址取貨發貨。

如果沒有這套機制，每次傳輸都要重新協商位址、重新建立連線，延遲會高到無法接受。

記憶體佈局：Region 與 Descriptor

NIXL 的核心概念是region（記憶體區域）和descriptor（描述符）。每個 KV Cache 層在 NIXL 中註冊為一個或多個 region，每個 region 有基底位址、塊長度、塊步長。

📎 vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py:740-751列出了 region 相關的核心欄位：

# Number of NIXL regions. Currently one region per cache
# (so 1 per layer for MLA, otherwise 2 per layer)
self.num_regions = 0
self.region_mem_types: list[str] = []
self.region_group_ids: list[int] = []
self._uses_region_group_mapping = False
self.region_names: list[str] = []
self.region_num_blocks: list[int] = []
self._mixed_mem_types = False

📎 vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py:897-900進一步說明了塊步長的來源：

# Per-region block stride in bytes. Taken from the registered tensor's
# stride(0) so it stays correct under layouts that interleave layers
# within a block (BLHNC/BHLNC), where stride > block_len.
self.block_stride_per_layer = list[int]()

這裡的關鍵洞察是：block_stride 不等於 block_len。在 BLHNC/BHLNC 這類層間交錯的佈局下，一個 block 的實際跨度可能大於其有效資料長度。如果直接用 block_len 做步長，會讀錯位址。

握手協議：ZMQ + 相容性雜湊

握手是 NIXL 連接器最複雜的部分。📎 vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py:974-1128的_nixl_handshake方法完整展示了這個過程。

第一步是設定 CUDA 裝置上下文。📎 vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py:988-998的註解解釋了原因：

# the first time we connect to a remote agent.
# be careful, the handshake happens in a background thread.
# it does not have an active cuda context until any cuda runtime
# call is made. when UCX fails to find a valid cuda context, it will
# disable any cuda ipc communication, essentially disabling any NVLink
# communication.
if not self.use_host_buffer:
    current_platform.set_device(self.device_id)

這是一個非常隱蔽的坑：握手在背景執行緒執行，如果沒有顯式設定裝置，UCX 找不到有效的 CUDA 上下文，會靜默停用 NVLink 通訊，退化成慢速路徑。

第二步是透過 ZMQ 發送元資料查詢。📎 vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py:1029-1036：

msg = msgspec.msgpack.encode(
    (GET_META_MSG, remote_pp_rank, remote_rank)
)
# Set receive timeout to 5 seconds to avoid hanging on dead server
sock.setsockopt(zmq.RCVTIMEO, 5000)  # milliseconds
start_time = time.perf_counter()
sock.send(msg)
reply_parts = sock.recv_multipart()

5 秒逾時是防止對端死掉後無限等待。同時，程式碼用 RTT 估算時鐘偏移📎 vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py:1042-1045，保留最小 RTT 樣本——因為高 RTT 只是雜訊，會扭曲中點估計。

第三步是相容性校驗。📎 vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py:1063-1080：

assert self.compat_hash is not None
if (
    self.enforce_compat_hash
    and handshake_payload.compatibility_hash != self.compat_hash
):
    raise RuntimeError(
        f"NIXL compatibility hash mismatch. "
        ...
    )

相容性雜湊在📎 vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py:1372-1376計算：

self.compat_hash = compute_nixl_compatibility_hash(
    self.vllm_config,
    self.backend_name,
    transfer_mode=self._TRANSFER_MODE,
)

注意transfer_mode也參與雜湊——📎 vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py:163-166的註解說明：push（WRITE）連接器和 pull（READ）連接器永遠不應該握手成功。

非同步握手排程

握手是非同步的，透過執行緒池執行。📎 vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py:824-835：

self._handshake_initiation_executor = ThreadPoolExecutor(
    # NIXL is not guaranteed to be thread-safe, limit 1 worker.
    max_workers=1,
    thread_name_prefix="vllm-nixl-handshake-initiator",
)
self._ready_requests = queue.Queue[tuple[ReqId, ReqMeta]]()
self._handshake_futures: dict[
    EngineId, Future[tuple[dict[tuple[int, int], str], float]]
] = {}
# Protects _handshake_futures and _remote_agents.
self._handshake_lock = threading.RLock()

max_workers=1是因為 NIXL 不保證執行緒安全。_handshake_lock保護_handshake_futures和_remote_agents兩個字典。

_ensure_handshake 📎 vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py:1257-1317實現了冪等的握手發起：如果已經握手成功直接回傳 None；如果正在握手中回傳已有的 Future；否則提交新任務並註冊回呼。

描述符構建：從 block ID 到 NIXL descriptor

握手完成後，需要為每個請求構建描述符。📎 vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py:172-310的_compute_desc_ids是核心。

對於純 attention 模型（無 SSM），走快速路徑📎 vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py:226-262。註解解釋了 HMA 場景下的處理：

# NOTE (NickLucche) With HMA, every kv group has the same number of layers
# and layers from different groups share the same kv tensor.
# eg block_ids=[[1, 2], [3]]->blocks [1, 2] need to be
# read across all regions, same for [3], but group0-group1 blocks will
# always differ (different areas). Therefore we can just flatten the
# block_ids and compute the descs ids for all groups at once.

對於混合 SSM 模型，描述符佈局更複雜📎 vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py:285-304：

elif _is_ssm_spec(spec_type):
    # NOTE (NickLucche) SSM and Attention block regions can
    # be exchanged arbitrarily by manager.  Therefore, descs
    # are laid out as:
    #   [descs_fa (all regions) | descs_ssm (all regions)].
    # num_fa_descs offset must be computed per-engine since
    # P and D can have different num_blocks (and thus
    # different FA desc counts).

傳輸拓撲與 TP 映射

異構 TP 是 NIXL 連接器最複雜的場景。📎 vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py:2130-2178的add_remote_agent文件詳細解釋了各種情況：

當 D.world_size > P.world_size 時，多個 D worker 從同一個 P worker 讀取不同的 KV head 分片。文件給出了具體例子：D TP=4，P TP=2，tp_ratio=2。D-Worker0 讀取 P-Worker0 的前半部分 KV head，D-Worker1 讀取後半部分。

對於 MLA 模型，KV Cache 在 TP worker 間是複製的，所以 rank_offset 永遠是 0。

租約與心跳：防止 block 被過早釋放

這是 NIXL 連接器最精妙的設計之一。Prefill 實例發送 KV 後，不能立即釋放 block——因為 decode 實例可能還在讀。但如果永遠不釋放，顯存會洩漏。

解決方案是租約（lease）。📎 vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py:528-528：

kv_lease_duration: int = vllm_config.kv_transfer_config.get_from_extra_config(
    "kv_lease_duration", 30
)
# NOTE (NickLucche): For now we use a hardcoded value for a simpler interface.
self._lease_extension = kv_lease_duration * 2 // 3

預設租約 30 秒，每次心跳延長 20 秒（2/3）。

心跳處理在📎 vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py:3014-3034：

def _handle_heartbeat(self, payload: str) -> None:
    new_expiry = time.perf_counter() + self._lease_extension
    for req_id in payload.split(","):
        if req_id in self._reqs_to_send:
            old = self._reqs_to_send[req_id]
            self._reqs_to_send[req_id] = max(old, new_expiry)

注意max(old, new_expiry)——心跳只能延長租約，不能縮短。

租約過期後的回收在📎 vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py:2986-3012：

def _reap_expired_send_leases(self, done_sending: set[str]) -> None:
    """Reclaim expired send-side KV leases into ``done_sending``.

    ``_reqs_to_send`` is not ordered by expiry: heartbeats update the
    deadline in place, and mixed TTLs share the map, so a live head
    entry can sit in front of already-expired ones. Scan every entry
    rather than stopping at the first still-live request.
    """

註釋指出了一個容易犯的錯誤：不能因為遇到第一個未過期的請求就停止掃描，因為心跳會原地更新過期時間，導致 map 不是按過期時間排序的。

傳輸狀態機與失敗恢復

傳輸的生命週期透過_pop_done_transfers 📎 vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py:3036-3086管理：

for handle in handles:
    try:
        xfer_state = self.nixl_wrapper.check_xfer_state(handle)
        if xfer_state == "DONE":
            res = self.nixl_wrapper.get_xfer_telemetry(handle)
            self.xfer_stats.record_transfer(res)
            self.nixl_wrapper.release_xfer_handle(handle)
        elif xfer_state == "PROC":
            in_progress.append(handle)
        else:
            self._log_failure(
                failure_type="transfer_failed",
                req_id=req_id,
                xfer_state=xfer_state,
            )

NIXL 傳輸有三種狀態：DONE（完成）、PROC（進行中）、其他（失敗）。

失敗處理在📎 vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py:3103-3127：

def _handle_failed_transfer(
    self,
    req_id: str,
    handle: int | None,
    failed_req_ids: set[str] | None = None,
    record_failed_transfer: bool = True,
) -> bool:
    if record_failed_transfer:
        self.xfer_stats.record_failed_transfer()
    if failed_req_ids is not None:
        failed_req_ids.add(req_id)
    return handle is None or self._try_release_xfer_handle(req_id, handle)

_try_release_xfer_handle 📎 vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py:3088-3101的註釋很關鍵：

except Exception as e:
    # A status error does not guarantee that the backend stopped DMA.
    self._log_failure(
        failure_type="transfer_release_failed",
        msg="Retaining handle and blocks until release succeeds",
        ...
    )
    return False

狀態錯誤不保證後端停止了 DMA。如果釋放失敗，必須保留 handle 和 block，直到釋放成功。這是一個典型的「寧可洩漏也不要用錯」的設計。

失敗請求的 block 處理

當接收失敗時，📎 vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py:2876-2891展示了處理邏輯：

for req_id in done_recving:
    meta = self._recving_metadata.pop(req_id, None)
    assert meta is not None, f"{req_id} not found in recving_metadata list"

    # Skip KV sync and post-processing for failed requests
    if req_id in failed_recv_reqs:
        self._pending_recv_notifs.pop(req_id, None)
        # TODO (NickLucche) handle failed transfer for HMA.
        if not self._is_hma_required:
            self._invalid_block_ids.put(set(meta.local_block_ids[0]))
        logger.warning(
            "Skipping KV post-processing for failed request %s",
            req_id,
        )
        continue

失敗的 block ID 被放入_invalid_block_ids隊列，Scheduler 透過get_block_ids_with_load_errors 📎 vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py:3491-3504取出，決定是否重試。

遠端引擎的 TTL 驅逐

長期運行的實例會不斷遇到新的遠端引擎，如果不清理，記憶體會無限增長。📎 vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py:3506-3532的_evict_stale_engines實現了 TTL 驅逐：

def _evict_stale_engines(self) -> None:
    """Scan for and evict remote engines that have exceeded their TTL.

    Called from the main thread in when a new remote engine appears.
    We can only go OOM as we discover and register a new remote, therefore we make
    sure we clean up stale engine data structures before then.
    """
    if self._engine_ttl <= 0:
        return

    now = time.perf_counter()
    busy = self._engines_with_inflight_transfers()
    for eid, last_active in list(self._engine_last_active.items()):
        if now - last_active > self._engine_ttl and eid not in busy:
            self._cleanup_remote_engine(eid)

關鍵約束是busy集合——有進行中傳輸的引擎不能被驅逐。📎 vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py:3534-3546的註釋解釋了原因：

"""Remote engines a transfer is still reading from.

The timestamp is stamped when a read is issued and not refreshed while
it runs, so a transfer that outlives the TTL leaves its engine looking
idle. A peer that has lost its NIC holds one indefinitely.
"""

如果對端網卡壞了，傳輸可能永遠掛著，時間戳不會刷新，引擎看起來是空閒的。busy集合顯式保護了這種情況。

握手與傳輸的時序

下面這張時序圖展示了從請求到傳輸完成的核心互動：

sequenceDiagram
    participant Sched as Scheduler
    participant Worker as NixlWorker
    participant BgThread as 握手后台线程
    participant Remote as 远程 NIXL Agent

    Sched->>Worker: build_connector_meta()
    Worker->>Worker: _ensure_handshake(engine_id)
    alt 已握手
        Worker->>Worker: 直接返回 None
    else 握手中
        Worker->>BgThread: 返回已有 Future
    else 新握手
        Worker->>BgThread: submit(_nixl_handshake)
        BgThread->>Remote: ZMQ GET_META_MSG
        Remote-->>BgThread: NixlHandshakePayload
        BgThread->>BgThread: 校验 compat_hash
        BgThread->>Remote: add_remote_agent()
        BgThread-->>Worker: done_callback 注册 _remote_agents
    end
    Worker->>Remote: prep_xfer_dlist + make_xfer_req
    Worker->>Worker: _recving_transfers[req_id] = handles
    Sched->>Worker: get_transfer_results()
    Worker->>Worker: _pop_done_transfers()
    alt xfer_state == DONE
        Worker->>Remote: release_xfer_handle
        Worker-->>Sched: finished_recving
    else xfer_state == PROC
        Worker->>Worker: 保留 handle 等待下一轮
    else 失败
        Worker->>Worker: _handle_failed_transfer
        Worker-->>Sched: failed_recving + invalid_block_ids
    end

---

三、設計思考：為什麼這樣設計

為什麼握手要異步？

握手涉及網路往返，可能耗時幾十毫秒。如果同步執行，會阻塞 Scheduler 的主迴圈，影響所有請求的調度。異步握手讓 Scheduler 可以先處理其他請求，握手完成後透過回調通知。

但異步也帶來了複雜性：_handshake_futures字典需要鎖保護，回調裡要處理成功和失敗兩種情況，還要防止重複握手。

為什麼用租約而不是引用計數？

引用計數需要 decode 實例顯式通知 prefill「我讀完了」。但如果 decode 實例崩潰，通知永遠不會到達，prefill 的 block 就永遠洩漏了。

租約是更魯棒的方案：即使 decode 崩潰，租約到期後 prefill 自動回收。心跳機制則保證正常情況下的租約續期。

為什麼失敗時保留 handle？

📎 vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py:3088-3101的註釋說得很清楚：狀態錯誤不保證 DMA 停止。如果此時釋放 handle，DMA 可能還在往已釋放的記憶體寫資料，導致資料損壞或崩潰。寧可暫時洩漏，也不能冒這個風險。

為什麼 TTL 驅逐要檢查 busy？

📎 vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py:3534-3546的註釋揭示了一個隱蔽的 bug 場景：時間戳在讀取發起時打上，讀取期間不刷新。如果傳輸時間超過 TTL，引擎看起來是空閒的，但實際上還在被讀取。如果此時驅逐，正在進行的傳輸會失敗。

生產環境踩坑點

1. CUDA 上下文問題：握手在後台線程執行，必須顯式set_device，否則 UCX 會靜默禁用 NVLink。

2. 兼容性哈希不匹配：P/D 實例的 vLLM 版本、模型、dtype、KV layout、attention backend 必須完全一致。不一致時握手會失敗，錯誤信息會提示如何禁用檢查（但不建議）。

3. 租約過期：如果 decode 實例負載很高，心跳可能延遲，導致租約過期。日誌裡會出現 "Releasing expired KV blocks" 警告。可以調大kv_lease_duration。

4. TP 不匹配：異構 TP 需要 block-contiguous 佈局（如 LBHNC）。如果用了非連續佈局，異構 TP 會失敗。

5. NIXL UAR 耗盡：📎 vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py:631-636的註釋警告：每個 UCX 執行緒透過 DevX 分配 UAR（doorbell pages），過多的 NIXL UAR 使用會耗盡 NIC UAR 空間，導致 NVSHMEM（DeepEP 核心使用）在 RDMA 初始化時失敗。

---

本章小結

本章深入了 KV Connector 體系的核心機制：

1. KVConnectorBase_V1定義了 Scheduler 側和 Worker 側的雙角色抽象，透過KVConnectorMetadata和KVConnectorTransferResults實現元資料交換和傳輸結果回饋。

2. NIXL 連接器是最成熟的實現，它透過 ZMQ 握手協定建立 P/D 實例間的連接，用相容性雜湊防止配置不匹配，用非同步執行緒池避免阻塞主迴圈。

3. 租約與心跳機制解決了 block 釋放的時序問題：prefill 發送 KV 後不立即釋放，而是等待 decode 的心跳續期或租約過期。

4. 失敗恢復遵循「寧可洩漏也不要用錯」的原則：釋放失敗時保留 handle，失敗的 block ID 上報給 Scheduler 決定重試。

5. TTL 驅逐防止長期運行時遠端引擎狀態無限增長，但必須保護有進行中傳輸的引擎。

下一章我們將轉向另一個消除開銷的方向：編譯加速與 CUDA Graph。當 PD 分離解決了資源利用率問題後，單次前向的啟動開銷成為新的瓶頸——如何用 CUDA Graph 把成百上千個核心啟動壓縮成一次重放。

本章思考與自測

至此，我們已經看清 KV Connector 如何在 prefill 與 decode 實例之間建立可靠的資料通道，以及它如何用租約、心跳和失敗恢復機制守住狀態一致性。但跨實例傳輸只是 PD 分離的一半故事——當 KV Cache 抵達 decode 實例後，推理引擎仍需在單實例內部高效執行每一步前向計算。而 Python 調度與內核啟動開銷，正是制約單步延遲的下一道瓶頸。下一章將轉向編譯加速與 CUDA Graph，看 vLLM 如何用 torch.compile 和 piecewise backend 消除這些開銷，並讓 CUDA Graph 與動態批處理形狀協調共存。

上一章我們看到，KV Connector 透過 NIXL、Mooncake 等連接器在 Prefill 與 Decode 引擎之間高效搬運 KV cache，讓分離式架構在降低 TTFT 的同時提升了資源利用率。但即便傳輸再快，自迴歸解碼中仍有兩項無法靠演算法消除的固定成本：Python 解譯器的調度開銷與 GPU 內核的啟動開銷。當模型前向被拆成數百個算子，每個算子都要經歷一次 Python 函式呼叫和一次 CUDA 內核啟動時，CPU 側的開銷足以讓 GPU 在兩次計算之間空轉。本章剖析 vLLM 如何用 torch.compile 把算子融合成靜態圖，再用 CUDA Graph 把整段內核啟動序列錄製成一次重放，從而把這兩類開銷壓到接近零。

編譯快取與編譯器適配層：讓編譯結果跨進程複用

直覺模型

編譯加速的收益是「一次編譯、多次執行」，但代價是首次編譯耗時可能長達數分鐘。如果沒有快取，每次服務重啟都要重新編譯，冷啟動時間無法接受。CompilerInterface這一層要解決的正是「編譯產物如何序列化、如何用雜湊標識、如何在下次啟動時精確命中」的問題。若沒有它，系統面臨的災難不是崩潰，而是每次重啟都退化成「首次執行」——在自動擴縮容的生產環境中，這意味著擴容出來的實例在數分鐘內無法提供低延遲服務。

資料結構與介面契約

CompilerInterface定義了編譯器適配器的抽象契約，核心是四個方法：initialize_cache負責把編譯器自身的快取目錄重定向到 vLLM 的快取目錄下📎 vllm/compilation/compiler_interface.py:36-51；compute_hash收集編譯器相關的配置資訊生成雜湊📎 vllm/compilation/compiler_interface.py:53-62；compile執行編譯並返回可呼叫物件與句柄📎 vllm/compilation/compiler_interface.py:64-95；load從句柄恢復編譯產物📎 vllm/compilation/compiler_interface.py:97-103。

這裡的關鍵設計是compile返回一個二元組(callable, handle)。callable是本次進程內可直接呼叫的編譯結果；handle是「下次啟動時用來恢復」的憑證，文件明確要求它應當是「plain Python object, preferably a string or a file path」📎 vllm/compilation/compiler_interface.py:81-81。這個分離讓快取命中路徑與首次編譯路徑可以走完全不同的程式碼——命中時根本不需要compile，只需要load。

compile_range參數承載了動態形狀的語義。註解說明它「could be concrete size (if compile_sizes is provided), e.g. [4, 4] or a range [5, 8]」，且「Right now we only support one variable in ranges for all inputs, which is the batchsize (number of tokens) during inference」📎 vllm/compilation/compiler_interface.py:74-74。這是 vLLM 編譯策略的核心約束：所有動態形狀被歸約為單一變數——token 數。

場景驅動：一次編譯請求的完整流轉

假設服務首次啟動，InductorAdaptor.compile被呼叫。它首先遞增編譯計數器📎 vllm/compilation/compiler_interface.py:477-489，然後進入一個精心構造的補丁堆疊。

第一步是深拷貝圖。註解指出「inductor can inplace modify the graph, so we need to copy it」📎 vllm/compilation/compiler_interface.py:500-502，這是防禦性設計——編譯失敗後原圖仍可用於重試。

第二步是安裝一系列 monkey-patch。hijacked_compile_fx_inner包裝了 Inductor 的內部編譯函式，在編譯完成後從inductor_compiled_graph._fx_graph_cache_key抓取雜湊📎 vllm/compilation/compiler_interface.py:512-536。hijack_compiled_fx_graph_hash則攔截雜湊計算函式本身📎 vllm/compilation/compiler_interface.py:538-542。為什麼要「劫持」雜湊？因為 vLLM 需要在 Dynamo 追蹤上下文之外單獨編譯，而 Inductor 的雜湊計算依賴該上下文。

第三步是_check_can_cache補丁，它直接返回、不做任何檢查📎 vllm/compilation/compiler_interface.py:544-551。註解解釋了動機：「Inductor refuses to cache the graph outside of Dynamo tracing context, and also disables caching for graphs with high-order ops. For vLLM, in either case, we want to cache the graph」📎 vllm/compilation/compiler_interface.py:544-551。

第四步是清理追蹤上下文。這是最微妙的一處：vLLM 從PiecewiseCompileInterpreter內部呼叫compile_fx，此時 Dynamo 的FakeTensorMode與子圖輸入的FakeTensorMode不一致，detect_fake_mode()會斷言失敗📎 vllm/compilation/compiler_interface.py:615-622。程式碼儲存TracingContext後將其置空，並註冊回調在退出時恢復📎 vllm/compilation/compiler_interface.py:623-630。

flowchart TD
    start["InductorAdaptor.compile()"] --> deepcopy["copy.deepcopy(graph)"]
    deepcopy --> patch_stack["ExitStack 安装补丁"]
    patch_stack --> p1["patch compiled_fx_graph_hash"]
    patch_stack --> p2["patch FxGraphCache._get_shape_env"]
    patch_stack --> p3["patch _check_can_cache"]
    patch_stack --> p4["清空 TracingContext"]
    p4 --> call_fx["compile_fx(graph, example_inputs)"]
    call_fx --> check{"hash_str is None?"}
    check -->|"是"| err["RuntimeError: 编译失败<br/>建议删除 torch_compile_cache"]
    check -->|"否"| check2{"file_path is None?"}
    check2 -->|"是"| assert_err["AssertionError"]
    check2 -->|"否"| ret["return (compiled_graph, (hash_str, file_path))"]
    err --> cleanup["ExitStack 退出<br/>恢复 TracingContext"]
    assert_err --> cleanup
    ret --> cleanup

設計思考：AlwaysHitShapeEnv 與快取一致性

AlwaysHitShapeEnv這個類別值得單獨剖析。它的文件字串直白地說明了動機：vLLM 只執行一次 Dynamo 位元組碼編譯，但要用不同形狀加一個通用形狀多次執行 Inductor 編譯；針對特定形狀的編譯發生在 Dynamo 上下文之外，此時沒有 shape environment 提供給 Inductor，會導致 Inductor 程式碼快取查找失敗📎 vllm/compilation/compiler_interface.py:114-131。

解決方案是提供一個「永遠命中」的假 shape environment：evaluate_guards_expression恆返回True 📎 vllm/compilation/compiler_interface.py:144-145，get_pruned_guards返回空列表📎 vllm/compilation/compiler_interface.py:144-145，produce_guards_expression返回空字串📎 vllm/compilation/compiler_interface.py:147-159。註解坦承這些方法是「obtained by trial-and-error until it works」📎 vllm/compilation/compiler_interface.py:137-142——這是與 PyTorch 內部實作耦合的脆弱點，也是升級 PyTorch 時最易出問題的地方。

快取雜湊的構成同樣關鍵。get_inductor_factors收集三類因子：系統狀態CacheBase.get_system()、PyTorch 狀態torch_key()、以及 Inductor 與 functorch 的配置📎 vllm/compilation/compiler_interface.py:165-185。注意 functorch 配置是在patch(_get_vllm_functorch_config())上下文中採集的📎 vllm/compilation/compiler_interface.py:188-189，這保證了「編譯時配置與快取鍵始終一致」——註解明確說這是為了讓set_functorch_config()和get_inductor_factors()保持一致📎 vllm/compilation/compiler_interface.py:147-159。如果這兩處不一致，就會出現「編譯時用了配置 A、快取鍵按配置 B 計算」的錯配，導致快取命中卻載入了錯誤的產物。

生產踩坑：_patch_standalone_compile_atomic_save是針對 torch < 2.10.0 的 backport📎 vllm/compilation/compiler_interface.py:205-243。它把CompiledArtifact.save()改為用write_atomic寫二進位格式，註解說明目的是「preventing corrupt cache files when multiple processes compile concurrently」📎 vllm/compilation/compiler_interface.py:208-210。在多副本同時冷啟動的場景下，多個行程會並發寫同一個快取檔案，非原子寫會產生半截檔案，後續行程讀到損壞產物後行為不可預測。

PiecewiseBackend：按形狀分檔編譯與執行時派發

直覺模型

PiecewiseBackend是編譯與執行之間的排程中樞。它把「一個 FX 子圖」編譯成「多個形狀檔位的可呼叫物件」，並在執行時根據實際 token 數選擇最合適的那一個。若沒有它，要麼所有形狀都走同一個通用編譯（效能次優），要麼每個形狀都單獨編譯（編譯時間爆炸）。

資料結構：RangeEntry 與編譯範圍

核心資料結構是RangeEntry，它把compile_range、compiled標誌和runnable綁定在一起📎 vllm/compilation/piecewise_backend.py:80-83。PiecewiseBackend維護一個range_entries: dict[Range, RangeEntry] 📎 vllm/compilation/piecewise_backend.py:166-171。

編譯範圍的構造分兩步。首先處理compile_sizes（精確尺寸），每個尺寸生成一個Range(start=size, end=size)的單點區間📎 vllm/compilation/piecewise_backend.py:166-171。注意這裡對字串"cudagraph_capture_sizes"直接拋NotImplementedError，並說明「should be handled inpost_init_cudagraph_sizes" 📎 vllm/compilation/piecewise_backend.py:166-171——這是一個顯式的職責邊界聲明。然後處理compile_ranges（區間），每個區間生成一個 entry📎 vllm/compilation/piecewise_backend.py:173-173。

PiecewiseBackend支援兩種互斥模式，建構函式用異或斷言強制這一點📎 vllm/compilation/piecewise_backend.py:117-119：編譯模式（有 graph，無 compiled_runnables）走compile_all_ranges() 📎 vllm/compilation/piecewise_backend.py:193-194；預編譯模式（無 graph，有 compiled_runnables）走load_all_ranges() 📎 vllm/compilation/piecewise_backend.py:193-194。這個設計讓冷啟動與熱啟動共享同一個類別，只是資料來源不同。

場景驅動：從編譯到執行時派發

編譯階段：compile_all_ranges遍歷所有 range entry，對每個未編譯的 entry 呼叫_log_compile_start記錄追蹤事件📎 vllm/compilation/piecewise_backend.py:252-256。關鍵分支在參數構造：如果是單點尺寸，呼叫create_concrete_args生成具體形狀的 FakeTensor📎 vllm/compilation/piecewise_backend.py:258-261；否則呼叫get_fake_args_from_graph直接復用圖中的 placeholder 元資料📎 vllm/compilation/piecewise_backend.py:262-263。

create_concrete_args的實作揭示了符號形狀具體化的細節。它構造一個帶ShapeEnv的FakeTensorMode 📎 vllm/compilation/piecewise_backend.py:54，然後遍歷 placeholder 節點。對SymInt類型的輸入，用concretize把所有自由符號替換為size 📎 vllm/compilation/piecewise_backend.py:47-52；對Tensor類型，則要同時具體化 shape、stride、storage_offset，並用compute_required_storage_length算出所需儲存長度，再透過as_strided重建張量📎 vllm/compilation/piecewise_backend.py:64-73。為什麼不能只改 shape？因為 stride 和 storage_offset 也可能含符號，且三者必須自洽，否則as_strided會越界。

執行時派發：__call__是熱路徑。如果存在sym_shape_indices，從args中取出執行時形狀📎 vllm/compilation/piecewise_backend.py:357-362，然後呼叫_find_range_for_shape查找。查找邏輯有優先級：先看是否命中精確的compile_sizes，命中則返回該單點區間📎 vllm/compilation/piecewise_backend.py:342-355；否則遍歷compile_ranges找包含該形狀的區間📎 vllm/compilation/piecewise_backend.py:342-355。

flowchart TD
    call["PiecewiseBackend.__call__(*args)"] --> has_sym{"sym_shape_indices 非空?"}
    has_sym -->|"是"| get_shape["runtime_shape = args[sym_shape_indices[0]]"]
    get_shape --> find["_find_range_for_shape(runtime_shape)"]
    find --> exact{"runtime_shape in compile_sizes?"}
    exact -->|"是"| exact_entry["返回 Range(start=shape, end=shape) 的 entry"]
    exact -->|"否"| scan["遍历 compile_ranges 找包含区间"]
    scan --> found{"找到?"}
    found -->|"否"| assert_fail["AssertionError: 形状超出编译范围"]
    found -->|"是"| entry_ok["返回对应 entry"]
    has_sym -->|"否"| static["取唯一已编译 entry"]
    static --> check_count{"compiled_entries 数量 == 1?"}
    check_count -->|"否"| count_err["AssertionError"]
    check_count -->|"是"| entry_ok
    exact_entry --> run["range_entry.runnable(*args)"]
    entry_ok --> run

設計思考：序列化與 CachingAutotuner 的特殊處理

序列化時還臨時開啟bundled_autograd_cache 📎 vllm/compilation/piecewise_backend.py:222，這與_get_vllm_functorch_config中的邏輯呼應——當VLLM_USE_MEGA_AOT_ARTIFACT未啟用時該配置為False 📎 vllm/compilation/compiler_interface.py:160-161，序列化時則強制為True，確保產物被打包。

load_all_ranges是熱啟動路徑，它斷言每個 range 都能在compiled_runnables中找到對應 key，否則拋出包含可用 key 列表的錯誤📎 vllm/compilation/piecewise_backend.py:329-339。這個錯誤訊息設計得很實用——直接列出可用 key，便於排查快取版本不匹配。

CUDA Graph 包裝器：捕獲、重放與嵌套派發

直覺模型

CUDA Graph 把「一串核心啟動」錄製成一張靜態圖，之後每次重放只需一次 API 呼叫。CUDAGraphWrapper就是錄製與重放的執行者。它面臨的核心難題是：vLLM 的批次大小是動態的，而 CUDA Graph 要求輸入位址固定。解決方案是「按 batch descriptor 分檔捕獲」——每個形狀檔位錄一張圖，執行時按 descriptor 查表重放。

資料結構：CUDAGraphEntry 與派發契約

CUDAGraphEntry持有三個關鍵欄位：batch_descriptor作為派發鍵📎 vllm/compilation/cuda_graph.py:128-135、cudagraph是捕獲的圖物件📎 vllm/compilation/cuda_graph.py:128-135、output是捕獲時的輸出（用弱引用保存以省記憶體）📎 vllm/compilation/cuda_graph.py:128-135。input_addresses僅在除錯模式下用於校驗重放時輸入位址一致📎 vllm/compilation/cuda_graph.py:128-135。

CUDAGraphWrapper的類別文件精確描述了派發契約：初始化時分配一個 runtime mode（FULL 或 PIECEWISE）📎 vllm/compilation/cuda_graph.py:158-158；執行時從 forward context 接收 runtime_mode 和 batch_descriptor 並「blindly trust them」📎 vllm/compilation/cuda_graph.py:158-158；若 runtime_mode 為 NONE 或不匹配則直接呼叫📎 vllm/compilation/cuda_graph.py:158-158；否則執行捕獲或重放📎 vllm/compilation/cuda_graph.py:158-158。

文件還特別聲明了一個邊界：「CUDAGraphWrapper does not store persistent buffers or copy any runtime inputs into that buffers for replay」📎 vllm/compilation/cuda_graph.py:164-164。這意味著輸入緩衝區的管理是呼叫方的責任——wrapper 只負責圖本身。

場景驅動：一次捕獲與一次重放

捕獲路徑：當__call__被觸發且 runtime_mode 匹配時，先檢查 forward context 是否可用。若不可用（如視覺編碼器的前向），直接呼叫底層函式📎 vllm/compilation/cuda_graph.py:232-233。這是多模態場景的關鍵分支——ViT 前向不走 CUDA Graph。

接著取batch_descriptor和cudagraph_runtime_mode 📎 vllm/compilation/cuda_graph.py:242-244。若 mode 為 NONE 或不匹配，直接呼叫📎 vllm/compilation/cuda_graph.py:246-256。這個「不匹配就直通」的設計讓嵌套 wrapper 得以共存：FULL wrapper 在外層、PIECEWISE wrapper 在內層，執行時只有一個會被激活。

若 entry 的cudagraph為 None，進入捕獲。先呼叫validate_cudagraph_capturing_enabled()校驗合法性📎 vllm/compilation/cuda_graph.py:279，然後記錄輸入位址📎 vllm/compilation/cuda_graph.py:281-284，建立torch.cuda.CUDAGraph() 📎 vllm/compilation/cuda_graph.py:285。

捕獲上下文中有幾處關鍵操作。若gc_disable開啟，則 patch 掉gc.collect和torch.accelerator.empty_cache 📎 vllm/compilation/cuda_graph.py:288-303。註解解釋了原因：piecewise 模式下每層都要捕獲一張圖，反覆 GC 會讓捕獲極慢，所以「only run gc for the first graph, and disable gc for the rest」📎 vllm/compilation/cuda_graph.py:289-294。接著設定 graph pool id📎 vllm/compilation/cuda_graph.py:305-308，並同步 offloader 的拷貝流📎 vllm/compilation/cuda_graph.py:310-312。

真正的捕獲在torch.cuda.graph(cudagraph, pool=..., stream=...)上下文中執行self.runnable(*args, **kwargs) 📎 vllm/compilation/cuda_graph.py:315-321。捕獲後呼叫get_offloader().join_after_forward()避免未 join 的流錯誤📎 vllm/compilation/cuda_graph.py:322-326。若weak_ref_output開啟，把 output 轉為弱引用以省記憶體📎 vllm/compilation/cuda_graph.py:327-334。最後 entry 保存弱引用 output 和圖物件📎 vllm/compilation/cuda_graph.py:338-339，但返回的是原始 output 而非弱引用——註解強調這是為了讓 PyTorch 在捕獲期間正確管理記憶體📎 vllm/compilation/cuda_graph.py:343-346。

重放路徑：若 entry 已有圖，除錯模式下校驗輸入位址一致📎 vllm/compilation/cuda_graph.py:348-357，然後同步 offloader📎 vllm/compilation/cuda_graph.py:359-361，呼叫entry.cudagraph.replay()並返回entry.output 📎 vllm/compilation/cuda_graph.py:362-363。

設計思考：為什麼輸出要弱引用，而返回要強引用

這是CUDAGraphWrapper中最反直覺的一處。捕獲時output由 PyTorch 的 cudagraph pool 管理📎 vllm/compilation/cuda_graph.py:320。如果 entry 強引用 output，那麼這張圖佔用的顯存永遠無法釋放；但如果在捕獲期間就把它轉成弱引用，PyTorch 可能在捕獲完成前就回收記憶體，導致捕獲失敗。所以程式碼在捕獲區塊內用弱引用📎 vllm/compilation/cuda_graph.py:334，在 entry 中存弱引用📎 vllm/compilation/cuda_graph.py:338，但函式返回值是強引用📎 vllm/compilation/cuda_graph.py:346。這個「三重引用狀態」是記憶體安全與顯存效率的精確平衡。

另一個值得注意的設計是_all_instances這個WeakSet 📎 vllm/compilation/cuda_graph.py:173-176。它讓clear_all_graphs能一次性清空所有 wrapper 的圖📎 vllm/compilation/cuda_graph.py:173-176，用於顯存緊張時的緊急回收。用WeakSet而非普通集合，是為了不阻止 wrapper 被 GC——否則 wrapper 本身會洩漏。

生產踩坑：__getattr__的實作會在除錯模式下對不存在的屬性拋出帶上下文的錯誤📎 vllm/compilation/cuda_graph.py:211-217。這看似小事，但在排查「為什麼某個方法呼叫失敗」時，能看到 wrapper 包裝的 runnable 字串描述，比裸AttributeError有用得多。

設計思考：編譯與 CUDA Graph 的解耦

設計文件明確記錄了這次重構的動機。早期 piecewise 編譯是為了支援 piecewise CUDA Graph 捕獲，把不支援 CUDA Graph 的算子（主要是 attention）排除在外📎 docs/design/cuda_graphs.md:25。後來加入 full CUDA Graph 支援，但「this tight coupling between compilation and cudagraph capture led to an all-or-nothing experience with little flexibility」📎 docs/design/cuda_graphs.md:25。

重構後的目標有四條：顯式區分 prefill/mixed 與 uniform-decode 批次並分別捕獲📎 docs/design/cuda_graphs.md:25-25；把 CUDA Graph 捕獲邏輯與編譯解耦，使「capturing piecewise and full cudagraphs using the same compiled graph」📎 docs/design/cuda_graphs.md:25-25；執行時按批次組成派發📎 docs/design/cuda_graphs.md:25-25；集中控制以降低複雜度📎 docs/design/cuda_graphs.md:25-25。

BatchDescriptor是派發鍵的核心結構，包含num_tokens、num_reqs、uniform、has_lora四個欄位📎 docs/design/cuda_graphs.md:86-93。uniform標誌尤為關鍵——許多 attention 後端只在批次 uniform 時支援 full CUDA Graph📎 docs/design/cuda_graphs.md:95-95。文件還預告了這個結構可能擴展，比如加入uniform_query_len支援多種 uniform decode 長度📎 docs/design/cuda_graphs.md:95-95。

派發優先級是FULL > PIECEWISE > None，若派發鍵不存在則回退到 NONE 模式做 eager 執行📎 docs/design/cuda_graphs.md:112-115。這個「降級而非報錯」的策略保證了任何批次組合都能執行，只是效能不同。

AttentionCGSupport枚舉量化了後端的 CUDA Graph 能力，取值ALWAYS=3 > UNIFORM_BATCH=2 > UNIFORM_SINGLE_TOKEN_DECODE=1 > NEVER=0 📎 docs/design/cuda_graphs.md:153-162。混合 attention 模型（如 mamba mixer）取所有後端能力的最小值，並據此降級 CUDA Graph 模式📎 docs/design/cuda_graphs.md:173-175。這個設計讓「能力宣告」與「模式選擇」解耦——新增後端只需宣告能力，降級策略自動生效。

本章小結

本章思考與自測

下一章將轉向量化與自訂核心，看 vLLM 如何從權重載入階段就介入精度控制，並用高度特化的算子把量化收益真正兌現為吞吐提升。

本章剖析了 vLLM 編譯加速的兩層機制。第一層是 CompilerInterface 與 PiecewiseBackend：前者定義了編譯器適配契約與快取雜湊策略，用 AlwaysHitShapeEnv 繞過 Dynamo 上下文缺失的問題；後者把單個 FX 子圖編譯成多個形狀檔位，執行時按 token 數派發。第二層是 CUDAGraphWrapper：它按 BatchDescriptor 分檔捕獲 CUDA Graph，透過 runtime mode 匹配實現嵌套派發，讓 FULL 與 PIECEWISE 兩種模式在同一編譯圖上共存。兩者的解耦是本次重構的核心——編譯產物可被兩種 CUDA Graph 模式複用，CUDA Graph 也可脫離編譯獨立工作。不過，編譯與圖捕獲解決的是排程開銷，模型本身的權重精度與算子效率仍是另一條優化主線。下一章將轉向量化與自訂核心，看 vLLM 如何解析量化配置、在權重載入時完成 FP8/INT4/AWQ/GPTQ 等格式轉換，並藉助 _custom_ops 與 Triton 核心進一步壓榨硬體效能。

上一章我們看到，torch.compile 與 CUDA Graph 把 Python 排程與核心啟動開銷壓到了極致。但排程再快，如果權重本身是 FP16、矩陣乘法走的是通用 GEMM，硬體算力仍然被顯示記憶體頻寬和低效算子拖住。量化與自訂核心是另一條正交的優化主線：前者在權重載入階段就把精度壓下來，後者把量化收益真正兌現為吞吐。本章從量化配置的解析入口出發，一路走到 _custom_ops 的算子註冊與 Triton 核心排程。

11.1 量化配置：從 CLI 字串到 QuantKey

直覺模型

量化配置模組的角色，像一家餐廳的點菜單翻譯器。使用者在前台說「我要 fp8_per_tensor」（CLI 字串），後廚需要的是精確的配方編號（QuantKey）。翻譯器必須處理三種輸入：純 CLI 簡寫、checkpoint 自帶的量化元資料、以及兩者疊加的組合場景。若沒有這層翻譯，後廚會收到一堆含義模糊的字串，無法決定該呼叫哪個 kernel。

資料結構與記憶體佈局

核心資料結構是QuantSpec與QuantizationConfigArgs。前者描述單類層（linear 或 MoE）的權重與啟動量化鍵，後者是使用者可見的頂層配置。

📎 vllm/config/quantization.py:73-99

@config
class QuantSpec:
    weight: QuantKeyField = None
    activation: QuantKeyField = None

    def __str__(self) -> str:
        def quant_key_str(quant_key: QuantKey | None) -> str:
            if quant_key is None:
                return "None"
            return next(
                (
                    name
                    for name, known_quant_key in QUANT_KEY_NAMES.items()
                    if known_quant_key == quant_key
                ),
                str(quant_key),
            )
        return quant_key_str(self.weight)

weight與activation都是可選的QuantKey。None的語義是「回退到方法類自己的預設值」——通常繼承自 checkpoint，在線量化場景下則意味著不量化📎 vllm/config/quantization.py:74-74。QuantKey本身是一個包含NamedTuple與ClassVar[GroupShape]聲明的複雜型別，pydantic 無法直接內省它，因此作者用GetPydanticSchema注入了一個自訂校驗器_coerce_quant_key，把字串或QuantKey統一歸一化📎 vllm/config/quantization.py:60-69。

QuantizationConfigArgs的欄位佈局值得注意📎 vllm/config/quantization.py:102-126：

• linear / moe：分別作用於LinearBase與FusedMoEFactory層；
• ignore：跳過量化的層名列表，在線量化還支援 fnmatch 通配；
• targets：逐層在線量化覆蓋，鍵可以是精確層名、re:前綴的正則、或 fnmatch 模式，值與linear/moe互斥。

targets與linear/moe的互斥由model_validator強制📎 vllm/config/quantization.py:172-179。這個約束不是形式主義：targets走的是逐層覆蓋路徑，linear/moe走的是全域預設路徑，兩者同時存在會讓「某層到底用哪個 spec」變得不可判定。

Step-by-Step：一次--quantization fp8_per_tensor的解析

代入場景：使用者在命令列傳入--quantization fp8_per_tensor，同時透過--quantization-config指定了 MoE 層的激活量化。

第一步，resolve_quantization_config被呼叫，參數是 CLI 字串與配置字典📎 vllm/config/quantization.py:233-235。它先檢查quantization是否在ONLINE_QUANT_SHORTHAND_NAMES中——這個元組包含所有簡寫名加一個"online" 📎 vllm/config/quantization.py:216-222。

第二步，fp8_per_tensor命中簡寫表，base被解析為_ONLINE_SHORTHANDS["fp8_per_tensor"]，即 linear 與 moe 都用kFp8StaticTensorSym 📎 vllm/config/quantization.py:188-190。

第三步，quantization_config非空，被構造為QuantizationConfigArgs物件。隨後進入合併邏輯📎 vllm/config/quantization.py:267-268：每個欄位用quantization_config.xxx or base.xxx決定——使用者顯式設置的欄位優先，未設置的繼承簡寫預設值。這裡用or而非if is not None是有意的：QuantSpec和空列表都是 falsy，語義上「未設置」與「空」等價。

第四步，如果quantization不在簡寫表中（比如是 checkpoint 自帶的awq），且quantization_config為None，函式直接返回None 📎 vllm/config/quantization.py:256-257。這表示「不疊加在線量化」，checkpoint 的量化方法保持主導。

有一個容易忽略的分支：_DEFERRED_ONLINE_SHORTHANDS包含mxfp4與mxfp8 📎 vllm/config/quantization.py:233-235。這兩個名字既是 CLI 簡寫，又是 checkpoint 量化方法名。當使用者只傳--quantization mxfp4而沒有quantization_config時，函式返回None而非base 📎 vllm/config/quantization.py:267-268，把決定權推遲給 checkpoint 元資料——只有當 checkpoint 沒有量化資訊時，才回退到在線簡寫。

flowchart TD
    start["resolve_quantization_config(quantization, quantization_config)"]
    check_shorthand{"quantization in ONLINE_QUANT_SHORTHAND_NAMES?"}
    checkpoint_path{"quantization_config is None?"}
    return_none1["return None (checkpoint 主导)"]
    build_args["QuantizationConfigArgs(**quantization_config)"]
    get_base["base = _ONLINE_SHORTHANDS.get(quantization)"]
    cfg_none{"quantization_config is None?"}
    deferred{"quantization in _DEFERRED_ONLINE_SHORTHANDS?"}
    return_none2["return None (推迟到 checkpoint)"]
    return_base["return base"]
    merge["逐字段合并: cfg.xxx or base.xxx"]
    return_merged["return 合并后的 QuantizationConfigArgs"]

    start --> check_shorthand
    check_shorthand -->|否| checkpoint_path
    checkpoint_path -->|是| return_none1
    checkpoint_path -->|否| build_args
    check_shorthand -->|是| get_base
    get_base --> cfg_none
    cfg_none -->|是| deferred
    deferred -->|是| return_none2
    deferred -->|否| return_base
    cfg_none -->|否| merge
    merge --> return_merged

設計思考與踩坑

_coerce_spec校驗器處理了一個微妙場景：當linear或moe收到字串時，先查_ONLINE_SHORTHANDS，命中則取出對應欄位的 spec；未命中則當作單個QuantKey名處理📎 vllm/config/quantization.py:130-139。這意味著linear="fp8_per_tensor"和linear="fp8_per_tensor_static"走的是兩條不同路徑——前者是完整配置簡寫，後者是單個量化鍵。如果簡寫中該欄位為None（比如int8_per_channel_weight_only沒有linear欄位），會拋出明確的ValueError而非靜默返回None 📎 vllm/config/quantization.py:130-139。

生產環境的一個常見陷阱：targets的正則鍵在_validate_targets中被預編譯驗證📎 vllm/config/quantization.py:166-167，但 fnmatch 模式的鍵不做驗證。如果使用者寫了一個永遠匹配不到任何層的 fnmatch 模式，不會報錯，只是該層保持未量化——排查時需要檢查層名是否真的匹配。

11.2 _custom_ops：算子註冊與 fake 實現

直覺模型

_custom_ops.py是 vLLM 與底層 CUDA/C++ 算子之間的適配層，像一座海關。PyTorch 的torch.ops._C命名空間裡註冊著編譯好的 C++ 算子，但直接呼叫它們有三個問題：不同平台（CUDA/ROCm/CPU/XPU）的算子集不同、torch.compile需要 fake 實現來推導輸出形狀、部分算子需要 Python 側的參數預處理。_custom_ops把這些問題統一封裝。

資料結構與註冊機制

模組載入時首先呼叫current_platform.import_kernels() 📎 vllm/_custom_ops.py:25-26，讓平台層有機會匯入自己的算子庫。隨後定義register_fake——在TYPE_CHECKING下是空裝飾器，執行時從torch.library匯入📎 vllm/_custom_ops.py:25-26。

fake 實現的核心作用是讓torch.compile在追蹤階段知道算子的輸出形狀與 dtype，而不實際執行。以scaled_fp4_quant為例：

📎 vllm/_custom_ops.py:90-100

if hasattr(torch.ops, "_C") and hasattr(torch.ops._C, "scaled_fp4_quant"):

    @register_fake("_C::scaled_fp4_quant")
    def _scaled_fp4_quant_fake(
        input: torch.Tensor,
        input_scale: torch.Tensor,
        is_sf_swizzled_layout: bool,
    ) -> tuple[torch.Tensor, torch.Tensor]:
        n = input.shape[-1]
        m = input.numel() // n
        return create_fp4_output_tensors(m, n, input.device, is_sf_swizzled_layout)

注意hasattr守衛：只有當平台真的註冊了_C::scaled_fp4_quant時，fake 實現才被定義。這保證了在 CPU 或舊 GPU 上匯入模組不會因為缺少算子而崩潰。

create_fp4_output_tensors展示了 FP4 量化輸出的記憶體佈局細節📎 vllm/_custom_ops.py:69-87。當is_sf_swizzled_layout=True時，scale 張量需要按 Tensor Core 要求的 128x4 tile 排布：行數向上取整到 128 的倍數，列數（n // 16）向上取整到 4 的倍數，每 4 個 float8_e4m3 打包進一個 int32📎 vllm/_custom_ops.py:55-64。註解明確指出 NVFP4 量化核心會顯式清零所有 padding 的 scale 條目，因此不需要單獨的零初始化 kernel📎 vllm/_custom_ops.py:60-61。

Step-by-Step：一次 AWQ GEMM 的呼叫流

代入場景：模型載入了一個 AWQ 量化的權重，前向傳播時需要對激活與量化權重做矩陣乘法。

第一步，呼叫awq_gemm 📎 vllm/_custom_ops.py:587-592。函式首先檢查環境變數VLLM_USE_TRITON_AWQ。如果為真，延遲匯入awq_gemm_triton並呼叫——這是一條純 Triton 實現路徑，用於不支援 CUDA 算子的平台或除錯場景。

第二步，預設路徑呼叫torch.ops._C.awq_gemm，傳入 input、qweight、scales、qzeros 和split_k_iters 📎 vllm/_custom_ops.py:598-598。

第三步，如果torch.ops._C.awq_gemm存在，fake 實作被註冊📎 vllm/_custom_ops.py:601-616。fake 返回的形狀是(split_k_iters, num_in_feats, qweight.size(1) * 8)然後.sum(0)——這精確模擬了 split-K 的中間結果形狀與歸約後的最終形狀。qweight.size(1) * 8來自 AWQ 的打包方式：每個 int32 存 8 個 4-bit 權重。

第四步，awq_dequantize走類似路徑📎 vllm/_custom_ops.py:553-559，但 fake 實作的形狀推導不同：out_c = qout_c * 8，因為反量化後列數擴展 8 倍📎 vllm/_custom_ops.py:587-592。

Marlin 系列的 repack 函式展示了另一種模式。gptq_marlin_repack的 fake 實作計算pack_factor = 32 // num_bits，輸出形狀是(size_k // 16, size_n * 16 // pack_factor) 📎 vllm/_custom_ops.py:1103-1119。這裡的16是 Marlin tile size，size_k // 16表示 K 維度按 tile 切分。MoE 版本的gptq_marlin_moe_repack在 Python 層迴圈每個 expert 呼叫單 expert 的 repack📎 vllm/_custom_ops.py:1154-1172，並斷言size_k % 16 == 0——這是 Marlin 格式的硬約束。

flowchart LR
    input["input: torch.Tensor (FP16/BF16)"]
    qweight["qweight: torch.Tensor (INT32 packed)"]
    scales["scales: torch.Tensor"]
    qzeros["qzeros: torch.Tensor"]
    check_env{"VLLM_USE_TRITON_AWQ?"}
    triton_path["awq_gemm_triton(input, qweight, scales, qzeros, split_k_iters)"]
    cuda_path["torch.ops._C.awq_gemm(...)"]
    output["output: torch.Tensor (FP16/BF16)"]

    input --> check_env
    qweight --> check_env
    scales --> check_env
    qzeros --> check_env
    check_env -->|是| triton_path
    check_env -->|否| cuda_path
    triton_path --> output
    cuda_path --> output

設計思考與踩坑

fake 實作必須與真實算子的輸出形狀完全一致，否則torch.compile追蹤出的圖會在執行時形狀不匹配。create_fp4_output_tensors的註解特別強調「Must match the C++ scaled_fp4_quant_func allocation exactly when padded_n is None」📎 vllm/_custom_ops.py:69-74。這是一個容易出錯的點：如果 C++ 側改了分配邏輯而 fake 沒同步，編譯後的圖會在 CUDA Graph 重放時崩潰。

另一個陷阱是torch.library.custom_op的別名規則。safeFusedQuantizeNv的註解指出，torch 2.12+ 不允許自訂算子的輸出別名任何輸入，因此作者把返回張量改為 in-place 參數📎 vllm/_custom_ops.py:4650-4655。這種「為了繞過框架限制而改變 API 形態」的做法在算子適配層很常見，排查時需要留意mutates_args宣告是否與實際行為一致。

CPUDNNLGEMMHandler展示了另一種資源管理模式：handler 指標存在一個 int64 tensor 裡，__del__時呼叫release_dnnl_matmul_handler釋放📎 vllm/_custom_ops.py:3708-3717。把指標存進 tensor 是為了防止被 Python 的整數內聯最佳化掉——這是一個底層綁定的經典技巧。

11.3 Triton 核心調度：KernelOverride與跨模組重綁定

直覺模型

Triton 核心調度器的角色，像一家公司的崗位替身系統。當某個平台（比如 ROCm）需要用自己的實作替換 vLLM 核心裡的 Triton 核心時，不能直接改核心程式碼——那會污染上游。dispatcher允許平台註冊一個替身，然後把所有指向原核心的引用悄悄換成替身。若沒有這層機制，每個平台都得維護一份 fork，合併上游變更時衝突不斷。

資料結構與記憶體佈局

核心資料結構是_registry字典與KernelOverride類📎 vllm/triton_utils/dispatcher.py:29-36。

KernelOverride的關鍵欄位📎 vllm/triton_utils/dispatcher.py:50-61：

• _impl：平台實作函式；
• arg_names：鏡像原核心的參數名元組，用於 launch 時的關鍵字綁定；
• constexprs：從原核心繼承的 constexpr 宣告；
• func：指向實作函式，供 warmup 內省；
• _forward_by_name：布林標誌，決定 launch 時按關鍵字還是按位置轉發參數。

_forward_by_name的計算邏輯是：比較inspect.signature(impl).parameters與原核心的arg_names是否完全相等📎 vllm/triton_utils/dispatcher.py:50-61。如果相等，說明實作的參數名與核心一致，可以安全地按關鍵字轉發；否則必須按原核心的參數順序位置轉發。

Step-by-Step：一次register_kernels的重綁定

代入場景：ROCm 平台在初始化時呼叫register_kernels({"vllm.v1.sample.rejection_sampler.expand_kernel": my_expand_impl})。

第一步，register_kernels遍歷 overrides，對每個名字呼叫_resolve_kernel 📎 vllm/triton_utils/dispatcher.py:162-166。_resolve_kernel把名字按最後一個.拆成模組名與屬性名📎 vllm/triton_utils/dispatcher.py:83-94。如果模組名的最後一段首字母大寫，說明核心屬於某個類（JIT warmup owner），需要先匯入父模組再getattr拿到類，返回(类, 属性名)；否則匯入模組本身，返回(模块, 属性名)。

第二步，拿到原核心物件後，構造KernelOverride包裝器，並記錄到_registry 📎 vllm/triton_utils/dispatcher.py:167-169。

第三步，_rebind_kernels執行全模組掃描📎 vllm/triton_utils/dispatcher.py:97-144。它遍歷sys.modules中所有模組的__dict__，對每個屬性值做身份比較——注意是is而非==，因為某些屬性值（如PlaceholderModule哨兵）在 hash/eq 時會觸發匯入或異常📎 vllm/triton_utils/dispatcher.py:116-123。

第四步，對於匹配到原核心的屬性，直接setattr替換為 wrapper📎 vllm/triton_utils/dispatcher.py:125-135。對於 JIT warmup owner（實例屬性kernel指向原核心的物件），替換value.kernel並清除快取的_kernel_arg_names，讓 launch 綁定重新從 wrapper 推導📎 vllm/triton_utils/dispatcher.py:138-139。

第五步，_rebind_kernels完成後，才把定義處的屬性也替換為 wrapper📎 vllm/triton_utils/dispatcher.py:170-174。註解解釋了順序的重要性：如果先替換定義處，掃描時就找不到原核心了📎 vllm/triton_utils/dispatcher.py:170-171。

sequenceDiagram
    participant Platform as "ROCm 平台"
    participant Dispatcher as "register_kernels"
    participant Resolver as "_resolve_kernel"
    participant Scanner as "_rebind_kernels"
    participant Modules as "sys.modules"

    Platform->>Dispatcher: register_kernels({"vllm...expand_kernel": my_impl})
    Dispatcher->>Resolver: _resolve_kernel("vllm...expand_kernel")
    Resolver-->>Dispatcher: (module, "expand_kernel")
    Dispatcher->>Dispatcher: KernelOverride(original, my_impl)
    Dispatcher->>Scanner: _rebind_kernels([(original, wrapper)])
    Scanner->>Modules: 遍历所有模块 __dict__
    Modules-->>Scanner: 属性值列表
    Scanner->>Scanner: lookup(value) 身份比较
    Scanner->>Modules: setattr(module, attr, wrapper)
    Scanner->>Modules: value.kernel = wrapper (JIT owner)
    Scanner-->>Dispatcher: 重绑定完成
    Dispatcher->>Modules: setattr(host, attr, wrapper)
    Dispatcher-->>Platform: 注册完成

設計思考與踩坑

KernelOverride.__getitem__返回self._launch，使得kernel[grid](**kwargs)這種 Triton 標準 launch 語法對 wrapper 透明📎 vllm/triton_utils/dispatcher.py:63-74。_launch的轉發邏輯分三種情況📎 vllm/triton_utils/dispatcher.py:63-74：有位置參數時直接透傳；_forward_by_name為真時按關鍵字轉發；否則檢查 kwargs 中是否有原核心不認識的參數名，有則拋RuntimeError，無則按原核心參數順序提取值位置轉發。

這個RuntimeError是一個重要的防禦：如果平台實現的參數名與內核不一致，且調用方傳了實現不認識的參數，靜默忽略會導致難以排查的錯誤結果。顯式報錯讓問題在註冊階段就暴露。

一個生產環境的陷阱：_rebind_kernels的掃描是 O(模組數 × 屬性數 × 內核數) 的。對於大型模型，sys.modules可能有數千個模組，每個模組數百個屬性。雖然只在初始化時執行一次，但如果註冊的內核很多，啟動時間會明顯增加。lookup函數用線性掃描而非雜湊查找，註釋解釋了原因——某些屬性值不可雜湊📎 vllm/triton_utils/dispatcher.py:116-123。這是一個典型的「正確性優先於效能」的權衡。

另一個陷阱：_resolve_kernel透過「模組名最後一段首字母大寫」來判斷是否是類屬性📎 vllm/triton_utils/dispatcher.py:83-94。如果某個模組名恰好以大寫字母開頭（不符合 Python 命名慣例但語法合法），會被誤判為類。這是一個約定優於配置的設計，依賴 vLLM 內部的命名規範。

設計思考

量化配置與算子註冊這兩層機制，共同構成了 vLLM 的「精度-效能」調節面。QuantizationConfigArgs的設計體現了「用戶意圖」與「方法預設值」的分離：None不是「不量化」，而是「讓方法類自己決定」。這種延遲決策讓同一份配置可以適配 checkpoint 量化和線上量化兩種場景。

_custom_ops的 fake 實現模式是torch.compile生態的標配，但 vLLM 的獨特之處在於hasattr守衛的普遍使用。這讓同一個模組可以在 CUDA、ROCm、CPU、XPU 上匯入而不崩潰，代價是每個算子都需要三處程式碼：Python 包裝、fake 實現、以及平台守衛。

Triton dispatcher 的跨模組重綁定是一個激進的方案。它不依賴 Python 的匯入鉤子或__getattr__，而是直接掃描並替換所有引用。這種做法的優點是徹底——無論內核被from mod import kernel複製到多少地方，都能被替換；缺點是脆弱——任何持有內核引用的新方式（比如閉包捕獲）都可能逃過掃描。

本章小結

本章思考與自測

下一章將轉向高級推理特性，看前綴快取如何複用 KV block、投機解碼如何用小模型加速大模型、以及 LoRA 如何在不改基座權重的前提下動態切換適配器。

本章剖析了 vLLM 量化與自訂核心的兩層基礎設施。第一層是量化配置解析：QuantSpec 與 QuantizationConfigArgs 把 CLI 字串、checkpoint 中介資料、逐層覆寫統一正規化為 QuantKey，resolve_quantization_config 處理簡寫展開與欄位合併，_DEFERRED_ONLINE_SHORTHANDS 解決了名稱衝突場景。第二層是算子適配：_custom_ops 透過 hasattr 守衛與 register_fake 實現跨平台算子註冊，fake 實現精確鏡像真實算子的輸出形狀以支援 torch.compile；dispatcher 透過 KernelOverride 與全模組掃描實現 Triton 核心的平台替換。兩者共同支撐了從權重載入到前向計算的量化收益兌現。接下來，我們將轉向提升吞吐與降低延遲的高級推理特性：自動前綴快取如何複用跨請求的 KV，投機解碼如何用草稿模型加速生成，以及 LoRA 如何動態切換適配器。

上一章我們深入了 vLLM 的量化體系與自訂算子基礎設施，看到量化配置如何被解析並選擇對應 kernel，以及 FP8、INT4、AWQ、GPTQ 等方案如何在權重載入時完成轉換。同時，我們探明了 _custom_ops 如何註冊 CUDA 算子、Triton 核心的調度機制，以及 MoE 融合核心如何減少顯存往返。這些底層能力為更高級的推理優化鋪平了道路。本章將聚焦 vLLM 的三大高級推理特性：自動前綴快取（APC）、投機解碼與 LoRA。它們看似獨立，實則共享同一套底層基礎設施——KV block 的雜湊、調度器的 slot 分配、以及模型執行時的動態權重注入。理解它們的關鍵，是理解它們如何在不破壞 PagedAttention 分頁語義的前提下，把「複用」這件事做到極致。

12.1 前綴快取：block hash 如何指紋化一段前綴

直覺模型

前綴快取就像圖書館的「公共段落摘抄本」：兩個學生寫作文，開頭都引用同一段古文，老師只需要批改一次這段古文，後面各自不同的部分再分別看。若沒有它，每個請求都要從頭 prefill 整段 prompt，長文檔問答場景下算力被重複消耗數倍。

資料結構：從 token 到 block hash 的映射

前綴快取的核心是「如何判斷兩個請求的前綴相同」。vLLM 的答案是：把 token 序列按 block 切分，對每個 block 計算一個鏈式雜湊。鏈式意味著第 N 個 block 的雜湊包含了前 N-1 個 block 的雜湊，因此一個 block hash 唯一指紋化了「從序列開頭到該 block 末尾」的整段前綴。

雜湊的載體是BlockHash，它被定義為bytes的NewType，而非裸bytes，目的是在類型層面防止誤用📎 vllm/v1/core/kv_cache_utils.py:59-62。當需要把 block hash 與 KV cache group id 組合成字典鍵時，vLLM 沒有用元組，而是把 4 位元組大端 group id 直接拼接到 hash 位元組尾部📎 vllm/v1/core/kv_cache_utils.py:75-76：

def make_block_hash_with_group_id(block_hash, group_id):
    return BlockHashWithGroupId(block_hash + group_id.to_bytes(4, "big", signed=False))

雜湊函數本身由hash_block_tokens承擔，它把父 block hash、當前 block 的 token id 元組、以及額外鍵一起餵給雜湊函數📎 vllm/v1/core/kv_cache_utils.py:650-680。注意第一個 block 的父雜湊不是None，而是全局的NONE_HASH：

if not parent_block_hash:
    parent_block_hash = NONE_HASH

📎 vllm/v1/core/kv_cache_utils.py:674-675。NONE_HASH的種子選擇藏著一個安全設計：對 SHA-256 這類密碼學雜湊，種子是固定的"vllm-none-hash"，使得不同 vLLM 進程對相同內容算出相同雜湊，從而跨節點共享前綴快取；而對 xxhash 這類非密碼學雜湊，種子是每進程隨機的，因為可預測的種子會讓攻擊者離線預計算碰撞 block📎 vllm/v1/core/kv_cache_utils.py:105-126。resolve_none_hash_seed實現了這個分叉：PYTHONHASHSEED環境變數優先，否則密碼學雜湊用固定種子、非密碼學雜湊用os.urandom(32) 📎 vllm/v1/core/kv_cache_utils.py:132-145。

場景驅動：一次請求的 block hash 計算

假設一個請求帶著 128 個 token 進入，block size 為 16。get_request_block_hasher返回的閉包負責增量計算📎 vllm/v1/core/kv_cache_utils.py:802-861：

第一步，確定從哪裡開始算。start_token_idx = len(request.block_hashes) * hash_block_size 📎 vllm/v1/core/kv_cache_utils.py:812-812，即已算過的 block 數乘以 block 大小。若剩餘 token 不足一個 block，直接返回空📎 vllm/v1/core/kv_cache_utils.py:812-812。

第二步，處理多模態偏移。如果起始位置落在某個多模態輸入內部，需要用get_mm_features_in_window重新定位curr_mm_idx 📎 vllm/v1/core/kv_cache_utils.py:823-832。這是因為多模態輸入的 placeholder token 本身不攜帶語意，必須把 mm 特徵標識符和它在 block 內的偏移作為額外鍵摻入雜湊。

第三步，迴圈計算每個 block。generate_block_hash_extra_keys收集所有額外鍵📎 vllm/v1/core/kv_cache_utils.py:611-647，包括 LoRA 名、多模態鍵、cache salt、prompt embeds 雜湊。其中 cache salt 只在第一個 block 生效📎 vllm/v1/core/kv_cache_utils.py:633-635，這是有意為之：salt 的作用是隔離整個快取命名空間，只需在鏈的起點注入一次。

第四步，hash_block_tokens把父雜湊、token 元組、額外鍵一起雜湊，結果作為下一個 block 的父雜湊📎 vllm/v1/core/kv_cache_utils.py:851-857。鏈式結構由此形成。

多 block size 的粒度轉換

當模型有多個 KV cache group 且 block size 不同時，雜湊粒度與 group 的 block 粒度可能不一致。BlockHashListWithBlockSize解決這個問題：它不重新計算雜湊，而是利用鏈式雜湊的性質——一個 target block 的雜湊，就是它內部最後一個 hash block 的雜湊📎 vllm/v1/core/kv_cache_utils.py:2781-2851。例如 hash block 為 16、target block 為 32 時，token 0-31 的雜湊就是第二個 16-size 雜湊（它已經鏈式覆蓋了 0-31）📎 vllm/v1/core/kv_cache_utils.py:2794-2806。_get_value_at的實現就是self.block_hashes[(idx + 1) * self.scale_factor - 1] 📎 vllm/v1/core/kv_cache_utils.py:2848-2851。

flowchart TD
    req["Request 到达"] --> check{"剩余 token >= hash_block_size?"}
    check -->|否| empty["返回空列表"]
    check -->|是| mm{"起始位置在多模态窗口内?"}
    mm -->|是| reloc["get_mm_features_in_window 重定位 curr_mm_idx"]
    mm -->|否| extra
    reloc --> extra["generate_block_hash_extra_keys 收集 LoRA/MM/salt/embeds 键"]
    extra --> hash["hash_block_tokens 链式哈希"]
    hash --> append["追加到 new_block_hashes"]
    append --> advance["start_token_idx += hash_block_size"]
    advance --> check

設計思考與踩坑

為什麼用鏈式雜湊而非獨立雜湊？獨立雜湊無法區分「相同 block 出現在不同前綴位置」的情況。鏈式雜湊讓 block hash 唯一指紋化整段前綴，這正是find_longest_cache_hit能安全復用 KV 的前提。

非密碼學雜湊的跨進程陷阱。若使用 xxhash 且未設PYTHONHASHSEED，每個進程的NONE_HASH不同，導致跨實例前綴快取完全失效。init_none_hash會列印警告📎 vllm/v1/core/kv_cache_utils.py:161-169。生產環境若部署多實例共享快取，必須顯式設定PYTHONHASHSEED或改用 sha256。

多模態偏移的微妙之處。 _gen_mm_extra_hash_keys把(mm_identifier, offset - start_token_idx)作為額外鍵📎 vllm/v1/core/kv_cache_utils.py:552。偏移是相對 block 起點的，這樣同一個 mm 項出現在不同 block 位置時雜湊不同，避免誤命中。

12.2 投機解碼：草稿與驗證的協同

直覺模型

投機解碼像秘書先替領導起草幾版回覆，領導只需快速圈定哪版可用。草稿模型（drafter）用極低成本預測多個候選 token，目標模型（target）一次前向並行驗證這些候選，接受匹配的部分。若沒有它，目標模型只能逐 token 串行生成，GPU 利用率在 decode 階段極低。

資料結構：EAGLE group 的標註

投機解碼在 KV cache 管理上的核心問題是：草稿模型的 KV 層與目標模型的 KV 層如何分組？_annotate_eagle_groups用兩條規則識別草稿組📎 vllm/v1/core/kv_cache_utils.py:2134-2189：

規則一是 spec 驅動：non_causal_multi_token_decode標誌位聲明在MLAAttentionSpec上，由運行非因果多 token decode 的草稿注意力層設置，且能存活過merge操作📎 vllm/v1/core/kv_cache_utils.py:2175-2177。

規則二是位置回退：MTP 草稿器（如 DeepseekV4/V4.1 DSpark）復用目標模型自己的 decoder 層，spec 上無標記，但它們的草稿注意力層總是在所有目標層之後註冊，因此標註持有最後註冊層的那個 group📎 vllm/v1/core/kv_cache_utils.py:2183-2184。這個規則只在 group 恰好劃分了kv_cache_spec所有層時才生效📎 vllm/v1/core/kv_cache_utils.py:2183-2184。

場景驅動：投機解碼的 KV 分配

當speculative_config啟用且use_eagle_block_drop()為真時，_annotate_eagle_groups被調用📎 vllm/v1/core/kv_cache_utils.py:2175-2177。標註結果is_eagle_group影響後續的 block 分配策略——草稿組的 block 可以在驗證後被丟棄。

在get_kv_cache_groups的主路徑中，標註發生在分組之後📎 vllm/v1/core/kv_cache_utils.py:2364-2365。若沒有任何 group 被標註為草稿組，_warn_if_unannotated_eagle_mamba會發出警告📎 vllm/v1/core/kv_cache_utils.py:2192-2222。

sequenceDiagram
    participant Sched as Scheduler
    participant Drafter as 草稿模型
    participant Target as 目标模型
    participant KV as KV Cache Manager
    Sched->>Drafter: 请求生成 k 个候选 token
    Drafter->>KV: 分配草稿组 block (is_eagle_group=True)
    Drafter-->>Sched: 返回候选 token 序列
    Sched->>Target: 并行验证候选 (一次前向)
    Target->>KV: 读取目标组 block
    Target-->>Sched: 返回接受/拒绝掩码
    Sched->>KV: 丢弃被拒绝的草稿 block

設計思考與踩坑

為什麼草稿組需要單獨標註？草稿模型生成的 token 在驗證後可能被拒絕，對應的 KV 需要丟棄。若草稿 KV 與目標 KV 混在同一 group，丟棄操作會誤傷目標 KV。標註讓調度器能精確回收。

位置回退規則的脆弱性。規則二依賴「草稿層最後註冊」這一約定，註釋中明確標註這是 hacky check 並留了 FIXME📎 vllm/v1/core/kv_cache_utils.py:2158-2159。當草稿的尾部快取跨多個 group 時，該規則只標註持有最後一層的 group，需要泛化。

Mamba 模型的額外約束。若啟用投機解碼但無 group 被識別為草稿組，且存在 Mamba group，會觸發警告📎 vllm/v1/core/kv_cache_utils.py:2211-2213。這通常意味著草稿層的 spec 與目標層無法區分，需要檢查模型註冊順序。

12.3 LoRA：不重載基座的動態適配器

直覺模型

LoRA 像給同一台手機換不同的手機殼：手機本體（基座模型）不變，換個殼（適配器）就變成不同風格。若沒有它，每個微調任務都要載入一份完整權重，顯存無法承受。

資料結構：雙 LRU 快取與 slot 陣列

LoRAModelManager用兩個 LRU 快取管理適配器生命週期📎 vllm/lora/model_manager.py:115-120：

self._registered_adapters: AdapterLRUCache[LoRAModel] = AdapterLRUCache(
    self.capacity, self.deactivate_adapter
)
self._active_adapters: AdapterLRUCache[None] = AdapterLRUCache(
    self.lora_slots, self._deactivate_adapter
)

capacity是 CPU 側能快取的適配器總數（max_cpu_loras）📎 vllm/lora/model_manager.py:340-342，lora_slots是 GPU 側能同時啟用的適配器數（max_loras）📎 vllm/lora/model_manager.py:345-346。_registered_adapters被移除時會觸發deactivate_adapter回呼📎 vllm/lora/model_manager.py:71-74，確保 CPU 快取淘汰時 GPU 上的副本也被清理。

lora_index_to_id是一個長度為lora_slots的陣列，把 GPU slot 索引映射到適配器 id📎 vllm/lora/model_manager.py:122。這個陣列是 punica wrapper 做批量 LoRA 計算時的核心索引。

場景驅動：適配器啟用

當請求攜帶 LoRA 適配器進入時，activate_adapter被呼叫📎 vllm/lora/model_manager.py:352-409：

第一步，檢查是否已啟用，若是則直接返回📎 vllm/lora/model_manager.py:352-354。

第二步，尋找空閒 slot。遍歷lora_index_to_id找到第一個None 📎 vllm/lora/model_manager.py:362-362。若無空閒 slot，拋出ValueError("No free lora slots") 📎 vllm/lora/model_manager.py:368-368。

第三步，更新狀態並遍歷所有已包裝模組，呼叫module.set_lora(index, lora_a, lora_b)把權重拷貝到 GPU 的 stacked buffer📎 vllm/lora/model_manager.py:377-401。若某模組沒有對應 LoRA 權重，呼叫reset_lora(index)清零📎 vllm/lora/model_manager.py:378-385。

第四步，若沒有任何權重被應用，列印一次性除錯日誌📎 vllm/lora/model_manager.py:411-416。這在流水線並行或專家並行下是預期行為——某些 rank 不持有被適配的層。

模組包裝：從 nn.Linear 到 BaseLayerWithLoRA

_create_lora_modules遍歷模型所有命名模組📎 vllm/lora/model_manager.py:462-606。關鍵邏輯：

• 跳過PPMissingLayer 📎 vllm/lora/model_manager.py:473-474。
• 根據target_modules過濾：若未指定則用is_supported_lora_module判斷，否則用_match_target_modules 📎 vllm/lora/model_manager.py:479-493。
• 處理別名模組：同一個底層模組可能透過多個路徑被存取（如 MoE gate 既在 block 上又在 runner 內）。此時把別名屬性重定向到同一個 wrapper，但不重複註冊，否則activate_adapter會對別名呼叫reset_lora清掉剛設置的權重📎 vllm/lora/model_manager.py:512-527。
• 用from_layer建立 wrapper 並替換原模組📎 vllm/lora/model_manager.py:546-553。

設計思考與踩坑

slot 佈局變化觸發映射更新。 set_adapter_mapping不僅比較 mapping 是否變化，還比較lora_index_to_id的元組快照📎 vllm/lora/model_manager.py:1323-1331。原因註釋說得很清楚：一次帶外的add_lora()可能觸發 LRU 淘汰並重新分配 slot，而執行中的 batch 及其 mapping 沒變📎 vllm/lora/model_manager.py:1323-1331。若只看 mapping，punica metadata 會用過期的 slot 佈局。

MoE 的 EP 切片。當啟用專家並行時，checkpoint 持有所有全域專家的權重，但每個 rank 只擁有local_num_experts個。_stack_moe_lora_weights先按global_num_expertsreshape，再切片[expert_start:expert_end] 📎 vllm/lora/model_manager.py:966-977。非 EP 時切片是 no-op。

pin_memory 的時機。權重打包（如pack_moe）可能使 pin_memory 分配失效，因此 pin_memory 在所有權重合併之後執行📎 vllm/lora/model_manager.py:916-934。註釋明確指出兩個原因：MoE 模型 LoRA 權重數量龐大，過早 pin 開銷顯著；打包可能使分配失效📎 vllm/lora/model_manager.py:916-921。

設計思考：三者的協同點

三個特性在 KV cache 管理層交匯。前綴快取透過 block hash 複用 KV；投機解碼透過is_eagle_group標註區分草稿 KV；LoRA 透過_gen_lora_extra_hash_keys把適配器名摻入 block hash📎 vllm/v1/core/kv_cache_utils.py:568-581，確保不同適配器的相同 token 序列不會誤命中彼此的 KV。

generate_block_hash_extra_keys把 LoRA 鍵放在額外鍵列表的最前面📎 vllm/v1/core/kv_cache_utils.py:640-642，與多模態鍵、cache salt、prompt embeds 鍵共同構成完整的雜湊輸入。這保證了：即使兩個請求的 token 完全相同，只要 LoRA 適配器不同，它們的 block hash 就不同，KV 不會串用。

本章小結

本章思考與自測

下一章將轉向外掛系統與可擴充性，看 vLLM 如何透過平台抽象、IO 處理器與端點擴充支援多樣化的部署形態。

本章剖析了 vLLM 三大進階推理特性的底層機制。前綴快取的核心是鏈式 block hash：hash_block_tokens 把父雜湊、token 元組、額外鍵一起雜湊，NONE_HASH 的種子策略在跨行程共享與碰撞安全之間權衡。投機解碼透過 is_eagle_group 標註區分草稿 KV 組。LoRA 透過雙 LRU 快取與 slot 陣列管理適配器生命週期，並在 block hash 中摻入適配器名實現快取隔離。這些特性共同展現了 vLLM 在推理優化上的深度與靈活性。接下來，我們將轉向 vLLM 的外掛系統與可擴充性，看平台外掛如何適配新硬體，IO processor 外掛如何介入多模態輸入處理，以及端點外掛如何注入自訂 API 路由。理解外掛註冊與發現的載入順序，將揭示如何在不修改核心程式碼的前提下擴充 vLLM 的能力。

上一章我們看到，前綴快取、投機解碼與 LoRA 這些進階特性都深度耦合在排程器、KV 管理與模型執行的核心路徑中。但一個推理引擎要真正走向生產，光有性能還不夠——它必須回答一個更棘手的問題：當社群想接入一塊新硬體、一種新的多模態輸入格式、或一條自訂 HTTP 路由時，如何在不 fork 核心程式碼的前提下完成？這正是外掛系統存在的意義。vLLM 的架構天然是多行程的：API Server 前端行程、EngineCore 行程、以及每個 TP/PP rank 對應的 Worker 行程。如果外掛機制只是簡單地「在 import 時執行一段程式碼」，那麼它要么在每個行程裡重複執行導致副作用疊加，要么只在主行程執行導致 Worker 拿不到擴充。本章要拆解的，就是 vLLM 如何用 Python 標準的 entry_points 機制，配合分組（group）+ 行程邊界 + 載入時機三重約束，構建出一套既能覆蓋所有行程、又能精確控制暴露面的外掛體系。我們聚焦三條主線：平台外掛（適配新硬體）、IO processor 外掛（介入多模態輸入處理）、端點外掛（注入自訂 API 路由）。三者的載入策略截然不同，理解這種差異，就理解了 vLLM 對「擴充能力」與「安全邊界」的權衡哲學。

一、外掛發現與載入：entry_points 的分組契約

直覺模型：外掛的「廣播頻道」

把 vLLM 的外掛系統想像成一組廣播頻道。每個外掛套件在安裝時，透過setup.py的entry_points向某個頻道「註冊」自己的呼號（plugin name）和回應函式（plugin value）。vLLM 在啟動時掃描這些頻道，決定哪些頻道在哪些行程裡被「收聽」。

若沒有這套機制，擴展 vLLM 只能靠改原始碼——社群每加一塊硬體就要維護一個 fork，最終版本分裂。分組機制的價值在於：同一個外掛套件可以只註冊到某個特定頻道，從而被限定在特定行程載入。

資料結構：五個分組常數與全域旗標位

vLLM 在vllm/plugins/__init__.py頂部定義了五個 entry point group 常數，每個常數對應一個載入策略：

📎 vllm/plugins/__init__.py:16-30

DEFAULT_PLUGINS_GROUP = "vllm.general_plugins"
IO_PROCESSOR_PLUGINS_GROUP = "vllm.io_processor_plugins"
PLATFORM_PLUGINS_GROUP = "vllm.platform_plugins"
STAT_LOGGER_PLUGINS_GROUP = "vllm.stat_logger_plugins"
ENDPOINT_PLUGINS_GROUP = "vllm.endpoint_plugins"

註解裡藏著關鍵資訊：DEFAULT_PLUGINS_GROUP在所有行程載入（process0、engine core、worker）；IO_PROCESSOR_PLUGINS_GROUP 只在 process0；PLATFORM_PLUGINS_GROUP在所有行程載入，但觸發時機是current_platform首次被存取時；STAT_LOGGER_PLUGINS_GROUP只在 process0 且非同步模式下；ENDPOINT_PLUGINS_GROUP只在 API Server 前端行程。

緊接著是一個模組級全域變數plugins_loaded = False 📎 vllm/plugins/__init__.py:32-33，它是冪等載入的守衛——註解明確寫著「make sure one process only loads plugins once」。

Step-by-Step：一次load_plugins_by_group的完整呼叫流

代入場景：使用者在setup.py裡註冊了vllm.general_plugins下的register_dummy_model，現在 vLLM 啟動，某個行程呼叫load_general_plugins()。

第一步：冪等守衛。 load_general_plugins先檢查plugins_loaded，若已為True直接回傳📎 vllm/plugins/__init__.py:77-90。注意這裡有個微妙之處：守衛在載入之前就置位，意味著即使後續載入拋異常，也不會重試。這是刻意的——外掛載入失敗不應導致行程反覆嘗試。

第二步：發現。進入load_plugins_by_group，透過importlib.metadata.entry_points(group=group)拿到該分組下所有已安裝的 entry points📎 vllm/plugins/__init__.py:36-45。若為空，記 debug 日誌後回傳空字典。

第三步：日誌分級。原始碼區分了預設分組與非預設分組的日誌級別：is_default_group為真時用logger.debug，否則用logger.info 📎 vllm/plugins/__init__.py:47-54。動機很實際——vllm.general_plugins下通常掛著大量模型註冊外掛，用 INFO 會刷屏；而平台/端點外掛數量少且重要，值得 INFO 可見。

第四步：白名單過濾。讀取envs.VLLM_PLUGINS，若為None則載入全部，否則只載入名字在列表中的外掛📎 vllm/plugins/__init__.py:62-70。注意plugin.load()被包在 try/except 裡，單個外掛載入失敗只記 exception 日誌，不影響其他外掛📎 vllm/plugins/__init__.py:68-72。

第五步：執行。回到load_general_plugins，對每個載入到的函式直接呼叫func() 📎 vllm/plugins/__init__.py:77-90。這就是為什麼文件強調外掛函式必須可重入（re-entrant）——它可能在多個行程中被多次呼叫。

下面這張流程圖刻畫了load_plugins_by_group的完整決策路徑：

flowchart TD
    start["load_plugins_by_group(group)"] --> discover["entry_points(group=group)"]
    discover --> empty{"len(discovered) == 0?"}
    empty -->|是| ret_empty["返回 {}"]
    empty -->|否| log["按 is_default_group 选 log_level"]
    log --> loop["遍历 discovered_plugins"]
    loop --> check{"allowed_plugins is None<br/>或 plugin.name in allowed?"}
    check -->|否| skip["跳过该插件"]
    check -->|是| load["func = plugin.load()"]
    load --> load_ok{"加载成功?"}
    load_ok -->|否| log_exc["logger.exception 记录"]
    load_ok -->|是| add["plugins[name] = func"]
    skip --> next["下一个插件"]
    log_exc --> next
    add --> next
    next --> loop
    loop --> ret["返回 plugins 字典"]

設計思考：為什麼用 entry_points 而非設定檔

---

二、平台外掛：硬體適配的抽象層

直覺模型：平台是「硬體方言翻譯官」

Platform類是整個 vLLM 與硬體對話的唯一翻譯官。模型程式碼只呼叫current_platform.get_attn_backend_cls()、current_platform.is_cuda_alike()這類抽象方法，從不直接import torch.cuda。若沒有這層抽象，每支援一塊新硬體就要在模型程式碼裡加if device == "xpu"的分支，最終變成義大利麵。

資料結構：Platform 基類的欄位佈局

Platform是一個純類（非實例化使用），關鍵類別屬性定義在vllm/platforms/interface.py開頭📎 vllm/platforms/interface.py:135-179：

class Platform:
    _enum: PlatformEnum
    device_name: str
    device_type: str
    dispatch_key: str = "CPU"
    ray_device_key: str = ""
    device_control_env_var: str = "VLLM_DEVICE_CONTROL_ENV_VAR_PLACEHOLDER"
    ray_noset_device_env_vars: list[str] = []
    simple_compile_backend: str = "inductor"
    dist_backend: str = ""
    supported_quantization: list[str] = []
    additional_env_vars: list[str] = []
    _global_graph_pool: Any | None = None

_enum是PlatformEnum列舉值，決定is_cuda()、is_rocm()等判定📎 vllm/platforms/interface.py:69-78。device_control_env_var是平台無關的「裝置可見性環境變數」抽象——CUDA 是CUDA_VISIBLE_DEVICES，其他平台各自定義📎 vllm/platforms/interface.py:151-152。_global_graph_pool是類別級別的 CUDA graph 記憶體池快取，透過get_global_graph_pool惰性初始化📎 vllm/platforms/interface.py:1210-1215。

值得注意的是__getattr__的兜底邏輯📎 vllm/platforms/interface.py:1189-1208：當存取 Platform 上不存在的屬性時，它會嘗試從torch.<device_type>命名空間轉發。這允許平台程式碼寫current_platform.memory_allocated()而實際呼叫torch.cuda.memory_allocated()。但原始碼特意排除了 dunder 方法——否則 pickle 檢查__getstate__時會拿到None並試圖呼叫它📎 vllm/platforms/interface.py:1182-1185。

Step-by-Step：裝置 ID 的三命名空間轉換

平台抽象中最容易踩坑的是裝置 ID 命名空間。原始碼註解明確列出三種📎 vllm/platforms/interface.py:275-283：

• logical：vLLM 內部的 local rank，索引_assigned_physical_gpu_ids
• visible：當前行程經CUDA_VISIBLE_DEVICES重映射後的 torch/CUDA 序號
• physical：NVML 等拓撲 API 使用的全域 GPU ID，不受環境變數影響

代入場景：一個 Worker 行程被分配了實體 GPU[4, 5]，環境變數CUDA_VISIBLE_DEVICES=4,5，現在需要把 local rank 0 轉成torch.device("cuda:0")。

第一步：logical → physical。 device_id_to_physical_device_id(0)先查_assigned_physical_gpu_ids，若已設定則直接索引回傳4 📎 vllm/platforms/interface.py:296-297。若未設定，則從device_control_env_var拆分逗號列表取第 0 項📎 vllm/platforms/interface.py:305-311。注意原始碼特意把空字串當作未設定處理——這是 Ray 在純 CPU placement group 上啟動引擎時的合法配置📎 vllm/platforms/interface.py:296-297。

第二步：physical → visible。 logical_device_id_to_visible_device_id(0)拿到 physical4後，再把環境變數拆成[4, 5]，找到4的索引0返回📎 vllm/platforms/interface.py:316-339。若 physical ID 不在可見列表中，拋RuntimeError——這是防止跨進程誤用不可見設備的硬防護。

set_assigned_physical_gpu_ids的冪等設計也值得注意：重複設置相同值是無操作，設置不同值則拋RuntimeError 📎 vllm/platforms/interface.py:38-56。這防止了多線程環境下設備映射被意外覆蓋。

平台插件的註冊與配置注入

平台插件透過vllm.platform_plugins分組註冊，插件函數返回平台類的全限定名（或None表示當前環境不支援）📎 docs/design/plugin_system.md:50-50。文檔給出的最小實現要求📎 docs/design/plugin_system.md:100-100：

• _enum通常設為PlatformEnum.OOT（out-of-tree）
• device_type返回 PyTorch 認識的設備類型字串
• check_and_update_config在 vLLM 初始化早期被調用，必須在此設置worker_cls
• get_attn_backend_cls返回注意力後端類名
• get_device_communicator_cls返回通信器類名

check_and_update_config是平台插件最關鍵的鉤子📎 vllm/platforms/interface.py:583-592。它接收VllmConfig引用並原地修改，可以調整 block size、graph mode 等。文檔強調「最重要的是 worker_cls 必須在此設置」📎 docs/design/plugin_system.md:105-105——因為 vLLM 需要知道用哪個 Worker 類來實例化工作進程。

設計思考：block size 對齊的三階段策略

平台接口中最複雜的邏輯是update_block_size_for_backend 📎 vllm/platforms/interface.py:666-708。它分三階段確保 block size 與注意力後端兼容：

Phase 1：若用戶未顯式指定--block-size，調用_preferred_block_size_for_backends選出所有後端都支持的最小 block size📎 vllm/platforms/interface.py:687-697。這個函數用 LCM（最小公倍數）枚舉候選值，因為某些後端（如 CPU_MLA）只接受精確尺寸而非倍數📎 vllm/platforms/interface.py:622-663。

Phase 2：混合模型（attention + mamba）需對齊 block 與 mamba page size📎 vllm/platforms/interface.py:699-702。

Phase 3：多種 KV dtype 共享 block pool 時（如 nvfp4 主 + 未量化 skip 層），需把主 block 撐大到能覆蓋最大的 padded spec page📎 vllm/platforms/interface.py:704-708。

---

三、IO Processor 與端點插件：輸入處理與 API 擴展

直覺模型：IO Processor 是「多模態翻譯層」

多模態模型（如 LLaVA）的輸入不是純文本，而是文本 + 圖像的混合體。IO Processor 插件負責把原始多模態數據轉換成模型能吃的張量，再把模型輸出轉回人類可讀格式。它像海關的翻譯官：進來的外語（圖像/音頻）翻譯成模型母語，出去的模型母語翻譯回外語。

Step-by-Step：IO Processor 的發現與實例化

代入場景：加載一個帶io_processor_plugin字段的 HF config 的模型。

第一步：確定插件名。 get_io_processor優先使用顯式傳入的plugin_from_init，否則從hf_config的io_processor_plugin字段讀取📎 vllm/plugins/io_processors/__init__.py:42-50。若兩者都為空，返回None——表示該模型不需要 IO processor📎 vllm/plugins/io_processors/__init__.py:52-54。

第二步：加載所有已安裝插件。調用load_plugins_by_group(IO_PROCESSOR_PLUGINS_GROUP)拿到該分組下所有插件📎 vllm/plugins/io_processors/__init__.py:59-61。

第三步：構建可加載映射。遍歷每個插件，調用其函數拿到processor_cls_qualname，若非None則記入loadable_plugins 📎 vllm/plugins/io_processors/__init__.py:66-76。注意這裡每個插件的函數調用也被 try/except 包裹，單個失敗不影響其他。

第四步：校驗與實例化。若可加載插件數為 0，拋ValueError提示「需要 IOProcessor 插件但一個都沒裝」📎 vllm/plugins/io_processors/__init__.py:66-76。若模型要求的插件名不在可加載列表中，拋ValueError並列出所有可用插件名📎 vllm/plugins/io_processors/__init__.py:80-81。最後透過resolve_obj_by_qualname解析類名並實例化📎 vllm/plugins/io_processors/__init__.py:80-81。

端點插件：默認拒絕的安全姿態

端點插件是本章最特殊的一類，因為它默認不加載。load_endpoint_plugins的文檔字串明確解釋了原因：端點插件會向 API Server 添加 HTTP 路由，擴大了網絡暴露面，因此採取比load_plugins_by_group更嚴格的「默認拒絕」姿態📎 vllm/plugins/__init__.py:93-94。

具體規則是：只有當插件名顯式出現在VLLM_PLUGINS中，且其required_tasks為None或與服務器支持的 tasks 有交集時，才被加載📎 vllm/plugins/__init__.py:108-108。

代入場景：用戶安裝了端點插件但忘了設VLLM_PLUGINS。

第一步：檢查 VLLM_PLUGINS 是否未設。若envs.VLLM_PLUGINS is None，先發現該分組下的插件，若有則記 warning 提示「必須顯式 allowlist」📎 vllm/plugins/__init__.py:126-126。注意源碼註釋特別指出：VLLM_PLUGINS=""解析為[""]而非None，因此被視為「匹配不到任何插件的 allowlist」，而非「未設置」📎 vllm/plugins/__init__.py:108-108。這個邊界區分很重要——空字串是顯式的「什麼都不加載」，而None是「未配置」。

第二步：加載並實例化。透過load_plugins_by_group拿到工廠函數後，逐個調用factory()實例化📎 vllm/plugins/__init__.py:133-141。實例化失敗記 exception 並 continue。

第三步：task 門控。檢查plugin.required_tasks，若不為None且與supported_tasks無交集，跳過該外掛📎 vllm/plugins/__init__.py:144-145。這允許同一個外掛套件針對不同任務（如 embedding vs generation）註冊不同端點。

下面這張時序圖刻畫了端點外掛從發現到載入的完整互動：

sequenceDiagram
    participant App as "API Server 前端进程"
    participant Loader as "load_endpoint_plugins()"
    participant Env as "envs.VLLM_PLUGINS"
    participant EP as "entry_points(ENDPOINT_PLUGINS_GROUP)"
    participant Factory as "plugin factory()"

    App->>Loader: load_endpoint_plugins(supported_tasks)
    Loader->>Env: 读取 VLLM_PLUGINS
    alt VLLM_PLUGINS is None
        Loader->>EP: entry_points(group)
        EP-->>Loader: discovered plugins
        Loader-->>App: 返回 [] (记 warning)
    else VLLM_PLUGINS 已设置
        Loader->>EP: load_plugins_by_group(group)
        EP-->>Loader: factories 字典
        loop 每个 factory
            Loader->>Factory: factory()
            Factory-->>Loader: EndpointPlugin 实例
            Loader->>Loader: 检查 required_tasks 交集
            alt tasks 不匹配
                Loader->>Loader: 跳过 (记 info)
            else tasks 匹配
                Loader->>Loader: append 到结果列表
            end
        end
        Loader-->>App: 返回 endpoint_plugins 列表
    end

設計思考：行程邊界決定載入策略

三類外掛的載入策略差異，本質是行程邊界的映射：

生產踩坑：外掛載入失敗的靜默降級

load_plugins_by_group對每個外掛的plugin.load()用 try/except 包裹，失敗只記 exception📎 vllm/plugins/__init__.py:68-72。這意味著一個損壞的外掛不會阻止 vLLM 啟動，但也不會給出顯式錯誤——使用者可能困惑於「為什麼我的外掛沒生效」。

排查建議：把日誌級別調到 DEBUG，搜尋"Failed to load plugin"。若外掛在vllm.general_plugins分組下，預設日誌級別是 DEBUG，需要顯式開啟才能看到載入詳情📎 vllm/plugins/__init__.py:49-50。

另一個坑是plugins_loaded守衛的置位時機📎 vllm/plugins/__init__.py:77-90：它在載入前就置True。若首次載入因某種原因失敗（如 entry_points 掃描異常），後續呼叫會直接返回而不重試。這在測試環境中可能導致「外掛時好時壞」的詭異現象。

---

本章小結

vLLM 的外掛系統建立在 Pythonentry_points之上，透過五個分組常數劃分擴展類型，透過行程邊界決定載入範圍，透過VLLM_PLUGINS白名單控制載入集合。平台外掛用Platform基類抽象硬體差異，其裝置 ID 三命名空間轉換（logical/visible/physical）是跨行程裝置管理的核心；IO processor 外掛透過 HF config 的io_processor_plugin欄位觸發，負責多模態輸入的翻譯；端點外掛採取「預設拒絕」姿態，只有顯式 allowlist 且 task 匹配時才載入，以控制網路暴露面。

三條主線共享同一套發現機制，但載入策略的差異體現了 vLLM 對「擴展便利性」與「安全邊界」的權衡：不暴露網路的外掛預設載入，暴露網路的外掛必須 opt-in。

本章思考與自測

---

下一章將轉向架構權衡、生產踩坑與未來演進，我們會把前十三章拆解過的機制放在一起，審視 vLLM 在效能、可維護性與擴展性之間的取捨，並展望推理引擎的演進方向。

至此，我們已經看清 vLLM 如何透過 entry_points 的分組機制、行程邊界感知的載入時機，以及平台、IO processor、端點三類外掛的差異化策略，在保持核心程式碼穩定的同時打開擴展面。這套外掛體系讓新硬體、新輸入格式和新 API 路由都能以非侵入方式接入，但擴展性本身也意味著更多需要權衡的維度。下一章將收束全書，系統梳理 vLLM 關鍵設計決策中的張力——連續批次處理與顯存碎片、CUDA Graph 與動態形狀、分離式部署與網路開銷——並給出一份生產環境踩坑清單與診斷路徑，同時展望 Rust 前端、IR 層與異構硬體方向的演進趨勢。

上一章我們拆解了 vLLM 的外掛化擴展機制，看到平台外掛、IO processor 外掛和端點外掛如何在不修改核心程式碼的前提下，讓引擎適配新硬體、新模態和新 API。這種可擴展性讓 vLLM 能夠快速擁抱變化，但擴展點越多，生產環境中的互動路徑就越複雜。當顯存碎片化、NCCL 握手失敗、編譯快取失效、網路抖動這些真實問題同時出現時，前十三章介紹的機制會彼此拉扯，暴露出理想環境下不曾顯現的張力。本章不再引入新的核心機制，而是把這些機制放在一起，以官方 troubleshooting 文件為錨點，結合 Rust 前端 bench 工具的設計，審視效能與可運維性之間的取捨，並給出一份可操作的診斷路徑。

一、優化等級：啟動時間與執行效能的顯式契約

直覺模型

優化等級就像相機的「場景模式」：自動檔（-O2）適合大多數場景，但當你需要快速抓拍（除錯）時，切到手動檔（-O0）能立刻響應，代價是畫質（效能）下降。vLLM 把這種取捨做成了顯式的四檔契約，而不是藏在幾十個布林 flag 裡讓使用者自己拼。

四檔的欄位佈局

vLLM 提供-O0到-O3四個等級📎 docs/design/optimization_levels.md:5-5。核心設計原則是：使用者顯式設定的 flag 優先於優化等級的預設值 📎 docs/design/optimization_levels.md:5-5。這意味著優化等級只是一組預設值的集合，不是硬性約束。

-O0關閉一切：無 autotuning、無編譯、無 cudagraph📎 docs/design/optimization_levels.md:32-33。具體落到四個開關：cudagraph_mode=NONE、mode=NONE、所有 fusion 關閉、enable_flashinfer_autotune=False 📎 docs/design/optimization_levels.md:37-40。

-O1是開發場景的平衡點：啟用PIECEWISEcudagraph 和VLLM_COMPILE模式📎 docs/design/optimization_levels.md:50-51。注意這裡有個精妙的細節：fuse_norm_quant和fuse_act_quant只在其中一個算子使用自訂 kernel 時才啟用，否則 Inductor 的自動融合效果更好📎 docs/design/optimization_levels.md:61。這是一個典型的「不要和編譯器搶活幹」的設計判斷。

-O2是預設值，面向生產📎 docs/design/optimization_levels.md:66-67。它在-O1基礎上追加FULL_AND_PIECEWISEcudagraph 和fuse_allreduce_rms 📎 docs/design/optimization_levels.md:72-73。-O3當前等同於-O2，為未來更激進的實驗性優化預留📎 docs/design/optimization_levels.md:80-81。

場景驅動的選擇流程

當一個使用者執行vllm serve model -O1時，內部發生了什麼？下面的流程圖展示了優化等級如何與使用者 flag 互動：

flowchart TD
    start["用户启动 vllm serve -O1"] --> parse["解析 optimization_level=1"]
    parse --> load_defaults["加载 O1 默认值集合"]
    load_defaults --> check_user{"用户是否显式设置了<br/>cudagraph_mode?"}
    check_user -->|是| user_wins["使用用户值<br/>覆盖 O1 默认"]
    check_user -->|否| use_default["使用 O1 默认<br/>PIECEWISE"]
    user_wins --> check_fusion{"fuse_norm_quant<br/>是否涉及自定义 kernel?"}
    use_default --> check_fusion
    check_fusion -->|是| enable_fuse["启用该 fusion"]
    check_fusion -->|否| skip_fuse["跳过，交给 Inductor"]
    enable_fuse --> done["配置完成，进入引擎初始化"]
    skip_fuse --> done

這個流程的關鍵在於check_user分支：使用者顯式設定永遠優先📎 docs/design/optimization_levels.md:5-5。這避免了「優化等級悄悄覆蓋了我的除錯 flag」這類難以排查的問題。

設計思考與踩坑

優化等級最常見的生產陷阱是啟動時間過長。文件明確建議：啟動時間過長時用-O0或-O1 📎 docs/design/optimization_levels.md:87。但這裡有個隱性代價——-O0下沒有 cudagraph，每個 kernel 的 CPU 發射開銷會暴露出來，在高併發場景下吞吐可能下降數倍。

另一個陷阱是編譯錯誤。-O2的FULL_AND_PIECEWISEcudagraph 對模型結構有更強的假設，某些自訂模型在-O2下編譯失敗但在-O1下正常。文件建議用debug_dump_path獲取更多除錯資訊📎 docs/design/optimization_levels.md:88。排查路徑應該是：先用-O0確認功能正確，再逐步升到-O1、-O2，定位是哪一檔引入的問題。

---

二、生產踩坑清單：從症狀到根因的診斷路徑

直覺模型

生產環境的故障排查就像急診分診：你不能對所有病人做全套檢查，必須先根據症狀（OOM、hang、崩潰）快速縮小範圍，再針對性深挖。vLLM 的 troubleshooting 文件本質上就是一份分診手冊。

症狀分類與診斷工具

文件把常見問題分成幾大類，我們按診斷難度遞進梳理。

第一類：模型下載/載入掛起。症狀是啟動後長時間無回應。根因通常是網路慢或共享檔案系統慢📎 docs/usage/troubleshooting.md:11-11。診斷手段是--load-format dummy跳過權重載入，隔離出到底是下載慢還是載入慢📎 docs/usage/troubleshooting.md:23-23。這是一個典型的「二分法隔離」技巧。

第二類：顯存 OOM。文件直接指向 conserving_memory 配置文件📎 docs/usage/troubleshooting.md:23。但生產中的 OOM 往往不是模型太大，而是 KV cache 碎片或並行請求數超預期。

第三類：生成品質變化。這是一個容易被忽視的坑。v0.8.0 改變了預設取樣參數的來源：從 vLLM 的中性預設值改為模型作者的generation_config.json 📎 docs/usage/troubleshooting.md:23-23。大多數情況下這提升了品質，但某些模型的配置反而更差📎 docs/usage/troubleshooting.md:23-23。診斷方法是回退到--generation-config vllm對比📎 docs/usage/troubleshooting.md:23-23。

第四類：卡死（hang）。這是最難診斷的一類。文件給出了一組遞進的除錯環境變數📎 docs/usage/troubleshooting.md:41-41：

• VLLM_LOGGING_LEVEL=DEBUG：打開詳細日誌
• VLLM_LOG_STATS_INTERVAL=1.：高頻輸出佇列和快取命中狀態
• CUDA_LAUNCH_BLOCKING=1：定位是哪個 CUDA kernel 出問題
• NCCL_DEBUG=TRACE：打開 NCCL 詳細日誌
• VLLM_TRACE_FUNCTION=1：記錄所有函式呼叫，但會拖慢 100 倍以上📎 docs/usage/troubleshooting.md:41

這裡有個重要的運維紀律：除錯完必須關閉這些環境變數，或直接開新 shell，否則殘留的除錯配置會持續拖慢系統📎 docs/usage/troubleshooting.md:11-11。

斷點除錯的行程邊界陷阱

vLLM 的多行程架構讓常規pdb斷點失效——斷點如果在子行程中執行，會拋出BdbQuit 📎 docs/usage/troubleshooting.md:45-54。兩種解法：用forked-pdb 📎 docs/usage/troubleshooting.md:57-61，或設定VLLM_ENABLE_V1_MULTIPROCESSING=0把排程器留在同行程📎 docs/usage/troubleshooting.md:63-68。

分散式通訊的診斷

分散式部署有專門的診斷文件。核心建議是：在叢集建立時設定環境變數，因為變數會傳播到所有節點；而在 shell 中設定只影響本地節點📎 docs/serving/distributed_troubleshooting.md:16-16。

一個高頻問題是No available node types can fulfill resource request，即使叢集有足夠 GPU 也會出現📎 docs/serving/distributed_troubleshooting.md:16-16。根因通常是節點有多個 IP，vLLM 選錯了。解法是用VLLM_HOST_IP顯式指定，並用ray status驗證📎 docs/serving/distributed_troubleshooting.md:16-16。

NCCL 初始化失敗的診斷腳本

文件提供了一個完整的診斷腳本，逐層驗證通訊堆疊📎 docs/usage/troubleshooting.md:89-150。它的設計很有層次：

flowchart TD
    start["运行诊断脚本"] --> nccl_test["测试 PyTorch NCCL<br/>dist.all_reduce"]
    nccl_test --> nccl_ok{"value == world_size?"}
    nccl_ok -->|否| hw_broken["硬件/驱动故障<br/>联系系统管理员"]
    nccl_ok -->|是| gloo_test["测试 PyTorch GLOO<br/>CPU 通信"]
    gloo_test --> gloo_ok{"value == world_size?"}
    gloo_ok -->|否| gloo_fail["GLOO 配置问题<br/>检查网络接口"]
    gloo_ok -->|是| pynccl_test["测试 vLLM PyNcclCommunicator"]
    pynccl_test --> pynccl_ok{"all_reduce 正确?"}
    pynccl_ok -->|否| pynccl_fail["vLLM NCCL 封装问题"]
    pynccl_ok -->|是| graph_test["测试 CUDA Graph 内 all_reduce"]
    graph_test --> graph_ok{"g.replay() 后正确?"}
    graph_ok -->|否| graph_fail["CUDA Graph 捕获问题<br/>检查 stream 语义"]
    graph_ok -->|是| success["sanity check 成功"]

這個腳本的精妙之處在於它逐層隔離：先驗證最底層的 PyTorch NCCL，再驗證 CPU 側的 GLOO，再驗證 vLLM 自己的 PyNcclCommunicator 封裝，最後驗證 CUDA Graph 內的通訊📎 docs/usage/troubleshooting.md:90-146。每一層失敗都指向不同的根因。

腳本中一個值得注意的細節：pynccl.disabled = False是為了向後相容 0.6.4 及以下版本📎 docs/usage/troubleshooting.md:121-125。0.6.5+ 預設啟用，但保留這行程式碼讓讀最新文件的用戶不會困惑。

多節點測試時，文件特意用--rdzv_backend=static而非c10d，因為c10d在多節點下會因 DNS 解析失敗📎 docs/usage/troubleshooting.md:168-168。這是一個典型的「踩過坑才知道」的配置。

設計思考與踩坑

NCCL 初始化失敗（ncclCommInitRank報 unhandled system error）通常指向兩個根因：缺少IPC_LOCKcapability 或/dev/shm未掛載📎 docs/usage/troubleshooting.md:311-311。這兩個都是容器化部署的經典陷阱。

CUDA PTX 工具鏈不匹配（the provided PTX was compiled with an unsupported toolchain）說明 wheel 裡的 PTX 是用更高版本的 CUDA toolkit 編譯的📎 docs/usage/troubleshooting.md:325-327。解法是啟用 CUDA forward compatibility：Docker 下加-e VLLM_ENABLE_CUDA_COMPATIBILITY=1 📎 docs/usage/troubleshooting.md:325-327，裸機下裝cuda-compat套件並設定VLLM_CUDA_COMPATIBILITY_PATH 📎 docs/usage/troubleshooting.md:325-327。

已知的 NCCL 記憶體開銷問題：vLLM >= 0.4.3, <= 0.10.1.1會設定NCCL_CUMEM_ENABLE=0來規避 NCCL bug，外部行程連接 vLLM 時也必須設定這個變數，否則會 hang 或崩潰📎 docs/usage/troubleshooting.md:375。NCCL 2.22.3 修復後，新版本移除了這個覆蓋以允許效能優化📎 docs/usage/troubleshooting.md:375。這個案例說明：跨行程的環境變數契約是分散式系統的隱性依賴，升級時必須同步。

---

三、Rust 前端：bench 工具的零拷貝設計哲學

直覺模型

如果說 Python 前端是「功能完備但笨重」的瑞士軍刀，Rust bench 工具就是「只為壓測而生」的手術刀。它的設計目標不是功能覆蓋，而是在高並行下把客戶端自身的開銷壓到最低，讓測出來的數字真實反映伺服器端效能。

資料結構與記憶體佈局

bench 工具的核心資料結構是RequestFuncInput 📎 rust/src/bench/src/backends/mod.rs:59-89。它大量使用Arc<str>和Arc<[u32]>而非String/Vec，這是零拷貝設計的核心。

看幾個關鍵欄位：prompt: Arc<str> 📎 rust/src/bench/src/backends/mod.rs:50-52——多個並發請求可以共享同一個 prompt 字串，避免每個請求都克隆一份。prompt_token_ids: Option<Arc<[u32]>> 📎 rust/src/bench/src/backends/mod.rs:77——預計算的 token ID 直接發給服務端，跳過服務端 tokenization📎 rust/src/bench/src/backends/mod.rs:74-76。

最精妙的是multi_modal_content: Option<Arc<[Arc<str>]>> 📎 rust/src/bench/src/backends/mod.rs:81。註解解釋：多模態內容作為預序列化的 JSON 片段，chat backend 直接拼接進 payload 位元組流，避免任何解析或深拷貝 base64 圖像資料📎 rust/src/bench/src/backends/mod.rs:78-80。這是一個雙層Arc結構：外層Arc<[...]>共享整個陣列，內層Arc<str>共享單個片段。

chat_messages_json: Option<Arc<str>>優先級最高，直接原樣拼進 payload📎 rust/src/bench/src/backends/mod.rs:82-85。

零分配反序列化

SSE 流式回應的解析是另一個效能關鍵點。註解明確指出：使用型別化反序列化避免構建完整的serde_json::Value樹，只提取需要的欄位📎 rust/src/bench/src/backends/mod.rs:20-24。

CompletionChunk只保留choices和usage兩個欄位📎 rust/src/bench/src/backends/mod.rs:20-24，ChatChunk同理📎 rust/src/bench/src/backends/mod.rs:33-37。#[serde(default)]讓缺失的choices欄位預設為空陣列📎 rust/src/bench/src/backends/mod.rs:20-24，這是流式回應的常見情況。

場景驅動的請求流程

當一個壓測請求發出時，資料如何流轉？下面的資料流圖展示了從輸入到輸出的轉換：

flowchart LR
    input["RequestFuncInput<br/>Arc&lt;str&gt; prompt"] --> build["build_headers<br/>+ payload 拼接"]
    build --> send["reqwest::Client<br/>send_request"]
    send --> sse["SSE 流式响应<br/>字节流"]
    sse --> parse["CompletionChunk<br/>类型化反序列化"]
    parse --> output["RequestFuncOutput<br/>ttft/itl/tpot"]

Backend列舉用靜態分發避免 async trait object 的問題📎 rust/src/bench/src/backends/mod.rs:150-154。send_request透過match分發到具體實作📎 rust/src/bench/src/backends/mod.rs:158-168。get_backend根據BackendKind返回對應後端📎 rust/src/bench/src/backends/mod.rs:172-181。

一個細節：API_KEY用OnceLock快取，避免每個請求都做一次環境變數 syscall📎 rust/src/bench/src/backends/mod.rs:186-188。build_headers依次插入 Content-Type、Authorization、extra headers、request-id📎 rust/src/bench/src/backends/mod.rs:191-215。

設計思考與踩坑

RequestFuncOutput的欄位設計也值得注意：ttft（time to first token）、itl（inter-token latency 陣列）、tpot（time per output token）📎 rust/src/bench/src/backends/mod.rs:93-105。這三個指標分別對應不同的效能維度：TTFT 反映 prefill 和排隊延遲，ITL 反映 decode 的穩定性，TPOT 反映整體吞吐。壓測時如果只看平均延遲，會掩蓋 ITL 的抖動。

---

設計思考：架構權衡的底層邏輯

把本章和前面十三章的機制放在一起，能看到 vLLM 的幾條核心權衡線。

CUDA Graph vs 動態形狀。CUDA Graph 要求靜態形狀，但連續批次處理的批次大小每步都在變。vLLM 的解法是PIECEWISE和FULL_AND_PIECEWISE模式📎 docs/design/optimization_levels.md:50,72——把可靜態化的部分捕獲成圖，動態部分保持 eager。-O0完全關閉 cudagraph 是為了除錯，-O2全開是為了生產，中間的-O1是折中。

分離式部署 vs 網路開銷。KV Connector 讓 prefill 和 decode 可以分離到不同實例，但 KV cache 的跨實例傳輸引入了網路延遲。文件中 GPUDirect RDMA 的配置要求（IPC_LOCK、/dev/shm）📎 docs/usage/troubleshooting.md:311-311說明這條路徑對基礎設施有硬性要求。網路抖動會導致 KV 傳輸超時，進而觸發重試或降級。

可運維性 vs 效能。優化等級、除錯環境變數、診斷腳本，這些都是為可運維性付出的成本。VLLM_TRACE_FUNCTION=1會拖慢 100 倍📎 docs/usage/troubleshooting.md:41，但它是定位 hang 問題的最後手段。一個成熟的引擎必須提供這些「慢但能看清」的工具。

---

本章小結

本章收束全書，把前十三章的機制放在生產視角下重新審視。

優化等級（-O0到-O3）是啟動時間與執行效能的顯式契約，使用者 flag 永遠優先於等級預設值📎 docs/design/optimization_levels.md:5-5。生產踩坑清單涵蓋了從模型載入、顯存 OOM、生成品質變化到分散式通訊失敗的完整診斷路徑，核心方法論是「二分法隔離」和「逐層驗證」。Rust bench 工具用Arc共享和型別化反序列化把客戶端開銷壓到接近零，確保壓測數字真實反映服務端效能。

三條核心權衡線貫穿全書：連續批次處理與顯存碎片、CUDA Graph 與動態形狀、分離式部署與網路開銷。理解這些張力，比記住任何單個機制都重要——因為生產環境的每一次調優，本質上都是在這些張力之間找平衡點。

本章思考與自測

---

至此，全書十四章的原始碼解讀告一段落。我們從一次 API 呼叫出發，穿過排程器、KV cache 管理器、注意力後端、分散式通訊層，最終抵達 GPU kernel 的發射點，又回到生產運維的診斷台。vLLM 的每一個設計決策背後都有明確的權衡，理解這些權衡，才能在面對新的硬體、新的模型、新的負載時，做出正確的工程判斷。推理引擎的演進不會停止——Rust 前端、IR 層、異構硬體支援都在快速推進——但底層的權衡邏輯是穩定的，這正是本書希望傳遞的核心能力。

至此，我們走完了從請求入口到 GPU Kernel 的完整旅程，也看清了生產環境中那些讓系統從「能跑」變成「跑得穩」的權衡與踩坑。vLLM 的演進不會止步於當前架構，更高效的注意力實現、更智慧的排程策略、更無縫的異構支援都在路上。但無論未來如何變化，理解這些機制之間的張力與取捨，始終是駕馭推理引擎的關鍵。