vllm 学习笔记

Appearance

学习日志 ​

进度总览 ​

  • 初始化学习站点
  • 完成架构概览主题
  • 完成引擎核心主题
  • 完成调度系统主题
  • 完成 KV 缓存与 PagedAttention 主题
  • 完成执行器与 Worker 主题
  • 完成模型库与算子层主题
  • 完成量化系统主题
  • 完成推测解码主题
  • 完成多模态处理主题
  • 完成分布式计算主题
  • 完成 API 服务与部署主题

Day 1 — 架构概览 ​

日期： 状态：

今日摘要 ​

困惑与突破 ​

  • 困惑：
  • 突破：

Day 2 — 引擎核心 ​

日期： 状态：

今日摘要 ​

困惑与突破 ​

  • 困惑：
  • 突破：

Day 3 — 调度系统 ​

日期： 状态：

今日摘要 ​

困惑与突破 ​

  • 困惑：
  • 突破：

Day 4 — KV 缓存与 PagedAttention ​

日期： 状态：

今日摘要 ​

困惑与突破 ​

  • 困惑：
  • 突破：

Day 5 — 执行器与 Worker ​

日期： 状态：

今日摘要 ​

困惑与突破 ​

  • 困惑：
  • 突破：

Day 6 — 模型库与算子层 ​

日期： 状态：

今日摘要 ​

困惑与突破 ​

  • 困惑：
  • 突破：

Day 7 — 量化系统 ​

日期： 状态：

今日摘要 ​

困惑与突破 ​

  • 困惑：
  • 突破：

Day 8 — 推测解码 ​

日期： 状态：

今日摘要 ​

困惑与突破 ​

  • 困惑：
  • 突破：

Day 9 — 多模态处理 ​

日期： 状态：

今日摘要 ​

困惑与突破 ​

  • 困惑：
  • 突破：

Day 10 — 分布式计算 ​

日期： 状态：

今日摘要 ​

困惑与突破 ​

  • 困惑：
  • 突破：

Day 11 — API 服务与部署 ​

日期： 状态：

今日摘要 ​

困惑与突破 ​

  • 困惑：
  • 突破：

上游同步 — 2025-05-26 ​

vllm 子模块：ff712f644 → d5cf7b4a2（247 commits）

主要变更 ​

  1. Offline API 拆分：LLM 类重构为 Mixin 组合架构（OfflineInferenceMixin + BeamSearchOfflineMixin + PoolingOfflineMixin）
  2. Rust Frontend 集成：RustFrontendProcessManager 管理 vllm-rs 二进制前端
  3. DP Supervisor：多端口数据并行管理器，为每个 DP rank 生成独立 server
  4. MooncakeStore 多组支持：支持混合注意力模型的多组 KV 缓存（如 DeepSeek V4 的 MLA + SWA）
  5. 文件系统分层：新增 FileSystemTierManager，纯 Python 磁盘后端 KV 缓存
  6. Elastic EP：弹性专家并行，在线扩展/缩减 EP 大小
  7. MoE Oracle 框架：统一后端选择（Triton、CUTLASS、FlashInfer B12x 等）
  8. Mamba 推测解码融合内核：消除 CPU-GPU 同步瓶颈
  9. GDN 子系统：Gated DeltaNet 注意力层（Kimi、OLMo、Qwen）
  10. DeepSeek V4 模型隔离：移出主仓库到 vllm/models/deepseek_v4/
  11. NVFP4 混合精度：新增 W4A16_NVFP4 量化模式
  12. Compressed Tensors 稀疏性移除：2:4 稀疏性支持已弃用

更新的笔记章节 ​

上游同步 — 2026-06-24 ​

vllm 子模块：d5cf7b4a2 → 4ed8eaafb（1036 commits，跨越 v0.22.0 → v0.22.1 → v0.23.0）

