PD 分离推理 — Request Routing 内部实现

① Request arrives → Router 选 P：Router/Proxy 挑一个可用 prefill instance（策略由上层决定，vLLM 自身仅暴露 do_remote_decode/do_remote_prefill 两个标志位）。

② P 执行 prefill：跑 full prefill，得到 KV cache blocks，提交 NIXL READ-ready 状态。

③ P 返回 kv_transfer_params：通过 HTTP response 将 P 的 NIXL 侧信道 (host/port/tp_size/engine_id/block 元信息) 给 Proxy。

④ Proxy 选 D 并签发 decode leg：D 端 worker pre-allocates 等量 KV blocks，对 P 发起 RDMA READ。

⑤ D 读取完成后通知 P：P 释放 blocks（lease 到期或 transfer 完成即释放）。

动机：默认 pull 模式下 D 必须主动拉，两侧握手顺序和 watchdog 逻辑复杂；push 让 P 直接 WRITE 到 D 预注册内存，"发送即完成"。

新增 nixl-push-writer 线程：每个 TP rank 起一个 background writer 线程，仅负责 nixl_wrapper.get_new_notifs / make_prepped_xfer / transfer(WRITE)。

Writer-local matching tables 实现两侧顺序无关的 request_id 匹配：_pending_d_registrations（D 侧发来的 PUSH_REG）与 _push_finished_blocks（P 侧 scheduler stage 的 blocks）。时间对齐用 get_base_request_id() 剥离 cmpl-uuid-index 后的 8-hex 随机 suffix。关键：这是 Proxy 给两腿的同一 X-Request-Id 被 input_processor 随机化后的解同步手段

Wire format：D→P 的 PUSH_REG 通过 NIXL notification 发 PUSH_REG:<msgpack>，字段：request_id, decode_engine_id, decode_host, decode_port, decode_tp_size, local_block_ids (per-group), remote_engine_id。

Transfer 流程：

D allocate → stash → worker build_connector_meta → meta.push_registrations
→ writer enqueue PUSH_REG → NIXL send_notif → P writer 收到 → _handle_push_reg_notif
P prefill finish → meta.push_finished_blocks → writer 匹配 → NIXL WRITE → D
→ D 收到 completion notif → update_connector_output(finished_recving) → stop watchdog

Wake model：三个事件源 + 1ms self-poll：① start_load_kv 握手产生新材料；② get_finished 始终唤醒（让 writer drain HB / completion / late PUSH_REG）；③ handshake 完成回调。

设计动机：单一大超时 480s 遇 D crash 保活浪费显存；过短则易误杀排队的 D。解法：lease renewal via heartbeat。

Lease 默认参数：initial lease 30s；heartbeat interval ≈5s（lease_duration//6）；每次续租延长 ≈20s（2/3 lease）；P 校验用 max(old_expiry, now + lease_extension)（never 缩短）。

关键设计：D 端 on_new_request() 从 request 进入 scheduler waiting queue 就开始发 HB，不等被 schedule 执行。所以 prefill 完成时 P blocks 立即进入 "leased" 状态。

HB 基于 request：不是 per-instance，而是 per-request。这样 P 无需知道 "哪个 D 持有我的 blocks"，路由解耦。

Transport：复用 NIXL send_notif/get_new_notifs，后端 IB/RoCE/TCP 自动 fallback。HB 消息格式 HB:<payload>，每个 HB 消息可批量续租同一 P 的所有 in-flight requests。

Proactive handshake：D 发 HB 时若尚未与 P 握手（请求还在排队），就触发 background thread 主动完成握手，加速后续 KV READ。

vLLM 自身不实现 Router，而是提供 Connector / LookupBuffer / Pipe 三层抽象：

• Connector：kv consumer 从 kv producer 拉取 KV caches 的入口。
• LookupBuffer：SQL 语义的 insert（非阻塞）+ drop_select（阻塞）KV cache 缓冲区。
• Pipe：单向 FIFO tensor 传输，send_tensor / recv_tensor。

每个进程一个 connector：Scheduler connector（调度 KV transfer ops）+ Worker connectors（执行 KV transfer ops）。

Connector 实现：NixlConnector、LMCacheConnectorV1、MooncakeConnector、MoRIIOConnector、MultiConnector、OffloadingConnector、FlexKVConnectorV1。

两种入口：

• Dynamo-native Frontend routing：client → Frontend → Router → workers，无需外部 gateway。
• Gateway API routing with GAIE：client → Gateway → EPP (Endpoint Picker Plugin) → Frontend sidecar (router-mode direct) → workers。

Router 决策基于 worker load + KV cache overlap（KV-aware routing），消除冗余 prefill 计算。

• Rust 写性能关键路径，Python 写扩展性。
• KVBM 在 SGLang 后端仍在开发（README 表格中 SGLang 列 🚧，TRT-LLM/vLLM 列 ✅）。
• 1.0 新增：Zero-config deploy (DGDR)、Agentic inference (per-request hints)、Multimodal E/P/D、K8s Inference Gateway plugin、Storage-tier KV offload (S3/Azure)。
• Day-0 Nemotron 3 Ultra recipes 已合 main，含 KV-aware routing + MTP + disaggregated prefill/decode。

