（八）vLLM 0.25.1 的两层 V1/V2：引擎命名空间 vs 模型执行器，以及 vLLM-Kunlun 的落点

1. 名字撞车：两层 V1/V2

读 vLLM 0.25.1 源码（以及它的昆仑叉 vLLM-Kunlun）时，最容易迷路的一点：代码里出现了两组截然不同的「V1 / V2」，它们不是同一个东西，级别相差两层。

• 第一层（引擎级）：vllm.v1 命名空间 = Engine V1。 这是 vLLM 自 0.8 起正式取代 V0 的新一代统一引擎，统一了调度、KV 管理、连续批处理。只要你的代码 import vllm.v1，用的就是 Engine V1，和本文的「V2」无关。
• 第二层（执行器级）：GPU Model Runner 的 V1 / V2。 在 Engine V1 的内部、GPU worker 这一层，存在两个并列的模型执行器：ModelRunner（老的 V1 runner）与 ModelRunnerV2（新的 V2 runner）。它们不是引擎版本，而是同一引擎下两种 GPU 前向执行路径。

一句话区分：Engine V1 是「总指挥」，Model Runner V1/V2 是「两种打法」。昆仑叉的 method:dspark（DeepSeek 风格的草稿—验证投机解码）会强制走 V2 打法，原因在第四节展开。

2. 文件布局：两个 runner 在同一个子包里

Engine V1 的 GPU worker 把所有执行器代码都放在 vllm/v1/worker/gpu/ 下。在 vLLM-Kunlun 0.25.1 里大致是这样：

vllm/v1/worker/gpu/
├── model_runner.py          # ModelRunner（V1 老执行器）
├── model_runner_v2.py       # ModelRunnerV2（V2 新执行器）← Kunlun 6 项 DSpark 优化全落这里
├── gpu_worker.py            # GPUWorker，根据开关选择实例化哪个 runner
└── ...                       # 其他 kernel / 工具

两个 runner 对外暴露的契约是一致的（同样的 execute_model 入口、同样的输入结构），差别在内部实现：V2 把草稿—验证投机解码的 scaffolding（草稿生成、accept 判定、KV 复用）内建进了前向循环，而 V1 对这些高级特性的支持是后补的、受限的。

3. runner 分派逻辑

GPU worker 在构造时根据两个信号决定用哪个 runner：

1. 配置项 use_v2_model_runner（用户/平台显式指定）；
2. 投机解码方法 method: dspark —— 一旦启用，会被强制抬升为 use_v2_model_runner = True。

伪代码（示意，非逐字源码）：

# gpu_worker.py（示意）
def _build_model_runner(self, vllm_config):
    spec_config = vllm_config.speculative_config
    method = spec_config.method if spec_config else None

    use_v2 = vllm_config.use_v2_model_runner
    # 关键行：dspark 强制走 V2 执行器
    if method == "dspark":
        use_v2 = True

    if use_v2:
        return ModelRunnerV2(...)   # vllm/v1/worker/gpu/model_runner_v2.py
    return ModelRunner(...)         # vllm/v1/worker/gpu/model_runner.py

4. vLLM-Kunlun 6 项 DSpark 优化：全落 V2 runner 子包

vLLM-Kunlun 在 0.25.1 上为 dspark（草稿—验证投机解码）做了 6 项 XPU 针对性优化。它们的共同点是：全部落在 vllm/v1/worker/gpu/model_runner_v2.py（及其直接引用的 V2 子模块）里，而不是 Engine 层或 V1 runner。这个结论很重要——它解释了为什么这些优化对 V1 runner 完全不可见，也解释了为什么「开了 dspark 才享受得到」。

6 项优化的开关（env 变量）与落点（按你原始材料要核对具体名称，这里给出类别与已确认的锚点）：

注：KUNLUN_HOSTVEC 是你原始材料里点名的环境变量，语义已确认（host 控制面向量化）。其余 5 项的具体 env 名称与精确语义请以你的原始贴文/ diff 为准——上面为类别示意名，架构位置（全部在 V2 runner 子包）是确定的。

5. host 控制面性能根因

为什么昆仑叉要把 6 项优化几乎都做成「host 侧 / 控制面」相关？根因在于 decode 阶段的瓶颈已从 GPU 算力转移到 host（CPU）控制面开销。

