# PR #2366 完整报告

- 仓库：`radixark/miles`
- 标题：docs: rewrite the fully async page around schedule, data path, eval, and metrics
- 合并时间：2026-08-12 00:41
- 原文链接：http://prhub.com.cn/radixark/miles/pull/2366

---

# 执行摘要

- 一句话：重写 Fully Async 文档，对齐代码并重构四章结构
- 推荐动作：值得精读。该页面现已成为理解 fully async 架构的最完整入口，文档的组织方式（机制 + flag 配对、把评测的两个正交轴拆开、reuse 与 export 分离）有很强的借鉴价值。对使用 fully async 模式的工程师，可直接把文中的 flag 与指标清单当作与代码对照的 checklist；对文档维护者，本 PR 展示了如何系统性地消除文档与代码的漂移。

# 功能与动机

PR body 明确指出页面已与代码脱节："The fully async page had drifted from the code. The sequence diagram showed an enqueue step that no longer exists, 'Tuning knobs' listed --sglang-server-concurrency and --num-steps-per-rollout as fully-async knobs, and nothing shipped since — DataBuffer, the submission scheduler, --async-unused-samples-handler, --async-data-buffer-capacity-factor, --async-max-concurrent-samples — was covered at all." 重写的目标是把文档对齐到 `upstream/main` 的实际实现，并让 knob 紧挨其作用的机制，而不是堆在一个无差别的列表里。

# 实现拆解

1. **页面结构重写**：`docs/user-guide/fully-async.md` 从 "Enable it / Queue model / Tuning knobs / Evaluation" 改为四章——The fully async schedule（持续 worker、提交粒度、driver step 调度、staleness 来源）、Data path（`DataBuffer` 的 `put` / `get` / `get_metrics` 契约、`DefaultDataBuffer` 与 buffer/staleness 相关 flag）、Evaluation（三种后端按 Mode 1/2/3 组织，权重快照的 export 与 reuse 两种模式分节展示）、Metrics（async rollout 指标、async eval 指标与 dashboard 性能分析）。
2. **事实纠错**：删除不存在的 `async/queue_depth`、`async/producer_throughput_qps`、`async/consumer_drain_seconds` 指标，改为 `DefaultDataBuffer.get_metrics()` 实际输出的内容；将 `aborted_groups_recycled` / `stale_groups_recycled` 修正为代码中的 `*_filtered` 命名；移除 `--sglang-server-concurrency` 与 `--num-steps-per-rollout` 两个非 fully-async knob；补充 `--eval-interval` 及 reuse 模式要求的 `eval_interval % save_interval == 0` 硬性约束；注明 staging 目录大小仅适用于 export 模式，因为 `EvalDispatcher._retire` 会跳过 reuse 模式的快照。
3. **序列图重建**：mermaid 图重画，`put()` / `get()` 作为箭头跨越 subgraph 边界——接口在框外、`DefaultDataBuffer` 在框内，直观体现 `--custom-async-data-buffer-path` 的替换点。
4. **导航与链接调整**：`docs/docs.json` 将 `user-guide/fully-async` 从页面列表末尾移到 `argument-groups` 之后；`docs/index.md`、`docs/user-guide/index.md`、`docs/user-guide/usage.md` 同步更新页面名称与描述。
5. **迭代与验证**：第二个 commit 放弃品牌色段落改用 bold（相应放弃 `style.css` 的 `.rx-lead` 类改动），第三个 commit 补充 metric logging hooks 的文档；作者以 `mint dev` 本地渲染并逐一核对锚点与代码路径，`pre-commit run --all-files` 与 `docs.json` 解析均通过。无自动化测试配套（纯文档变更）。

