我之前在 verl 里见过两种 vLLM offload 级别，后来又接触到 vLLM 的 KV offloading。再往 Mooncake 看，项目里似乎已经有 GDS。于是看到 vLLM Issue #48504 还要做 “GDS + KV offloading” 时，一个很自然的困惑出现了：这些机制是不是在重复做同一件事？

真正需要拆开的不是两个实现，而是三种不同的 offload 语义，以及两类不同的 GPU Direct。本文沿着实际数据路径，解释当前 vLLM 会自动做什么、Mooncake 怎样通过 Connector、Store 与 Transfer Engine 的解耦透明接入 GDS，以及 #48504 为什么仍然有独立价值。

最初的问题很直接：Mooncake 管理 KV Cache，那么“KV Cache 的元数据”能否选择放在内存或 SSD？继续追问后才发现，元数据这个词把几种完全不同的东西揉在了一起：PagedAttention 的 Block Table、Master 保存的全局副本目录、SSD backend 保存的文件位置索引，以及为了故障恢复生成的 snapshot。

只有先回答“哪一种元数据真正负责定位 KV Cache 数据页”，才有可能讨论它应该放在哪里。本文基于 Mooncake 固定版本 0518784d，沿代码中的两级定位链路展开，再解释 Master snapshot 如何以较短在线停顿保存控制面状态，以及它为什么不能替代 KV payload 的持久化。

我最开始想确认的是一个很具体的问题：Mooncake Classic TE 和 TENT 打开的究竟都是文件系统普通文件，还是也能把 /dev/nvme0n1 这样的 SSD 裸块设备交给 GDS？源码里两边都会调用 open(path, O_DIRECT)，NVIDIA cuFile 又确实接受 device fd，看起来答案应该是“可以”。继续向上追到 Segment 层后，结论却发生了分叉。

这篇文章把这条调用链从头串起来：先解释普通文件、块设备、S_ISREG 与 S_ISBLK，再看 GDS 提供了什么 API、Mooncake 实际用了什么，最后落到 cuFileBatchIOSubmit 的同一组参数为什么在两个场景里具有不同含义。核心判断是：GDS 统一了 I/O 接口，却没有替 Mooncake 补上块设备的容量、对齐、越界和独占语义。

看到“应用必须持有 Transport*”时，我真正卡住的是：持有到底是什么意思？为什么直接保存一个后端指针就能工作，统一的 TransferEngine 反而走不通？

把这个词拆开后，Classic 与 TENT 的差异就不再只是两套接口。Classic 的公共 Batch 先于后端选择而创建，后端私有状态缺少稳定的安放位置；TENT 则在选定后端后，为每个 transport 创建独立 SubBatch，再由统一运行时协调提交、状态与回收。

因此，判断一个 Engine 是否容易扩展多个后端，不能只数有多少个 Transport 子类。真正要问的是：后端的私有状态放在哪里，由谁创建，又由谁保证它完成整个异步生命周期。

在分析 Mooncake 的 NDS 接入位置时，经典 NVMeoFTransport 很容易被误认为 TENT GdsTransport 的前一版：二者都注册 buffer 和文件 handle，都使用 cuFile Batch API，也都维护异步完成事件。

但这条旧路径真正特殊的地方不在 cuFile，而在 Batch 所有权。可运行的调用必须直接持有 Transport*，并始终走 xport->allocateBatchID → xport->submitTransfer → xport->getTransferStatus → xport->freeBatchID。一旦换成 engine->allocateBatchID → engine->submitTransfer，批次便由 MultiTransport 创建，NVMeoFTransport 无法附加私有 descriptor，最终返回 NotImplemented。

本文把这条旧路径单独展开：先给出从 NVMe-oF 挂载到专用测试的 SOP，再画出可运行路径与断路分支，最后按执行顺序逐句解释 Batch 分配、请求切片、cuFile 提交、完成事件聚合与资源回收。

上一篇文章从 FAST’25 论文出发，解释了 P/D 解耦、分布式 KV Cache 与调度机制。论文读懂以后，打开代码仓却很容易再次迷路：Connector、Mooncake Store、Transfer Engine、TENT 看起来像四个并列组件，实际却跨越 vLLM 与 Mooncake 两个仓库，并分别承担框架适配、对象管理、字节搬运和新传输内核。

本文固定在 Mooncake 6a00c353 与 vLLM 5bbc58c0，从仓库结构、请求流、时序和关键类关系重新组织这些概念，最后给出一套可重复的源码走读与开发 SOP。

上一篇文章把 TENT 的请求路径压缩成了一串箭头。那串箭头没有错，但它隐藏了代码走读时最容易断掉的几处连接：公共 Request 在哪里变成 TaskInfo，为什么 selector 会返回 GDS，一个逻辑 task 怎样展开成多个 cuFile slice，以及完成事件怎样重新聚合成公共状态。

本文固定在 Mooncake 提交 89da2c3a，只追踪一次成功的 GDS 读取。每个关键节点都给出实际会执行的 C++ 片段；代码语句保持原样，只增加中文走读注释和明确的省略标记。

一开始我只知道一件事：Mooncake 通过 TENT 接入了 NVIDIA GPUDirect Storage。真正沿代码往下追时，三个问题很快连在了一起：TENT 到底怎样调度一次传输，GDS 向上提供了哪些能力，以及新后端怎样实现同一套契约。

最关键的判断是：TENT 不是 GDS 的一层薄封装，而是负责 Segment、内存注册、后端选择、批次和状态推进的统一运行时；GdsTransport 才负责把 File Segment 请求翻译成 cuFile Batch I/O。 理清这条分工后，submitTransferTasks、cuFileBatchIOGetStatus 和新后端接口会自然落在同一张图里。

手里已经有一套面向 NPU 的 NDS send/receive 接口，下一步是把它接入 Mooncake。乍看之下，这只是把 GDS 的 cuFile* 调用替换为 NDS API；但沿源码真正走一遍后，会遇到两个容易误判的事实：Mooncake 同时保留了新旧两代 GDS 路径，而 Mooncake Store 的磁盘副本读写目前又绕开了它们。

因此，接入点不应先选旧 NVMeoFTransport，也不能只新增一个 transport 就宣称 Store 已经获得 NPU 直读 SSD。更稳妥的路径是：先把 NDS 实现为 TENT 的 NdsTransport，复用其选择、批次、状态与回退机制；再单独改造 Store 的文件副本路径。

我看到 Mooncake 为 Ascend 提供了三个编译开关：USE_ASCEND、USE_ASCEND_DIRECT 和 USE_UBSHMEM。最直接的问题是：它们是不是三套并列的通信 engine？特别是后两个名字里已经有 Direct 和 SHMEM，是否意味着数据传输已经由 AIV 直驱？

沿着合入 PR 和源码调用链看下去，答案逐渐清楚：这不是三套同层方案，而是 Mooncake 先后解决“能传”“通用地传”和“把远端内存映射后再传”三个问题留下的三条路径。更重要的是，按当前可见源码，三者都不能直接称为 AIV 直驱。