GLM-5.3 推理全链路（十三）：PD 分离的控制面——路由、bootstrap 握手、取消与失败在两侧怎么走

SGLang router 先选 P/D，再铸一个 room

SGLang 的 router 在 server/routes/chat/forward.rs 里完成配对。它先选出 prefill 与 decode，然后为这条请求生成一个 BootstrapFields：

1
let pd = decode.map(|decode| {
2
    let bootstrap = BootstrapFields {
3
        host: prefill.bootstrap_host().to_string(),
4
        port: prefill.bootstrap_port(),
5
        room: match prefill_rank {
6
            Some(rank) => generate_room_id_for_rank(rank, prefill.dp_ranks()),
7
            None => generate_room_id(),
8
        },
9
    };
10
    (decode, bootstrap)
11
});

generate_room_id 只取 63 位：

1
pub(super) fn generate_room_id() -> u64 {
2
    rand::random::<u64>() & (i64::MAX as u64)
3
}

这个掩码不是随手写的。room 后面要作为 torch.int64 进入 metadata buffer；如果最高位是 1，Python 侧会把它解释成负数，room 匹配和日志都会出错。generate_room_id_for_rank 则保证 room % dp_ranks == rank：

1
pub(super) fn generate_room_id_for_rank(rank: u32, dp_ranks: u32) -> u64 {
2
    let dp_ranks = u64::from(dp_ranks);
3
    (generate_room_id() >> 1) / dp_ranks * dp_ranks + u64::from(rank)
4
}

这条约束对应 SGLang 的 follow_bootstrap_room 负载均衡策略：decode 侧不额外查询 prefill 的 DP rank，而是直接用 room % dp_ranks 推断“这条请求应该落在哪个 DP rank”。如果 router 选了 rank 3，但 room 算出来是 rank 5，CommonKVSender.__init__ 会直接记一条 follow_bootstrap_room conflict，把 room 标成 Failed，而不是让请求悄悄落到错误的 rank 上。

router 把同一个 room 注入两段请求的 body：

• prefill leg 拿到 bootstrap_host、bootstrap_port、bootstrap_room，prefill 的 tokenizer manager 会把它们挂到 Req 上；
• decode leg 拿到同样的三个字段，decode 的 DecodePreallocQueue 用它们创建 CommonKVReceiver。

prefill 请求不是同步等待 decode 的。spawn_prefill_request 把 prefill leg 放进一个独立 task，decode 则走 admit_decode 的 decode_gate。两段并行推进，但 decode 的响应才是客户端看到的响应。这个结构带来两个控制面细节：

1. prefill 失败要能取消 decode。prefill task 返回错误时，stream_abort.cancel() 会取消 decode 的流；如果 decode 还没出第一个 token，客户端看到的是 prefill 的错误，而不是一个空的 decode 流。
2. decode 准入失败要能取消 prefill。admit_decode 失败时，router 侧持有的 AbortOnDrop 会在 drop 时向 prefill 发 /abort_request，避免 prefill 继续算一条 decode 已经不接受的请求。

AbortOnDrop 的实现很短，但它定义了一条重要的安全边界：

1
pub(super) fn new(
2
    client: &Client,
3
    worker: &Url,
4
    headers: &HeaderMap,
5
    rid: Option<&str>,
6
) -> Self {
7
    Self(rid.filter(|rid| !rid.is_empty()).map(|rid| {
8
        let mut request = client
9
            .post(worker.join("/abort_request").expect("validated worker URL"))
10
            .json(&serde_json::json!({"rid": rid, "abort_all": false}))
11
            .timeout(Duration::from_secs(5));
12
        // ... 透传 Authorization
13
        request
14
    }))
15
}

注释里写着“Only router-minted IDs are safe: the engine aborts by prefix.”SGLang 的 abort_request 用 req.rid.startswith(recv_req.rid) 匹配请求；如果 rid 来自客户端，一个短 rid 可能前缀匹配到别的请求，把无关请求一起 abort。router 自己铸 rid，才能保证前缀匹配是精确的。这个约束在自建网关时经常被忽略：网关把客户端传来的 request_id 直接透传，PD 两侧又都拿它做前缀 abort，结果一次客户端断开可能清掉一整批请求。

vLLM 没有 room：kv_transfer_params 就是控制面

vLLM 不在 router 里铸 room。它的 PD 路由是“两段 HTTP 请求”的编排：

1. 路由器先向 prefill 实例发请求，body 里带 kv_transfer_params: {"do_remote_decode": true}；
2. prefill 正常算完 prompt，request_finished 返回一组 kv_transfer_params，随响应回到路由器；
3. 路由器把同一组参数改写成 do_remote_prefill: true，发给 decode 实例；
4. decode 的调度器看到 do_remote_prefill，走远端 KV 加载路径。

