---
tags: [nanochat, pretraining, 数据]
阶段: 05-预训练Pretraining
难度: ★★☆
created: 2026-10-22
related: "[[数据加载器dataloader]], [[词表与特殊token]], [[缩放定律与模型深度]], [[MOC-预训练]]"
---

# 训练数据：FineWeb 与 ClimbMix

## 定义

**预训练数据集**（pretraining dataset）在 nanochat 中指一组按固定大小切分、经 zstd 压缩的 parquet 文件，文件名为 `shard_XXXXX.parquet`，每行含一个 `text` 字段；训练时除字典序最后一个文件外全部作为训练集，最后一个文件固定作为验证集。

本篇出现的符号与术语：

- shard（分片）：一个 parquet 文件。`nanochat/dataset.py` 中 `MAX_SHARD = 6542`，`index_to_filename = lambda index: f"shard_{index:05d}.parquet"`，因此编号为 0 至 6542，共 6543 个文件。
- row group（行组）：parquet 内部的读取单元，重打包时固定 `row_group_size = 1024`，即每个行组含 1024 篇文档。分布式训练以行组为分片单位，而不是以文件为单位。
- document（文档）：`text` 列中的一条字符串。dataloader 将其编码为 token 序列，并在最前面插入一个 BOS token。
- `base_dir`：由 `nanochat.common.get_base_dir()` 决定，优先取环境变量 `NANOCHAT_BASE_DIR`，否则为 `~/.cache/nanochat`。数据、分词器、checkpoint 都位于该目录下。
- `DATA_DIR`：当前为 `base_dir/base_data_climbmix`；旧版为 `base_dir/base_data`。
- train / val 划分：`parquet_paths[:-1]` 为训练集，`parquet_paths[-1:]` 为验证集，即字典序最后一个 shard 恒为验证集。
- epoch（轮次）：完整遍历一次训练 shard 集合的计数，dataloader 从 1 开始计数。
- FineWeb：由 CommonCrawl 抽取并清洗的英文网页语料；FineWeb-EDU 是其中按教育质量分类器打分过滤的子集。
- ClimbMix-400B：NVIDIA 发布为 `nvidia/Nemotron-ClimbMix`，以 GPT-2 分词器存为 token id；nanochat 侧解码回文本、打乱并重新上传为 `karpathy/climbmix-400b-shuffle`。
- data:param ratio（数据参数比）：训练 token 数 $D$ 与参与缩放律统计的参数量 $N_{\text{scaling}}$ 之比，由 `--target-param-data-ratio` 控制，speedrun 取 8。
- bpb（bits per byte，每字节比特数）：验证集上 $\text{bpb}=\dfrac{\sum \text{nats}}{\ln 2\cdot\sum \text{bytes}}$，对分词器词表大小不变，是跨数据集的损失比较单位。

当前快照的关键常量集中在 `nanochat/dataset.py` 开头：

| 名称 | 取值 | 含义 |
|---|---|---|
| `BASE_URL` | `https://huggingface.co/datasets/karpathy/climbmix-400b-shuffle/resolve/main` | 下载根地址 |
| `MAX_SHARD` | 6542 | 最大 shard 编号，同时是固定的验证 shard |
| `index_to_filename` | `shard_{index:05d}.parquet` | 5 位零填充，保证字典序等于数值序 |
| `DATA_DIR` | `base_dir/base_data_climbmix` | 新数据目录，与旧目录分离 |
| 每 shard 字符数 | $2.5\times10^{8}$ | 由 `chars_per_shard` 控制 |
| 每行组文档数 | 1024 | 决定 DDP 分片粒度 |

## 为什么重要