关键文件：
- `docs/user-guide/fully-async.md`（模块 用户指南；类别 docs；类型 documentation）: 核心变更文件，全面重写 fully async 文档为四章结构，修正与代码漂移的序列图、knob 列表、指标命名，并补充 DataBuffer、submission scheduler、eval 硬约束等新内容。
- `docs/docs.json`（模块 站点配置；类别 config；类型 configuration）: 调整 User Guide 侧边栏页面顺序，将 fully-async 移到 argument-groups 之后，是站点导航结构变化的关键配置。
- `docs/user-guide/usage.md`（模块 用法文档；类别 docs；类型 documentation）: 更新 Training Backend 页对 fully async 的入站链接与描述，保证导航文字与页面新定位一致。
- `docs/index.md`（模块 文档首页；类别 docs；类型 documentation）: 首页 Core features 中同步 fully async 的链接文案，保持入口一致性。
- `docs/user-guide/index.md`（模块 指南索引；类别 docs；类型 documentation）: 用户指南索引页更新条目位置与描述，把 fully async 提升为紧邻 Argument Groups 的核心条目。

关键符号：未识别

## 关键源码片段

### `docs/docs.json`

调整 User Guide 侧边栏页面顺序，将 fully-async 移到 argument-groups 之后，是站点导航结构变化的关键配置。

```jsonc
{
  "tab": "User Guide",
  "groups": [
    {
      "group": "User Guide",
      "root": "user-guide/index",
      "pages": [
        "user-guide/concepts",
        "user-guide/argument-groups",
        // fully-async 从列表末尾移到 argument-groups 之后，
        // 与“连续生成解耦训练”的主题定位保持一致。
        "user-guide/fully-async",
        "user-guide/usage",
        "user-guide/training-script-walkthrough",
        "user-guide/monitoring",
        "user-guide/dashboard"
      ]
    }
  ]
}
```

# 评论区精华

该 PR 没有产生任何 review 评论，Shi-Dong 直接 APPROVED。设计取舍主要体现在提交历史中：作者在第二个 commit 主动放弃品牌色段落的 `.rx-lead` CSS 类，改为 bold 强调，避免引入新的样式代码；第三个 commit 又补记了 metric logging hooks 章节。整体属于作者自查自收敛的文档迭代，无公开争议。

- 暂无高价值评论线程

# 风险与影响

- 风险：风险集中在文档与代码的一致性与链接稳定性：1）文档内容以 `upstream/main` 为基准核对，但 rollout 代码仍在演进（`DataBuffer`、submission scheduler 均为较新机制），后续若接口或 flag 变化，本页存在再次漂移风险，建议将文中 flag 与指标清单纳入定期核对流程；2）页面改名（Fully Async Rollout → Fully Async RL）与章节重排可能使仓库外链接失效，仓库内锚点虽已逐一验证，但外部引用无法控制；3）`docs.json` 顺序调整影响侧边栏，若存在依赖旧顺序的缓存或文档快照，可能出现展示偏差。无运行时回归、性能或安全风险。
- 影响：对用户（工程团队）影响较大：fully async 是核心训练模式，重写后的页面首次系统覆盖 `DataBuffer`、提交调度、staleness 与评测模式等真实机制，修正了误导性 knob 与指标，学习与排障路径更清晰。对系统无运行时影响，仅文档站结构与侧边栏顺序变化。对团队的意义在于确立了一种文档范式：机制与配置配对、以代码为唯一事实源，同类页面（如 argument-groups、monitoring）可参照此结构。
- 风险标记：文档与代码同步风险 , 页面改名影响外部链接 , 侧边栏顺序调整 , 无自动化文档校验

# 关联脉络

- PR #2220 Add the GLM-5.2 744B x terminal-bench-2 Daytona example: 重写后的 fully-async.md 将 `examples/experimental/openenv/glm52_tbench2/run_glm5_2_744b_a40b_daytona.py` 列为 16 节点 agentic 端到端示例，两个 PR 直接衔接，同属 fully async 与 agentic rollout 功能线。
- PR #2274 refactor(openenv): move duplicated sandbox helpers into the TB2 recipe: TB2 沙箱辅助函数上收共享 recipe，与 #2220 的 Daytona 示例共同构成文档所述 tbench2 工作负载的基础设施，且本 PR 引用同一示例文件。