w wyl123ly 的博客
MD

本地环境搭建

29 KB 2026.10.22 原文件

本地环境搭建

定义

复现环境(reproducible environment)是一组确定的软件与路径状态,其并集足以让仓库中的任一脚本在目标机器上产生预期产物:解释器版本、依赖解析结果、CUDA 驱动与 PyTorch wheel 的匹配关系、精度开关的取值,以及所有中间产物的根目录。

本篇出现的术语与符号定义如下。

术语含义
uvAstral 开发的 Python 包与项目管理器,nanochat 用它创建虚拟环境、解析依赖、生成锁文件
虚拟环境(venv)与系统 Python 隔离的解释器副本,nanochat 固定使用仓库根目录下的 .venv/
extrapyproject.toml 中 [project.optional-dependencies] 定义的可选依赖组,nanochat 有 cpu 与 gpu 两个
锁文件(lockfile)uv.lock,记录每个包的确切版本、来源与哈希,使两次安装得到同一组 wheel
计算能力(compute capability)NVIDIA GPU 的架构版本号,记作 SM 主版本.次版本,如 A100 为 8.0、H100 为 9.0
COMPUTE_DTYPEnanochat/common.py 在导入时确定的全局计算精度,取值 bfloat16、float16 或 float32
NANOCHAT_BASE_DIR所有中间产物的根目录,未设置时取 ~/.cache/nanochat
shard预训练数据的 parquet 分片,文件名 shard_00000.parquet 到 shard_06542.parquet
token_bytes每个 token 的原始字节数向量,用于把损失换算成 bits per byte

文中其余符号在首次出现处定义,例如 表示词表大小,默认 。

为什么重要

环境决定了「能复现」这条主线能否开始,而它的失败方式往往不报错。import torch 成功但 torch.cuda.is_available() 为 False 时,base_train.py 的 autodetect_device_type() 会静默返回 cpu,训练不会崩溃,只是从每秒数万 token 掉到每秒数十 token。缺少 FA3 内核时,scripts/base_train.py 打印四行警告后回退到 SDPA,训练仍然进行,吞吐下降接近一半。分词器未训练时,get_tokenizer() 在 RustBPETokenizer.from_directory 中直接抛 FileNotFoundError,而报错路径是 ~/.cache/nanochat/tokenizer/tokenizer.pkl,若设置了 NANOCHAT_BASE_DIR 则指向别处。

这四条链路对应四种返工:精度与设备错误影响全部后续实验,FA3 缺失影响每小时的吞吐成本,数据与分词器缺失影响第一个训练步,基准目录不一致影响「以为跑过、其实没跑」。以 8×H100 约 24 美元每小时计,环境环节多花一小时的成本相当于十次 d12 短跑。

在全书中的位置:本篇是 10 阶段的第一篇,为 跑通speedrun脚本 提供前置状态;它的产物(数据、分词器、COMPUTE_DTYPE)被 训练脚本与speedrun 直接消费;它的失败分支汇总在 常见问题踩坑。懂原理对应「知道每个依赖为何存在」,能复现对应「在没有 GPU 的机器上也能装出可运行的环境」,懂工程对应「在 Linux 与 Windows/WSL2 之间做出正确选择」。

原理与推导

1 依赖清单:九个直接依赖与两个互斥的 extra

pyproject.toml 的 [project].dependencies 列出九个运行时依赖,每一个都对应一处不可省略的功能。

依赖版本约束在 nanochat 中的用途缺失后的症状
torch==2.9.1张量、自动微分、torch.compile、torch._scaled_mm无法导入任何模块
kernels>=0.11.7从 Hugging Face Hub 取 FA3 内核回退 SDPA,吞吐下降
rustbpe>=0.1.0训练 BPE 词表tok_train 导入失败
tiktoken>=0.11.0推理期编码与解码tokenizer.py 导入失败
pyarrow>=21.0.0读取 parquet 分片数据加载失败
numpy>=1.26.0数值辅助部分脚本导入失败
filelock>=3.19.0多 rank 下载评测包时的文件锁多进程同时下载同一文件
psutil>=7.1.0系统与进程信息基准脚本缺依赖
wandb>=0.21.3训练曲线与指标--run 非 dummy 时初始化失败