- 数据决定模型损失的下界。同样的模型与优化器，换掉训练语料可以在不增加算力的条件下改变最终 CORE。`dev/LOG.md` 2026-03-04 记录，从 FineWeb-EDU 100B 切到 ClimbMix 400B 把 GPT-2 speedrun 从 2 小时 46 分降到 2 小时 1 分，降幅 27%，并允许模型从 d26 缩小到 d24；这是该阶段最大的单项改进。
- 数据结构决定指标可比性。验证集固定为最后一个 shard，因此 val bpb 在不同步数、不同模型之间可比；若验证集随下载数量漂移，同一条 bpb 曲线在不同运行之间没有意义。
- 行组决定分布式正确性。`nanochat/dataloader.py` 的 `_document_batches` 以 `rg_idx = ddp_rank`、步长 `ddp_world_size` 遍历行组；若行组大小不整除世界大小，或文件名排序错乱，某些 rank 会反复读同一段数据。
- 下载与迁移是真实的工程成本。170 个训练 shard 约 17 GB，全量 6543 个 shard 约 650 GB。断点续传、跳过已存在文件、legacy 目录回退，三者共同决定一次中断是否需要从头开始。
- 数据规模与 token 预算必须匹配。`--target-param-data-ratio=8` 对 d24 给出约 5.84B token；若语料总量不足，ratio 只能靠多 epoch 满足，重复数据的边际收益迅速下降。
- 在全书中的位置：前置为 [[词表与特殊token]]（文本如何变成 token）与 [[nanochat的Rust分词器实现]]（分词器训练需要文本）；后续为 [[数据加载器dataloader]]（如何切 batch）与 [[缩放定律与模型深度]]（需要多少 token）。对应能力目标：懂原理对应「说明质量与规模各自的边际收益」，能复现对应「下载、校验、迁移、重训分词器」，懂工程对应「估算磁盘与带宽并处理中断」。

## 原理与推导

数据从源头到 GPU 的完整路径如下。每一步都改变数据的物理形态，但不改变文本内容：

```mermaid
flowchart LR
    A[CommonCrawl / NVIDIA 语料] --> B[源数据集过滤<br/>FineWeb-EDU 分类器 / ClimbMix 策展]
    B --> C[repackage<br/>shuffle 42 + 每 2.5e8 字符切分]
    C --> D[HF shard_00000 至 06542<br/>zstd, 行组 1024 文档]
    D --> E[dataset.py 下载与排序<br/>train 除末位, val 末位]
    E --> F[dataloader 编码 + BOS + best-fit 打包]
    F --> G[GPU 上的 B x T token]
```

图中前两步的质量决策在 nanochat 仓库之外，第三步之后才是本仓库负责的部分。理解这条边界是理解本篇后续所有代码的前提。

### 步骤 1 为什么数据布局是 parquet shard

训练需要三个性质：可随机访问、可流式读取、可压缩存储。nanochat 的方案是把语料切成约 2.5 亿字符的 shard，每个 shard 内按 1024 篇文档一个行组写入。这样：

1. 行组是可独立解码的单元，多进程各读各的行组，不需要共享文件指针。
2. 单文件约 2.5 亿字符，zstd 压缩后约 100 MB，HTTP 下载与按需取用都可处理；单个 650 GB 文件无法按需下载。
3. 行组数量与文档数成正比，便于把数据切成与世界大小同余的份数。

重打包脚本用两个条件同时成立才写一个 shard：

```python
shard_characters += len(text)
collected_enough_chars = shard_characters >= chars_per_shard            # 250_000_000
docs_multiple_of_row_group_size = len(shard_docs) % row_group_size == 0 # 1024
if collected_enough_chars and docs_multiple_of_row_group_size:
    shard_path = os.path.join(output_dir, f"shard_{shard_index:05d}.parquet")
    shard_table = pa.Table.from_pydict({"text": shard_docs})
    pq.write_table(
        shard_table, shard_path,
        row_group_size=row_group_size,
        use_dictionary=False,
        compression="zstd",
        compression_level=3,
        write_statistics=False,
    )
```

第一个条件保证 shard 大小近似一致，第二个条件保证行组不出现尾部残缺。代价是 shard 实际大小由一个行组的粒度决定，会略大于 2.5 亿字符；这也是「每个 shard 约 100 MB」只能写作约数的原因。

### 步骤 2 FineWeb 与 FineWeb-EDU

FineWeb 是 CommonCrawl 的清洗产物：抽取正文、语言识别、去重、启发式过滤后得到的大规模英文网页语料。FineWeb-EDU 在其上再训练一个教育质量分类器，按分数保留更接近教材与作业的文档，因此 token 数更少但单位 token 的信息密度更高。