主要变更 ​

  1. Model Runner V2 (MRV2) 默认启用：v1（约 7400 行）与 MRV2（约 1600 行）双轨并存，由 use_v2_model_runner 按架构白名单（Llama/Mistral/Qwen3/DeepseekV2/Qwen2Moe/GraniteMoe）选择；把注意力元数据/多模态预处理/采样拆到 gpu/{model_states,sample,spec_decode,mm,pool}/ 子包，引入 RequestState/ModelState 两层状态管理
  2. MoE 层控制反转重构：FusedMoE 拆为 FusedMoERouter + RoutedExperts + MoERunner 三件套，后端下沉到 experts/（30 个文件），oracle 按精度分散为 oracle/{fp8,int_wna16,nvfp4,...}.py
  3. 渲染与解析层：入口层与引擎层之间新增 vllm/renderers/（OnlineRenderer/OnlineDerenderer）与 vllm/parser/（流式解析器引擎），OpenAI/Anthropic/Responses 三套 API 共用；新增 /render、/derender 支持 PD 分离
  4. Anthropic Messages API 成熟：/v1/messages 支持 effort、thinking 内容块、count_tokens、cache usage
  5. Strict Tool Calling：tools[].strict + VLLM_ENFORCE_STRICT_TOOL_CALLING，通过 xgrammar structural-tag 在生成阶段约束参数（Rust 前端也集成）
  6. NIXL 连接器 Pull/Push 双模式：NixlPullConnector（READ）与 NixlPushConnector（WRITE 直写 D 端显存）；kv_both 角色弃用
  7. 多级 KV 卸载编排器：TieringOffloadingManager 以 CPU 为 gateway，下挂磁盘/对象存储 secondary tier；AsyncLookupManager 后台批量 lookup；自描述 KV 事件
  8. WideEP + DeepEP V2：decode 用 do_expand=False（cudagraph 安全）、prefill 用 do_expand=True；NIXL EP 解除与 DBO 的互斥
  9. 异步 EPLB 默认：use_async=True，新增 NixlEplbCommunicator 零拷贝通信器，支持 DSv4 Mega MoE；EPLB 后端枚举化
  10. 推测解码扩展：统一 BaseSpeculator/AutoRegressiveSpeculator 抽象；新增 DFlash（掩码并行起草）、Dynamic SD（按并发调 K）、Gemma4 MTP（Q-only 跨模型 KV 共享）；MTP 方法族扩展到近 20 种变体
  11. 量化目录重组：新增 online/、inc/、turboquant/、humming.py 子包；WNA16 oracle 统一；ModelOpt mixed 扩展到 Ampere/Turing；GGUF 迁移为 plugin
  12. 调度增强：KV cache watermark、DP prefill_schedule_interval、Marconi 式混合缓存准入、partial prefix cache 原语、sliding-window/Mamba 稀疏保留间隔
  13. 多模态：VideoLoaderRegistry 按 processor 自动选后端；Gemma4 Unified（encoder-free）；多模态项处理 O(n)→O(log n)；ASR CPU 预处理 2.5x RTFx；WhisperModelState 泛化为 EncoderDecoderModelState
  14. Worker 优化：warmup 后 freeze_gc_heap() 冻结 GC 堆；cumem/sleep 可用性统一经 Platform 接口门控；不再内部设置 CUDA_VISIBLE_DEVICES（改用 device_ids）

更新的笔记章节 ​

上游同步 — 2026-06-28 ​

vllm 子模块：4ed8eaafb → 09841ae70（177 commits，约 4 天，工作版本 v0.23.1rc0）

