DeepInfer 源码拆解（三十七）：EngineType 与 P/D 分离接口——同一个引擎类如何分饰预填充、解码与混合三种角色

2.1 枚举定义

Python 侧的定义在 deepinfer/engine/engine_type.py：

1
class EngineType(enum.Enum):
2
    """
3
    LLMEngine type
4

5
    请和 csrc/engine/scheduler.hpp 中的 enum class EngineType 保持一致
6
    """
7

8
    NORMAL = 0  # process prompts & completions
9
    PROMPT = enum.auto()  # only process prompts
10
    COMPLETION = enum.auto()  # only process completions
11

12
    @property
13
    def default_zero_overhead_scheduling(self) -> bool:
14
        return self in (EngineType.NORMAL, EngineType.COMPLETION)

C++ 侧在 csrc/engine/scheduler.hpp：

1
/// LLMEngine 类型。
2
/// 请和 deepinfer/engine/engine_type.py 中的定义保持一致
3
enum class EngineType : int {
4
    NORMAL = 0,     // process prompts & completions
5
    PROMPT = 1,     // only process prompts
6
    COMPLETION = 2, // only process completions
7
};

两侧必须一致，是因为 SchedulerConfig 把 engine_type.value 作为一个 int 传给 nanobind 包装的 C++ 调度器，C++ 侧用 static_cast<EngineType> 直接转回来。一旦 Python 侧插入新枚举值，C++ 侧的 NORMAL=0/PROMPT=1/COMPLETION=2 就会错位，NORMAL 可能被当成 PROMPT 来解释——整个集群的步型都会错。所以两边都写了”保持一致”的中文注释，csrc/engine/scheduler.hpp 的构造函数里还有一句兜底：

1
TORCH_CHECK(false, "unknown engine_type ", int(engine_type));

_schedule() 的 switch 没有 default 分支而是在 switch 之后断言，任何未识别的值都会在第一次调度时炸出来，而不是静默走错路径。

default_zero_overhead_scheduling 是一个容易看漏的地方：PROMPT 引擎默认不开启零开销调度（ZOS）。原因是 ZOS 的价值在于把解码步的 CPU 后处理移到下一拍，和 GPU 前向重叠；预填充引擎的每一步都是一个大批次 prefill，前后处理体量与 decode 完全不同，重叠收益有限，而且 PE 需要尽快把处理完的请求连同 KV 发出去，延后一拍反而增加交接延迟。ZOS 的步编排细节可以参考 DeepInfer 源码完全拆解（二）：异步调度与零开销调度 ZOS。

2.2 构造期：角色改写环境变量

EngineArgs 是一个 dataclass，engine_type 只是字段之一。在 __post_init__ 里，角色被翻译成三个副作用：

1
def __post_init__(self):
2
    if self.tokenizer is None:
3
        self.tokenizer = self.model
4
    os.environ.setdefault(
5
        "DEEPINFER_ZERO_OVERHEAD_SCHEDULING",
6
        "1" if self.engine_type.default_zero_overhead_scheduling else "0",
7
    )
8
    environ.rearm("DEEPINFER_ZERO_OVERHEAD_SCHEDULING")
9
    os.environ.setdefault(
10
        "DEEPINFER_USE_MULTIMODAL_POOL",
11
        "1" if self.engine_type != EngineType.COMPLETION else "0",
12
    )
13
    environ.rearm("DEEPINFER_USE_MULTIMODAL_POOL")

这里用 setdefault 而不是直接赋值，含义是：如果运维已经在环境变量里显式写了 DEEPINFER_ZERO_OVERHEAD_SCHEDULING=1，就以运维为准，角色只提供默认值。随后 environ.rearm 让 DeepInfer 的环境变量缓存重新读取该键——DeepInfer 的环境变量是模块加载时一次性快照的，若不在改写后重读，后面读到的还是旧值。

DEEPINFER_USE_MULTIMODAL_POOL 对 COMPLETION 引擎强制关闭，这一点后面还有旁证：LLMEngine.__init__ 里 mm_enabled 的判定是

1
mm_enabled = hasattr(model_class, "multi_modal_mapper") and engine_type != EngineType.COMPLETION

也就是说解码引擎根本不构造 MultimodalProcessor。理由很直接：图像编码是预填充阶段的工作，解码侧的输入只有 token id 和已经就位的 embedding，没有任何多模态数据需要处理。视觉编码器 VE 与预填充分离后，CE 连多模态对象的引用都不需要持有，自然也就不应该为它预留显存和 CPU 线程。