启动命令：

# P 端
python -m sglang.launch_server --model-path ... --disaggregation-mode prefill --port 30000
# D 端
python -m sglang.launch_server --model-path ... --disaggregation-mode decode --port 30001
# Router
python -m sglang_router.launch_router --pd-disaggregation \
  --prefill http://127.0.0.1:30000 --decode http://127.0.0.1:30001 --host 0.0.0.0 --port 8000

Router 把请求先送 P，P 完成 prefill 后把 transfer_info 给 Router，Router 再送 D。

四个阶段：

1. Bootstrap Queue
   a. 为每个 request 初始化 sender
   b. 用 queue 存储 bootstrap 未完成的 requests
   c. poll senders 检查 bootstrap 状态
   d. bootstrap 完成后移到 Waiting Queue

2. Waiting Queue
   a. PrefillAdder pop requests
   b. 跑 forward
   c. 移到 Inflight Queue

3. Inflight Queue
   a. 非阻塞 poll sender
   b. transfer 完成后 return request

Sender 通过 bootstrap_room 与 D 端 receiver 握手，bootstrap_addr 是 P 端的 HTTP bootstrap server 地址。

四个阶段：

1. PreallocQueue
   a. 为每个 request 初始化 receiver
   b. request 先 handshake，有可用 KV 时 pre-allocate
   c. 移到 TransferQueue

2. TransferQueue
   a. poll receiver 检查 transfer 状态
   b. transfer 完成后移到 waiting queue

3. WaitingQueue
   a. 用 queue 中的 requests 构造 PrebuiltExtendBatch
   b. 跳过 prefill forward，只填充 metadata

4. RunningBatch
   a. 把 PrebuiltExtendBatch 合并进 running batch 跑 decoding

关键：D 端 跳过 prefill forward，直接用 P 端传来的 KV 构造 PrebuiltExtendBatch，省掉 prefill 计算。

CommonKVBootstrapServer：只在 P 端启动，HTTP 服务，D 端 receiver 通过它发现 P 端 sender。

CommonKVManager：每个 TP rank 一个，bind ZMQ PULL socket，管理 request_status / socket_cache / failure_records。

CommonKVSender.init(num_kv_indices, aux_index)：设置本地 request 的 index metadata。

CommonKVSender.send(kv_indices, state_indices)：把指定 indices 的 KV cache 推到 D 端。

CommonKVSender.poll()：检查 transfer 状态，返回 KVPoll (Failed/Bootstrapping/WaitingForInput/Transferring/Success)。

DP attention 下的 prefill dp_rank 注册：_register_prefill_dp_rank() 把 P 端的 dp_rank 注册到 bootstrap server，D 端据此选择正确的 P rank。follow_bootstrap_room 模式用 bootstrap_room % dp_size 决定。

2717 行，核心：

• _KVXferMemSegment：描述 VRAM/DRAM 内存段。
• _normalize_kv_mem_kinds / _pack_kv_mem_kinds：支持 VRAM + DRAM 混合 KV 内存。
• NIXL 错误处理：nixlRemoteDisconnectError / nixlBackendError / nixlCancelledError 统一捕获。
• Staging buffer 支持：异构 TP 时 P 端 gather KV head slices → contiguous buffer → bulk RDMA → D 端 scatter，2-5x 吞吐提升。

TransferInfo 结构：

@dataclasses.dataclass
class TransferInfo:
    room: int
    endpoint: str
    dst_port: int
    mooncake_session_id: str
    dst_kv_indices: npt.NDArray[np.int32]
    dst_aux_index: int
    dst_state_indices: List[List[int]]
    required_dst_info_num: int
    is_dummy: bool
    decode_prefix_len: Optional[int] = None
    staging: Optional[StagingTransferInfo] = None

Mooncake 用 mooncake_session_id 标识 session，支持 SGLANG_MOONCAKE_CUSTOM_MEM_POOL 环境变量选择 NVLINK / INTRA_NODE_NVLINK / BAREX 模式。

DecodeHiCachePreallocMixin / DecodeHiCacheTransferMixin：D 端 mixin，支持从 P 端恢复 KV cache 时做 prefix match。

HiCacheRestoreGatedKVReceiver：带门控的 KV receiver，restore 失败时回退到本地重 prefill。

DecodePrefixMatch：在 D 端 radix cache 中匹配已有 prefix，减少需要传输的 KV 量。

sgl_router --pd-disaggregation --prefill <urls> --decode <urls>

Router 把请求先送 P，P 完成 prefill 后把 transfer_info 给 Router，Router 再送 D。

环境变量：

• SGLANG_DISAGGREGATION_THREAD_POOL_SIZE：每 TP rank 的 KV transfer 线程数（默认 0.75*cpu_count/8，限制 4-12）。
• SGLANG_DISAGGREGATION_QUEUE_SIZE：并行 transfer 队列数（默认 4），多 D 请求共享带宽。
• SGLANG_DISAGGREGATION_BOOTSTRAP_TIMEOUT：bootstrap 超时（默认 300s）。
• SGLANG_DISAGGREGATION_HEARTBEAT_INTERVAL / MAX_FAILURE：D→P 心跳（默认 5s / 2 次失败标记 offline）。