主要变更 ​

  1. DeepSeek V3.2 / GLM-5（DSA 稀疏注意力）：新增 vllm/models/deepseek_v32/，同一套 DSA（DeepSeek Sparse Attention）代码服务 V3.2 与 GLM-5.2。DSA 在标准 MLA 之上叠加 lightning indexer，每若干层对所有已缓存 KV token 打分选出 top-k，后续 decode 只对这 top-k 槽位做注意力，把全上下文 O(N) 降为 O(k)。配套 fused_indexer_q_rope_quant Triton 内核与 dsv3_router_gemm CUDA kernel。
  2. Sparse MLA 后端：为 DSA 的 top-k 选择新增 decode-only 后端 —— FLASH_ATTN_MLA_SPARSE（Hopper）、FLASHINFER_MLA_SPARSE_SM120（Blackwell），另有 FlashMLA / ROCm AITER / XPU 变体。
  3. DCP（Decode Context Parallelism）：把 TP 组切成 DCP 子组、每子组持 KV 一份切片以支持更长上下文；MLA decode 路径现已支持 FP8 KV cache（移除旧硬断言），a2a 通信后端把每层 MLA 的 NCCL 调用从 3 次降到 2 次。
  4. 混合模型 block size 放宽：移除 Mamba+Attention 混合模型在 FP32 缓存下仅 [16,32,64] 的 FlashAttention block size 限制，统一为 MultipleOf(16)。
  5. /render 端点扩展：新增 return_assistant_tokens_mask（借助 {% generation %} 产出 assistant token 掩码，支持 SFT/RLHF/草稿模型训练数据生成）与 return_token_offsets（字符级偏移，便于归因/高亮）。
  6. Rust 前端统一解析器：把分离的 reasoning / tool parser 合并为 UnifiedParser 接口，单 parse_into() 增量产出 Text/Reasoning/ToolCall 三类事件并保留交错顺序（ToolParserOutput → Vec<ToolParserEvent>）；Gemma4 原生实现，Qwen3 等走 CombinedParser 适配；seed_oss（Harmony）作为 Qwen3 子类接入流式解析引擎。
  7. MoE 后端扩展：新增 Tencent HPC-Ops 融合 MoE 后端（--moe-backend hpc，SM90+/FP8）；Oracle 以 MoEKernelOracle 抽象基类标准化六项选择契约；共享专家融合（FSE）把 shared expert 并入分组 GEMM。
  8. MRV2 成熟：realtime embeddings（流式 ASR 持续注入音频嵌入）、EVS（高效视频采样，喂入 LLM 前丢冗余帧）、DFlash 全层 K/V/RMSNorm 融合 + 后端可选、use_local_argmax_reduction（贪心草稿采样 TP 通信从 O(词表) 降到 O(2·tp)）。
  9. KV 卸载重构：OffloadingHandler → OffloadingWorker（显式 worker 进程语义）；lookup 返回 LookupResult 枚举（HIT/MISS/HIT_PENDING/RETRY）替代 bool|None；CPU pinned memory 注册移到后台 CPUTensorPinThread；Mooncake 用 VLLM_MOONCAKE_LOAD_RECV_THREADS 多线程并行接收；NIXL 支持 Mamba1/Mamba2/GDN 卷积状态分离，NixlPushConnector 双向模式默认关闭。
  10. INT4 per-token-head KV cache 量化：KVQuantMode.INT4_PER_TOKEN_HEAD，打包 + Randomized Hadamard Transform + 统一 Triton 注意力读取内核，相比 FP16 翻倍容量。
  11. 量化扩展：Humming 支持 2/3/5/6/7-bit pack-quantized 仅权重量化（亦可用作 MoE 后端）；NVFP4 无原生硬件时由 Triton EmulationNvFp4LinearKernel 软件模拟（融合反量化）。
  12. 多模态 GPU 显存准入（VRAM Semaphore）：MultiModalGPUMemoryPool 在前端进程以字节信号量门控硬件解码缓冲，引擎侧按 --mm-ipc-gpu-memory-gb 从 KV cache 预留，避免解码挤爆引擎显存。

更新的笔记章节 ​

上游同步 — 2026-06-29 ​

vllm 子模块：09841ae70 → 36bbecd64（33 commits，约 1 天，工作版本 v0.24.0）