2.3 chunked_prefill 的默认值与角色

EngineArgs 里 chunked_prefill: bool = False，看起来是个与角色无关的开关。但 C++ 调度器里有一行：

1
prompt_limit = chunked_prefill ? max_model_len : std::min(max_model_len, max_num_batched_tokens);

而 SchedulerConfig._verify_args() 在 chunked_prefill=False 时要求：

1
if (not self.chunked_prefill) and self.max_num_batched_tokens < self.max_model_len:
2
    raise ValueError(...)

合起来看：不开分块预填充时，最长的一条 prompt 必须能在一个批次里放下，因此 max_num_batched_tokens 至少等于 max_model_len。此时 max_num_batched_tokens 的上界——也就是一步能携带的 token 预算——必须撑得住”最长 prompt 整条塞进来”，但 _schedule_prefill 仍然可以在这个预算内放多条短 prompt。真正的差别在于长 prompt：一条超过预算的 prompt 在不分块时只能独自成批，短 prompt 才有机会拼批。PE 的职责是以尽可能大的批量吸收大量请求，它应当显式配置 chunked_prefill=True，让调度器按 token 预算切分长 prompt，从而把多条 prompt 的尾块和短 prompt 拼进同一个批次，而不必让一条长 prompt 独占一拍。

换句话说，chunked_prefill 的默认值暴露了一个隐含假设：默认配置面向”一条一条来”的通用引擎；P/D 分离部署里的 PE 需要显式切换到批量模式。代码层面并没有强制检查这一点，这是一处需要部署者自行意识到的角色化配置。

4.1 _schedule() 的三种分支

调度器 _schedule() 的骨架非常短，因为角色差异被平铺成三个 case：

1
switch (engine_type) {
2
case EngineType::PROMPT:
3
    // PROMPT 引擎只做 prefill，即使没调度到请求也返回（空的）prefill 结果
4
    return _schedule_prefill(acquire);
5
case EngineType::COMPLETION:
6
    // COMPLETION 引擎只做 decode
7
    return _schedule_decode(acquire);
8
case EngineType::NORMAL: {
9
    // NORMAL 引擎：决定这一步全组做 prompt 还是 decode
10
    ...
11
}
12
}
13
TORCH_CHECK(false, "unknown engine_type ", int(engine_type));

PROMPT 与 COMPLETION 两个分支都只有一行，这是角色化设计最彻底的地方：PE 永远只看等待队列，CE 永远只看运行队列，它们不需要任何”这一步做什么”的判断。所有复杂度都集中在 NORMAL 分支。

PROMPT 分支还有一条隐含语义：即使 waiting 为空，它也要返回一个空的 SchedulerOutputs，而不是 nullptr。因为它的调用方——PE 的主循环——需要一个统一的”SchedulerOutputs 结构”来做后续处理；返回 nullptr 会让上层走到”转 decode”的逻辑，而 PE 根本没有 decode 通道。这一条在下文 4.2 节会对比 NORMAL 的空手返回。

4.2 _schedule_prefill 的收口

_schedule_prefill 的尾部有两处角色判断：

1
// ... 逐条从 waiting 里挑请求 ...
2
if (is_chunked && engine_type == EngineType::NORMAL) {
3
    break;
4
}
5

6
if (engine_type != EngineType::NORMAL || !scheduled.empty() || !ignored_seqs.empty()) {
7
    return _make_outputs(std::move(scheduled), true, num_batched_tokens, {}, std::move(ignored_seqs), std::move(seqlens_q), 0);
8
}
9

10
// NORMAL 引擎且本轮没有调度到任何 prompt，交由 _schedule 决定是否转为 decode
11
return nullptr;

第一处 break 的含义是：NORMAL 引擎在开分块预填充时，一旦挑中一条分了块的请求，就停止继续挑选，把本步的 token 预算留给定块。原因是 NORMAL 引擎的 prefill 步之后紧接的就是 decode 步，如果一步放进去太多分块请求，本步的时间会显著变长，后面等待 decode 的请求全部被拖慢；相比之下，PE 引擎可以一路挑完，因为它不需要为这一步的后续 decode 让步。

第二处是返回值语义的分叉：