`dev/repackage_data_reference.py` 的 FineWeb 分支取 `HuggingFaceFW/fineweb-edu` 的 `sample-100BT` 配置：

```python
dataset_kwargs = {
    "path": "HuggingFaceFW/fineweb-edu",
    "split": "train",
    "name": "sample-100BT",  # ~100B GPT-2 tokens at ~3 chars/token => ~300B chars
}
```

`~100B GPT-2 tokens` 与 `~300B chars` 是同一规模在两种单位下的表述，换算比例约 3 字符/token。旧版 nanochat 使用该语料，训练 shard 共 1823 个，目录为 `base_data/`。

质量差异可以量化。`dev/LOG.md` 记录了六次试图在 CORE 上超过纯 FineWeb-EDU 的实验，前五次为负结果，第六次为 ClimbMix：

| 日期 | 改动 | 对照 | 结果 |
|---|---|---|---|
| 2026-01-15 | 换成 Olmo 3 的 `dolma3_mix-6T`，过滤短于 100 字符的文档 | d16 | CORE 15.5 → 13.8 |
| 2026-02-17 | 换成未过滤的 FineWeb | d26 | CORE 0.2602 → 0.2241 |
| 2026-02-17 | FinePDFs 50% + DCLM 30% + FineWeb-EDU 20% | d26 / d18 | 0.2602 → 0.2549 / 0.199 → 0.192 |
| 2026-03-04 | 换成 ClimbMix-400B | d26 → d24 | 通过，speedrun 2h46m → 2h01m |

这些负结果共同说明：在该规模下，过滤强度比语料多样性更重要；混合更多来源并不自动带来更好的 CORE，只有当新来源同时提高质量与规模时才有净收益。

### 步骤 3 ClimbMix-400B

ClimbMix 由 NVIDIA 发布为 `nvidia/Nemotron-ClimbMix`，是 400B token 的混合语料。相对 FineWeb-EDU 的优势有两点：同等 token 预算下 CORE 更高；总规模大四倍，为更深的模型与更长的训练留出余量。

上游数据以 GPT-2 分词器存储为 token id，列为 `tokens`。重打包时先解码回文本：

```python
elif dataset_tag == "climbmix":
    import tiktoken  # the ClimbMix data is stored tokenized with GPT-2 tokenizer
    dataset_kwargs = {"path": "nvidia/Nemotron-ClimbMix", "split": "train"}
    output_dirname = "climbmix"
    data_column_name = "tokens"
    tokenizer = tiktoken.encoding_for_model("gpt-2")
    upload_tag = "climbmix-400b-shuffle"
```

`tiktoken` 的 `decode` 是字节级无损的，解码回文本不丢失内容；重新用 nanochat 的 32768 词表编码属于重新切分，token 数与边界都会变化。这不影响训练，但意味着「ClimbMix 的 400B token」与「nanochat 训练时的 token」不是同一单位，两者不能直接换算字符数。

发布版在重打包前用 `ds.shuffle(seed=42)` 打乱，因此 shard 编号与原始语料顺序无关，任意前缀 shard 都是近似均匀的样本。这一点是「只下载 150 个 shard」能成立的前提：前缀不是某一个来源的偏斜切片。

规模对比：

| 项目 | FineWeb-EDU 100B（旧） | ClimbMix-400B（当前） |
|---|---|---|
| 源数据集 | `HuggingFaceFW/fineweb-edu`，`sample-100BT` | `nvidia/Nemotron-ClimbMix` |
| 存储列 | `text` | `tokens`（GPT-2 token id） |
| 总量 | 约 100B token | 约 400B token |
| 数据 shard 数 | 1823 | 6543 |
| 本地目录 | `base_data/` | `base_data_climbmix/` |
| speedrun 深度 | d26 | d24 |
| speedrun 时间 | 2h46m | 2h01m |