逐 token 解码时，每个 step 都要在 CPU 侧准备一堆元数据：位置编码、attention mask、分页 KV 的 block table、投机草稿的候选……这些操作本身不在 GPU 上算，却是 GPU 能开工的前置条件。当 batch 里夹杂投机草稿、且 XPU 的 kernel launch 成本不低时，host 准备这些元数据的时间会拖累整步延迟，形成「GPU 在等 CPU 备料」的气泡。

KUNLUN_HOSTVEC 的做法是：把逐 token 的元数据准备向量化 + 批量处理——一次为一组 token 装配好 mask/position/block-table，减少重复的 Python/调度开销。这正对应第 4 节那张表里「host 侧向量化」这一项。其余几项（批量元数据、惰性 KV、mask 融合）本质也是在削减每步控制面的次数和体量——它们是同一根因下的不同切面。

6. 一句话总结

vLLM 0.25.1 的「V1/V2」是两回事：Engine V1 是引擎命名空间，ModelRunner(V1)/ModelRunnerV2(V2) 是 GPU 执行器；method:dspark 强制 use_v2_model_runner=True，而 vLLM-Kunlun 的 6 项 DSpark 优化全部落在 V2 runner 子包，通过把 host 控制面元数据向量化/批量化的方式，消解了 decode 阶段的 CPU 备料瓶颈。

7. 顶层框架图

把上面的分派与落点画成一张端到端框架图（对应你原始材料里的 mermaid flowchart TB）：

8. 与 DeepSpec 的代码对照

「DeepSpec」在这里指 vLLM 社区里把投机解码标准化为 spec_decode 模块的方向——把草稿器（draft）、验证器（verify）、accept 判定统一成接口。method:dspark 是 DeepSpec 体系里的一种草稿策略（基于 n-gram / 局部重复模式快速生成草稿）。

代码对照的要点：

• DeepSpec（社区主线）：spec_decode 模块提供通用的 SpecDecoder 接口，草稿与验证解耦，理论上 V1/V2 runner 都可挂；
• vLLM-Kunlun 0.25.1：把 dspark 这一具体草稿策略内建进 V2 runner 的前向循环（model_runner_v2.py），而非走通用的 spec_decode 解耦路径。好处是草稿生成、accept 判定、KV 复用可以在 V2 runner 内部做更激进的融合；代价是这份 dspark 实现是 V2 专属、与主线 spec_decode 不是同一份代码。

所以「DeepSpec 代码对照」的核心差异是：主线把投机解码放在 runner 之上的独立模块，昆仑叉把 dspark 焊进了 V2 runner 内部。这也是为什么昆仑叉的 6 项优化只能作用于 V2——它们依赖 V2 runner 内部的执行钩子。

9. V2 吞吐 / DSpark 接受率结论

把上面的机制落到收益上，结论分两层：

1. 架构层（确定）：只要走 method:dspark（→ V2 runner），就能吃到全部 6 项昆仑优化，其中 KUNLUN_HOSTVEC 等 host 控制面优化直接砍掉了 decode 每步的 CPU 备料税，这是 V2 相对 V1 runner 在昆仑 XPU 上吞吐更高的根本原因。
2. 数据层（以你的原始材料为准）：V2 + dspark 的草稿接受率（acceptance rate）与端到端吞吐的具体数字（你的贴文里应有实测对比），应填入此处——它们取决于模型、batch、序列长度。可验证的定性关系是：接受率越高，同等算力下 step 产出的 token 越多 → 吞吐越接近线性放大；而 V2 通过把控制面开销压到最低，让高接受率真正转化为吞吐增益，而不是被 CPU 备料吃掉。

延伸阅读

• vLLM 源码：vllm/v1/worker/gpu/model_runner.py 与 model_runner_v2.py（注意 use_v2_model_runner 的分派）
• vLLM-Kunlun 仓库的 dspark / KUNLUN_* 环境变量开关（以你 fork 的 README 与 diff 为准）
• vLLM 官方文档：Speculative Decoding
• 本系列前文：（七）图模式：CUDA Graph 原理与 vLLM / SGLang 的实现