torch 的版本是精确锁定(==2.9.1)而不是范围,原因是 nanochat/fp8.py 直接调用 torch._scaled_mm 的私有接口,其参数签名在版本之间会变。这个选择把「升级 torch」变成一次需要重新验证 FP8 路径的改动。

两个 extra 互斥。[tool.uv] conflicts 声明 cpu 与 gpu 不能同时安装,因为二者给出同一个包的两个不同来源:

[tool.uv.sources]
torch = [
    { index = "pytorch-cpu", extra = "cpu" },
    { index = "pytorch-cu128", extra = "gpu" },
]

cpu extra 还额外包含 setuptools,因为 CPU 版 torch 的部分依赖在安装时需要它。[tool.uv] default-groups = [] 把 dev 组排除在默认安装之外,因此 uv sync --extra gpu 装出的环境里没有 pytest;要跑 tests/ 必须显式加 --group dev。

2 uv 的三层模型:解释器、环境、锁

uv 把「用哪个 Python」「装到哪个目录」「装哪些版本」拆成三个独立决定。

第一层是解释器。仓库根目录的 .python-version 只有一行 3.10,requires-python 是 >=3.10。uv 读取前者后,若本机没有 CPython 3.10,会自动下载一份到自己的目录,不需要系统包管理器参与。

第二层是环境。uv venv 在仓库根目录创建 .venv/,其解释器来自第一层。uv sync 在 .venv 存在时直接同步,不存在时先创建,因此 [ -d ".venv" ] || uv venv 这一行是幂等的优化而不是必需步骤。

第三层是解析结果。uv.lock 记录全部传递依赖的确切版本。uv sync 默认会先重新解析,只有 --frozen 才强制使用锁文件。可复现的做法是首次 uv sync --extra gpu 生成锁,之后在相同平台上用 uv sync --frozen --extra gpu。

命令与产物的对应关系如下。

目的命令产物或副作用
安装 uv`curl -LsSf https://astral.sh/uv/install.sh \sh`~/.local/bin/uv
安装指定解释器uv python install 3.10uv 托管的 CPython
创建环境uv venv.venv/
装 GPU 依赖uv sync --extra gpu.venv/ 内含 cu128 版 torch
装 CPU 依赖uv sync --extra cpu.venv/ 内含 CPU 版 torch
追加开发依赖uv sync --extra gpu --group devpytest、matplotlib、ipykernel、python-dotenv
严格按锁安装uv sync --frozen --extra gpu不重新解析,版本与 uv.lock 一致
清理缓存uv cache clean删除下载缓存,下一次安装重新下载

切换 extra 时必须重建环境。uv sync --extra cpu 会在已装 GPU 版的 .venv 上把 torch 换源,uv 检测到来源冲突时会报错;可靠做法是删除 .venv 后重装,或用 uv sync --reinstall --extra cpu。

3 CUDA 驱动、PyTorch wheel 与计算能力的三方匹配

三者是三个独立变量,必须同时满足约束。

第一个变量是驱动版本。cu128 的 torch wheel 自带 CUDA 12.8 运行时,系统不需要安装 CUDA Toolkit,只需要 NVIDIA 驱动。nvidia-smi 右上角的 CUDA Version 是驱动支持的最高运行时版本,它必须不低于 wheel 的版本。NVIDIA 的次版本兼容机制允许 r525 以上的驱动运行 12.x 编译的程序,但使用新架构指令时会失败,因此保守判据是 CUDA Version >= 12.8。

第二个变量是 PyTorch 的 CUDA 构建。安装后可用两条命令核对:

python -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available())"