> [!info] 版本说明
> 2025 年 10 月版本的 nanochat 使用 FineWeb-EDU 100B，目录为 `base_data/`，speedrun 配置为 d20，叙述中的成本约 100 美元。当前 master（commit `92d63d4`）使用 ClimbMix-400B，目录为 `base_data_climbmix/`，speedrun 为 d24 + `--fp8`，8×H100 约 1.5 至 2 小时、约 48 美元。两套叙述不可混用；旧目录仅作为回退保留。

### 步骤 4 下载、断点续传与验证集固定

`nanochat/dataset.py` 的下载器遵守三条规则：

1. 已存在即跳过。`download_single_file` 首先检查 `os.path.exists(filepath)`，命中则打印 `Skipping ... (already exists)` 并返回 `True`。
2. 先写 `.tmp` 再原子改名。下载写入 `filepath + ".tmp"`，完成后 `os.rename` 到正式名；失败时删除 `.tmp` 与正式文件。这样中断不会留下被误认为完整的半文件。
3. 有限重试与指数退避。`max_attempts = 5`，第 `attempt` 次失败后等待 `2 ** attempt` 秒（2、4、8、16），`timeout=30`，`chunk_size` 为 1 MB。

命令行入口的语义需要精确理解：

```python
num_train_shards = MAX_SHARD if args.num_files == -1 else min(args.num_files, MAX_SHARD)
ids_to_download = list(range(num_train_shards))
ids_to_download.append(MAX_SHARD) # always download the validation shard
```

- `-n 170` 表示下载编号 0 至 169 的 170 个训练 shard，外加编号 6542 的验证 shard，共 171 个文件。
- 验证 shard 恒为 `shard_06542.parquet`，与 `-n` 无关。因此先下 8 个、后下 170 个，验证集始终是同一个文件，val bpb 全程可比。
- `-n -1` 的帮助文本写作 `-1 = disable`，实际行为是下载全部 6542 个训练 shard 加验证 shard，约 650 GB。帮助文本与实现不一致，不应把 -1 理解为「不下载」。

并发由 `multiprocessing.Pool(processes=args.num_workers)` 提供，默认 4 个 worker；返回值列表求和后打印 `Done! Downloaded: X/Y shards`。

带宽与时间的量级可以直接算。171 个文件约 17 GB，若 4 个 worker 合计 80 MB/s，需约 3.6 分钟；实际耗时由网络决定，因此 `runs/speedrun.sh` 在后台下载 170 个 shard 的同时训练分词器，等分词器与评测完成后再 `wait $DATASET_DOWNLOAD_PID`。磁盘需要预留至少 20 GB，全量下载则需约 650 GB。

### 步骤 5 legacy 回退与迁移

`list_parquet_files` 在目标目录不存在时打印迁移提示并回退到旧目录：

```python
if not os.path.exists(data_dir):
    if warn_on_legacy:
        print("  nanochat recently switched from FinewebEdu-100B to ClimbMix-400B.")
        print("    python -m nanochat.dataset -n 170     # download ~170 shards, enough for GPT-2")
        print("    python -m scripts.tok_train           # re-train tokenizer on new ClimbMix data")
    data_dir = os.path.join(base_dir, "base_data")
```

打印的完整提示为：

```text
================================================================================
  WARNING: DATASET UPGRADE REQUIRED
================================================================================

  Could not find: /home/user/.cache/nanochat/base_data_climbmix

  nanochat recently switched from FinewebEdu-100B to ClimbMix-400B.
  Everyone who does `git pull` as of March 4, 2026 is expected to see this message.
  To upgrade to the new ClimbMix-400B dataset, run these two commands:

    python -m nanochat.dataset -n 170     # download ~170 shards, enough for GPT-2, adjust as desired
    python -m scripts.tok_train           # re-train tokenizer on new ClimbMix data

  For now, falling back to your old FinewebEdu-100B dataset...
================================================================================
```

三个细节决定这段代码的实际行为：

- 警告只在 `warn_on_legacy=True` 时打印。`_document_batches` 把它设为 `ddp_rank == 0 and split == "train"`，即只有 0 号进程在训练集上会看到提示，验证集与其他 rank 静默回退。
- 回退只检查旧目录是否存在，不检查是否为空。若旧目录存在但为空，`list_parquet_files` 返回空列表，最终在 dataloader 的 `assert len(parquet_paths) != 0` 处失败。
- 若旧目录也不存在，`os.listdir` 直接抛出 `FileNotFoundError`，用户看到异常而不是迁移提示。

