Transfer Engine

Mooncake 仓库同时存在经典 Transfer Engine 和 TENT（Transfer Engine Next）。TENT 不是简单增加一种 Transport，而是重构了 Segment 生命周期、运行时调度、拓扑选择、QoS、故障转移和插件体系。 阅读版本： Mooncake commit: 777cc7782417b6e554cf7c2d53210d0d8f89f5cc 一、为什么需要下一代引擎 经典 TE 已经支持 RDMA、TCP、NVLink 和多种硬件，但随着后端增加，TransferEngineImpl + MultiTransport + 各 Transport 容易出现几个问题： Segment 生命周期分散在元数据和后端注册逻辑中； 传输选择主要依赖静态协议与局部规则； 多 rail、拥塞、故障和 QoS 难以统一调度； 不同后端各自维护进度线程和资源模型； 新硬件接入需要理解大量经典内部约定； 请求取消、deadline 和 failover 缺少统一运行时。 TENT 将这些能力上移到 Runtime 层。 二、目录结构 TENT 核心位于： tent/src/runtime/ ├── transfer_engine_impl.cpp ├── segment.cpp ├── segment_manager.cpp ├── segment_registry.cpp ├── segment_tracker.cpp ├── transport_loader.cpp ├── transport_selector.cpp ├── progress_worker.cpp ├── admission_queue.cpp ├── qos_contract.cpp ├── receiver_credit.cpp ├── topology.cpp ├── control_plane.cpp └── proxy_manager.cpp 外围包括： ...

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 的核心抽象不是“远端指针”，而是 Segment + BufferDesc + Metadata。应用注册本地内存后，TE 将地址范围、设备位置和传输协议发布为 Segment 描述，其他节点才能定位并建立连接。 阅读版本： Mooncake commit: 777cc7782417b6e554cf7c2d53210d0d8f89f5cc 一、为什么不能直接发送指针 一个进程中的地址： 0x7f12... 在另一个进程中通常没有意义。即使两台机器都使用相同数值，它们也不指向同一块物理内存。 高性能传输还需要额外信息： 这是 CPU DRAM 还是 GPU VRAM； 对应哪张 GPU； 是否注册成 RDMA MR； rkey 和网卡 endpoint 是什么； 是否能用 NVLink、GPU IPC 或 CXL； 节点当前是否存活； 地址区间是否已经注销。 因此 TE 把地址空间包装成 Segment，并通过元数据服务交换描述。 二、SegmentDesc TransferMetadata::SegmentDesc 是远端发现的中心结构，主要承载： Segment ID Segment 名称 协议或协议集合 本机 RPC / endpoint 信息 BufferDesc 列表 设备与拓扑信息 后端扩展元数据 可以把一个 Segment 理解成某个 TE 实例公开的可传输地址空间： Segment: decode-node-7 ├── Buffer A: CPU metadata pool, protocol=rdma ├── Buffer B: GPU KV pool, protocol=rdma └── Buffer C: GPU KV pool, protocol=hip 同一块 GPU buffer 可以被多个后端注册，从而同时支持： ...

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： ...