---
tags: [nanochat, repro, environment]
阶段: 10-复现与实验
难度: ★★☆
created: 2026-10-22
related: "[[跑通speedrun脚本]], [[常见问题踩坑]], [[训练脚本与speedrun]], [[PyTorch实战入门]]"
---

# 本地环境搭建

## 定义

**复现环境**（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 |

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

## 为什么重要

环境决定了「能复现」这条主线能否开始，而它的失败方式往往不报错。`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` 不能同时安装，因为二者给出同一个包的两个不同来源：

```text
[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 构建。安装后可用两条命令核对：

```bash
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()` 是所有路径的唯一来源：

```python
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` 在导入时执行一次检测：

```python
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()` 的断言会给出明确提示：

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

### 7 环境自检的最小命令

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

```python
# 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 节点上的预期输出如下，行序即执行顺序。

```text
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 层，参数量约 $2.3\times10^{7}$ |
| `--head-dim` | 64 | 默认 128 会让 384 维只能切 3 头，64 给出 6 头 |
| `--window-pattern` | L | SDPA 的滑动窗口实现需要显式掩码，全上下文更快 |
| `--max-seq-len` | 512 | 激活与 logits 显存按 $T$ 线性下降 |
| `--device-batch-size` | 32 | 单进程无累积 |
| `--total-batch-size` | 16384 | 手工指定，不触发自动批推导 |
| `--num-iterations` | 5000 | 共 $8.19\times10^{7}$ 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`，则 $16384 < 32\times512\times8=131072$，断言 `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 发行版内执行。

```bash
# 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` |

## 关键直觉

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

## 例子与代码

### 例 1：Linux 从零到可训练

```bash
# 变量集中在顶部，后续命令只引用变量，避免路径漂移
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：数据与分词器的完成判据

```bash
# 数据：先 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 向量。

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

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

```bash
# 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` 避免了几十分钟的评测。

## 易错点

> [!warning] 以下六条都能用一条命令复核
> 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 问题。