迁移必须同时做两件事：下载新数据、重训分词器。原因是分词器在旧语料上训练，词表与新语料分布不匹配；更严格地说，重训后同一段文本的 token id 会整体改变，旧 checkpoint 与新分词器不兼容。`checkpoint_manager.build_model` 只断言 `tokenizer.get_vocab_size() == model_config_kwargs["vocab_size"]`，两者都是 32768，断言通过，因此不兼容是静默的，只会在损失曲线上表现为异常。

### 步骤 6 重打包脚本实际做了什么

脚本头部明确声明它只用于文档化数据准备，运行时不需要：

```text
NOTE: This file is meant only as reference/documentation of the
dataset preparation and it is not used during the project runtime.
```

逐段核对后，流程如下：

1. 按 `dataset_tag` 选择源数据集、文本列与是否需要解码；`fineweb_edu` 与 `climbmix` 两个分支之外抛 `ValueError`。
2. `ds = load_dataset(**dataset_kwargs)` 载入源数据。
3. `ds = ds.shuffle(seed=42)` 打乱顺序。
4. 遍历文档，累计字符数；当字符数达到 2.5 亿且文档数是 1024 的整数倍时，把当前缓冲区写成一个 shard：`row_group_size=1024`、`use_dictionary=False`、`compression="zstd"`、`compression_level=3`、`write_statistics=False`。
5. 若 `upload_to_hf`，用 `HfApi.upload_large_folder` 上传到 `karpathy/<upload_tag>`。

必须明确的是：该脚本不去重、不做质量过滤、不做语言识别、不截断文档长度。所有质量控制在源数据集侧完成，FineWeb-EDU 由分类器过滤，ClimbMix 由 NVIDIA 策展。nanochat 侧只做打乱、重打包与分片。把重打包当作数据清洗脚本会得出错误结论，例如以为它去掉了重复文档，实际重复文档会原样进入 shard。

两处工程限制：输出目录硬编码为 `/home/ubuntu/.cache/nanochat/base_data_{output_dirname}`，不读取 `NANOCHAT_BASE_DIR`；脚本 `import datasets`，而 `datasets` 不是 nanochat 依赖，真要运行需要单独安装。

### 步骤 7 数据如何影响可比较的指标

训练进程打印的是 val bpb，而不是平均交叉熵。`nanochat/loss_eval.py` 的实现是分别累加目标 token 的负对数似然与字节数，再相除：

$$
\text{bpb}=\frac{\sum_{i}\ell_i}{\ln 2\cdot\sum_i b_i},
$$

其中 $\ell_i$ 是第 $i$ 个目标 token 的负对数似然（单位 nat），$b_i$ 是该 token 的字节数，由 `token_bytes` 张量提供，特殊 token 的字节数为 0 因而被排除。这样做的原因是：更换数据集往往同时更换分词器，词表大小变化会让平均损失不可比，而字节数是文本的固有单位。

因此数据替换在指标上有两层影响：一是分布变化改变 $\ell_i$ 的期望，二是分词器重训改变 $b_i$ 与切分方式。前者的收益是真实的，后者的变化是度量口径的变化；leaderboard 在 ClimbMix 那一行同时给出 val bpb 0.71854 与 CORE 0.2571，正是为了让两者可区分。跨数据集比较损失时必须用 bpb，不能用 `loss`。

### 步骤 8 为什么数据质量是最大单项改进

leaderboard 的时间序列给出对照：d24 基线 3.04 小时（1 月 29 日）→ d26 + fp8 2.91 小时（2 月 2 日）→ 总批大小提到 1M token 2.76 小时（2 月 5 日）→ 换 ClimbMix 2.02 小时（3 月 4 日）。前两项是训练侧改动，累计降低 0.28 小时；数据替换单项降低 0.74 小时，并允许深度从 d26 降到 d24。