主要变更 ​

  1. GLM-5 / DSv3.2 算子融合大手术（PR #46876）：NVIDIA 路径（新增 models/deepseek_v32/nvidia/kernels.py，823 行）把每解码层约 10 个独立 kernel 融成 3 个 Triton 内核 + 1 个 FlashInfer 融合：fused_norm_rope（Q/KV LoRA RMSNorm + RoPE + KV/indexer cache 写入 + FP8 量化 + top-k buffer 填哨兵，四路 program 并行）、fused_q（q_pe/ql_nope RoPE+量化打包成 FlashInfer sparse 期望的单段连续 FP8 query）、fused_eh_norm（MTP 草稿层置零+双 RMSNorm+拼接）、fused_allreduce_rms_norm（FlashInfer TRT-LLM fast path，all-reduce+残差+RMSNorm 三合一）。关键设计是延迟 all-reduce：o_proj 与 MoE runner 设 reduce_results=False、新增 skip_final_all_reduce，把本层 all-reduce 推到下层 norm 里融合。
  2. GLM-5.2 序列并行 MoE（PR #46635）：use_sequence_parallel_moe 把 MoE 输出聚合从「切块→本地 MoE→all-gather」改为「全 hidden→MoE→reduce-scatter」，每 rank 只传 hidden_dim/tp_size、通信量减半，端到端吞吐 +3.1~3.2%。
  3. KV Offload 后台 pin 线程回退（PR #46958，勘误）：上次记录的 CPUTensorPinThread 后台异步 pinning（#45850）因引入竞态（传输在 pin 完成前就开始）仅 5 天即被完全回退，当前为同步 pinning（mmap 区域经 pin_mmap_region()、其余张量经 PyTorch pin_memory=True）。
  4. Humming MoE 标准化为一等后端（PR #43373）：专家继承 FusedMoEExpertsModular、标准 apply() 签名、显式 SUPPORTED_W_A（16 种组合）、按 QuantKey 经 oracle 协商；所有 schema→QuantKey 转换抽取到 quantization/utils/humming_utils.py，与 Triton/CUTLASS/FlashInfer/HPC 走同一套 kernel/oracle/quant 选择链。
  5. CPU INT8 W8A8 MoE（PR #42920）：compressed-tensors INT8 W8A8 MoE 支持 CPU，权重经 Intel VNNI 预打包，由 CPUExpertsInt8 + fused_experts_cpu(is_vnni=True) 执行，oracle 在 CPU 平台优先 Int8MoeBackend.CPU。
  6. OCP MX 模拟回归（PR #46629）：把 Mxfp4MoeBackend.EMULATION 重新加回 GPT-OSS MXFP4 的优先级列表，无原生 MX 支持的 GPU 自动回退到 Triton 模拟，无需手动 --moe-backend emulation。
  7. Helion 内核框架（PR #44010，[1/N]）：Red Hat（Humming 同团队）的 GPU kernel 编写+自动调优框架（vllm/kernels/helion/，Python DSL + JSON 调优配置），首个 kernel fused_qk_norm_rope 把注意力前的 Q/K RMSNorm 与 RoPE 融合为单次 in-place 操作，附 H100/B200 预调优配置。
  8. MLA decode logits workspace 预分配（PR #46819）：Triton MLA split-KV 的 logits 缓冲（(B, q_heads, num_kv_splits, kv_lora_rank+1)）改为 __init__ 时从共享 workspace 按最坏情况一次性预预留，消除每步 torch.empty 分配，warmup 后锁定、与 CUDA graph 兼容。
  9. ROCm AITER FlashAttention MLA prefill 后端（PR #45033）：ROCM_AITER_FA 直接调 aiter.flash_attn_varlen_func，原生支持 MLA 不对称的 Q/K(192) vs V(128) head_dim 而无需 padding，ROCm 平台优先级最高。
  10. Rust 前端 Harmony Renderer（GPT-OSS）（PR #46800）：HarmonyChatRenderer 用 openai-harmony crate 把对话直接渲染成 token id、完全绕过 HF tokenizer，处理 Harmony 通道协议（final/analysis/commentary）、tool-call 接收方（functions.{name} + <|constrain|>json）与 preamble，成为继 HF/DSV3.2/DSV4 后第 4 种 renderer；与既有 Harmony 输出解析器共享 encoding 单例。Rust tool 参数解析也修了 string 类型保留字面量 "null"（PR #46827）。
  11. Scale-out 端点整合（PR #44512）：render/derender/token_in_token_out（原 disagg）统一收到 entrypoints/scale_out/ 包，由 scale_out/factories.py 集中初始化，derender 提升为正式 ServingDerender 类。
  12. Gemma3 Encoder CUDA Graph（PR #43591）：Gemma3ForConditionalGeneration 实现 SupportsEncoderCudaGraph，单路径 image-only 图（vision_tower → projector → flatten），加入 DeepSeek-OCR/GLM-4.1V/InternVL/Kimi-VL/Qwen-VL 等支持编码器 CUDA graph 的 VLM 列表。
  13. EPLB padding 掩码（PR #38128）：MoE expert load 记录现掩掉 padding token（每 ubatch 一次 num_unpadded_tokens 张量，CUDA graph 安全），避免空 token 虚高负载触发无谓迁移；EPLB 扩展到推测解码草稿模型（DraftModelSpeculator.set_eplb_state()）。
  14. Mooncake DCP>1 lookup 修复（PR #46855）：DCP>1 时 lookup key prefix 必须显式枚举 (tp_rank, pcp_rank, dcp_rank, pp_rank) 全组合（DCP 复用 TP worker、KV-head 去重不再适用），否则漏掉 DCP rank 1+ 的块导致 cache miss。