NIXL connector 的 request_finished 里能直接看到这组字段的来源：

1
return delay_free_blocks, dict(
2
    do_remote_prefill=is_p_node,
3
    do_remote_decode=is_d_node,
4
    remote_block_ids=block_ids,
5
    remote_engine_id=self.engine_id,
6
    remote_request_id=request.request_id,
7
    remote_host=self.side_channel_host,
8
    remote_port=self.side_channel_port,
9
    tp_size=self.transfer_tp_size,
10
    dcp_size=self.vllm_config.parallel_config.decode_context_parallel_size,
11
    pp_size=self.vllm_config.parallel_config.pipeline_parallel_size,
12
    remote_num_tokens=remote_num_tokens,
13
    remote_blocks_expiry_time=blocks_expiry_time,
14
    remote_registration_generation=self._registration_generation,
15
    transfer_mode=self._TRANSFER_MODE,
16
)

这里的 remote_block_ids 是按 KV cache group 组织的块号列表；remote_engine_id 用来在 connector 的远端引擎表里找到 NIXL agent；remote_host/remote_port 是 side channel 地址；remote_request_id 是 prefill 侧的请求 id；remote_blocks_expiry_time 是块租约的到期时间。字段名会随 connector 版本变化，但语义稳定：decode 要知道去哪个引擎、哪些块、用什么会话取数据，以及这些块还能活多久。

vLLM 的配对键不是 room，而是 (remote_engine_id, remote_request_id)。prefill 侧 on_new_request 会把 do_remote_prefill 的请求登记到 _heartbeat_req_engine：

1
if params is None or not params.get("do_remote_prefill"):
2
    return
3
remote_engine_id = params.get("remote_engine_id")
4
remote_request_id = params.get("remote_request_id")
5
# ... 校验 host/port/tp_size
6
if remote_engine_id not in self._heartbeat_by_engine:
7
    self._heartbeat_by_engine[remote_engine_id] = HeartbeatInfo(
8
        req_ids=set(), host=host, port=port, tp_size=tp_size, ...
9
    )
10
self._heartbeat_by_engine[remote_engine_id].req_ids.add(remote_request_id)

decode 的调度器心跳会把 req_ids 发给 prefill，prefill 的 worker 收到 HB:req1,req2,... 后延长这些请求的块租约。这个机制解决的是“decode 还在排队，prefill 的块不能提前还给池子”的问题。SGLang 用 room + 每请求状态表解决同一个问题，vLLM 用 engine id + request id + 租约解决。前者的查询是显式的 /route，后者是隐式的“谁持有这个 request id”。

没有独立 room 也意味着没有“room 冲突”这一层保护。如果两个 decode 请求带相同的 remote_engine_id 和 remote_request_id 来拉同一组块，connector 只能靠请求 id 去重；如果路由器重试时复用了同一个 id，prefill 侧可能把第二次请求当成第一次的重复。vLLM 文档要求 decode 请求使用新的 request id，原因就在这里。

路由层最容易被低估的两个错误

第一个错误是把 room 当成可复用的分配槽。SGLang 的 DeferredBootstrap 注释写得很清楚：“A room identifies one request, not a reusable allocation slot.”一个 room 只属于一条请求；请求结束后，prefill 会在 clear() 里把 room 删掉，或者留一个有超时的 tombstone，防止迟到的 decode endpoint 挂到下一条请求上。如果实现把 room 当成固定槽位循环使用，迟到的 BOOTSTRAP 消息会注册到新请求的 room 上，decode 就会把旧请求的地址发给新请求。

第二个错误是在路由层做“前缀 abort”。SGLang 的 abort_request 用 startswith 匹配，vLLM 的 finish_requests 用精确 id。前者要求 rid 全局唯一且由 router 生成，后者要求 abort 的 id 与请求 id 完全一致。把两种语义混在一起，就会出现“取消一条请求，误伤一批请求”或者“取消根本没生效”。

注册：每个 prefill rank 往注册表里填一行

prefill 的 CommonKVManager.register_to_bootstrap() 会向 /route 发 PUT，payload 包含：