机制上有两条，其中只有第一条对当前 speedrun 生效：

1. 单位 token 的有效信息更高。质量过滤去掉模板页、导航文本、机器翻译残留等低预测难度的内容，相同 token 预算下模型见到的有效语言现象更多，等价于扩大数据量。
2. 可用总量更大，解除上限。d24 在 ratio 8 下只需 5.84B token，约占 FineWeb-EDU 100B 的 5.8%；即使按 34.6% 裁剪率折算为读入 8.9B token，也只占 8.9%。因此 100B 并未在当前 speedrun 上构成瓶颈，400B 的意义在于为更深的模型与更长的训练留出余量，`dev/LOG.md` 的表述是「allowing for longer training in the future」。

第二条与 [[缩放定律与模型深度]] 中的 token 预算直接相关，但结论与直觉相反：对 d24 而言，FineWeb-EDU 的总量已经足够，所以换数据集的收益只能来自质量而非数量。这也解释了为什么 `dev/LOG.md` 在记录 ClimbMix 时强调的是 CORE 与时间，而不是「数据不够用」。

### 在 nanochat 中的落地

| 位置 | 作用 | 去掉会怎样 |
|---|---|---|
| `nanochat/dataset.py` 的 `BASE_URL`、`MAX_SHARD`、`index_to_filename`、`DATA_DIR` | 定义数据集身份与本地布局 | 地址或编号规则错误会让部分 shard 404 或写错目录 |
| `dataset.py:list_parquet_files` | 列出 shard、过滤 `.tmp`、legacy 回退 | 无回退则升级后直接崩溃；不过滤 `.tmp` 会把半文件当 shard 读 |
| `dataset.py:parquets_iter_batched` | 按行组迭代并产出文本批；`split` 决定 train/val | 若在此做额外切分，验证集不再固定，bpb 不可比 |
| `dataset.py:download_single_file` | 跳过已存在、流式下载、`.tmp` 改名、5 次重试 | 断点续传失效，弱网下需要整段重下 |
| `dataset.py:__main__` | 解析 `-n`、恒定追加验证 shard、进程池并发 | 若验证 shard 随 `-n` 变化，跨次运行的 val bpb 不可比 |
| `dev/repackage_data_reference.py` | 记录 FineWeb 与 ClimbMix 两种打包配置 | 无法复现发布版 shard 的划分方式与压缩参数 |
| `runs/speedrun.sh` 的 `python -m nanochat.dataset -n 8` 与 `-n 170` | 先取约 2B 字符训分词器，再后台补齐预训练数据 | 先下 170 个会推迟分词器训练，整条流水线串行化 |
| `scripts/tok_train.py` 的 `text_iterator` | 用 `parquets_iter_batched` 的文本训练 32768 词表，`--max-chars` 默认 2e9 | 分词器不重训则与 ClimbMix 的 id 分布错配 |

`-n 8` 的选择不是随意的：每个 shard 约 2.5 亿字符，8 个 shard 正好 20 亿字符，等于 `tok_train.py` 的 `--max-chars` 默认值 2_000_000_000。`scripts/tok_eval.py` 随后用 `parquets_iter_batched` 取训练集与验证集的首个行组作为样本，把压缩率与 GPT-2、GPT-4 分词器对比，用于确认分词器与新语料匹配。

`nanochat/dataloader.py` 的 `_document_batches` 只调用 `list_parquet_files(warn_on_legacy=warn_on_legacy)`，不直接读 `BASE_URL` 或 `MAX_SHARD`。这意味着数据层的抽象边界是「一个已排序的 parquet 路径列表」：替换数据集只需要改 `dataset.py` 的常量与目录，dataloader 与训练脚本无需改动。

## 关键直觉

> [!tip] 数据集有两个互不相同的属性：可数的物理布局与不可数的分布质量。nanochat 的 `dataset.py` 只负责前者，即 shard 的数量、大小、下载、排序与 train/val 切分；后者在 HuggingFace 数据集侧已经固化，`repackage_data_reference.py` 也只做打乱与重打包，不做过滤。因此替换数据集在代码上只改四个常量并重训分词器，但收益可以超过任何训练侧超参数改动，因为后者只能在给定分布内调整优化路径。裁剪与打包造成的 token 浪费属于第三层：它不改变分布，只改变读入 token 中真正参与梯度的比例，由 [[数据加载器dataloader]] 负责。