PROMPT 能返回空的 prompt_run 结果，依赖 step() 里对空步的处理：is_placeholder 路径会用 _placeholder_seq_metadata(is_prompt) 拼一个占位 meta，让 Worker 侧执行一次”空前向”。所以 PE 的每一拍都有一次前向，哪怕什么都没排到。这是有意的：PE 的主循环被设计成固定节拍，空拍前向的结果会被丢弃，但保证了 PE 的 CPU 侧与 GPU 侧的节拍对齐。

4.3 NORMAL 引擎的 DP 投票

NORMAL 分支是整个调度器最绕的部分。关键前提是 NORMAL 引擎的 DP 组内所有 rank 必须一起走同一个步型（都做 prefill 或都做 decode）。这和 vLLM、SGLang 不一样——那两家的 DP 副本各自独立调度，一个 rank 做 prefill 时另一个 rank 可以做 decode。DeepInfer 之所以要求步型一致，是因为它的 DP Attention 和 MoE EP 共用同一组集合通信（详见 DeepInfer 源码拆解（十三）：DP Attention 与 Wide-EP），MoE 层的 All-to-All 需要所有 rank 在同一拍上都有 token 要交换；一个 rank 做 prefill 另一个做 decode 会导致通信域内的形状不一致。

投票逻辑可以拆成两个尝试点：

1
bool is_any_point = (decode_step != 0) && (decode_step % prefill_any_attempt_interval == 0);
2
bool is_all_point = (decode_step % prefill_attempt_interval == 0);
3
if (!is_any_point && !is_all_point) {
4
    return _schedule_decode(acquire);
5
}
6
bool want = (get_gpu_cache_usage() <= GPU_CACHE_PREFILL_WATERMARK) && _has_prefill_waiting();
7
bool do_prefill;
8
if (is_any_point) {
9
    do_prefill = (_dp_allreduce(want ? 0 : 1, c10d::ReduceOp::MIN) == 0); // ANY：任一 rank 想做即触发
10
} else {
11
    do_prefill = (_dp_allreduce(want ? 1 : 0, c10d::ReduceOp::MIN) == 1); // ALL：全员想做才触发
12
}

两个默认间隔来自环境变量：DEEPINFER_PREFILL_ATTEMPT_INTERVAL 默认 70，DEEPINFER_PREFILL_ANY_ATTEMPT_INTERVAL 默认 100。

• ALL 点（每 70 个 decode step 一次）：所有 rank 都有可调度的 prefill 才触发，用 MIN 归约 want ? 1 : 0，只有全组都是 1 才做 prefill。这样避免一个 rank 有活、其余 rank 陪跑空 prefill 步。
• ANY 点（每 100 个 decode step 一次）：任一 rank 有活就全组一起做 prefill，用 MIN 归约 want ? 0 : 1。它的作用是给孤立 rank 兜底：如果某个 rank 的 waiting 队列里只有一条请求，而其余 rank 都没有，ALL 点永远触发不了，这条请求就会无限期饿死。ANY 点保证它最多等 100 个 decode step。

还有第二道投票，处理”想做但排不出”的情况：

1
if (want) {
2
    outputs = _schedule_prefill(acquire);
3
}
4
// 第二轮投票：确认这轮真有 rank 排出了 prefill。
5
bool any_scheduled = (_dp_allreduce(outputs ? 0 : 1, c10d::ReduceOp::MIN) == 0);
6
if (!any_scheduled) {
7
    return _schedule_decode(acquire);
8
}
9
if (outputs) {
10
    return outputs;
11
}
12
// 组内确有 rank 在做 prompt：本 rank 陪跑空 prompt step 保持步型一致
13
return _make_outputs({}, true, 0, {}, {}, {}, 0);

want 只看 waiting 非空和 KV 水位，并不保证 _schedule_prefill 一定能排到（可能 max_num_seqs 满了，也可能 KV 块不够）。因此第一轮投票之后还要再投票一次”本轮全组是否有任何 rank 真的排到了”。如果全组都空手，就必须转 decode；否则会出现死循环——running 满 + waiting 非空，want 恒为真，每一步都空手做 prefill，每个 prefill step 又会把 decode_step 清零，导致下一次又落在 ALL 点……代码里专门留了注释说明这一点。