预期输出形如 2.9.1+cu128 12.8 True。若第二项是 None,装到的是 CPU wheel;若第三项是 False,驱动或设备不可见。

第三个变量是 GPU 的计算能力,它决定默认精度与内核可用性。

硬件计算能力默认 COMPUTE_DTYPEFA3--fp8
H100 / H2009.0bfloat16可用(varunneal/flash-attention-3)可用
A100 / A8008.0bfloat16可用(kernels-community/flash-attn3,需已缓存)不可用
L40S / RTX 40908.9bfloat16可用(同上,需已缓存)可用
B200 / GB20010.0bfloat16回退 SDPA可用
V100 / T47.0 / 7.5float32回退 SDPA不可用
CPU / Apple MPS无float32回退 SDPA不可用

表中「FA3」一列来自 nanochat/flash_attention.py 的加载逻辑:主版本 9 时取 varunneal/flash-attention-3,其它 CUDA 卡先用 has_kernel 探测本地是否已有 kernels-community/flash-attn3,有才加载,没有则返回 None,因此非 Hopper 卡首次使用前需要联网预热内核缓存。Blackwell 的注释明确写着需要等 FA3 重新编译或 FA4。

--fp8 一列没有在代码中做能力检查:base_train.py 只在 device_type != "cuda" 时忽略该参数,在 sm80 的 A100 上仍会完成 Float8Linear 转换,然后在第一次 torch._scaled_mm 处报错。因此 FP8 的可用判据是计算能力不低于 8.9。

4 基准目录与磁盘预算

nanochat/common.py 的 get_base_dir() 是所有路径的唯一来源:

def get_base_dir():
    if os.environ.get("NANOCHAT_BASE_DIR"):
        nanochat_dir = os.environ.get("NANOCHAT_BASE_DIR")
    else:
        home_dir = os.path.expanduser("~")
        cache_dir = os.path.join(home_dir, ".cache")
        nanochat_dir = os.path.join(cache_dir, "nanochat")
    os.makedirs(nanochat_dir, exist_ok=True)
    return nanochat_dir

它有两处行为值得注意。环境变量优先于默认值,所以「换一个目录做实验」只需改环境变量,不必改代码;函数每次调用都执行 makedirs,因此首次调用会创建目录,后续调用是幂等的。

目录布局与容量如下。表中大小是按数据类型和元素数计算的量级估计,不是实测值。

子目录内容量级
base_data_climbmix/训练分片,-n 170 时 171 个文件约 17 GB
tokenizer/tokenizer.pkl 与 token_bytes.pt数 MB
base_checkpoints/d24/模型、meta、每 rank 一份优化器分片约 4 GB 加约 6 GB
base_eval/每次评测一个 CSV数十 KB
eval_bundle/CORE 评测数据,首次评测时下载数百 MB
chatsft_checkpoints/d24/SFT 检查点,规模同 base约 4 GB
chatrl_checkpoints/d24/RL 检查点,由 chat_rl 产生约 4 GB

训练一个 d24 并完成 SFT 至少需要 40 GB 可用空间。模型文件约 4 GB 的来源可以逐项核对:transformer_matrices 与 lm_head 以 fp32 保存,约 2.9 GB;wte 与 value embeddings 以 bf16 保存,约 1.3 GB。优化器分片按 rank 均摊:AdamW 的二阶矩与一阶矩合计约 3 GB,Muon 的动量约 2.7 GB,八卡平均每卡约 0.7 GB。

5 精度开关 COMPUTE_DTYPE

nanochat 不使用 torch.amp.autocast,而是用单个全局量控制计算精度。common.py 在导入时执行一次检测:

def _detect_compute_dtype():
    env = os.environ.get("NANOCHAT_DTYPE")
    if env is not None:
        return _DTYPE_MAP[env], f"set via NANOCHAT_DTYPE={env}"
    if torch.cuda.is_available():
        capability = torch.cuda.get_device_capability()
        if capability >= (8, 0):
            return torch.bfloat16, f"auto-detected: CUDA SM {capability[0]}{capability[1]} (bf16 supported)"
        return torch.float32, f"auto-detected: CUDA SM {capability[0]}{capability[1]} (pre-Ampere, bf16 not supported, using fp32)"
    return torch.float32, "auto-detected: no CUDA (CPU/MPS)"
COMPUTE_DTYPE, COMPUTE_DTYPE_REASON = _detect_compute_dtype()

三个分支对应三条硬件路径。检测结果与原因字符串会由训练脚本打印,这是环境自检最直接的证据。

精度的影响是分层的,需要逐项区分。

  • master 权重与优化器状态保持 fp32,只有前向与反向的矩阵乘使用 COMPUTE_DTYPE。自定义 Linear 在 forward 中执行 F.linear(x, self.weight.to(dtype=x.dtype)),这是替代 autocast 的唯一机制。
  • embedding 直接以 COMPUTE_DTYPE 存储以节省显存;唯一的例外是 fp16 路径,因为 GradScaler 无法对 fp16 梯度做 unscale。
  • FA3 只支持 bf16 与 fp8,因此在 fp16 或 fp32 下 USE_FA3 为 False,即使硬件是 Hopper 也会回退 SDPA。
  • fp16 训练会在 base_train.py 与 chat_sft.py 中创建 GradScaler,但 chat_rl.py 没有对应逻辑,因此 RL 阶段不能使用 fp16。

NANOCHAT_DTYPE 的合法取值只有三个:bfloat16、float16、float32。写入其它字符串会在 _DTYPE_MAP[env] 处抛 KeyError,且发生在任何日志之前。

6 数据下载与分词器产物

nanochat/dataset.py 定义数据来源与下载协议。

  • BASE_URL 为 https://huggingface.co/datasets/karpathy/climbmix-400b-shuffle/resolve/main,文件名为 shard_{index:05d}.parquet。
  • MAX_SHARD = 6542 是最后一个分片编号。-n 指定训练分片数,验证分片始终额外下载 MAX_SHARD,因此 -n 170 实际得到 171 个文件。
  • 下载按 -w 指定的 4 个进程并行;每个文件先写 .tmp 再 os.rename,因此中断不会留下被误读的半文件。
  • 已存在的文件被跳过,重复执行同一条命令是安全的。

-n 8 与 -n 170 的差别是分词器与预训练的分工。每个分片约 2.5 亿字符,8 个分片约 20 亿字符,正好够分词器训练;170 个分片约 17 GB,够 d24 在一次训练中不重复数据。runs/speedrun.sh 先同步下 8 个,再后台下 170 个,用 wait 在预训练前汇合。

分词器由 scripts/tok_train.py 产生两个文件:

文件生成者用途
tokenizer/tokenizer.pkltokenizer.save(tokenizer_dir)pickle 序列化的 tiktoken 编码,供 get_tokenizer() 读取
tokenizer/token_bytes.pttok_train.py 末尾每个 token 的字节数,供 bpb 计算

token_bytes 的构造逻辑需要记住两点:特殊 token 的字节数记为 0(它们不贡献字节),普通 token 用 decode_single_token_bytes 取原始字节长度而不是解码成字符串再取长度(后者会破坏非 UTF-8 的 token)。缺失时 get_token_bytes() 的断言会给出明确提示:

AssertionError: Token bytes not found at ~/.cache/nanochat/tokenizer/token_bytes.pt? It gets written by tok_train.py

7 环境自检的最小命令

一个环境是否可用,可以用一段不依赖 GPU 的脚本判定。下面这段直接运行,逐项打印。

# env_check.py —— 只依赖已安装的 nanochat 与其依赖,任何平台可运行
import sys
import torch

