本地环境搭建
定义
复现环境(reproducible environment)是一组确定的软件与路径状态,其并集足以让仓库中的任一脚本在目标机器上产生预期产物:解释器版本、依赖解析结果、CUDA 驱动与 PyTorch wheel 的匹配关系、精度开关的取值,以及所有中间产物的根目录。
本篇出现的术语与符号定义如下。
| 术语 | 含义 |
|---|---|
| uv | Astral 开发的 Python 包与项目管理器,nanochat 用它创建虚拟环境、解析依赖、生成锁文件 |
| 虚拟环境(venv) | 与系统 Python 隔离的解释器副本,nanochat 固定使用仓库根目录下的 .venv/ |
| extra | pyproject.toml 中 [project.optional-dependencies] 定义的可选依赖组,nanochat 有 cpu 与 gpu 两个 |
| 锁文件(lockfile) | uv.lock,记录每个包的确切版本、来源与哈希,使两次安装得到同一组 wheel |
| 计算能力(compute capability) | NVIDIA GPU 的架构版本号,记作 SM 主版本.次版本,如 A100 为 8.0、H100 为 9.0 |
COMPUTE_DTYPE | nanochat/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.10 | uv 托管的 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 dev | pytest、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_DTYPE | FA3 | --fp8 |
|---|---|---|---|---|
| H100 / H200 | 9.0 | bfloat16 | 可用(varunneal/flash-attention-3) | 可用 |
| A100 / A800 | 8.0 | bfloat16 | 可用(kernels-community/flash-attn3,需已缓存) | 不可用 |
| L40S / RTX 4090 | 8.9 | bfloat16 | 可用(同上,需已缓存) | 可用 |
| B200 / GB200 | 10.0 | bfloat16 | 回退 SDPA | 可用 |
| V100 / T4 | 7.0 / 7.5 | float32 | 回退 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.pkl | tokenizer.save(tokenizer_dir) | pickle 序列化的 tiktoken 编码,供 get_tokenizer() 读取 |
tokenizer/token_bytes.pt | tok_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。它把模型缩到能在几十分钟内跑完,参数选择都有明确的理由。
| 参数 | 取值 | 理由 |
|---|---|---|
--depth | 6 | 384 维、6 层,参数量约 |
--head-dim | 64 | 默认 128 会让 384 维只能切 3 头,64 给出 6 头 |
--window-pattern | L | SDPA 的滑动窗口实现需要显式掩码,全上下文更快 |
--max-seq-len | 512 | 激活与 logits 显存按 线性下降 |
--device-batch-size | 32 | 单进程无累积 |
--total-batch-size | 16384 | 手工指定,不触发自动批推导 |
--num-iterations | 5000 | 共 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 + CUDA | WSL2 + CUDA | Windows 原生 |
|---|---|---|---|
运行 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 常见依赖问题
四个与依赖有关的高频故障,都有可判定的症状与单条修复命令。
| 依赖 | 症状 | 原因 | 处理 |
|---|---|---|---|
rustbpe | uv 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 问题。