其它小修：DSv3.2 indexer weights 在 index-cache-skipped 层跳过加载（#46600）、deepseek_v2 backbone 末层 aux hidden state 捕获（#46973）、CPU fused MoE 用原生 SiLU（#45961）、transformers 后端 tied-embedding lm_head.bias 与 M-RoPE mm_token_type_ids 重算（#46835/#46552）、推测解码草稿 prefill 跳过冗余 hidden states gather（#46968）。

更新的笔记章节 ​

上游同步 — 2026-07-29 ​

vllm 子模块：36bbecd64 → 6fbbcf215（1075 commits，约 1 个月，工作版本 v0.26.1rc0）

主要变更 ​

  1. KV 卸载新增 P2P 层级（PD 分离 / 对称 P2P）（PR #42285 + #48021，vllm/v1/kv_offload/tiering/p2p/，本月最大新子系统）。作为新的 SecondaryTierManager（类型 "p2p"），让 PD 分离的 decoder 经 RDMA 直接从 prefiller 的 CPU 缓存拉 KV 块。控制面与数据面解耦：ZMQ（ZmqTransport，VLLM_P2P_SIDE_CHANNEL_HOST:PORT 默认 localhost:5710，端口按 DP rank 偏移）做 peer 发现/握手/lookup 协调；NIXL RDMA（NixlTransport，backends 默认 ["UCX"]）做实际块传输。每个 remote peer 持一个双向 P2PSession（ClientRole+ServerRole）。两种角色：经典 PD（remote_prefiller，lookup 立即 HIT → FetchMsg → NIXL WRITE）；对称 P2P（remote_kv_source，先 RETRY 再步末批量 LookupMsg 探测 peer 持有哪些块）。握手强制 PYTHONHASHSEED 一致 + SHA-256 config_fingerprint 拒不兼容 peer；新增 ParentManager ABC 供 secondary tier 反查主层级。该层叠在 OffloadingWorker 之上而非取代它。
  2. 容错框架（DP+EP 外部 LB 部署）（PR #44428 + #43637）。enable_fault_tolerance + engine_recovery_timeout_sec（默认 120s）。run_busy_loop 被 @fault_tolerant_wrapper 包裹——EngineCore 出错时 EngineCoreSentinel.on_fault() 中止所有请求（FINISHED_ABORTED）、置 UNHEALTHY，在超时窗口内等外部经 FT_UTILITY_METHOD（handle_fault_tolerance）下发的 retry；retry 用 stateless 进程组 API 重建 DP group、WorkerSentinel（经 collective_rpc）清空 worker/buffer、重建 all2all buffer（仅 deepep_low_latency/nixl_ep 后端支持）。控制端点 POST /fault_tolerance/apply。配套 query_active_mask()/query_fault() 让 runner 检测对端 rank 掉线、丢弃被污染 batch；device communicator 新增 process-checkpoint 生命周期钩子（首见 FlashInfer）。
  3. MRV2 成为稠密模型默认（PR #44443）。use_v2_model_runner 依次按 VLLM_USE_V2_MODEL_RUNNER、强制 V2 项（PCP / dspark / 混合 DFlash 草稿 / 扩散）、_is_default_v2_model_runner_model()（核心判定 not is_moe）解析，无 Triton 或含未支持特性时回退 V1。MRV2 的可扩展性根基是 model_states/interface.py 的 ModelState ABC（新架构实现一个 state 即接入），新增 EncoderOnlyModelState（BERT/RoBERTa，无 KV cache，#49331），并补齐了多模态 encoder cache 的显存 profiling（原仅 V1，#47985）。PCP 现由 MRV2 的 gpu/pcp_manager.py 以 virtual-batch 实现（仅 MLA，#46570）并强制 V2。
  4. JIT 预热基础设施（VllmJitKernel）（PR #46182/#47451/#49903，vllm/model_executor/warmup/）。把 Triton/CuTeDSL 内核 JIT 编译从「首请求触发」挪到启动 warmup，避免冷启动延迟。VllmJitKernel ABC 三段式（dispatch→编译 key→compile），AST 追踪把 WarmupIntRange/zip_inputs 展开成 key 网格预编译；FA4 MLA prefill（CuTeDSL）、sparse MLA indexer、KVBlockZeroer 等已接入。FlashAttention 4 SM100 后端新增 headdim-256 与 FP8 KV cache 支持（#42669/#42569）。
  5. 推测解码三连：
    • 异构词表 TLI（PR #38174，use_heterogeneous_vocab）：允许 draft/target 词表不同，归一化 token 串求交集，采样前 constrain_draft_logits 置 -inf、采样后 map_draft_to_target_ids 翻译 ID（新文件 v1/spec_decode/vocab_mapping.py），贪心解码无损。
    • Bailing 混合模型 MTP（PR #44880）：线性注意力+MLA+MoE 混合模型支持 MTP，难点在带状态线性注意力的回滚——新增融合内核 _bailing_linear_attn_decode_spec_step_kernel 在 GPU 端按 num_accepted_tokens 选状态槽位（免 CPU 同步）。
    • Block verification（PR #46781）：rejection_sample_method='block'（Sun et al. 2024），维护联合前缀比 p_i 整块判定接受长度，仅 MRV2 sampler 实现。另有 speculative_config.kv_cache_dtype 可单独指定草稿 KV 精度（#48787）。
  6. 安全加固集群（资源耗尽 DoS 防护）。一组 fix(security) 提交，统一模式「昂责处理前先校验/设上限 + 可调环境变量」：VLLM_MAX_IMAGE_PIXELS（图像/视频解压炸弹 #47010）、VLLM_REGEX_COMPILATION_TIMEOUT_S（ReDoS #47595）、超长 prompt 字符预裁剪（#47007）、VLLM_MAX_COMPLETION_PROMPTS（completions 扇出 #47845）、请求级 GPU video backend 守卫（#47259）、derender 资源上限（#47260）。
  7. EngineCore 弹性与 RL 训练集成。（a）ZMQ 输出缓冲复用 bugfix（#50053）：复用首帧改用 _send_msg_tracking_payload() 单独 track，客户端删除手动 pending_messages，零拷贝帧由 ZMQ memoryview→owner 链保活。（b）Elastic EP 扩缩容改两阶段（#47288）：prepare_elastic_ep 重配置但不路由、commit_elastic_ep finalize，VLLM_ENGINE_READY_TIMEOUT_S 等新 engine。（c）RL 集成：权重版本号 _weight_version（#49040）+ 有状态 TrainerWeightTransferEngine/WeightSource ABC（#48042 [1/N]，trainer_init 绑定 source 后无参 send_weights() 重放）。
  8. 注意力 / KV-cache 布局。（a）按 KV-cache group 选后端 AttentionConfig.backend_per_kind（#48012，get_attn_spec_kind() 推导层组 kind）。（b）KV-cache 内存布局跨后端标准化（#44455/#44456）：K/V 按 content dim 统一打包、Mamba cache 标准化、移除 get_transfer_cache_regions。
  9. 其它：kv_cache_interface.py 的 AttentionSpec.page_size_bytes 拆为 unpadded + padding（#48411）修正 per-token-head 量化下卸载页传输宽度；Rust 前端新增 profiler 控制路由与 gRPC server 持续对齐 Python；stream_interval 升格为请求级采样参数（#49754）；KV events replay 补 topic frame（#45177）。