## 例子与代码

下面的命令可直接在 8×H100 节点上执行，用于下载并核对 shard 布局。第一条命令同时下载验证 shard，因此得到 9 个文件。

```bash
export NANOCHAT_BASE_DIR="$HOME/.cache/nanochat"
mkdir -p "$NANOCHAT_BASE_DIR"

# 8 个训练 shard + 固定验证 shard = 9 个文件，约 2.0e9 字符
python -m nanochat.dataset -n 8

# 补齐到 170 个训练 shard；已存在的文件会被跳过
python -m nanochat.dataset -n 170

ls "$NANOCHAT_BASE_DIR/base_data_climbmix"/shard_*.parquet | wc -l   # 171
du -sh "$NANOCHAT_BASE_DIR/base_data_climbmix"                        # 约 17G
ls "$NANOCHAT_BASE_DIR/base_data_climbmix"/shard_*.parquet | tail -1  # shard_06542.parquet
```

预期输出：第一次运行打印 `Downloading 9 shards using 4 workers...`，结束时为 `Done! Downloaded: 9/9 shards`；第二次打印 `Downloading 171 shards using 4 workers...`，其中 9 个被跳过，最终计数仍为 171 个文件。`tail -1` 必须是 `shard_06542.parquet`，它同时是验证集。

下面的 Python 片段核对行组数量、文档数与 train/val 切分。它只依赖已下载的 shard，不需要 GPU。

```python
import pyarrow.parquet as pq
from nanochat.dataset import list_parquet_files, parquets_iter_batched

paths = list_parquet_files()                      # 已排序，.tmp 被过滤
print(len(paths), paths[0].split("/")[-1], paths[-1].split("/")[-1])
# 171 shard_00000.parquet shard_06542.parquet

val_path = paths[-1]                              # parquets_iter_batched 的 val 划分
pf = pq.ParquetFile(val_path)
print(pf.num_row_groups, pf.metadata.num_rows)    # 行组数, 文档数
print(pf.metadata.row_group(0).column(0).compression)  # ZSTD

first_val_batch = next(parquets_iter_batched(split="val"))
print(len(first_val_batch), len(first_val_batch[0]))
# 1024 以及第一篇文档的字符数
```

`pf.num_row_groups` 乘以 1024 应等于或略大于 `pf.metadata.num_rows`，因为只有最后一个行组可能不满。第一行训练数据来自 `paths[0]` 的第一个行组，验证数据来自 `paths[-1]`，两者不重叠。

最后一个手算例估计 170 个 shard 是否够 d24 使用。设每 shard 2.5e8 字符，平均 $c$ 字符/token：

$$
T_{\text{docs}} \approx \frac{170 \times 2.5\times10^{8}}{c}.
$$

取 $c=4$，得 $T_{\text{docs}}\approx 1.06\times10^{10}$。dataloader 的裁剪率约 34.6%，有效 token 为 $0.654\times1.06\times10^{10}\approx 6.9\times10^{9}$。d24 在 `--target-param-data-ratio=8` 下需要 $D=8\times7.298\times10^{8}\approx 5.84\times10^{9}$ token，因此 170 个 shard 的单 epoch 有效 token 约覆盖需求的 1.18 倍，余量对应 20 个 shard 的 padding。取 $c=3.5$ 时余量更小但结论不变；取 $c=3$ 时不足 1 倍，需要确认实测字符/token 比。该估算与 `dev/LOG.md` 的「约 150 个 shard 约 7B token」在 $c\approx3.5$ 时一致。

## 易错点