第二轮投票还有一层含义：如果组内某个 rank 排到了而本 rank 没排到，本 rank 必须陪跑一个空 prefill 步，返回 prompt_run=true 的空 SchedulerOutputs，而不是 nullptr。因为如果返回 nullptr，本 rank 就会转去 decode，与组内其他 rank 的 prefill 步型不一致，MoE 通信域立刻错位。

这三层投票合起来，可以用一张表概括 NORMAL 引擎每一步的决策：

4.4 请求入队时的角色差异

Scheduler::add_sequence 是请求进入等待队列的唯一入口，它内部有一处只在 NORMAL 引擎里生效的预分配：

1
void add_sequence(std::shared_ptr<Sequence> seq) {
2
    seq->request.arrival_time = get_timestamp_ms();
3
    if (engine_type == EngineType::NORMAL) {
4
        seq->reserve_output_tokens();
5
        seq->cache.block_table.reserve(_block_table_capacity(*seq));
6
    }
7
    waiting.push_back(std::move(seq));
8
}

reserve_output_tokens 预先给 token 缓冲预留 max_tokens 的空间，_block_table_capacity 按”整个序列长度 + 最大输出 + 一个块的余量”预留块表容量。两者都是 std::vector::reserve，只申请容量不改变大小。为什么只在 NORMAL 里做？

• NORMAL 引擎的请求从入队到结束一直在同一个调度器里，token 会一个接一个地追加到 input.tokens，块表也会逐块生长；一次性预留够整个生成过程的空间，可以避免 decode 过程中反复 realloc 并暂停调度线程（std::sort/vector 扩容发生在调度临界区内）。
• COMPLETION 引擎的请求是交接进来的，块表在入队时已经被 PE 那边的布局钉过（见 fork_seq 的 pin_blocks），由交接流程决定容量，不是调度器自己从零长起来的。
• PROMPT 引擎的请求在前向完成后就转出去了，它只处理 prompt token，不需要为 max_tokens 预留输出空间。

这条差异很小，却是”同一引擎类、三种角色”设计里最典型的体现：某个优化只在某一角色下成立，就在角色上挂一个 if，而不是复制一份 Scheduler。

4.5 半途接手的序列：fork_seq 与 prompted 队列

CE 接到的请求不是从零开始的 prompt，而是”前缀已经算好、只差继续生成”的序列。调度器里专门有一条入口处理这种序列：

1
SequencePtr fork_seq(const SequencePtr &seq, py::object blocks, std::string &&target_branch_id,
2
    py::object sampling_params, py::object so_matcher, int sp_token, int replace_last_token_id,
3
    int64_t seq_id, double arrival_time) {
4
    TORCH_CHECK(seq->cache.num_tokens > 0, "Cannot fork a sequence without a computed prefix");
5
    TORCH_CHECK(!sampling_params.attr("prompt_logprobs").cast<bool>(), "Forking a cached prefix does not support prompt logprobs");
6
    const bool prompt_incomplete = seq->cache.num_tokens < seq->get_len() - 1;
7
    ...
8
    if (prompt_incomplete) {
9
        waiting.emplace_front(fork_seq);
10
    } else {
11
        prompted.emplace_back(fork_seq, true);
12
    }
13
}

几个细节值得展开。

prompt_incomplete 的判定是 num_tokens < get_len() - 1。 num_tokens 是 KV 已经算到的位置，get_len() 是序列当前 token 总数。如果 num_tokens == get_len() - 1，说明除最后一个 token 之外全部算完——这正好是”预填充完成、第一个输出 token 已由 PE 采样出来”的状态：最后一个 token 就是 PE 采出的首个输出 token，它没有自己的 KV（它刚被生成，还没作为 query 跑过），但它是有效的输入。于是 prompt_incomplete=False，序列进入 prompted 队列而不是 waiting。这与 DeepInfer 源码拆解（三十六）：选行与采样输入 里”prefill 只采最后一行”的设计严丝合缝：PE 只需要为一个位置采样，CE 拿到的就是”前缀 + 首个输出 token”。

prompted 队列在 decode 调度里先于 waiting 被处理。 _schedule_decode 的注释写明”先把 prompted 队列中的 seq 移入 running，再按 LCFS 挑选本轮 decode 的 seq”：