更新的笔记章节 ​

回归审计 — 2026-07-29 ​

对全站笔记做了一次整体回归（对齐 HEAD 6fbbcf215 的代码事实 + 完整性扫描）。

勘误（14 处陈旧/错误，已修正） ​

补全（6 处缺漏章节，新增） ​

  • topics/serving/concepts — OpenAI Responses API（有状态会话/后台/内置工具/命名式 SSE、ConversationContext、Harmony 分支）、Pooling 服务（embed/classify/score/late-interaction ColBERT MaxSim + flash 路径）、Profiler（kineto 逐层计时，区别于 profile_run()）。
  • topics/engine-core/concepts — 指标与可观测性（StatLoggerManager 扇出、vllm:* 指标族、perf.py 解析式 MFU 估算、/metrics、ObservabilityConfig）。
  • topics/model-layers/concepts / torch-compile — 自定义 Inductor 融合 pass（14 个 fusion pass + piecewise/breakable cudagraph 协同）。
  • topics/executor-worker/concepts — Sleep 模式（显存时分复用，level 1/2、SleepModeBackend 抽象、RFC #34303）。

自动化校验：79 个源码路径全部解析（仅 2 处已知伪报：api_server.py 迁移叙述、练习题新建文件）；15 个 VLLM_* 环境变量全部存在；VitePress 构建通过。