> [!warning] 以下六条均可在不训练模型的情况下验证。
>
> 1. 把 `-n 170` 理解为「下载 170 个文件」。实际是 170 个训练 shard 加 1 个固定验证 shard，共 171 个文件；`ls | wc -l` 与 `-n` 的差恒为 1。
> 2. 把 `MAX_SHARD = 6542` 理解为 shard 总数。它是最大编号，文件数为 6543；`dev/LOG.md` 也写作 6543，二者不矛盾。
> 3. 认为 `-n -1` 表示不下载。实现中 `-1` 走 `MAX_SHARD` 分支，会下载全部 6543 个文件，与帮助文本的 `-1 = disable` 相反。
> 4. 认为重打包脚本会去重或过滤。它只有 shuffle 与重打包；重复文档原样保留，质量由源数据集决定。
> 5. 重训分词器后继续使用旧 checkpoint。`checkpoint_manager.build_model` 只校验 vocab size 相等，不校验 tokenizer 身份，错配不报错，只表现为损失异常。
> 6. 手工加入非 5 位编号的 shard（如 `shard_10000.parquet`）。`sorted()` 是字典序，6 位文件名排在 `shard_06542.parquet` 之后，会取代它成为验证集。

## 关联笔记

- 前置：[[词表与特殊token]] —— 文本到 token 的映射决定词表大小与特殊 token 编号，数据与分词器必须成对迁移。
- 前置：[[nanochat的Rust分词器实现]] —— `tok_train` 需要文本，ClimbMix 的上游 token 必须先解码回文本。
- 后续：[[数据加载器dataloader]] —— 本笔记给出 shard 与行组，下一篇解释如何把它们切成 BOS 对齐的 batch。
- 对照：[[缩放定律与模型深度]] —— 数据总量与 token 预算共同决定 `--target-param-data-ratio` 是否可满足。
- 跨库：[[数据集质量控制]] —— 通用原理见该篇，本篇只讲 nanochat 的数据接口与迁移，不重复质量分类器的训练细节。

## 达标检测

- [ ] 能写出 `shard_{index:05d}.parquet` 的编号范围，并说明 `-n 170` 实际产生多少个文件。
- [ ] 能解释为什么验证集固定为最后一个 shard，以及若验证集随下载量漂移会破坏什么。
- [ ] 能复述 `download_single_file` 的三条规则（跳过已存在、`.tmp` 改名、5 次指数退避），并说明 `.tmp` 与 `list_parquet_files` 过滤条件的关系。
- [ ] 能指出 `list_parquet_files` 回退逻辑的两个漏洞，并写出触发条件。
- [ ] 能说明重打包脚本不做去重与过滤，并指出质量控制实际发生在哪一层。
- [ ] 给定每 shard 字符数与字符/token 比，能估算 170 个 shard 的有效 token 数，并与 d24 的 5.84B token 需求比较。
- [ ] 能写出 bpb 的公式，并解释为什么跨数据集比较必须用 bpb 而不是平均损失。
- [ ] 能列出迁移到 ClimbMix 的两条命令，并解释为什么必须重训分词器。

## 参考来源

- Karpathy, *nanochat*（commit `92d63d4`），`nanochat/dataset.py` 与 `dev/repackage_data_reference.py` —— 对应本篇的 shard 常量、下载器、回退逻辑与重打包流程。
- Karpathy, *nanochat* `dev/LOG.md`（2026-03-04、2026-02-17、2026-01-15）—— 对应 FineWeb-EDU → ClimbMix 迁移的 2h46m → 2h01m、d26 → d24，以及未过滤 FineWeb 与混合语料的负结果。
- Karpathy, *nanochat* `README.md`（commit `92d63d4`），Time-to-GPT-2 Leaderboard —— 对应 3.04 → 2.91 → 2.76 → 2.02 小时的时间序列与 GPT-2 CORE 0.256525 门槛。
- Penedo et al., *The FineWeb Datasets: Decanting the Web for the Finest Text Data at Scale*（arXiv:2406.17557）—— 对应 FineWeb 与 FineWeb-EDU 的构造与过滤方式。
- Hoffmann et al., *Training Compute-Optimal Large Language Models*（arXiv:2203.15556）—— 对应 token 预算与参数量之比的取值依据，即本篇的手算例。
- Hugging Face, *datasets* 文档 —— 对应 `load_dataset`、`shuffle`、`ParquetFile` 行组读取的接口语义。