1
payload = {
2
    "attn_tp_size": attn_tp[0],
3
    "attn_tp_rank": attn_tp[1],
4
    "attn_cp_size": attn_cp[0],
5
    "attn_cp_rank": attn_cp[1],
6
    "attn_dp_size": self.attn_dp_size,
7
    "attn_dp_rank": self.attn_dp_rank,
8
    "pp_size": self.pp_size,
9
    "pp_rank": self.pp_rank,
10
    "system_dp_size": self.system_dp_size,
11
    "system_dp_rank": self.system_dp_rank,
12
    "rank_ip": self.local_ip,
13
    "rank_port": self.rank_port,
14
    "page_size": self.kv_args.page_size,
15
    "kv_cache_dtype": self.kv_cache_dtype_str,
16
    "kv_layout": self.kv_layout,
17
    "dsv41_spec_layout": self.dsv41_spec_layout,
18
    "load_balance_method": get_parallel().load_balance_method,
19
    "enable_dsa_cache_layer_split": get_parallel().enable_dsa_cache_layer_split,
20
    "enable_kv_cache_sharding": get_parallel().enable_kv_cache_sharding,
21
    "prefill_http_port": get_serving().port,
22
}
23
payload["decode_allocation_policy"] = (
24
    get_disagg().disaggregation_decode_allocation_policy
25
)

这组字段里，rank_ip:rank_port 是数据面的 ZMQ 控制地址，page_size/kv_cache_dtype/kv_layout/dsv41_spec_layout 是兼容性判据，attn_tp/cp/dp/pp 是拓扑坐标，prefill_http_port 是重算/rebootstrap 时回打 prefill HTTP 接口用的。decode_allocation_policy 也会一起登记：bootstrap server 在第一次注册时记下策略，后续注册如果策略不一致，直接返回 400。

bootstrap server 用一张五层嵌套表存这些信息：

1
self.prefill_port_table: Dict[
2
    int, Dict[int, Dict[int, Dict[int, PrefillRankInfo]]]
3
] = {}

维度依次是 DP group、CP rank、TP rank、PP rank。_is_ready() 检查注册数是否达到：

1
expected = self.dp_size * self.attn_cp_size * self.attn_tp_size * self.pp_size
2
return self._registered_count >= expected

这个 expected 是 decode 侧决定“能不能开始握手”的门槛。如果 expected 算错，比如把 system_dp_size 和 attn_dp_size 混用，bootstrap server 会一直返回 503 Prefill server not fully registered yet，decode 的请求全部卡在 Bootstrapping。这类错误在异构 DP/CP 部署里很常见：prefill 是 DP8 + TP1，decode 是 TP8，bootstrap 的 DP group 应该按 system_dp_size 还是 attn_dp_size 取，取决于是否开了 DP Attention。

/route 同时支持 PUT 和 GET。PUT 用来注册；GET 有两种形态：

• 四个 rank 参数都是 -1：返回整台 prefill 的 PrefillServerInfo，用于 decode 第一次接触时的兼容性检查；
• 四个 rank 是具体坐标：返回该 rank 的 rank_ip、rank_port，用于建立具体的数据面连接。

/register_dp_rank 和 /query_dp_ranks 是给非 follow_bootstrap_room 的负载均衡策略用的：decode 的 sender 在创建时把 bootstrap_room -> dp_rank 写进 bootstrap server，prefill 侧后续用 /query_dp_ranks 批量查回。room_to_dp_rank 表有一个后台清理任务，超过 entry_cleanup_interval 的条目会被删掉，避免一张长生命周期的映射表无限增长。

握手：decode 拉地址，prefill 建 sender

decode 的 DecodePreallocQueue._create_receiver_and_enqueue 先创建 CommonKVReceiver，然后在 _init_receiver 里调用 kv_receiver.init(prefill_dp_rank)。init 做四件事：

1. 如果 bootstrap_addr 不在 prefill_info_table，记录失败并返回；
2. 用 /route?prefill_dp_rank=-1&... 拉整台 prefill 的信息，校验 page_size、kv_cache_dtype、kv_layout、dsv41_spec_layout 和 allocation policy；
3. 根据 target_tp_ranks、target_cp_ranks、target_pp_ranks 逐个 /route 拉具体 rank 的地址，建立 bootstrap_infos；
4. 把 decode 的 KV 布局参数注册给 prefill（_register_kv_args），然后按策略决定是直接进入 WaitingForInput，还是先等 prefill 完成。

兼容性校验是硬失败，不是 warning：

1
if info.page_size is not None and info.page_size != self.kv_args.page_size:
2
    raise RuntimeError(
3
        f"Page size mismatch: prefill server has page_size={info.page_size}, "
4
        f"but decode server has page_size={self.kv_args.page_size}. "
5
        f"Both servers must use the same --page-size value."
6
    )

kv_cache_dtype 和 kv_layout 的校验同理。GLM-5.3 的 fp8_ds_mla 布局是 656 字节一行；如果 decode 按 fp8_e4m3 的 576 字节解释，KV 的 K/V 会整体错位。这个错误不会在传输层报错，只会在 decode 输出里表现为胡言乱语。把校验放在握手阶段，是 PD 控制面最重要的一条“尽早失败”原则。

