w wyl123ly 的博客
MD

训练数据与FineWeb

28 KB 2026.10.22 原文件

训练数据: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 数 与参与缩放律统计的参数量 之比,由 --target-param-data-ratio 控制,speedrun 取 8。
  • bpb(bits per byte,每字节比特数):验证集上 ,对分词器词表大小不变,是跨数据集的损失比较单位。

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

名称取值含义
BASE_URLhttps://huggingface.co/datasets/karpathy/climbmix-400b-shuffle/resolve/main下载根地址
MAX_SHARD6542最大 shard 编号,同时是固定的验证 shard
index_to_filenameshard_{index:05d}.parquet5 位零填充,保证字典序等于数值序
DATA_DIRbase_dir/base_data_climbmix新数据目录,与旧目录分离
每 shard 字符数由 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 的完整路径如下。每一步都改变数据的物理形态,但不改变文本内容:

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:

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 配置:

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 字符的文档d16CORE 15.5 → 13.8
2026-02-17换成未过滤的 FineWebd26CORE 0.2602 → 0.2241
2026-02-17FinePDFs 50% + DCLM 30% + FineWeb-EDU 20%d26 / d180.2602 → 0.2549 / 0.199 → 0.192
2026-03-04换成 ClimbMix-400Bd26 → d24通过,speedrun 2h46m → 2h01m

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

步骤 3 ClimbMix-400B

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

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

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-100BTnvidia/Nemotron-ClimbMix
存储列texttokens(GPT-2 token id)
总量约 100B token约 400B token
数据 shard 数18236543
本地目录base_data/base_data_climbmix/
speedrun 深度d26d24
speedrun 时间2h46m2h01m

版本说明

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。

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

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 在目标目录不存在时打印迁移提示并回退到旧目录:

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")

打印的完整提示为:

================================================================================
  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 重打包脚本实际做了什么

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

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 的负对数似然与字节数,再相除:

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

因此数据替换在指标上有两层影响:一是分布变化改变 的期望,二是分词器重训改变 与切分方式。前者的收益是真实的,后者的变化是度量口径的变化;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 与训练脚本无需改动。

关键直觉

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

例子与代码

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

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。

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 字符,平均 字符/token:

取 ,得 。dataloader 的裁剪率约 34.6%,有效 token 为 。d24 在 --target-param-data-ratio=8 下需要 token,因此 170 个 shard 的单 epoch 有效 token 约覆盖需求的 1.18 倍,余量对应 20 个 shard 的 padding。取 时余量更小但结论不变;取 时不足 1 倍,需要确认实测字符/token 比。该估算与 dev/LOG.md 的「约 150 个 shard 约 7B token」在 时一致。

易错点

以下六条均可在不训练模型的情况下验证。

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 行组读取的接口语义。