上游同步 — 2026-09-08 ​

vllm 子模块：6fbbcf215 → 7c2f1ff495（1740 commits，约 6 周，v0.26.1rc0 之后的 main，期间未出新 tag）

主要变更 ​

  1. MRV2 成为全部模型的默认 runner（PR #53183，8 月底）。删除 DEFAULT_V2_MODEL_RUNNER_ARCHITECTURES 架构白名单，VllmConfig.use_v2_model_runner 默认 True（pooling 更早，#48290）；仅 ROCm 上 DeepseekV32/V4（ROCM_DEFAULT_MRV1_ARCHITECTURES）与无 Triton 场景回退 V1，含 _get_v2_model_runner_unsupported_features() 清单特性（stock torch.compile、SP+TP>1、ngram、P-Eagle、DBO、elastic EP、自定义 logits processors 等）时告警回退。反向地，V1 拒绝 PCP/dspark/adaptive verification/dflash2/扩散/batch-sharded sampling。两份 unsupported 清单成为 V1/V2 能力边界的单一事实来源。
  2. KV-Cache Layout Refactor 收官（RFC #42082，#51612/#51704/#51718）。新文件 vllm/v1/kv_cache_layout.py 的 KVCacheLayout 枚举（逻辑形状 [L,B,H,N,C] + stride 置换）取代各 backend 的 get_kv_cache_shape() 等方法，backend 改经 supported_kv_cache_layouts() 声明偏好、customize_spec() 发布 packing（TurboQuant 等），布局在 engine core 一次性解析（resolve_kv_cache_layout()）。kv_cache_utils.py 随之支持混合 page size 分组：Qwen3.8-Flash-Next 的贪心分桶 + _approximate_gcd（#53896）、GLM-5Next 的 Mamba/MLA/Kpool tail 混排（#53906）。
  3. DCP 生态成型。集合通信收敛到 v1/attention/ops/dcp.py 的 MLADCPManager（#52839，对称内存直连 A2A 优先）；DCP × 前缀缓存打通：resolve_dcp_kv_block_size 按 dcp_world_size 放大 block 几何、partial hash hit 解除 dcp_world_size==1 限制（#50493/#53324/#53598，Kimi K3 打通）、MooncakeStore 支持混合 DCP 远端命中（#53324）。
  4. 有状态层的前缀缓存：Mamba/KDA「内部 prefill checkpoint」在 chunked prefill 中途写状态快照（MambaSpec.prefill_checkpoint_alignment，#52789/#53614，TTFT +9~25%），并与推测解码兼容；NONE_HASH 种子默认确定性（sha256 用固定种子，#51875）使跨进程块哈希复用可行；retention interval 从环境变量升格为 CacheConfig.prefix_cache_retention_interval（默认 0，#52216）。
  5. 前端架构收整：删除 v0 时代的 InputPreprocessor（#53064，prompt 预处理统一走 Renderer）；entrypoints「启动器出仓」重组——launchers/api_server/（#52131）、run_batch（#53500）、cli_args/dp_supervisor（#53659）、engine/protocol.py（#54492）移出 openai/；输入校验错误全面迁移到 VLLMValidationError 家族（VLLMError 二分 Client/Server，#49665 系列）；server 级准入控制（#49445）--max-num-queued-reqs/tokens 在 API server 进程判定、超限 HTTP 503。
  6. Rust 前端长成 RL rollout server 控制面（#51316 等）：gRPC control service 12 个 RPC（pause/sleep/权重传输全生命周期）、RlCapabilities 能力协商、LoRA 全生命周期（#52031/#54837）、Mooncake/NIXL connector 指标（#52755）。
  7. 推测解码扩展：DSpark（DSparkSpeculator，DFlash 基础上的半自回归并行起草 + 顺序 Markov head，走 DCP 式 attention）；自适应验证（按生存概率分配 top-k 验证预算，#47808，#52242 后兼容 logprobs）；multi-module MTP（Inkling 类多 MTP 模块轮转，#48892/#50062）；每请求接受度指标进 OpenAI 响应（#48915）；EAGLE3 扩展到 Sarvam（#53052）。
  8. 新模型潮（厂商目录模式 vllm/models/<model>/<vendor>/ 固化）：Kimi K3（KDA 线性注意力 + NoPE MLA + latent MoE + 三档 tail 调度）、GLM-5.3-Flash（KDA + MLA + MHC 超连接 + Kpool 索引器）、Qwen3.8-Flash-Next（hyperconnection + QSA 无权重索引器 + PLE 层）、HY-V4（DSA + iHC）、K2 Horizon（MoVA V 专家路由）、Bailing MoE V3、Muse Glimmer、Sarvam MLA、Cohere Compass；KDA 内核成为 K3/GLM-5Next/Bailing 共享底座并可切 FlashInfer（#55364）。
  9. 量化与内核：ModelOpt 重构为 QuantKey 驱动的单一 ModelOptLinearMethod（#49381）+ Fast Start IPC 权重缓存（#54921）；AMD Quark per-block FP8 fused MoE（#52263）；NVFP4 W4A4/W4A16 内核优先级修正（#55170）；[warmup][DSv4] 四部曲把 DSv4 内核全面迁入 JIT warmup（#50175/#53564/#53565/#50176）；PDL 铺开（fusedQKNormRope #55755 等）；FlashInfer all-reduce 默认开启（#52998）。
  10. RL 权重传输成体系：distributed/weight_transfer/ 新增 sharded RDT（Ray Direct Transport，trainer 侧 NIXL producer + consumer 侧 BAKE/REPLAY 两阶段按 slice 拉取，约 3000 行）、稀疏坐标 NCCL 更新（#53751）、IPC 引擎（#52497）；DP 状态同步自适应（--dp-sync-interval 默认 32→16 + wave 首步强制同步，#52957）。
  11. 多模态简化：MM processor 收敛为纯 token-id 输入（#53093/#53275 系列，text 处理归 Renderer）；video.py 拆为 video_decoders/ 包且 PyAV 弃用（#49155/#54231）；ECMooncakeConnector 打通 EPD encoder cache 传输（#41567）。
  12. 其它：确定性解码回放 trace_decode_token_ids（#46701，GPU 侧全实现）、batch-sharded sampling（#50465）、GPU 端 compact sampling masks（#54901）、hybrid 模型 wake_up 崩溃修复（#41602）、renderer warmup 与引擎初始化重叠（#54557）、top-p 小批量 split-row kernel（#54651）。

更新的笔记章节 ​

出链