1
// prompted 队列头部的 seq 依次转入 running（或已结束的转入 finished），
2
// forked seq 需要先克隆 state 和最后一个（可能写了一半的）block。
3
while (!prompted.empty() && running.size() < max_seqs) {
4
    auto &&[seq, forked] = prompted.front();
5
    ...
6
    if (forked) {
7
        if ((state_manager && !state_manager->can_allocate_single_nolock()) || !block_manager->can_allocate_single_nolock()) {
8
            break;
9
        }
10
        _clone_state(*seq);
11
        int new_block = block_manager->allocate_single_nolock();
12
        ...
13
    }
14
}

forked=true 的序列在转入 running 之前要做两件事：克隆状态槽（_clone_state）和复制最后一个可能写了一半的块。这两件事与 step() 里 clone_states / clone_blocks 的处理是同一套机制：_schedule_decode 把它们记进 SchedulerOutputs.clone_states 与 clone_blocks，step() 在调度之后、前向之前调用 Worker 的 clone_and_zero_states_and_blocks_on_default_stream 完成设备侧的复制。

blocks 参数允许外部传入块表。 fork_seq 的 blocks 可以是 None（沿用源序列的 block_table），也可以是一个显式的 int 数组。后者正是跨实例交接需要的形状：CE 上的块表由交接协议给定，而不是 CE 自己从零分配。传了 blocks 之后，fork_seq 会 TORCH_CHECK(!init.cache.block_table.empty(), "Cannot fork a sequence without allocated KV blocks")——没有块表就不允许 fork。

需要说明的是，fork_seq 在开源代码里主要服务于同实例内的分支/前缀复用场景（target_branch_id、replace_last_token_id 这些参数都指向分支管理），它并不等同于”P/D 交接协议”。但它是代码里唯一一个”接收已有前缀并把它送进解码队列”的入口，其形状与交接所需完全一致；未开源的 P/D 子类是否直接调用它、还是走一条等价的私有路径，从开源部分无法确认。这也是读这类”接口先行”代码时需要保留的边界：能确认的是结构与不变量，不能确认的是未公开实现的具体调用关系。

4.6 COMPLETION 引擎的一条硬约束

CE 的调度分支虽简单，但构造期有一条必须成立的约束：

1
// COMPLETION engine 没有 prefill 调度通道，无法重算被抢占的请求。启动时拦截，禁止该配置组合
2
TORCH_CHECK(engine_type != EngineType::COMPLETION || stop_preempted_request,
3
    "COMPLETION engine cannot recompute preempted requests (no prefill channel); "
4
    "it must be deployed with stop_preempted_request=true (--stop-preempted-request)");

当 KV 块不足时，调度器会把某个仍在运行的请求抢占。被抢占的请求有两种处理方式：终止（stop_preempted_request=true），或者放回 waiting 队首等待重新 prefill（stop_preempted_request=false）。CE 没有 prefill 通道，第二种方式的请求会永远留在 waiting 里，has_unfinished 恒为真，整个实例就被一条死请求拖住。这也解释了为什么 DeepInfer 的 CE 在线上部署里必须接受”显存不足就终止”的语义。关于抢占之后请求如何回收、取消如何跨实例传播，可以参考横向对比文章 请求的取消与抢占：五个推理框架为什么在同一个「停」字上，走出五条不同的回收路径。

还有一条与 CE 有关的断言写在 LLMEngine.__init__ 里：

1
if self.parallel_config.context_parallel_size > 1:
2
    assert engine_type != EngineType.COMPLETION

CE 不能开上下文并行。原因与 CP 的语义有关：CP 把一个长序列的 attention 切成 zigzag 段分布到多 rank 上，每个 rank 只负责一段，KV 收集由 CP 组的 mirror 布局完成。对预填充来说，这可以显著降低单条长序列的 attention 开销；对解码来说，它不但没有收益，还会在每一拍引入跨 rank 的 KV 收集。而且 CP 的切分粒度是按序列的 token 位置切，解码时一个序列只有 1 个 query token，却要收集所有 rank 上的 KV，代价远大于收益。所以 CE 的角色是”用 Wide-EP 扩大并行、用整序列 KV 做 attention”，与 CP 的定位互斥。

5.1 虚函数清单

LLMEngine 在 init_pd_split 之前定义了一组中文注释为”虚函数”的回调。Python 里没有 virtual 关键字，这里的”虚函数”只是架构约定：一个基类提供空实现或默认实现，生产部署的 LLMEngine 子类（未在开源仓库里）重写它们。清单如下：