_setup_bootstrap_infos 还有一个容易忽略的细节：它按 target_cp_rank 分组，组内按 target_pp_rank 倒序拉地址。PP 倒序是为了让高 PP rank 先 bootstrap，减少 PP 流水线在握手阶段的空转。bootstrap_infos 里每个条目带一个 is_dummy 标记：MLA 后端下，只有 target_tp_rank 对应的 rank 是真实目标，其余 TP rank 是 dummy，不参与实际写入；非 MLA 后端的所有 TP rank 都是真实目标，因为每个 rank 持有不同的 KV head 切片。

room 的语义：一条请求的临时地址簿

SGLang 的 room 不是 bootstrap server 分配的。router 铸 room，prefill 的 CommonKVSender 和 decode 的 CommonKVReceiver 各自用这个数字建本地状态。bootstrap server 只知道 room -> dp_rank 的临时映射，不知道 room 的完整生命周期。

prefill 侧的 DeferredBootstrap 是 prefill_complete 策略下的 room 表：

1
@dataclass
2
class BootstrapRoom:
3
    owner: object | None = None
4
    endpoint: tuple[str, int] | None = None
5
    ready: bool = False
6
    ready_notified: bool = False
7
    failed: bool = False
8
    expires_at: float = 0.0

五个字段分别表示：谁拥有这个 room（sender 对象）、decode 的控制端点、prefill 是否已经完成、是否已经通知过 decode、是否失败、何时过期。open() 只允许一个 owner；register() 只允许一个 endpoint，第二个不同的 endpoint 会收到 (endpoint, True) 的失败通知；complete() 只在 owner 匹配且未失败时把 ready 置 True；close(success=True) 会删掉 room，让后续请求可以复用同一个数字。

DeferredBootstrap 的注释强调“It performs no I/O, including while holding its lock.”这是为了避免在持锁时向一个已经死掉的 decode 发消息：所有通知都通过 _notify_bootstrap 转成状态消息，在锁外发送。room 表本身只做内存状态，不做网络操作，这样即使 decode 挂掉，prefill 的调度线程也不会被一个阻塞的 socket 卡住。

失败时，room 不会被立即删除，而是留一个有 expires_at 的 tombstone：

1
state.owner = None
2
already_failed = state.failed
3
state.failed = True
4
state.expires_at = time.monotonic() + self.timeout
5
# Retain a bounded tombstone: a late endpoint must not wait forever
6
# or attach to a second request using the same bootstrap room.

这个 tombstone 的寿命是 waiting_timeout + bootstrap_timeout，默认 600 秒。它的作用是接住“取消已经发生，但 decode 的 BOOTSTRAP 消息还在路上”的竞态：迟到的 endpoint 会收到失败通知，而不是挂到一个不存在或已被复用的 room 上。

状态机：KVPoll 的五个值在两侧各是什么意思

SGLang 用同一个 KVPoll 枚举描述 sender 和 receiver，但两侧对同一个值的语义并不完全相同：

1
class KVPoll:
2
    Failed = 0
3
    Bootstrapping = 1
4
    WaitingForInput = 2
5
    Transferring = 3
6
    Success = 4

• Bootstrapping：room 已建立，但还没有拿到对端的完整元数据。decode 侧表示“已分配本地页，正在等 /route/KV args 注册完成”；prefill 侧表示“sender 已创建，正在等 decode 的 metadata”。
• WaitingForInput：decode 侧表示“元数据已发出，等 prefill 算完/发完”；prefill 侧表示“已收到 decode 的 metadata，可以开始 prefill 或发送”。
• Transferring：KV 正在按 chunk 发送。SGLang 的 request_status 用 max(current, status) 推进状态，Transferring 只是中间态；最终的 Success 要等所有 chunk 和所有 rank 都完成。
• Success：所有需要的层/页都到齐，decode 可以把请求放进 waiting queue。
• Failed：任一侧 abort、超时、校验失败或节点死亡。

CommonKVSender.poll() 有一个“结论缓存”：一旦看到 Success 或 Failed，就把 conclude_state 固定下来，后续 poll 不再查表。这个缓存避免了“状态已经 Success，但 room 被清理后查表变成 Failed”的抖动。CommonKVReceiver.poll() 则额外处理 WaitingForInput 的超时：它把 _prefill_wait_start 清零，改用 init_time 重新计时，因为“等 prefill 完成”和“等 KV 到达”是两个不同的阶段，不能共用一个 deadline。

两条准入时间线：early 与 prefill_complete

SGLang 有两个 decode 分配策略，差别就在“decode 什么时候占 57GB”。

early（默认） 的时间线：

