# PR #2535 完整报告

- 仓库：`radixark/miles`
- 标题：docs: add Mooncake rollout data transfer guide
- 合并时间：2026-08-21 06:06
- 原文链接：http://prhub.com.cn/radixark/miles/pull/2535

---

# 执行摘要

- 一句话：新增 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 的价值主体。

```bash
# 选择传输协议：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 挂载入口，可对照其导航组织方式。