表里八条是因为 should_copy_state 和 do_copy_state 配对，do_copy_state 不是虚函数，它是基类提供的一个具体实现，把 seq.state_id 对应的 GPU 状态槽复制到 copy_state 缓冲区。虚函数只决定”要不要复制”，具体怎么复制是基类的事。

5.2 为什么 PE 分成两个钩子

把 PE 的交接拆成 pe_prepare_save_kvcache（采样前）和 pe_do_save_kvcache（采样后）两段，是为了让交接的动作可以跨过采样 kernel。一次 prefill 步的 GPU 侧顺序大致是：

1. 前向：注意力 + MoE + 写出 KV 到设备块表；
2. 采样：对本步挑选的”最后一行” logits 下发采样 kernel，结果要等到事件同步后才可读；
3. 采样结束事件。

pre_sampler_sync 在 2 的 kernel 下发之后、3 之前触发，此时 KV 已经把 1 产出的数据写在设备上，且 copy_state_event（如果记录过）已经同步。PE 可以在这个时点把”要交接的请求”打包、发起 D2G 或远端传输的启动指令——这一步只下发，不等 GPU 计算完。post_process 在 3 之后触发，_post_process_step 先 sample_end_evt.synchronize() 再调用引擎的 post_process_fn，pe_do_save_kvcache 才真正落实交接：等待传输完成、更新请求状态、记录交接的 KV 范围。

这样拆的收益是延迟：采样核本身不大，但 post_process 里的 Python 侧后处理开销不小（_process_model_outputs、RequestOutput 构造、日志），如果整段交接都在采样之后做，PE 的每拍就会有”GPU 等 CPU”的空窗。把交接的启动放进采样同步点之前，就让交接指令的下发与前向、采样在 GPU 上排队执行，而不是等采样同步后 CPU 再一条条发指令。

5.3 decode 侧的 copy_state

do_copy_state 是基类里一个完整的实现：

1
def do_copy_state(self, seqs: list[Sequence]) -> None:
2
    """把给定 seq 当前的 GPU state 拷贝到 copy_state buffer，并更新 last_copy_state_token_idx。
3

4
    该方法仅下发任务到 GPU，不等待完成，消费方需自行同步。
5
    """
6
    if self.copy_state is None:
7
        return
8
    for seq in seqs:
9
        if seq.state_id != -1:
10
            state_id = seq.state_id
11
            self.copy_state[state_id].copy_(self.driver_worker.cache_engine.gpu_states[state_id])
12
            seq.last_copy_state_token_idx = seq.num_cached_tokens

注释里点名”仅下发任务，不等待完成”。对应的同步点在 pre_sampler_sync：

1
if not scheduler_outputs.prompt_run:
2
    if self.copy_state_event is not None:
3
        self.copy_state_event.synchronize()
4
    self.do_save_kvcache(scheduler_outputs.scheduled_seqs, scheduler_outputs.finished_seqs)

也就是说，step() 里记录 copy_state_event，等到下一拍的 pre_sampler_sync 才同步。这样 do_save_kvcache 读到的一定是完整的副本，而不是半拷贝的状态。这个模式与官方文档对 CE 的 SWA KV 复制描述完全一致：每一次请求跨越 128 token 边界时，把当前窗口复制一份到设备侧的副本区；请求结束时，从副本区最近一次完成的拷贝中取存储——拷贝位置最多越过边界 5 个 token，由槽位环形缓冲多出的 6 个位置吸收。源码里的 copy_state / copy_state_event 正是这个”副本区 + 异步拷贝”实现的骨架。

5.4 结束请求的分叉

finalize_seq 的默认实现只有一句 scheduler.free_seq(seq)，但它只在 COMPLETION/NORMAL 引擎里被调用：

1
if self.engine_type in [EngineType.COMPLETION, EngineType.NORMAL]:
2
    for seq in scheduler_outputs.finished_seqs:
3
        self.finalize_seq(seq)

PE 的结束请求不走这里。PE 的请求生命周期终点是”被交接出去”，而不是”完成生成”。PE 的 send_processed_prompts 在 post_process 的末尾被调用——注释是”把已经处理完的 prompt sequence 发送给 completion engine 并从 scheduler 中删除”。这意味着 PE 的请求是被”转走”而不是”释放”：KV 归属从 PE 的调度器转移到 CE 和 KV 存储系统，PE 自己的块表在交接完成后才能回收。

