# PR #2398 完整报告

- 仓库：`radixark/miles`
- 标题：docs: download the DAPO jsonl mirror the launcher expects
- 合并时间：2026-08-12 07:41
- 原文链接：http://prhub.com.cn/radixark/miles/pull/2398

---

# 执行摘要

- 一句话：修正 Quick Start 的 DAPO 数据下载，对齐 launcher 期望格式
- 推荐动作：值得快速浏览而非精读：纯 2 行文档变更，但背景揭示了“以 launcher 数据契约为准验证数据集兼容性”的方法，适合作为文档类修复的范本。关注点：提交说明清晰、验证详尽、善用 follow-up 拆分同类问题。

# 功能与动机

PR body 明确说明：用户按 Quick Start 页面操作时，DAPO 下载命令拉取的仓库内容与 scripts/run-qwen3-4B.sh 的消费方式不匹配——页面下载 BytedTsinghua-SIA/DAPO-Math-17K 只含 data/dapo-math-17k.parquet 且 label 嵌套在 reward_model.ground_truth，而 launcher 期望 /root/dapo-math-17k/dapo-math-17k.jsonl 的扁平 prompt/label 行结构。修复目标是让下载命令与 launcher 的数据契约完全对齐，确保 Quick Start 能端到端跑通。

# 实现拆解

1. **定位并核对数据契约**：分析 scripts/run-qwen3-4B.sh 的期望——--prompt-data /root/dapo-math-17k/dapo-math-17k.jsonl、--input-key prompt、--label-key label；逐一对比 BytedTsinghua-SIA/DAPO-Math-17K 实际内容，发现路径、格式、key 布局三个维度均不满足。
2. **验证替代镜像**：通过拉取 Hugging Face repo tree 与首行数据，确认 zhuzilin/dapo-math-17k 提供 dapo-math-17k.jsonl，行结构为 {"prompt": [chat messages], "label": "..."}，与 launcher 完全对齐；同时该镜像已是其他 recipe 页面的通用选择（同页 zhuzilin/aime-2024 一直可用），佐证了生态一致性。
3. **同步两处文档**：docs/getting-started/quick-start.md 将 hf download 命令的数据集源替换为 zhuzilin/dapo-math-17k；docs/models/qwen/index.md 将 DAPO-Math-17k 链接指向同一镜像（纯链接变更），避免两个入口指引不同数据源。
4. **测试与后续**：手动执行 hf download 并验证 jsonl 行字段，纯文档变更无自动化测试配套；同时审计发现 docs/examples/reproducibility.md 的 gsm8k 下载存在同类问题，拆分为 follow-up PR（2399）处理。

关键文件：
- `docs/getting-started/quick-start.md`（模块 快速开始；类别 docs；类型 documentation）: Quick Start 页面是新手跑通端到端的入口，本 PR 核心修复点就在此：将 DAPO 数据集下载源改为 launcher 实际消费的 zhuzilin 镜像，并同步了格式说明。
- `docs/models/qwen/index.md`（模块 模型文档；类别 docs；类型 documentation）: Qwen 模型索引页给出了同一 DAPO-Math-17k 数据集的链接与路径，需与 Quick Start 页保持一致，避免两个入口指引不同数据源。

关键符号：未识别

## 关键源码片段

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

Quick Start 页面是新手跑通端到端的入口，本 PR 核心修复点就在此：将 DAPO 数据集下载源改为 launcher 实际消费的 zhuzilin 镜像，并同步了格式说明。

```bash
# 训练数据：17k 道可校验答案的数学题
# 必须使用 zhuzilin 镜像，它提供 launcher: scripts/run-qwen3-4B.sh 期望的
# dapo-math-17k.jsonl 文件，行结构为 {"prompt": [chat messages], "label": "..."}
# 旧指引的 BytedTsinghua-SIA/DAPO-Math-17K 只含 parquet，且 label 嵌套在
# reward_model.ground_truth 下，导致 --prompt-data、--input-key prompt、--label-key label
# 全部对不上 launcher 的数据契约，新手按原文档无法端到端跑通。
hf download --repo-type dataset zhuzilin/dapo-math-17k --local-dir /root/dapo-math-17k

```

# 评论区精华

本 PR 无 review 评论或讨论线程，reviewer Zhichenzzz 直接 APPROVED。核心判断依据来自 PR body 中的三方核对：launcher 数据契约（路径 + 双 key）、旧镜像实际内容（parquet + 嵌套 label）、新镜像实际内容（jsonl + 扁平 key）。这种以消费方契约为基准、逐一验证供应方内容的做法是本 PR 可借鉴之处。

- 暂无高价值评论线程

# 风险与影响

- 风险：风险整体很低，需注意以下几点：
 - 外部依赖风险：zhuzilin/dapo-math-17k 是外部 Hugging Face 镜像，若被删除或改名，文档将再次失效；但该镜像已被多个 recipe 页面长期使用，风险较低。
 - 用户缓存风险：已按旧命令下载过 BytedTsinghua 数据集的用户不受影响，但如需重跑需重新下载；文档修复不会自动纠正已产生的错误目录。
 - 一致性风险：qwen/index.md 仅改链接，路径与文件名维持不变（统一为 /root/dapo-math-17k/dapo-math-17k.jsonl），没有引入新的不一致点。
 - 无代码、性能、安全影响。
 - 影响：用户侧：Quick Start 新手和 Qwen 模型页读者不再因数据集格式不匹配卡在下载 / 启动步骤，首次运行体验直接改善。系统侧：无运行时影响，不涉及镜像构建、CI 或训练代码。团队侧：帮助维护者确立了“文档下载命令需与启动脚本数据契约对齐”的检查标准；PR body 附带的验证方法可作为后续文档审计模板。
 - 风险标记：外部镜像可用性 , 无测试覆盖 , 纯文档变更

# 关联脉络

- PR #2399 docs: fix the gsm8k download on the reproducibility page: PR body 明确指出的 follow-up，修复同类文档下载命令与数据契约不匹配问题（gsm8k 数据集）。
- PR #2402 scripts: download the DAPO dataset the NPU recipe trains on: 同一条 DAPO 数据集功能线，修复 NPU 训练脚本的数据 / 模型路径错位，与本 PR 共同将快速开始与各 recipe 的数据契约对齐。
- PR #2300 scripts: enable the Miles dashboard in the quick-start launcher: 改动同一份快速开始配套脚本 scripts/run-qwen3-4B.sh，与本 PR 涉及的 launcher 数据契约直接相关。
- PR #2298 docs: polish the Quick Start page: 修改了同一文件 docs/getting-started/quick-start.md，属于同一页面维护线。