1. router 铸 room，prefill 与 decode 两段同时发出；
2. decode 的 DecodePreallocQueue 创建 receiver，init 拉 /route、校验布局、注册 KV args，状态 Bootstrapping；
3. decode 按请求的 token 数计算需要的页，调用 pop_preallocated 分配本地 KV 槽位；分配成功后进入 DecodeTransferQueue，状态 WaitingForInput；
4. decode 的 send_metadata 把页号、aux_index、state indices 发给 prefill 的每个 bootstrap_info；
5. prefill 的 PrefillBootstrapQueue.pop_bootstrapped 看到 WaitingForInput，finalize_bootstrap 分配 metadata buffer、初始化 sender，把请求放进 waiting queue；
6. prefill 开始算 prefill，每算完一个 chunk 就 send_kv_chunk；decode 的 pop_transferred 轮询，直到所有 rank 返回 Success；
7. decode 把请求放进 waiting queue，调度器才允许它进 batch。

early 的关键是第 3 步：decode 在 prefill 还没开始算的时候就把 57GB 的页占住了。对 1M 请求，这意味着 decode 的页池在整段 prefill 时间里都少了一条请求的容量。它的好处是 prefill 一开始算就能往外写，chunk 与传输可以重叠；坏处是长 prefill 会把 decode 的容量按住不放。

prefill_complete 的时间线：

1. prefill 先算 prefill，不等待 decode 的页；optimistic_prefill_attempts 会被自动设成 1，允许 prefill 在没有 bootstrap 完成时先走一次前向；
2. prefill 算完最后一个 chunk，mark_prefill_complete() 把 DeferredBootstrap 的 room 标成 ready，并通过状态消息通知 decode 的 endpoint；
3. decode 收到 WaitingForInput，这时才开始分配本地 KV 槽位、发 metadata；
4. prefill 收到 metadata 后，把已经保留在显存里的 KV 按页发出去；
5. 传输完成，decode 进 batch。

这条时间线把 decode 的容量占用推迟到最后，代价是 prefill 必须把 KV 留在自己的显存里直到 decode 来取，而且 chunk 与传输的重叠消失了。SGLang 的文档明确说它“不是通用的吞吐优化”：它适合“长 prefill 与活跃 decode 争抢 decode 容量”的场景，不适合所有负载。它还要求 Mooncake（RDMA 或 mooncake_tcp）、Python bootstrap registry、attention TP/CP/PP 为 1；这些限制来自 prefill_complete 的实现路径，不是配置上的随意选择。

两条时间线里，PrefillBootstrapQueue 的 max_input_len 都是一道硬门槛：

1
self.max_total_num_tokens = (
2
    self.scheduler.tp_worker.model_runner.effective_logical_max_total_num_tokens
3
    * self.scheduler.kv_shard_widening
4
)
5
self.max_input_len = max_bootstrap_input_len(
6
    capacity=self.max_total_num_tokens,
7
    page_size=self.scheduler.token_to_kv_pool_allocator.page_size,
8
    shard_size=self.scheduler.kv_shard_widening,
9
)

effective_logical_max_total_num_tokens 是 prefill 侧能装下的 token 数；kv_shard_widening 是逻辑页分片因子，开了 KV cache sharding 后每个 rank 只拥有部分逻辑页，容量按 N 倍放大，但准入上限要按最严格的 add_one_req_ignore_eos 路径算。max_bootstrap_input_len 在 shard_size == 1 时直接返回容量；在分片时返回：

1
(capacity - shard_size * page_size - 3) // page_size * page_size

这条公式的意思是：分片模式下每条请求的 prompt 要按页对齐，每个 shard 至少留一页，再加 1 个 new token 和 1 个 spare token。1M 请求如果超过这个上限，_check_if_req_exceed_kv_capacity 会在 bootstrap 之前就 prepare_abort，返回 400，而不是等握手完成才发现装不下。

从 HTTP 到引擎：AbortReq 怎么走

SGLang 的取消入口是 /abort_request，body 是 {"rid": "...", "abort_all": false}。router 的 AbortOnDrop 在 decode 准入失败或客户端断开时发这个请求；引擎的 abort_request 按 rid 前缀匹配，分四条路径处理：

1. waiting queue：直接 pop，_release_aborted_request，如果是 decode 模式还要 release_kv_cache；如果是 prefill 模式，调用 release_aborted_prefill_waiting_req。
2. bootstrap queue：prefill 还没完成握手的请求，sender.abort()，释放 metadata buffer，清掉 pending chunk send。
3. inflight queue：prefill 已经开始发 KV 的请求，sender.abort()；sender 会把 room 标 Failed，并让 transfer worker 在下一个 chunk 出队时跳过。
4. decode 的 prealloc/transfer/retracted queue：prealloc 里的 receiver 直接 abort()；transfer 里的 receiver 如果在 host staging，先 prepare_abort 但不立即释放，等 prefill 停止写；否则 receiver.abort()。