print("python:", sys.version.split()[0])
print("torch:", torch.__version__, "| cuda build:", torch.version.cuda)
print("cuda available:", torch.cuda.is_available())
if torch.cuda.is_available():
    print("device:", torch.cuda.get_device_name(0), "| capability:", torch.cuda.get_device_capability(0))

# 导入即触发精度检测;同时打印原因字符串
from nanochat.common import COMPUTE_DTYPE, COMPUTE_DTYPE_REASON, get_base_dir
print("COMPUTE_DTYPE:", COMPUTE_DTYPE, "|", COMPUTE_DTYPE_REASON)
print("base_dir:", get_base_dir())

# 分词器缺失时这里抛 FileNotFoundError,即第 6 节所说的失败模式
from nanochat.tokenizer import get_tokenizer
tok = get_tokenizer()
print("vocab_size:", tok.get_vocab_size(), "| bos_id:", tok.get_bos_token_id())

在 8×H100 节点上的预期输出如下,行序即执行顺序。

python: 3.10.19
torch: 2.9.1+cu128 | cuda build: 12.8
cuda available: True
device: NVIDIA H100 80GB HBM3 | capability: (9, 0)
COMPUTE_DTYPE: torch.bfloat16 | auto-detected: CUDA SM 90 (bf16 supported)
base_dir: /home/user/.cache/nanochat
vocab_size: 32768 | bos_id: 32759

bos_id 等于 32759 是一个可核对的恒等式:vocab_size - len(SPECIAL_TOKENS) = 32768 - 9 = 32759 是可合并 token 的数量,9 个特殊 token 依次占用 32759 到 32767,而 <|bos|> 是 SPECIAL_TOKENS 的第一项,因此它的编号等于这个差值。若这一项不等于 vocab_size - 9,说明分词器被替换过或词表大小被改过。

8 CPU 与 MPS 的降级配置

无 GPU 时唯一被维护的路径是 runs/runcpu.sh。它把模型缩到能在几十分钟内跑完,参数选择都有明确的理由。

参数取值理由
--depth6384 维、6 层,参数量约
--head-dim64默认 128 会让 384 维只能切 3 头,64 给出 6 头
--window-patternLSDPA 的滑动窗口实现需要显式掩码,全上下文更快
--max-seq-len512激活与 logits 显存按 线性下降
--device-batch-size32单进程无累积
--total-batch-size16384手工指定,不触发自动批推导
--num-iterations5000共 token
--core-metric-every-1训练中不跑 CORE,避免数十分钟的评测

--head-dim=64 这一项容易被忽略:build_model_meta 用 model_dim // head_dim 得到头数,同时把 model_dim 向上取整到 head_dim 的倍数。depth 6、aspect 64 给出 384,384 是 64 的倍数,因此宽度不变而头数从 3 变为 6。

Apple Silicon 走 MPS 分支。默认精度是 fp32,可选用 NANOCHAT_DTYPE=bfloat16 换取约四分之一的显存下降与相近的速度;runcpu.sh 不带该变量,因此在 M 系列上默认跑 fp32。

CPU 与 MPS 都只能验证代码路径。DEVICE_BATCH_SIZE 与 total_batch_size 的整除断言在这里仍然生效:若把 runcpu.sh 的 --total-batch-size=16384 直接用于 torchrun --nproc_per_node=8,则 ,断言 total_batch_size % world_tokens_per_fwdbwd == 0 失败。

9 Linux 与 Windows/WSL2 的差异

nanochat 的目标平台是 Linux 加 CUDA。仓库中的四个 run 脚本都是 bash,分布式训练依赖 NCCL,部分依赖是平台相关的二进制包。三种平台的能力边界如下。