vLLM Instance(s)
     |
     | ZMQ (tcp)
     v
MessageQueueServer (mq.py)
     |
     | dispatch by RequestType
     v
MPCacheServer (server.py)
     |
     |--- TokenHasher / SessionManager
     |
     v
StorageManager (distributed/storage_manager.py)
     |
     |--- L1Manager (l1_manager.py)
     |       |--- L1MemoryManager (CPU DRAM) or
     |       |    GDSL1MemoryManager (NVMe slab via cuFile / hipFile)
     |       |--- TTLLock per object (read/write)
     |
     |--- StoreController  -----> L2 Adapter(s) (async L1->L2 push)
     |--- PrefetchController ---> L2 Adapter(s) (async L2->L1 load)
     |--- EvictionController ----> L1Manager (watermark-triggered eviction)
     |
     v
EventBus + OTel providers (observability)

Server 入口：lmcache server（推荐，ZMQ + FastAPI HTTP frontend）或 python3 -m lmcache.v1.multiprocess.server（legacy）。

最小部署 5 个进程：

• Prefill vLLM (producer)：MultiConnector[NixlConnector (kv_producer), LMCacheMPConnector]
• Decode vLLM (consumer)：MultiConnector[NixlConnector (kv_consumer), LMCacheMPConnector]
• Two LMCache servers：每个 vLLM 实例一个（不能共享）
• Router：vllm-router --vllm-pd-disaggregation

KV source order on prefill path：本地 GPU cache → LMCache → recompute。

配置：

--kv-transfer-config '{"kv_connector":"MultiConnector","kv_role":"kv_both",
  "kv_connector_extra_config":{"connectors":[
    {"kv_connector":"NixlConnector","kv_role":"kv_both"},
    {"kv_connector":"LMCacheMPConnector","kv_role":"kv_both"}]}}'

关键 PR：vllm-project/vllm#46865（MultiConnector real-blocks fix）是 LMCache offload 的前置条件。

问题：多节点部署时，每个节点独立缓存，相同 prefix 在不同节点需重复 prefill。

解法：P2P 把 per-node caches 变成逻辑上的一个 cache。

三组件：

• Coordinator：一个小型 HTTP 服务（每个 deployment 一个），跟踪 LMCache server 的存活。
• LMCache server：每个 server 的 P2P controller 定期从 coordinator 获取 peer list，为每个 live peer 开连接。
• Transfer channel：RDMA 层，每个 server 启动时注册 L1 buffer，peers 可直接 read。

流程：cache miss → 向拥有 prefix 的 peer 请求 lock-and-locate → 拿到远端地址 → RDMA read 到本地 L1 → 服务请求。

特点：one-sided RDMA read，拥有数据的 node 不被中断；peer 自动发现/断开。

vLLM ↔ LMCache 用 ZMQ DEALER/ROUTER 模式通信。

RequestType 枚举：

Transfer mode：--supported-transfer-mode 可选 lmcache_driven / engine_driven / auto（默认）。

• Mooncake Transfer Engine：Moonshot AI 开源的 KV cache 传输引擎，支持 RDMA / NVLink / TCP。
• SGLang 集成：--disaggregation-transfer-backend mooncake，环境变量 MOONCAKE_TE_META_DATA_SERVER / MOONCAKE_MASTER / MOONCAKE_PROTOCOL / MOONCAKE_GLOBAL_SEGMENT_SIZE。
• vLLM 集成：MooncakeConnector / MooncakeStoreConnector，见 docs/features/disagg_prefill.md。
• NVLink 模式：SGLANG_MOONCAKE_CUSTOM_MEM_POOL=NVLINK + MC_FORCE_MNNVL=True（NVL72 推荐）。
• Intra-Node NVLink：SGLANG_MOONCAKE_CUSTOM_MEM_POOL=INTRA_NODE_NVLINK + MC_INTRANODE_NVLINK=true（A100/H20/H100）。
• Global multimodal embedding cache：SGLang EPD 模式下，encoder 可把 ViT embeddings 存到 Mooncake 全局缓存，重复 image 直接复用。

所有原始资料保存在 /Users/backyes/work/claude_workspace/pd_routing_research/：

• vllm_nixl_kv_push_connector.txt — vLLM push 模式设计文档
• vllm_nixl_kv_cache_lease.txt — vLLM lease 机制设计文档
• vllm_disagg_prefill.md — vLLM PD 分离抽象层
• dynamo_readme.txt — NVIDIA Dynamo README
• sglang_pd_disaggregation.mdx — SGLang PD 用户文档
• lmcache_mp_index.rst — LMCache MP 模式架构
• lmcache_mp_disagg.rst — LMCache MP PD 分离
• lmcache_p2p.rst — LMCache P2P KV 共享
• lmcache_nixl_1p1d.rst — LMCache 1P1D 示例
• url_status.md — URL 访问状态