# PR #2537 完整报告

- 仓库：`radixark/miles`
- 标题：docs: quick-start pre-flight checks, disk sizing, and honest timing
- 合并时间：2026-08-14 12:37
- 原文链接：http://prhub.com.cn/radixark/miles/pull/2537

---

# 执行摘要

- 一句话：quick-start 补预检命令、磁盘要求升 500 GB、时间表述改诚实
- 推荐动作：值得快速阅读，可作为文档改进范例——特别是磁盘空间计算的理由（fp32 master weights + moments ≈ 12 bytes/param）值得在后续模型训练文档中复用。无需精读代码，因为不涉及任何实现逻辑。

# 功能与动机

issue #2532 提出三项改进：
1. 增加 pre-flight 检查命令；
2. 提高 Qwen 任务的磁盘空间要求；
3. 澄清标题表述，让用户明白是“1 小时内开始运行”而非“1 小时内完成训练”。PR body 进一步解释了磁盘计算逻辑：Adam 加分布式优化器下，4B 模型单个 checkpoint 约 50 GB（fp32 主权重加两个 fp32 动量约 12 bytes/param，另加 bf16 权重），每 20 个 rollout 保存一次，长时间运行会远超 200 GB。

# 实现拆解

1. **更新 quick-start 描述与磁盘要求**：在 `docs/getting-started/quick-start.md` 中将 description 改为“Get an RL training job up and running in under an hour”，去掉模型名限定与“finish”歧义；磁盘要求从“Roughly 200 GB”改为“At least 500 GB”。

2. **新增 Pre-flight checks 命令块**：在“What you need”之后插入三行 bash 检查命令，分别验证 GPU 驱动（`nvidia-smi -L`）、Docker 能否透传 GPU（`docker run --rm --gpus all ubuntu nvidia-smi`）、以及 Docker 根目录分区剩余空间（`df -h $(docker info -f '{{.DockerRootDir}}')`），每条命令都配注释说明目的。

3. **补充“What you will accomplish”措辞**：明确是“Launch a GRPO run on Qwen3-4B”，并引导不同模型用户去 Models 页面；对应调整来自作者自查评论（在正文明确提及 Qwen3-4B）。

4. **同步首页入口描述**：在 `docs/index.md` 的“Start here”部分，将 Quick Start 链接描述改为“a training job up and running in under an hour”，与 quick-start 页保持一致，消除“完成训练”的误导。

5. **测试与审查配套**：无自动化测试，测试计划为 Mintlify 预览渲染检查和命令实机验证；作者提交了 3 条自查评论后通过第二个 commit 完成文案精简。

关键文件：
- `docs/getting-started/quick-start.md`（模块 快速入门；类别 docs；类型 documentation）: 核心改动文件：新增 pre-flight 检查命令块、磁盘要求从 200 GB 提升到 500 GB、description 措辞改为诚实的“启动任务”表述，并补充了模型引用。
- `docs/index.md`（模块 首页文档；类别 docs；类型 documentation）: 同步首页“Start here”入口描述，避免“一小时内跑通”的歧义，确保文档口径一致。

关键符号：未识别

## 关键源码片段

### `docs/getting-started/quick-start.md`

核心改动文件：新增 pre-flight 检查命令块、磁盘要求从 200 GB 提升到 500 GB、description 措辞改为诚实的“启动任务”表述，并补充了模型引用。

**What you need**

- A node with 8 GPUs (H100 / H200 / B-series).
- At least 500 GB of free disk.
- Docker with GPU access.

**Pre-flight checks**

```bash
# Driver up, all 8 GPUs listed?
nvidia-smi -L
# Docker can hand GPUs to a container?
docker run --rm --gpus all ubuntu nvidia-smi
# Enough free disk where Docker stores data?
df -h $(docker info -f '{{.DockerRootDir}}')

```

**What you will accomplish**

- Launch a GRPO run on Qwen3-4B and watch the reward climb!

Training a different model? The flow is the same — see [Models](/models/index) for the per-model recipes.

# 评论区精华

作者 Shi-Dong 在 review 中留下三条自查评论并最终采纳：

> “Just say at least 500 GB”——要求精简磁盘描述的冗余解释，最终正文只保留“At least 500 GB”。

> “Remove 'Qwen3-4B'”——要求从页面 description 中移除模型名，避免描述过长，最终 description 为通用表述。

> “Mention 'Qwen3-4B' here.”——要求在“What you will accomplish”部分补充模型名，最终改为“Launch a GRPO run on Qwen3-4B”。

三条评论均为作者对自己初稿的打磨，无外部争议，全部在第二个 commit `04367942` 中解决，审阅者 nblintao 最终批准。

- 磁盘描述精简 (style): 已采纳，最终只保留一句简洁要求
- description 中移除模型名 (style): 已采纳，description 改为通用表述
- 正文中补充模型名 (question): 已采纳，在“What you will accomplish”中加入 Qwen3-4B

# 风险与影响

- 风险：风险极低，属于纯文档改动。潜在问题：
 - `df -h $(docker info -f '{{.DockerRootDir}}')` 依赖 Docker CLI 输出格式与 Linux 环境，Windows / macOS Docker Desktop 用户可能得到不同路径；
 - 磁盘估算（50 GB/checkpoint、500 GB 总量）基于 Adam + 分布式优化器的默认配置，若用户改优化器或关闭中间 checkpoint，实际占用会不同，文档未注明该前提；
 - 命令块未包含异常分支说明（如缺少 Docker 组权限时的处理）。
 - 影响：影响范围集中在新用户上手路径：pre-flight 检查能显著减少因驱动、Docker 权限或磁盘不足导致的启动失败，提升首次体验；磁盘要求提高 2.5 倍可能让部分小磁盘用户提前评估成本，但也更符合长时间训练的实际占用。对团队而言，这是一次低成本的文档质量修正，与近期多篇文档改进 PR 同向。
 - 风险标记：文档估算依赖默认优化器配置 , 命令未覆盖非 Linux 环境

# 关联脉络

- PR #2484 docs: add disaggregated RL rollout guide: 该 PR 修改了 docs/getting-started/quick-start.md，与本 PR 处于同一文档文件，内容上涉及快速入门路径的持续演进。
- PR #2533 docs: rebrand environments bullet as agentic, add HUD, sync README and docs index: 该 PR 同样修改了 docs/index.md，与本 PR 同步维护首页入口描述，属于同一文档维护脉络。