这四个路径的共同点是：先让状态机进入 Failed，再释放本地资源。顺序反了，transfer worker 可能在资源释放后还拿着页号去写。

release_aborted_prefill_waiting_req 是 prefill 侧最完整的清理函数：

1
def release_aborted_prefill_waiting_req(self: Scheduler, req: Req) -> None:
2
    self.clear_pending_chunk_send(req)
3
    sender = getattr(req, "disagg_kv_sender", None)
4
    if sender is not None and hasattr(sender, "abort"):
5
        sender.abort()
6
    maybe_release_metadata_buffer(req, self.req_to_metadata_buffer_idx_allocator)
7
    if req.kv.holds_kv or req.kv.holds_mamba:
8
        release_kv_cache(req, self.tree_cache, checkpoint=False)
9
    req.pending_bootstrap = False

clear_pending_chunk_send 清的是 disagg_prefill_pending_chunk_rids。这个集合记录“已经发出 chunk 但还没收到 last_chunk 确认”的请求；如果不清，它会让 unified memory 的 compaction gate 一直关着。注释里专门写了这个坑：“a stale entry holds the unified-memory compaction gate closed for the process lifetime.”

跨侧通知：ABORT、ABORT_ACK 与 generation

SGLang 的取消不是单向的。decode 的 CommonKVReceiver.abort() 会做两件事：

1. 把本侧 room 标 Failed，记录 failure reason；
2. 向所有 bootstrap_infos 发 ABORT 消息。

ABORT 的 wire format 是：

1
class AbortNotification(msgspec.Struct, frozen=True):
2
    room: int
3
    decode_ip: Optional[str] = None
4
    decode_port: Optional[int] = None
5
    generation: Optional[int] = None

generation 是 decode 侧为这次取消分配的代数。prefill 收到 ABORT 后，把 room 标 Failed，并检查是否需要等传输排空（drain）再回 ABORT_ACK。ABORT_ACK 的格式是：

1
class AbortAck(msgspec.Struct, frozen=True):
2
    room: int
3
    prefill_rank: int
4
    generation: Optional[int] = None

prefill 的 _send_abort_ack 在 _staging_outstanding[room] == 0 时发送，表示“我这个 rank 的上一次传输已经排空，decode 可以安全复用这些页”。decode 的 _deferred_abort_ack_tracker 按 room 记录 generation 和已经 ACK 的 prefill rank 集合；is_abort_release_safe(room, required_acks) 只有在收到足够多的 ACK 后才返回 True。

这层 ACK 机制是为 host destination（staging buffer）准备的。如果 decode 的 KV 目标是 host 内存，prefill 的 RDMA 写可能还在 CPU 侧排队；仅仅把 receiver 标 Failed 并不能证明写已经完成。BaseKVReceiver.is_abort_release_safe 的注释说得很直接：“A failed poll or elapsed timeout alone does not prove the buffers can be reused.”所以 SGLang 引入了 deferred release：abort 后不立即释放 host buffer，等 ACK 或 release timeout。device destination 的路径通常不需要 ACK，因为 CUDA stream 的顺序性可以保证写完才复用。

generation 的另一个作用是防止“旧 ACK 迟到，误放新请求的页”。room 数字可以被复用，但 generation 每次取消递增；prefill 的 ACK 带 generation，decode 的 tracker 只接受当前 generation 的 ACK。没有 generation，一个迟到的 ACK 会让下一条复用同一 room 的请求提前释放页。

vLLM 的取消：finish_requests 与 delay_free_blocks

vLLM 的取消入口在 EngineCore.abort_requests：

1
def abort_requests(self, request_ids: list[str]):
2
    self.scheduler.finish_requests(request_ids, RequestStatus.FINISHED_ABORTED)

finish_requests 的第一遍扫描把请求从 running/waiting 队列移除，第二遍统一设置状态并调用 _free_request。对 PD 最关键的一段是：

1
if request.status == RequestStatus.WAITING_FOR_REMOTE_KVS:
2
    delay_free_blocks = (
3
        request.request_id not in self.finished_recving_kv_req_ids
4
    )
5
    self.finished_recving_kv_req_ids.discard(request.request_id)
6
    self.failed_recving_kv_req_ids.discard(request.request_id)
7
request.status = finished_status
8
self._free_request(request, delay_free_blocks=delay_free_blocks)

如果 decode 请求还在 WAITING_FOR_REMOTE_KVS，而且 connector 还没有报告 finished_recving，delay_free_blocks 为 True，块不会立即还给池子。这个延迟是必要的：prefill 可能还在写这些块，decode 先释放会让下一条请求读到半截 KV。等 worker 的 finished_recving 或 finished_sending 回到 KVConnectorOutput，_update_from_kv_xfer_finished 再释放：

1
for req_id in kv_connector_output.finished_recving or ():
2
    req = self.requests[req_id]