这与 CE 侧形成一条清晰的所有权边界：PE 在请求在途期间持有 KV 块；交接动作成功之后，块的所有权转移到 KV 存储系统或 CE 的块管理器；CE 从等待队列接走请求时，要重新建立自己的块映射。这条边界如果画在虚函数内部，就是 pe_do_save_kvcache 与 finalize_seq 的职责分界。

7.1 显存估算的 profile 形状

WorkerBase.profile_num_available_blocks 会调用 ModelRunner.profile_run(cache_config) 测量峰值显存。profile_run 里有一句：

1
is_prompt = self.parallel_config.engine_type != EngineType.COMPLETION

然后按 is_prompt 走不同的假序列形状：

• PE / NORMAL：按真实的 prefill 形状构造假序列，长队列的 seq_len_q 分布、seq_len_k 从 1 到 max_model_len 不等，让峰值显存覆盖完整的长 prompt 前向；
• CE：每条假序列 seq_len_q = 1 + nextn，seq_len_k = 1 + nextn，seq_data_len = 1。也就是说 CE 的 profile 只测单 token 解码的峰值。

这样测出的峰值决定了 num_gpu_blocks，也就是这台机器能装多少 KV 块。CE 因为前向时激活量小（只有少量 token），可以装更多块；PE 因为激活量大，同一张卡能装的块就少。角色化后同一个模型、同一种硬件，PE 和 CE 算出来的 KV 容量会相差不少——这也是为什么 P/D 分离里 P 和 D 的 GPU 配比不是 1:1 的直接原因之一。

7.2 CUDA Graph 的角色差异

ModelRunner.__init__ 里：

1
self.use_cuda_graph = not envs.DEEPINFER_ENFORCE_EAGER and self.parallel_config.engine_type != EngineType.PROMPT

PROMPT 引擎默认关闭 CUDA Graph。原因在 DeepInfer 源码完全拆解（十二）：CUDA Graph 捕获与重放 里讲过：图捕获的分档是按 batch size 划分的，decode 的 batch size 变化小、形状相对规整，捕获几百张图即可覆盖绝大多数场景；prefill 的”形状”由每条序列的 seq_len_q 分布决定，变化范围大，按批大小分档无法充分覆盖。对 PE 来说，图捕获的收益（把 kernel 调度开销压出去）不足以抵消一次 prefill 本身的计算量与捕获成本。

DFlash（DeepInfer 的投机草稿头）也有类似的角色判断：

1
self.prefill_only = cfg.engine_type == EngineType.PROMPT
2
if self.prefill_only:
3
    logger.info("DFlash prefill_only 模式：只加载 main-cache 路径参数")

草稿头在 PE 里只保留主 KV 的投影参数——因为草稿生成只在 CE 发生，PE 不需要草稿 KV 路径。这一条能直接省显存：DFlash 每层都要多一份草稿 KV 投影权重，prefill_only 模式下这些权重不物化。投机解码在 DeepInfer 里的完整链路可以参考 DeepInfer 源码完全拆解（五）：投机解码。

7.3 MTP 信息池只在 CE 侧构造

ModelRunner.load_model 里：

1
if self.is_driver_worker and self.parallel_config.engine_type != EngineType.PROMPT and self.model.MTP_module is not None:
2
    self.model.MTP_module.init_mtp_info_pool(self.scheduler_config.max_num_seqs)

MTP 信息池是投机解码的槽位分配器：每个请求占用一个槽，存放草稿 token、置信度、接受状态等。PE 不会做投机验证，所以不分配这个池；CE 和 NORMAL 都分配，尺寸是 max_num_seqs。这也是角色差异的显存体现。

7.4 EPLB 重排的时刻

ExpertLoadBalancer 的构造函数接收 is_normal_engine 参数，并据此配置两个开关：

1
self._schedule_rearrangement_after_prefill = is_normal_engine and envs.DEEPINFER_REARRANGE_AFTER_PREFILL_IN_NORMAL_ENGINE
2
self._skip_rearrangement_on_prefill = is_normal_engine and not self._schedule_rearrangement_after_prefill

重排逻辑的核心是：

1
def _update_rearrangement(self, is_prompt: bool) -> None:
2
    if self._rearrangement_interval == 0:
3
        return
4
    if is_prompt and self._skip_rearrangement_on_prefill:
5
        return
6
    ...
7
    if is_prompt and self._schedule_rearrangement_after_prefill:
8
        # 下一个非 prefill step 立即 rearrange。
9
        self._rearrangement_step = self._rearrangement_interval - 1
10
        return
11
    self._rearrangement_step += 1
12
    if self._rearrangement_step < self._rearrangement_interval:
13
        return
14
    self._rearrangement_step = 0
15
    self._rearrange_experts()

对 NORMAL 引擎，prefill 步不走重排计数，默认等到下一个 decode 步再重排；对 PROMPT / COMPLETION，is_normal_engine=False，两个开关都是 False，重排计数在每一步（无论是 prompt 还是 decode）都推进。原因很直接：NORMAL 引擎的 prefill 步通常会改变专家的热度分布（大批 prompt 触发的专家与 decode 触发的专家往往不同），如果在 prefill 步内做重排，会把 prefill 的时间进一步拉长；而 P/D 分离时，PE 和 CE 各自是纯粹的 prefill / decode 引擎，重排按自己的节拍走即可。EPLB 的放置策略参考 DeepInfer 源码完全拆解（四）：MoE 专家并行与 EPLB。

7.5 MoE 与 Engram 的缓冲尺寸

MoE 层与 Engram 层都保存了 engine_type，据此选择缓冲尺寸：

1
self.max_num_tokens = self.max_num_decoding_tokens if self.engine_type == EngineType.COMPLETION else self.max_num_prefilling_tokens

config.py 里的定义是：

1
max_num_decoding_tokens = max_num_seqs * (1 + envs.DEEPINFER_USE_NEXTN_DECODE)
2
return max(max_model_len, 4096, max_num_decoding_tokens)

真正的定义在 model_loader.finalize_model_config 里：

1
model_cfg.gpt.max_num_decoding_tokens = model_cfg.gpt.max_num_seqs * (1 + envs.DEEPINFER_USE_NEXTN_DECODE)
2
model_cfg.gpt.max_num_prefilling_tokens = model_cfg.gpt.max_num_batched_tokens // PG.context_parallel_group().size()

max_num_prefilling_tokens 以 max_num_batched_tokens 为基数（默认至少 max_model_len），再按 CP 组大小整除——开了 CP 之后，一条序列的 prefill token 被切分到多个 CP rank 上，每个 rank 只看自己那一段。max_num_decoding_tokens 则是 max_num_seqs * (1 + nextn)，因为 decode 一步最多处理 max_num_seqs 条序列、每条 1 + nextn 个 token（1 个 query + 最多 nextn 个草稿）。MoE 层的 workspace 不是一次性按角色定死，而是按 input_metadata.is_prompt 在每个批次上二选一：

1
num_max_tokens_per_rank=self.max_num_prefilling_tokens if input_metadata.is_prompt else self.max_num_decoding_tokens,

因此”引擎类型决定缓冲尺寸”这一条，严格说是 NORMAL 引擎里的保守上限——NORMAL 两类批次都会出现，取 prefill 上界；单独的 PE / CE 引擎取各自的上界。MoE 层本身的执行细节参考 DeepInfer 源码拆解（三十五）：MoE 层的 MLP。

7.6 注意力层的融合路径

v4_modules/attn.py 里：

1
self.use_fused_norm_rope_attn_rope_cast = (
2
    ((not envs.DEEPINFER_BATCH_INVARIANT and cfg.engine_type == EngineType.PROMPT) or self.is_sparse or not self.has_packed_kv)
3
    and self.num_heads in (64, 128)
4
    and PLATFORM.is_gpu
5
)

融合 norm-RoPE 的路径只在三种情况之一开启：PE 引擎且非 batch-invariant；或注意力是稀疏的；或没有 packed KV。其中”PE 引擎”这一项的含义是：PE 默认不开 batch-invariant（若开了 DEEPINFER_BATCH_INVARIANT，即便角色是 PE 也要回退到分算路径）。batch-invariant 的推理结果对 batch 组成不敏感，在 Batch-invariant 推理完全拆解 里讲过它的代价是必须在 kernel 层面固定归约顺序；PE 只做前向、不产出用户可见 token，因此默认不需要这条约束，融合 kernel 就可以把 RMSNorm、RoPE 的写回省掉一次。CE 与 NORMAL 引擎只有在该层是稀疏注意力或没有 packed KV 时才例外启用融合。融合 kernel 的实现参考 DeepInfer 源码拆解（三十二）：fused_transform。