# PR #2298 完整报告

- 仓库：`radixark/miles`
- 标题：docs: polish the Quick Start page
- 合并时间：2026-08-11 04:05
- 原文链接：http://prhub.com.cn/radixark/miles/pull/2298

---

# 执行摘要

- 一句话：润色快速上手文档并默认启用 Miles dashboard
- 推荐动作：值得精读。这是一次高质量的文档重构，核心看点包括：把技术解释从操作步骤中剥离并下沉到页面末尾的设计决策、CLI 命令逐 flag 换行的可读性处理、以及 " 先脚本 PR、后文档 PR 叠加 " 的协作流程。对文档维护者而言，Step N 锚点命名与 dashboard 推荐替换是后续写作的规范参考；对功能开发者而言，DASHBOARD_ARGS 的注入方式可以直接复用到其他启动脚本。

# 功能与动机

Issue #2297 对 Quick Start 页面提出 7 条具体建议：把 working 改为 quick、在 start the container 前增加 What you need 与 What you will accomplish 两组列表、两引擎段落不必放在开头、步骤标题改为 Step N 且 CLI 每个 flag 单独一行、保持页面简洁亲切、不要在步骤中解释 flag 而是把技术解释移到页面末尾的 What's happening、What's happening 本身也要简单生动。PR body 明确说明 "No content is lost — everything that was explained before is still explained, just in the right place"，即本次是内容重排而非裁剪。

# 实现拆解

1. **重构页面骨架**：在 `docs/getting-started/quick-start.md` 中把 frontmatter 的 description 从 a working RL training job 改为 a quick RL training job；引言改为 What you need（8 GPU、200 GB 磁盘、Docker）和 What you will accomplish（启动 GRPO 并观察 reward 上升）两个加粗列表，并保留训练其他模型时的 Models 链接指引。
2. **重排操作步骤**：四个小节标题从 `## 1. Start the container` 风格改为 `## Step 1: Start the container` 风格；`docker run` 命令改为每个 flag 单独一行（`--gpus all`、`--ipc=host`、`--shm-size=32g` 等）；Step 2 的三条 `hf download` 命令每行增加行内注释（模型、训练 prompt、eval 基准）；Step 3 的转换命令增加 MODEL_ARGS 注释；正文不再逐 flag 解释，技术细节全部移走。
3. **内容下沉到 What's happening**：把原来散落在步骤里的 docker flags、MODEL_ARGS、launch script 结构、colocation 与 weight-sync 传输、reward 函数、KL 正则、metric 行解释统一收进页面末尾的 What's happening 小节下的 The details behind each step 列表；What's happening 循环描述缩短为四步通俗描述，传输细节并入 colocation bullet；Step 4 的默认行为改写为 A few things it already does for you 列表，并把原 Ray dashboard 观测项替换为 Miles dashboard。
4. **合并脚本变更**：通过 merge 引入 `scripts/run-qwen3-4B.sh` 的改动，新增 `DASHBOARD_ARGS` 参数组（`--use-miles-dashboard`、`--dump-details /root/Qwen3-4B_miles/dump_details`），并在 `ray job submit` 的参数拼接中追加 `${DASHBOARD_ARGS[@]}`，使 Quick Start 启动脚本默认开启 Miles dashboard 遥测。
5. **测试与校验**：PR 测试计划列出三项人工校验——Mintlify 预览渲染（标题、mermaid 图、表格）、确认无其他页面链接到被改名的 `## N.` 锚点、确认命令与 main 一致（含 `model_args_utils.py` 的 MODEL_ARGS 行），未引入新的自动化测试。

关键文件：
- `docs/getting-started/quick-start.md`（模块 快速上手；类别 docs；类型 documentation；符号 What you need, What you will accomplish, Step 1: Start the container, What's happening）: 本次 PR 的核心变更文件，按 Issue #2297 的 7 条建议重构页面结构、步骤命名、内容排布，并引入 Miles dashboard 的观测说明。
- `scripts/run-qwen3-4B.sh`（模块 启动脚本；类别 other；类型 core-logic；符号 DASHBOARD_ARGS）: 通过合并 #2300 分支引入的配套脚本变更，新增 DASHBOARD_ARGS 参数组并在 ray job submit 中追加，使 Quick Start 启动脚本默认启用 Miles dashboard，文档中的观测说明由此落地。

关键符号：DASHBOARD_ARGS

## 关键源码片段

### `scripts/run-qwen3-4B.sh`

通过合并 #2300 分支引入的配套脚本变更，新增 DASHBOARD_ARGS 参数组并在 ray job submit 中追加，使 Quick Start 启动脚本默认启用 Miles dashboard，文档中的观测说明由此落地。

```bash
# 新增 DASHBOARD_ARGS：启用 Miles dashboard 并指定 dump 输出目录，
# 与 PROMETHEUS_ARGS 等参数组并列，便于用户按需裁剪
DASHBOARD_ARGS=(
  --use-miles-dashboard
  --dump-details /root/Qwen3-4B_miles/dump_details
)

# 在 ray job submit 的参数拼接中追加 DASHBOARD_ARGS，
# 使 Quick Start 默认运行即开启遥测采集
ray job submit --address="http://127.0.0.1:8265" \
  ${EVAL_ARGS[@]} \
  ${SGLANG_ARGS[@]} \
  ${PROMETHEUS_ARGS[@]} \
  ${DASHBOARD_ARGS[@]} \
  ${MISC_ARGS[@]}

```