3
    if req.status == RequestStatus.WAITING_FOR_REMOTE_KVS:
4
        self.finished_recving_kv_req_ids.add(req_id)
5
    else:
6
        self._free_blocks(self.requests[req_id])
7
for req_id in kv_connector_output.finished_sending or ():
8
    self._free_blocks(self.requests[req_id])

注意 finished_recving 的两种分支：请求还在等 KV 时，只记 id，不释放；请求已经 finished（客户端取消/超时）时，直接 _free_blocks。这就是 vLLM 的“取消后延迟释放”实现：取消先把请求标成 finished，块留给 connector 的完成回调来释放。

vLLM 的 connector request_finished 还有一条专门的“取消前没来得及调度”的路径。NIXL 的 pull scheduler 里：

1
if params.get("do_remote_prefill"):
2
    # If do_remote_prefill is still True when the request is finished,
3
    # update_state_after_alloc must not have been called ...
4
    self._reqs_need_recv[request.request_id] = (request, [], (), False)
5
    params["do_remote_prefill"] = False
6
    return False, None

这条路径处理的是 decode 请求在调度前就被 abort 的情况：decode 还没有分配本地块，也没有发 metadata；connector 用空的 block_ids 登记一次“接收”，worker 侧会向 prefill 发通知，让 prefill 释放已经保留的块。没有这条路径，prefill 会一直持有这些块直到租约过期。

取消的工程边界：哪些资源必须等，哪些可以立即放

把两侧的取消路径放在一起，可以归纳出三条边界：

• device 页可以立即放，host staging 页要等 drain ACK。device 写有 CUDA stream 顺序，host 写没有；SGLang 的 deferred release 和 vLLM 的 delay_free_blocks 都在处理这条边界。
• metadata buffer 可以立即放，但 transfer 的最后一个 chunk 不能。SGLang 的 clear_pending_chunk_send 会在释放 metadata 之前清掉“已发未确认”的 chunk；vLLM 的 finished_sending 则在 _free_blocks 之前由 connector 统一收口。
• room/request id 不能立即复用。SGLang 的 tombstone 和 generation、vLLM 的 request id 去重，都是为了防止迟到的消息挂到新请求上。

SGLang 的三类失败

第一类：bootstrap 超时。 prefill 的 CommonKVSender._check_bootstrap_timeout 从 init_time 开始计时，默认 300 秒：

1
start = (
2
    self._prefill_complete_time
3
    if self.kv_mgr.defer_decode_allocation
4
    else self.init_time
5
)
6
elapsed = time.time() - start
7
if elapsed < self.kv_mgr.bootstrap_timeout:
8
    return None

超时后，sender 记录 failure reason，把 room 标 Failed。decode 的 CommonKVReceiver._check_waiting_timeout 从 send_metadata 的 init_time 开始计时，也是 300 秒；超时后除了标 Failed，还会主动发 ABORT，让 prefill 停止等待。

这里有两个不同的计时起点，容易混：

• prefill 的 bootstrap timeout 等的是“decode 的 metadata 什么时候到”；
• decode 的 waiting timeout 等的是“prefill 的 KV 什么时候发完”。

early 策略下，这两个阶段是串行的：decode 先发 metadata，prefill 再算 prefill。prefill 的 300 秒覆盖“从 sender 创建到 metadata 到达”；decode 的 300 秒覆盖“从 metadata 发出到 KV 完成”。如果 prefill 的排队时间很长，decode 的 waiting timeout 可能先到，即使 prefill 还没开始算。这就是为什么 SGLang 允许用 SGLANG_DISAGGREGATION_WAITING_TIMEOUT 单独调大 decode 侧的超时。

第二类：prefill 节点死亡。 decode 的 CommonKVManager 启动一个 heartbeat_checker 线程，默认每 5 秒请求一次每个 prefill 的 /health；连续失败 2 次就调用 _handle_node_failure：

1
self.heartbeat_interval = max(
2
    envs.SGLANG_DISAGGREGATION_HEARTBEAT_INTERVAL.get(), 2.0
3
)
4
self.max_failures = max(
5
    envs.SGLANG_DISAGGREGATION_HEARTBEAT_MAX_FAILURE.get(), 1
6
)

失败处理会清掉 connection_pool、prefill_info_table，断开缓存的 ZMQ PUSH socket，然后把 addr_to_rooms_tracker 里属于该 prefill 的所有 room 标 Failed。这个机制只覆盖“bootstrap server 还活着，但 prefill 数据面已经死了”的情况；如果整个 prefill 进程死了，bootstrap server 的 /health 也会失败，decode 会在 2 个心跳周期内发现。

