执行摘要

• 一句话：新增 Mooncake rollout 数据传输指南并挂载文档导航
• 推荐动作：值得快速浏览：对需要启用 Mooncake rollout 数据通道的团队，这是一份可直接执行的操作手册；对文档维护者，其验证流程（逐项核对 CLI 选项、shell 展开后 JSON、Mintlify 结构与导航 JSON）可作为高质量文档 PR 的样板。重点关注两处容易踩坑的细节：环境变量命名差异（示例中的 MOONCAKE_MASTER_ADDR 与真实环境变量 MOONCAKE_MASTER 的区分），以及 CUDA 13 镜像限定。

功能与动机

PR body 明确列出四个目标：document how to enable the Mooncake rollout object-store backend introduced in #591；clarify requirements, endpoint ownership, and the separation from model-weight transfer；provide portable TCP and RDMA configuration plus a complete two-node FSDP example；list the supported Mooncake configuration fields and add the guide to the documentation navigation。背景是 #591 已实现 Mooncake 作为 rollout 传输的可替代后端，但缺少用户文档；同时 rollout 数据传输与模型权重传输是两套独立设置，容易混淆，需要专门页面澄清 endpoint 归属与前置条件。

实现拆解

1. 新增指南文档（docs/advanced/mooncake-rollout-transfer.md，+248 行）：先说明默认使用 Ray object store、Mooncake 可整体替换，并强调 --object-store-backend 与 --update-weight-transfer-mode 分别控制 rollout 数据传输与模型权重传输；随后列出 Requirements（各节点运行相同 Miles/Mooncake 版本、mooncake_master 端点可达、为 global_segment_size / local_buffer_size 预留内存、RDMA 需暴露设备并允许内存锁定），并给出 TCP/RDMA 环境变量与 CLI 参数示例，最后附双节点 FSDP 启动示例与支持的 Mooncake 配置字段清单，以及 CUDA 13 镜像限定说明。
2. 更新导航配置（docs/docs.json，+1 行）：在 Advanced Features > Scale & Reliability 分组中、advanced/p2p-weight-transfer 与 advanced/disaggregated-rollout 之间插入 advanced/mooncake-rollout-transfer，使新页面可在文档站点直接访问。
3. 合入前修正（commit ee16ce9，合入者 Zhichenzzz）：移除指南中过时的 MILES_EXPERIMENTAL_ROLLOUT_REFACTOR 引用，因为 main 上 #2522 已将类式 rollout 设为默认、仅保留 MILES_USE_LEGACY_ROLLOUT_V1 opt-out；同时合并 main 解决导航结构冲突。

配套说明：本 PR 无源码、测试或 CI 变更，仅文档与导航配置；作者验证了每个 CLI 选项与配置键、shell 变量展开后的 JSON、内部链接及 Mintlify tab/fence 结构。

关键文件：

• docs/advanced/mooncake-rollout-transfer.md（模块 进阶文档；类别 docs；类型 documentation）: 核心变更：248 行新指南，说明 Mooncake rollout 后端选择、环境要求、TCP/RDMA 配置、双节点 FSDP 示例与配置字段清单，是全 PR 的价值主体。
• docs/docs.json（模块 导航配置；类别 config；类型 configuration）: 导航配置：将新页面挂载到 Advanced Features > Scale & Reliability 分组，保证文档站点可访问性。

关键符号：未识别

关键源码片段

docs/advanced/mooncake-rollout-transfer.md

核心变更：248 行新指南，说明 Mooncake rollout 后端选择、环境要求、TCP/RDMA 配置、双节点 FSDP 示例与配置字段清单，是全 PR 的价值主体。

# 选择传输协议：TCP 可直接走可路由数据网络；RDMA 还需每节点暴露本地 RDMA 设备。
export MOONCAKE_PROTOCOL="<tcp-or-rdma>"
export MOONCAKE_MASTER_ADDR="<mooncake-master-host>:50051"
​
# RDMA 专用：在启动 Ray 前设置为当前节点的 RDMA 设备名（各节点设备名可不同）
# export MOONCAKE_DEVICE="<local-rdma-device>"
​
# 将 shell 变量注入 Miles 训练命令；JSON 值必须保持为一个 shell 参数：
# --object-store-backend mooncake \
# --mooncake-store-init-kwargs \
# "{\"protocol\":\"${MOONCAKE_PROTOCOL}\",\"master_server_address\":\"${MOONCAKE_MASTER_ADDR}\"}"

评论区精华

该 PR 没有任何 review 评论，Zhichenzzz 直接给出 APPROVED。唯一可见的反馈来自合入前的修正提交 ee16ce9，本质是“文档必须与当前 main 对齐”的约定：commit message 指出 MILES_EXPERIMENTAL_ROLLOUT_REFACTOR 在 main 上已无人读取——#2522 已将类式 rollout 设为默认并改用 MILES_USE_LEGACY_ROLLOUT_V1 opt-out，因此从 walkthrough 的 Ray runtime env 中移除了该变量引用。这体现了文档示例必须与当前实现路径严格同步的维护标准。

• 暂无高价值评论线程

风险与影响

• 风险：整体风险低（纯文档变更），但存在以下具体风险：
  1) 文档与 #591 实现的漂移：--mooncake-store-init-kwargs 字段、MOONCAKE_MASTER 等环境变量后续变化会让指南失效并误导用户；
  2) 外部依赖：mooncake_master 端点由用户自行启动，Miles 不管理其生命周期，文档示例假设端点已可达且节点间网络可路由；
  3) 硬件依赖：RDMA 路径依赖每节点设备暴露、内存锁定与宿主内存预留，不同集群差异较大，通用示例无法覆盖所有情况；
  4) CUDA 版本限定：structured-object wheel 仅随 CUDA 13 镜像提供，CUDA 12 下 mooncake.structured_object_store 导入失败，文档虽已注明但用户混用镜像版本时仍可能踩坑。
  • 影响：影响范围限定在文档站点与使用 Mooncake 的用户群：新增页面进入 Advanced Features > Scale & Reliability 分组，与 pd-disaggregation、p2p-weight-transfer、disaggregated-rollout 并列，完善了数据传输/分解类文档体系；对启用 Mooncake rollout 后端的团队提供了可直接套用的 TCP/RDMA 配置与双节点 FSDP 示例，降低上手成本；对运行时行为零影响，不改变任何默认行为。团队侧收益是形成了一条“先核对实现再写文档”的合入流程。
  • 风险标记：纯文档变更, 文档与 #591 实现需同步维护, 依赖外部 Mooncake 服务, RDMA 硬件依赖

关联脉络

• PR #2651 docs: fix stale paths, flags, env vars and metric names: 同属 docs/advanced 文档维护线，同样强调文档与 main 实现严格对齐；本 PR 合入前也做了类似的过时引用修正。
• PR #2606 update doc & readme: 同样修改 docs/docs.json 导航结构，说明文档新增页面挂载导航的标准配套方式。
• PR #2583 docs(diffusion): latest doc ported from miles diffusion: 同为新增文档并通过 docs/docs.json 挂载入口，可对照其导航组织方式。