RDMA on Hellokitty's Blog

vLLM 与 Mooncake 对接源码解读：Prefill/Decode 分离中的 KV Cache 如何跨节点传输

Mon, 24 Aug 2026 16:58:43 +0800

深入分析 vLLM 内置 MooncakeConnector：从代理拆分请求、Scheduler 元数据、GPU KV Cache 注册，到 Mooncake Transfer Engine 通过 RDMA 将 Prefill KV 直接搬到 Decode 节点。

Mooncake Transfer Engine 源码阅读（三）：RDMA、TCP 与请求完成状态机

Fri, 21 Aug 2026 11:17:00 +0800

Transfer Engine 的公共 API 很统一，但 RDMA 和 TCP 的实现差异很大。RDMA 需要 MR、QP、WR 和 CQ；TCP 需要连接、lane、消息 framing 和接收端主动拷贝。本文沿源码比较两条路径，并分析 Batch 状态如何完成。

阅读版本：

Mooncake commit: 777cc7782417b6e554cf7c2d53210d0d8f89f5cc

一、Transport 抽象

Transport 基类统一定义：

install / uninstall
registerLocalMemory / unregisterLocalMemory
submitTransfer
getTransferStatus
allocateBatchID / freeBatchID

它还定义 TransferRequest、TransferStatus 和内部 BufferEntry。

公共抽象要求每个后端回答三个问题：

本地内存如何准备为可传输状态；
请求怎样排队和执行；
如何查询每个 task 的最终状态和字节数。

具体连接模型不属于公共 API。

二、RDMA 初始化

RDMA 后端主要位于：

rdma_transport.cpp
rdma_context.cpp
rdma_endpoint.cpp
endpoint_store.cpp
worker_pool.cpp

安装阶段通常完成：

枚举 RDMA devices / ports / GID
  -> 创建每张 HCA 的 context
  -> 建立 PD、CQ 等资源
  -> 启动 worker / poller
  -> 发布 NIC endpoint metadata
  -> 准备 endpoint store

Mooncake 支持多 HCA、多端口和 GPU 内存，因此一个逻辑请求可能被切到多个 rail 上并行发送。

Mooncake Transfer Engine 源码阅读（一）：统一传输 API 与整体架构

Fri, 21 Aug 2026 11:15:00 +0800

Mooncake Transfer Engine（简称 TE）是 Mooncake 数据平面的基础组件。它不负责决定 KV Cache 应该放在哪里，而是提供统一接口，把一段本地内存搬到远端 Segment，或者从远端 Segment 读取到本地内存。

本文基于 Mooncake 官方仓库：

commit: 777cc7782417b6e554cf7c2d53210d0d8f89f5cc
commit date: 2026-08-21

当前仓库同时保留经典 Transfer Engine 和下一代 TENT。前三篇先阅读经典实现，第四篇再分析 TENT 如何重构控制面、调度和传输后端。

一、源码布局

核心目录为 mooncake-transfer-engine/：

路径	作用
`include/transfer_engine.h`	对外 C++ API
`include/transfer_engine_impl.h`	经典实现内部接口
`include/transport/transport.h`	Transport 抽象、请求和状态
`include/transfer_metadata.h`	Segment、Buffer 与元数据接口
`src/transfer_engine.cpp`	公共 API 转发层，同时兼容经典 TE 与 TENT
`src/transfer_engine_impl.cpp`	初始化、内存注册、Segment 与批次管理
`src/multi_transport.cpp`	安装和选择具体 Transport
`src/transport/`	RDMA、TCP、NVLink、NVMe-oF、EFA 等后端
`tent/`	Transfer Engine Next 实现

TE 的经典架构可以概括为：

应用 / Mooncake Store
        │
        ▼
TransferEngine
        │
        ▼
TransferEngineImpl
   ┌────┼──────────────┐
   ▼    ▼              ▼
Metadata  MultiTransport  Batch 生命周期
          │
   ┌──────┼───────────────┐
   ▼      ▼       ▼       ▼
  RDMA   TCP    NVLink   NVMe-oF ...

二、公共 API 是一层门面

TransferEngine 类本身很薄，大多数函数转发给 TransferEngineImpl：