第三类：传输失败。 SGLang 的 transfer worker 在发送 chunk 时检查 room 状态；如果 state 不是 Transferring，就跳过。真正的失败信号来自 poll == KVPoll.Failed：

• prefill 的 handle_inflight_transfer_failure 会调用 sender.failure_exception()，记录异常、abort trace、释放 KV cache，并把请求的 finish reason 设为 FINISH_ABORT（如果之前没有）；
• decode 的 pop_transferred 看到 Failed，调用 _abort_failed_transfer，再 prepare_abort，把请求从 transfer queue 摘掉。

SGLang 还支持可选的 KV checksum：prefill 在 metadata buffer 里写一份 checksum，decode 在 _commit_transfer_to_req 里保存 expected_kv_checksum，进 batch 前再校验。校验失败会走 _handle_kv_checksum_mismatch，把请求 abort。这个功能默认关闭，因为 57GB 的校验本身要读一遍全部 KV，代价不小；但在“传输层没有端到端校验”的 RDMA 环境里，它是唯一能发现静默损坏的手段。

vLLM 的三类失败

第一类：握手/布局不兼容。 NIXL 的握手带一个 compatibility_hash，覆盖 vLLM 版本、模型、dtype、KV cache 布局、attention backend 等。prefill 和 decode 的 hash 不一致时，worker 直接抛 RuntimeError，请求失败。这个检查比 SGLang 的 /route 校验更早：它在数据面连接建立时发生，不需要等到第一页传输。

NixlAgentMetadata 还会校验 engine_id、tp_size、dcp_size、pp_size 和 region_group_ids。如果 decode 的 TP 拓扑与 prefill 的 block 布局不匹配，_validate_remote_parallel_config 会失败。GLM-5.3 的 MLA 在 TP8 下每个 rank 持有完整 KV 头的切片；如果 prefill 是 TP8、decode 是 TP4，block 里的 head 布局对不上，必须拒绝，而不是做隐式重排。

第二类：接收失败。 NIXL worker 的 get_transfer_results 会返回三组信息：

1
return KVConnectorTransferResults(
2
    finished_sending=done_sending,
3
    finished_recving=done_recving,
4
    failed_recving=failed_recv_reqs,
5
)

failed_recving 是“请求级”的失败集合，比 invalid_block_ids 更适合多 KV group 的模型，因为 block id 只在组内唯一。调度器的 _handle_invalid_blocks 会先处理 invalid_block_ids，再处理 failed_recving；失败策略由 kv_load_failure_policy 决定：

1
kv_load_failure_policy: Literal["recompute", "fail"] = "fail"

默认是 fail：请求直接 FINISHED_ERROR，客户端收到错误。recompute 则把 num_computed_tokens 截断到第一个失败块之前，重新调度请求，让 decode 自己重算缺失的块。对 1M 请求，recompute 的代价是重算最多 1M token 的 prefill；但它比重试整条 PD 链路更便宜，因为本地块还在，只是缺了一段远端 KV。

第三类：远端死亡/租约过期。 vLLM 没有 SGLang 那样的 /health 心跳，而是用块租约：prefill 在 request_finished 时给块设置 remote_blocks_expiry_time，decode 的调度器按 _heartbeat_interval = _kv_lease_duration // 6 发心跳；worker 收到 HB:req1,req2,... 后把租约延长 _lease_extension。如果 decode 死了，prefill 的 _reap_expired_send_leases 会在租约到期后释放块，避免 57GB 永久占着。

租约过期后，decode 如果还活着但一直没来拉，会看到 failed_recving 或 invalid_block_ids，请求失败。这个设计的代价是“prefill 可能在 decode 还没开始拉之前就把块放了”；所以 decoder_kv_blocks_ttl 默认 480 秒，比一般的传输时间长得多。对 1M 请求，480 秒的租约足够覆盖排队和传输，但不能覆盖“decode 被上层暂停几分钟”的场景；那种场景需要调大 TTL 或改用 kv_load_failure_policy=recompute。

失败处理的共同原则

两套实现虽然机制不同，但失败处理遵循同一组原则：

1. 失败要在最早的可判定点发生。布局、页大小、TP 拓扑、compatibility hash 都在握手阶段校验，不等到第一页数据。
2. 失败必须同时终止两侧的状态机。SGLang 的 KVPoll.Failed 会被 sender 和 receiver 同时看到；vLLM 的 failed_recving 回到调度器，同时 request_finished 让 connector 清理远端状态。
3. 失败后的页不能立即复用。SGLang 用 tombstone + generation，vLLM 用 delay_free_blocks + finished_sending/recving。
4. 失败要能被上层观察到。SGLang 的 prepare_abort 会把错误写进输出流；vLLM 的 FINISHED_ERROR 带 RequestError。没有可观测性的失败，在下一次请求里会变成“偶发输出错误”。