# 评论区精华

> Shi-Dong 在自评中对初稿提出一轮风格收紧："These are not accomplishments. Remove them."（指 What you will accomplish 列表前三条，只保留 Launch a GRPO run and watch the reward climb!），并要求 "Exclamation mark at the end!"、"Add a comment for each line"、"Make it bold"。

> 关于观测入口，Shi-Dong 提出 "Send a new PR to enable Miles dashboard in scripts/run-qwen3-4B.sh, and stack the current PR on top of the new one"，随后通过 merge 引入 dashboard 分支；另一条评论要求 "Replace the command with Miles dashboard"，最终文档以 `python -m miles.dashboard.serve --dump-details ...` 替代了原先的 Ray dashboard 建议。

> Zhichenzzz 提出 "could we also give a FSDP choice for users since now FSDP is supported?"，Shi-Dong 回复 "This is Quick Start and I want to keep the page as clean as possible. But I'll mention in this Step that FSDP is also available"——即保持页面精简，仅在该步骤提及 FSDP 可用（背景是 FSDP 后端已迁出 experimental，见 PR #2272）。

> Zhichenzzz 建议 "maybe put some example figures and curves here?"，Shi-Dong 表示 "I'll have to rerun the QWen example to generate the plots. Will update in a future PR"，该建议留待后续 PR。

> guapisolo 询问 "Shall we add more scripts with dashboards?"，Shi-Dong 回答 "Yes definitely!"，规划未来把 Miles dashboard 推广到更多启动脚本。

- Miles dashboard 接入方式：拆 PR 后叠加 (design): 先合并脚本 PR #2300，再将文档 PR 叠加在其上；最终文档以 `python -m miles.dashboard.serve --dump-details /root/Qwen3-4B_miles/dump_details` 替换了 Ray dashboard 的说明。
- What you will accomplish 列表内容审查 (style): 列表精简为只保留最终的成就描述（Launch a GRPO run and watch the reward climb!），并加感叹号增强感染力。
- 是否在 Quick Start 中提供 FSDP 选项 (question): 保持 Quick Start 简洁，仅在该步骤提及 FSDP 也可用，不展开操作细节。
- 在页面中加入示例图与训练曲线 (docs): 需要重新运行 Qwen3-4B 示例以生成真实曲线图，推迟到未来 PR 补充。
- 是否给更多启动脚本启用 dashboard (design): 确认后续会向更多启动脚本推广 Miles dashboard，本次仅覆盖 Quick Start 的 Qwen3-4B 脚本。

# 风险与影响

- 风险：
 1. **文档锚点变更风险**：所有小节标题从 `## 1./2./...` 改为 `## Step 1:/Step 2:/...`，若站内其他页面或外部链接引用了旧锚点会失效；PR 已自查无页面引用旧锚点，但 Mintlify 搜索索引与缓存可能短暂滞后。
 2. **启动脚本行为变更**：`scripts/run-qwen3-4B.sh` 新增 `--use-miles-dashboard` 与 `--dump-details`，会改变默认运行行为并增加 `dump_details` 目录的落盘数据，对磁盘与 I/O 有额外占用；该脚本同时被启动脚本快照测试覆盖（如 #1901、#1908 引入的测试），本 PR 自身未附测试，依赖 #2300 的验证结果。
 3. **命令一致性风险**：PR 声明命令与 main 一致（含 `MODEL_ARGS_LINE`），但文档中对 `model_args_utils.py` 的调用方式若有变动，需重新核对 `Qwen3-4B` 的 MODEL_ARGS 行。
 4. **文档内容丢失风险**：虽然 PR 声称无内容丢失，但大量文本重排后仍需人工确认 metric 行、reward 函数等关键解释在新位置可被读者找到。
 - 影响：**用户影响**：Quick Start 页面可读性显著提升，首次接触 Miles 的用户可以更快上手，What's happening 末尾的 The details behind each step 为进阶理解提供完整参考；同时 Quick Start 启动脚本默认启用 Miles dashboard，新用户首次运行即可获得可视化遥测，观测体验从 Ray dashboard 迁移到 Miles 自有 dashboard。**系统影响**：启动脚本新增 dashboard 参数，运行时会多写 `dump_details` 目录，磁盘占用小幅增加；其他脚本暂不受影响。**团队影响**：确立了文档与脚本联动的 PR 协作模式（先发脚本 PR，再在其上 stack 文档 PR），并明确后续将向更多脚本推广 dashboard，是 docs 与 dashboard 两条功能线的交汇点。
 - 风险标记：文档锚点重命名 , 启动脚本行为变更 , 无自动化测试覆盖

# 关联脉络

- PR #2300 scripts: enable the Miles dashboard in the quick-start launcher: 本 PR 通过 merge `origin/shi/qwen3-4b-dashboard` 直接吸收了 #2300 的脚本变更，文档中的 Miles dashboard 说明依赖该脚本启用。
- PR #2272 refactor: move the FSDP backend out of experimental: FSDP 后端升级为正式模块是 Zhichenzzz 建议在 Quick Start 中提供 FSDP 选项的背景，Shi-Dong 据此在文档中提及 FSDP 可用。
- PR #2297 Miles docs Quick Start page suggestions: 关联 Issue，本 PR 的全部改动均围绕其 7 条建议展开并显式关闭该 Issue。