维度Linux + CUDAWSL2 + CUDAWindows 原生
运行 runs/*.sh直接可跑直接可跑需要 Git Bash 且部分命令不可用
torchrun 多卡NCCL 可NCCL 可无 NCCL,多卡不可
FA3 内核可可平台 wheel 不确定
rustbpe 训练分词器可可平台 wheel 不确定,可能需 Rust 工具链
数据下载与 tokenizer 推理可可可
CPU 冒烟可可可

结论是分层的:Windows 原生适合读代码、下数据、做 CPU 冒烟;任何 GPU 训练都应在 WSL2 或 Linux 上做。WSL2 的关键前提是驱动装在 Windows 侧,WSL 内不需要也不能装 NVIDIA 驱动,只装 CUDA 运行时(cu128 wheel 已自带)。

WSL2 的搭建顺序如下,命令在 Ubuntu 发行版内执行。

# 1) 在 Windows PowerShell(管理员)中安装发行版,然后重启并进入 Ubuntu
#    wsl --install -d Ubuntu-22.04
# 2) 在 WSL 内确认 GPU 直通;应输出与 Windows 相同的显卡型号
nvidia-smi
# 3) 安装 uv 并克隆仓库;不要在 WSL 内复用 Windows 的 .venv
curl -LsSf https://astral.sh/uv/install.sh | sh
git clone https://github.com/karpathy/nanochat.git
cd nanochat
# 4) 安装 GPU 依赖;锁文件与 Linux 平台一致
uv sync --extra gpu
source .venv/bin/activate
python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"

第 3 步的警告有实际后果:Windows 与 Linux 的 wheel 平台标签不同,.venv 里的二进制不能在另一侧导入。若仓库放在 /mnt/c/... 这类跨文件系统路径上,uv 建环境与数据读写都会变慢,建议把仓库克隆到 WSL 的 ext4 文件系统(如 ~/nanochat)。

三个平台选择之外的第四个选项是远程 GPU 节点。runs/speedrun.sh 的设计假设正是一台空白的 8×H100 机器,本地只需要 ssh 与 screen;把环境问题放到节点上解决,本地保留代码与笔记,通常是成本最低的分工。

10 常见依赖问题

四个与依赖有关的高频故障,都有可判定的症状与单条修复命令。

依赖症状原因处理
rustbpeuv sync 阶段编译失败当前平台没有预编译 wheel,需要 Rust 工具链装 rustup 后重试,或改用 WSL2/Linux
kernels(FA3)首次导入卡住,或回退 SDPA运行时从 Hugging Face Hub 拉取内核,离线失败联网预热缓存,或接受 SDPA
uv 缓存No space left on device缓存与 .venv 占满磁盘uv cache clean,或用 UV_CACHE_DIR 换盘
torch 混装版本与 uv.lock 不一致曾在 .venv 外用 pip 装过 torch删 .venv 后用 uv sync 重装

最后一行与前一行是同一类问题:uv 认为环境已满足,但实际导入的是另一份包。判据是 python -c "import torch; print(torch.__file__)" 的路径是否落在仓库的 .venv 内。

在 nanochat 中的落地

位置作用写错或缺失的后果
pyproject.toml 的 [tool.uv.sources]把 torch 指向 cu128 或 cpu 索引装到 CPU wheel,cuda.is_available() 为 False
pyproject.toml 的 [tool.uv] default-groups = []使 dev 组不被默认安装以为装了 pytest,运行时 ModuleNotFoundError
.python-version固定解释器为 3.10用 3.12 时部分依赖的 wheel 缺失或行为差异
nanochat/common.py:get_base_dir唯一的产物根目录解析两套目录并行,找不到检查点与分词器
nanochat/dataset.py:BASE_URL 与 MAX_SHARD数据来源与验证分片固定点手动放数据时验证集取错文件
nanochat/tokenizer.py:get_tokenizer从基准目录读取 tokenizer.pkl未训练分词器时直接抛 FileNotFoundError
nanochat/tokenizer.py:get_token_bytes读取 token_bytes.pt 并断言存在bpb 无法计算,训练在启动阶段退出
runs/speedrun.sh 的环境段上述步骤的自动化版本手工操作时容易漏掉 activate 或 wait

关键直觉

环境的判据是「三个打印」,不是「安装成功」

一次可靠的搭建会在日志里留下三条可核对输出:torch.version.cuda 与 torch.cuda.is_available() 说明设备路径通,COMPUTE_DTYPE: ... (auto-detected: ...) 说明精度分支落在预期位置,vocab_size: 32768 与 bos_id: 32759 说明分词器与词表一致。三者中任一缺失,后续训练都可能在不报错的情况下走错分支。这与第 3 节的三方匹配、第 5 节的精度检测、第 6 节的分词器产物一一对应:环境不是一组安装动作,而是三组可验证的状态。

例子与代码

例 1:Linux 从零到可训练

# 变量集中在顶部,后续命令只引用变量,避免路径漂移
export NANOCHAT_BASE_DIR="$HOME/.cache/nanochat"
export OMP_NUM_THREADS=1
mkdir -p "$NANOCHAT_BASE_DIR"

# 1) 安装 uv(已安装则跳过)并创建环境
command -v uv >/dev/null 2>&1 || curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv
uv sync --extra gpu --group dev

# 2) 激活环境;torchrun 需要 .venv/bin 在 PATH 中
source .venv/bin/activate
which python          # 期望 .../nanochat/.venv/bin/python

# 3) 版本三方核对
python -c "import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available())"
nvidia-smi --query-gpu=name,memory.total,driver_version --format=csv

# 4) 精度与设备自检
python -c "
from nanochat.common import COMPUTE_DTYPE, COMPUTE_DTYPE_REASON
print(COMPUTE_DTYPE, COMPUTE_DTYPE_REASON)
"

第 1 步的 --group dev 不是可选项:default-groups = [] 使 dev 组默认不装,而 tests/ 下的用例需要 pytest。第 4 步的输出在 H100 上应为 torch.bfloat16 auto-detected: CUDA SM 90 (bf16 supported)。

例 2:数据与分词器的完成判据

# 数据:先 8 个分片供分词器使用,再补齐到 170 个
python -m nanochat.dataset -n 8
python -m nanochat.dataset -n 170

# 分片计数:170 个训练分片加 1 个验证分片
ls "$NANOCHAT_BASE_DIR/base_data_climbmix"/*.parquet | wc -l
# 期望 171

# 验证分片固定为最后一个编号
ls "$NANOCHAT_BASE_DIR/base_data_climbmix" | tail -1
# 期望 shard_06542.parquet

# 分词器:约 20 亿字符,词表 32768
python -m scripts.tok_train
python -m scripts.tok_eval

# 产物核对
ls -l "$NANOCHAT_BASE_DIR/tokenizer"

ls | tail -1 能给出验证分片,是因为 list_parquet_files 对文件名排序后取最后一个作为 val 分片,而五位数编号的字典序等于数值序。tok_eval 会同时加载 gpt2 与 cl100k_base 两个编码做压缩率对比,首次运行需要联网下载 tiktoken 的编码文件;离线环境下它会在这里失败,但不影响 tok_train 已写出的产物。

预期目录内容如下。token_bytes.pt 的大小与 vocab_size 同阶,因为它是 int32 向量。

tokenizer/
├── tokenizer.pkl        # tiktoken Encoding 的 pickle
└── token_bytes.pt       # torch.int32,长度 32768+9

例 3:不装 GPU 也能验证的降级路径

# CPU 环境:只装 cpu extra,跑官方冒烟脚本
uv sync --extra cpu
source .venv/bin/activate
bash runs/runcpu.sh

runcpu.sh 的规模是刻意压到最小的:深度 6、上下文 512、总批 16384、5000 步,在 M3 Max 上约 30 分钟(脚本注释)。它的作用是证明分词器、dataloader、优化器、检查点、SFT 与 CLI 六条路径都能走通;代价是模型完全没有能力,--core-metric-every=-1 避免了几十分钟的评测。

易错点

以下六条都能用一条命令复核

1. 复用 Windows 的 .venv 到 WSL。症状是 import torch 报 ModuleNotFoundError: No module named 'torch._C' 或平台标签错误。复核:python -c "import sys; print(sys.platform)" 与 .venv/pyvenv.cfg 中的 home 路径。

2. 同时指定两个 extra。uv sync --extra cpu --extra gpu 会因 [tool.uv] conflicts 直接失败。复核:grep -A3 "conflicts" pyproject.toml。

3. 忘记 source .venv/bin/activate 就运行 torchrun。torchrun 用系统 python 启动子进程,报 No module named nanochat。复核:which python 应指向仓库内的 .venv/bin/python。

4. 把 NANOCHAT_BASE_DIR 设成相对路径。get_base_dir 只做 os.path.join,相对路径会相对当前工作目录解析,换目录后产物分裂到两处。复核:python -c "from nanochat.common import get_base_dir; print(get_base_dir())" 必须输出绝对路径。

5. 认为 uv sync 会安装 dev 组。default-groups = [] 明确关闭了默认安装,pytest --version 会失败。复核:uv pip list | grep pytest。

6. 在缺少 token_bytes.pt 时先跑预训练。base_train.py 启动时即调用 get_token_bytes,断言失败并退出,日志看起来像数据问题。复核:ls ~/.cache/nanochat/tokenizer。

关联笔记

  • 前置 训练脚本与speedrun:给出 base_train.py 的启动顺序与产物命名,本篇只负责让这些脚本具备可运行的输入。
  • 后续 跑通speedrun脚本:假定本篇的三条打印均已通过,逐段解释端到端流水线。
  • 后续 常见问题踩坑:本篇的失败分支在那里按症状展开为故障树。
  • 前置 nanochat的Rust分词器实现:解释 rustbpe 与 tiktoken 的分工,以及 token_bytes 为何必须由此产生。
  • 跨库 PyTorch实战入门:通用原理见该篇,本篇只写 nanochat 的安装矩阵、精度开关与基准目录。

达标检测

  • [ ] 能说明 uv.lock、.python-version、pyproject.toml 三者各自固定了什么,以及缺一会出现什么漂移。
  • [ ] 能写出 cu128 wheel 对驱动的最低要求,并用 nvidia-smi 与 torch.version.cuda 两个输出互相核对。
  • [ ] 能根据 get_device_capability() 的返回值判断 COMPUTE_DTYPE、FA3 与 --fp8 三者是否可用。
  • [ ] 能给出 -n 8 与 -n 170 各自的数据量与用途,并说明验证分片为何总是第 6542 个。
  • [ ] 能运行第 7 节的自检脚本,并说明 bos_id = vocab_size - 9 的来源。
  • [ ] 能列举 Windows 原生无法完成的两项训练相关操作,并给出 WSL2 的替代路径。

参考来源

  • Karpathy, nanochat(commit 92d63d4),README.md 的 Setup 与 Precision 两节、pyproject.toml、.python-version —— 对应本篇的依赖清单、两个 extra 与精度默认值。
  • Karpathy, nanochat(commit 92d63d4),nanochat/common.py、nanochat/dataset.py、nanochat/tokenizer.py、scripts/tok_train.py —— 对应基准目录、数据下载协议、分词器产物与自检脚本的全部行为。
  • Astral, uv documentation(uv sync、uv python、uv cache、dependency groups 章节) —— 对应第 2 节的三层模型与命令表。
  • PyTorch documentation, CUDA semantics 与 torch.cuda.get_device_capability、torch.set_float32_matmul_precision —— 对应第 3 节的三方匹配与第 5 节的精度机制。
  • NVIDIA, CUDA C++ Programming Guide(compute capability 与 FP8 支持)与 CUDA on WSL User Guide —— 对应第 3 节的硬件能力表与第 9 节的 WSL2 前提。
  • Karpathy, rustbpe 仓库 —— 对应分词器训练依赖的 Rust 扩展与平台 wheel 问题。