---
tags: [nanochat, pretraining, distributed]
阶段: 05-预训练Pretraining
难度: ★★★
created: 2026-10-22
related: "[[Muon优化器]], [[检查点与恢复]], [[缩放定律与模型深度]], [[分布式训练与部署]]"
---

# 分布式训练与优化器分片

## 定义

nanochat 的分布式训练是**数据并行 + 优化器内同步 + 优化器状态分片**：每个 rank 持有完整的模型参数、只处理不同的数据子集，梯度在优化器 `step()` 内部用集合通信规约，优化器状态按 rank 分片存储（ZeRO-2 式）。

符号与术语定义如下。

- **rank**：进程编号 $r\in\{0,\dots,N-1\}$。**world size** $N$：进程总数。
- **`RANK` / `LOCAL_RANK` / `WORLD_SIZE`**：`torchrun` 注入的环境变量，分别是全局进程序号、节点内 GPU 序号、进程总数。三者同时存在即表示「由 torchrun 启动」。
- **进程组**（process group）：集合通信的作用域。nanochat 用 `nccl` 后端，每个进程绑定 `LOCAL_RANK` 对应的 GPU。
- **梯度累积**（gradient accumulation）：在一个优化器步内做 $G$ 次前向与反向，把梯度累加后再更新一次。$G$ 由全局批大小除以「单卡批大小 × 序列长度 × world size」得到。
- **ZeRO-2**：只分片优化器状态、不分片参数的方案（ZeRO 论文的第二阶段）。nanochat 的参数在所有 rank 上复制，`exp_avg`、`exp_avg_sq`、`momentum_buffer` 等状态按 rank 切分。
- **all_reduce**：所有 rank 的输入求和（或取平均、最大），结果写回所有 rank。
- **reduce_scatter**：先按 rank 数把张量切成 $N$ 份，规约后第 $r$ 个 rank 只保留第 $r$ 份。
- **all_gather**：每个 rank 贡献一份，所有 rank 得到拼接后的完整张量。
- **`ReduceOp.AVG`**：PyTorch 的规约算子，等价于求和后除以 world size。
- **chunk**：Muon 参数组按 rank 切分后，单个 rank 负责的参数个数 $\lceil K/N\rceil$，$K$ 为该组的参数个数。

## 为什么重要

它决定了 8 卡能否被有效利用。speedrun 的默认配置是 `torchrun --nproc_per_node=8`，单卡批 16、序列 2048、总批 $2^{20}$ token，因此每步要做 4 次梯度累积、跨越 8 个 rank，共 32 个微批。若同步逻辑有误，最直接的后果是梯度被放大或缩小 $N$ 倍，损失曲线在几千步内失真。

它决定了显存能否装下训练。d24 的总参数为 1,384,122,122；若不分片，仅 value embeddings 一项的参数、梯度与两份 fp32 矩合计约 9.7 GB（每元素 16 字节），分摊到 8 个 rank 后每 rank 的优化器状态约 0.72 GB（估算见第 9 节）。

它也决定了 checkpoint 的形态：优化器状态分片是 `optim_{step}_rank{r}.pt` 存在的原因，而模型参数不分片是 `model_{step}.pt` 只需 rank 0 保存的原因。

在三个维度中，本篇属于「懂工程」：机制不复杂，但每一处都对应一个可测量的失败模式。

## 原理与推导

### 1. 启动与进程组

`torchrun --standalone --nproc_per_node=8` 为每个 GPU 启动一个进程，并注入 `RANK`、`LOCAL_RANK`、`WORLD_SIZE`。`nanochat/common.py` 的 `is_ddp_requested()` 用「三个变量是否同时存在」判断是否应该初始化进程组：

```python
def is_ddp_requested() -> bool:
    return all(k in os.environ for k in ("RANK", "LOCAL_RANK", "WORLD_SIZE"))

def compute_init(device_type="cuda"):
    # 为聚焦关键步骤只保留核心行；随机种子、tf32 与设备可用性检查见 nanochat/common.py 原文
    is_ddp_requested, ddp_rank, ddp_local_rank, ddp_world_size = get_dist_info()
    if is_ddp_requested and device_type == "cuda":
        device = torch.device("cuda", ddp_local_rank)
        torch.cuda.set_device(device)   # 让 "cuda" 默认指向本 rank 的卡
        dist.init_process_group(backend="nccl", device_id=device)
        dist.barrier()
    else:
        device = torch.device(device_type)
    return is_ddp_requested, ddp_rank, ddp_local_rank, ddp_world_size, device
```

三个细节。第一，返回值的第一个元素虽然被调用方命名为 `ddp`，但它只是一个布尔标志，没有任何 DDP 包装器被创建。第二，`compute_init` 还设置 `torch.manual_seed(42)`、`torch.set_float32_matmul_precision("high")`（启用 tf32）与 `device`，因此所有 rank 的初始化状态一致。第三，`dist.barrier()` 在所有 rank 完成初始化后同步一次，避免某些 rank 提前进入数据下载或文件写入。

### 2. 数据并行下的批大小与梯度语义

每一步的有效 token 数由三层乘法决定：

$$
D_{\text{step}}=\underbrace{B_{\text{dev}}}_{\text{单卡批}}\times\underbrace{T}_{\text{序列长度}}\times N\times G .
$$

`scripts/base_train.py` 先做整除断言，再求 $G$：

```python
tokens_per_fwdbwd = args.device_batch_size * args.max_seq_len        # 单 rank 一个微批
world_tokens_per_fwdbwd = tokens_per_fwdbwd * ddp_world_size        # 全部 rank 一个微批
assert total_batch_size % world_tokens_per_fwdbwd == 0, \
    f"total_batch_size ({total_batch_size}) must be a multiple of {world_tokens_per_fwdbwd}."
grad_accum_steps = total_batch_size // world_tokens_per_fwdbwd
```

d24 的当前配置代入：$B_{\text{dev}}=16$、$T=2048$、$N=8$，得到 world 微批 $262{,}144$ token；自动批大小为 $2^{20}=1{,}048{,}576$，因此 $G=4$。每个微批的损失先除以 $G$ 再反传（`loss = loss / grad_accum_steps`），优化器内部再用 `ReduceOp.AVG` 跨 rank 平均，于是最终梯度是全部 $N\cdot G$ 个微批的全局均值：

$$
\nabla L=\frac{1}{NG}\sum_{r=1}^{N}\sum_{g=1}^{G}\nabla L_{r,g}.
$$

这条等价关系解释了为什么不需要额外乘以 world size：除以 $G$ 与 AVG 各承担一部分归一化。

### 3. 为什么不用 DDP

DDP 的工作方式是在反向传播时按桶（bucket）触发 `all_reduce`，把梯度同步与反传重叠，并在结束时保证每个 rank 的梯度一致。nanochat 放弃这条路径，原因有三。

第一，Muon 需要按参数形状分组、堆叠后整体处理。若由 DDP 先逐参数规约，优化器仍要重新堆叠，通信与计算都多一次搬运。第二，优化器状态要按 rank 分片，而分片的边界是「参数组内的 chunk」，与 DDP 的桶边界无关；把规约放在优化器里，规约结果直接落在分片所需的布局上。第三，单卡与多卡可以用同一份代码：`MuonAdamW` 在 `world_size == 1` 时跳过全部集合通信，所有分片代码退化为整张量更新。

代价是失去 DDP 的自动重叠。nanochat 用显式的三段式异步通信补回来（下一节）。

### 4. 三阶段异步通信

`MuonAdamW.step` 把每一步的通信与计算排成三个阶段，目的是让「先完成的组的通信」与「后完成的组的计算」重叠。

第一阶段：为所有参数组发起异步规约。AdamW 组走 `_reduce_adamw`，Muon 组走 `_reduce_muon`，得到一组 future，不等待。

第二阶段：按参数组顺序，等待该组的规约完成、计算更新、再发起异步 gather。由于组之间串行处理，先处理的组发起 gather 后，其传输与后处理组的计算并行。

第三阶段：等待所有 gather 完成，把结果写回原始参数张量。

这一结构的关键是不引入全局屏障：每个组只等待自己的 future。若改成「先全部等待再全部计算」，通信与计算完全串行，重叠带来的收益全部消失。

### 5. AdamW 组的通信

参数按元素数分成两类，路径不同。

小于 1024 个元素的参数（`resid_lambdas` 24 个、`x0_lambdas` 24 个、`smear_gate.weight` 24 个、`smear_lambda` 1 个、`backout_lambda` 1 个）走 `all_reduce`：规约后每个 rank 都持有完整梯度，各自更新完整参数。这些张量极小，复制状态的代价可忽略。注意 value embedding 的门 `ve_gate` 不在其中：它位于 `transformer.h` 内，被归入 Muon 的矩阵参数组。

大于等于 1024 个元素的参数（`wte`、`lm_head`、12 个 value embedding）走 reduce_scatter：

```python
assert grad.shape[0] % world_size == 0, \
    f"AdamW reduce_scatter requires shape[0] ({grad.shape[0]}) divisible by world_size ({world_size})"
rank_size = grad.shape[0] // world_size
grad_slice = torch.empty_like(grad[:rank_size])
future = dist.reduce_scatter_tensor(grad_slice, grad, op=dist.ReduceOp.AVG, async_op=True).get_future()
param_infos[p] = dict(future=future, grad_slice=grad_slice, is_small=False)
```

更新时只对本 rank 的切片调用融合 AdamW 核，状态 `exp_avg`、`exp_avg_sq` 也只为该切片分配。更新完成后 `all_gather_into_tensor(p, p_slice)` 把切片写回完整参数。这要求第 0 维能被 world size 整除；对 d24，`wte`、`lm_head`、value embeddings 的第 0 维都是 32768，除以 8 得 4096，满足条件。

### 6. Muon 组的通信

Muon 的参数是 2D 矩阵。`setup_optimizer` 先按形状分组，同形状的参数才能堆叠；`step` 再把每组的 $K$ 个梯度堆成一个 $(K,\cdot,\cdot)$ 张量。

```python
chunk_size = (len(params) + world_size - 1) // world_size      # ceil(K/N)
padded_num_params = chunk_size * world_size
grad_stack = torch.stack([p.grad for p in params])
stacked_grads = torch.empty(padded_num_params, *shape, dtype=dtype, device=device)
stacked_grads[:len(params)].copy_(grad_stack)
if len(params) < padded_num_params:
    stacked_grads[len(params):].zero_()                       # 零填充，仅为通信对齐
grad_chunk = torch.empty(chunk_size, *shape, dtype=dtype, device=device)
future = dist.reduce_scatter_tensor(grad_chunk, stacked_grads, op=dist.ReduceOp.AVG, async_op=True).get_future()
```

于是每个 rank 只拿到 `chunk_size` 个参数的梯度，只对这些参数做 Polar Express 正交化、方差缩放与 cautious 权重衰减，状态 `momentum_buffer`、`second_momentum_buffer` 也只按 chunk 分配。更新后：

```python
updated_params = torch.empty(chunk_size, *shape, dtype=dtype, device=device)
updated_params[:num_owned].copy_(stacked_owned)
if num_owned < chunk_size:
    updated_params[num_owned:].zero_()
stacked_params = info["stacked_grads"]          # 复用 reduce 的输入缓冲
future = dist.all_gather_into_tensor(stacked_params, updated_params, async_op=True).get_future()
gather_list.append(dict(future=future, stacked_params=stacked_params, params=params))
```

最后在第三阶段用 `torch._foreach_copy_` 把堆叠张量的前 $K$ 行拆回各个参数。复用一个缓冲区是显式设计：`stacked_grads` 在规约完成后已经无用，把它当作 gather 的输出可以省下一份与参数量同大的显存。

以 d24、8 卡为例，Muon 组的实际切分是：

| 参数形状 | $K$ | chunk $\lceil K/8\rceil$ | 填充后 | 每 rank 覆盖的参数 |
|---|---|---|---|---|
| $(1536,1536)$（每层 q/k/v/proj） | 96 | 12 | 96 | 12 |
| $(6144,1536)$（MLP `c_fc`） | 24 | 3 | 24 | 3 |
| $(1536,6144)$（MLP `c_proj`） | 24 | 3 | 24 | 3 |
| $(12,12)$（value embedding 门） | 12 | 2 | 16 | 2（填充 4 个） |

最后一行说明填充确实会发生：$K=12$ 不能被 8 整除，填充到 16 后规约，gather 回来再忽略后 4 行。

### 7. 单卡退化

`world_size == 1` 时两条路径都跳过通信。AdamW 把 `future` 置为 `None`、`is_small` 置为 `True`，更新完整参数；Muon 直接把参数堆叠成 `grad_chunk`，`stacked_grads` 置为 `None`，`_compute_muon` 跳过 `all_gather`，改在第三阶段把堆叠结果直接映射回参数。这样单卡与 8 卡共用同一份优化器代码，不需要分支版本。

### 8. fp16 的 GradScaler 与 inf 同步

`COMPUTE_DTYPE` 为 fp16 时启用 `torch.amp.GradScaler`（bf16 与 fp32 不需要，因为 bf16 与 fp32 的指数范围相同）。fp16 训练中某 rank 可能独立遇到 inf/nan 梯度，若各 rank 自行决定是否跳步，参数会永久错位。`scripts/base_train.py` 用一次 `MAX` 规约强制所有 rank 同步决定：

```python
scaler.unscale_(optimizer)
if is_ddp_initialized():
    for v in scaler._found_inf_per_device(optimizer).values():
        dist.all_reduce(v, op=dist.ReduceOp.MAX)   # 任一 rank 有 inf，全体跳步
scaler.step(optimizer)
scaler.update()
```

这是训练步内、优化器之外唯一一处显式集合通信；评测阶段另有 `evaluate_bpb` 与 `evaluate_task` 的 `all_reduce`，但不属于训练步。

### 9. 一步的通信量估算

设参数组 $g$ 的元素数为 $S_g$、元素字节数为 $b_g$，环形算法下单 rank 的收发总量为

$$
V=\frac{2(N-1)}{N}\sum_g b_g S_g .
$$

d24 的各项代入（矩阵参数为 fp32 主权重，`wte` 与 value embeddings 为 bf16，`lm_head` 为 fp32）：

| 组 | 元素数 | dtype | 字节 |
|---|---|---|---|
| Muon 矩阵 | 679,478,976 | fp32 | 2.72 GB |
| `wte` | 50,331,648 | bf16 | 0.10 GB |
| value embeddings | 603,979,776 | bf16 | 1.21 GB |
| `lm_head` | 50,331,648 | fp32 | 0.20 GB |
| 合计 $S$ | | | 4.23 GB |

取 $N=8$：$V=2\times(7/8)\times4.23=7.40$ GB/rank。H100 SXM 的 NVLink 双向带宽标称 900 GB/s，单向有效带宽按一半计约 450 GB/s，则纯传输时间约 $7.40/450\approx16.4$ ms。对照 d24、ratio 8 的运行（1.65 小时、5568 步，反推约 1.07 s/步），通信占比约 1.5%，且大部分被三段式结构掩盖。这说明在此规模下通信不是瓶颈；分片的主要动机是显存，而不是带宽。

### 在 nanochat 中的落地

第一处是 `nanochat/common.py` 的 `compute_init`。它把进程组初始化、设备绑定、随机种子与 tf32 设置集中到一个函数，所有脚本（`base_train.py`、`base_eval.py`、`chat_sft.py` 等）都调用它。这样做的收益是行为一致：任何脚本在 8 卡下的默认设备与精度相同。

第二处是 `nanochat/optim.py` 的 `MuonAdamW.step`。它是全仓库唯一做梯度规约的地方，也是唯一知道「参数如何分组、状态如何分片」的地方。把这两个职责放在一起，是因为分片边界必须与通信单位一致；若拆开，任何分组改动都要同步修改两处。

第三处是 `nanochat/checkpoint_manager.py` 的 `save_checkpoint`：因为状态分片，每个 rank 都要调用保存，`optim_{step}_rank{r}.pt` 的 rank 后缀不是调试信息而是数据契约。

## 关键直觉

> [!tip] 同步点从「反向传播的钩子」移到「优化器的参数组」，通信单位因此与参数分组绑定
> DDP 的通信单位是桶，桶按张量大小装箱，与优化算法无关；nanochat 的通信单位是参数组，而参数组由「形状相同、优化方式相同」定义。这样一次 `reduce_scatter` 就能同时完成三件事：规约梯度、把结果放到本 rank 的切片位置、让状态分配与分片边界对齐。与严格定义的关系：定义中的「优化器内同步」不是实现风格，而是让 ZeRO-2 分片与 Muon 堆叠共享同一次数据搬运的必要条件。

## 例子与代码

### 1. 启动一次 8 卡训练

```bash
# runs/speedrun.sh 中的实际命令（预训练部分）
OMP_NUM_THREADS=1 torchrun --standalone --nproc_per_node=8 -m scripts.base_train -- \
    --depth=24 \
    --target-param-data-ratio=8 \
    --device-batch-size=16 \
    --fp8
```

`--standalone` 表示不需要外部 rendezvous 服务，由 torchrun 自己选端口。`--nproc_per_node=8` 必须与实际 GPU 数一致；单卡实验直接去掉 `torchrun` 前缀用 `python -m scripts.base_train`，此时 `compute_init` 返回 `world_size=1`，全部通信路径退化。

### 2. 计算分组与通信量

```python
# 独立运行：按 nanochat 的规则复算 d24 在 8 卡下的 chunk 与每步通信量
N = 8
muon_groups = {"1536x1536": 96, "6144x1536": 24, "1536x6144": 24, "12x12": 12}
for shape, K in muon_groups.items():
    chunk = (K + N - 1) // N
    print(f"{shape:>10}: K={K:>3} chunk={chunk} padded={chunk * N} 填充={chunk * N - K}")

payload_bytes = 679_478_976 * 4 + 50_331_648 * 2 + 603_979_776 * 2 + 50_331_648 * 4
traffic = 2 * (N - 1) / N * payload_bytes
print(f"payload={payload_bytes/1e9:.2f} GB  per-rank={traffic/1e9:.2f} GB")
print(f"传输下界={traffic/450e9*1e3:.1f} ms")
# 预期：1536x1536: K= 96 chunk=12 padded=96 填充=0
# 预期：  12x12: K= 12 chunk= 2 padded=16 填充=4
# 预期：payload=4.23 GB  per-rank=7.40 GB
# 预期：传输下界=16.4 ms
```

### 3. 观察一次梯度同步是否正确

```python
# 独立运行：验证「除以 G 再 AVG」与「全局均值」等价
import torch
G, N = 4, 8
local_grads = torch.randn(G, N, dtype=torch.float64)     # 模拟每个 rank 的 G 个微批梯度
manual = local_grads.mean()                               # 全局均值
scaled = (local_grads / G).sum(dim=0).mean()              # 每微批除以 G，跨 rank 取 AVG
print(float(manual), float(scaled))                       # 两者应相等
```

这个恒等式是排查「梯度被放大 N 倍」类问题的出发点：若损失曲线在 8 卡下比单卡陡 $N$ 倍，说明 AVG 被误改成 SUM，或除法被漏掉。

## 易错点

> [!warning] 六个可检验的错误
> 1. 看到 `ddp` 变量就以为模型被 DDP 包装。`compute_init` 返回的第一项只是「是否由 torchrun 启动」的布尔；`scripts/base_train.py` 里没有 `DistributedDataParallel`，梯度同步全部在优化器内。
> 2. 认为 reduce_scatter 对任何形状都可用。AdamW 大参数路径断言 `grad.shape[0] % world_size == 0`；当前大参数的第 0 维是补齐到 64 的倍数的词表维度（d24 为 32768），因此 world size 必须整除 32768，而不是只要求整除 64。8 卡与 128 卡成立，3 卡会触发断言。
> 3. 在 8 卡下自行把损失乘以 world size。正确的归一化是「除以 $G$（累积步数）+ AVG（跨 rank 平均）」；再乘 $N$ 会使梯度放大 $N$ 倍。
> 4. 认为单卡也会走 all_gather。`world_size == 1` 时 `_reduce_muon` 返回 `stacked_grads=None`，`_compute_muon` 跳过 gather 分支；若在单卡上依赖 gather 的副作用会拿到空值。
> 5. 在 Muon 组里混入不同形状的参数。`setup_optimizer` 按 `p.shape` 分组后再 `torch.stack`；手工构造优化器时若同组形状不一致，堆叠会直接报错。
> 6. fp16 训练时忽略 `found_inf` 的 MAX 规约。各 rank 独立判断会导致「有的 rank 更新、有的跳过」，参数从此不再一致，而损失可能在数百步后才显现异常。

## 关联笔记

- 前置 [[Muon优化器]]：Polar Express、NorMuon 方差缩放与 cautious 权重衰减的数学形式，本篇只讲它们在多卡下如何分片。
- 对照 [[检查点与恢复]]：`optim_{step}_rank{r}.pt` 的存在原因即本篇第 5、6 节的分片。
- 后续 [[缩放定律与模型深度]]：总批大小、梯度累积步数与深度的联动。
- 跨库 [[分布式训练与部署]]：通用原理见该篇（集合通信原语、ZeRO 三阶段、张量并行），本篇只讲 nanochat 把同步放进优化器的落地方式。

## 达标检测

- [ ] 能说明 `RANK`、`LOCAL_RANK`、`WORLD_SIZE` 三者的区别，以及 `compute_init` 用它们做了什么。
- [ ] 能写出 $D_{\text{step}}=B_{\text{dev}}\cdot T\cdot N\cdot G$ 并代入 d24 的当前配置得到 $G=4$。
- [ ] 能解释为什么 nanochat 不用 DDP，并列出至少两条具体理由。
- [ ] 能按顺序复述三段式通信的三个阶段，并说明若改成「全部等待再全部计算」会损失什么。
- [ ] 能区分 AdamW 的小参数与大参数路径，并指出 reduce_scatter 的整除前提。
- [ ] 能计算 d24 在 8 卡下 Muon 四个形状组的 chunk 与填充量，指出哪一组发生填充。
- [ ] 能按 $V=2(N-1)/N\sum b_gS_g$ 估算 d24 的每步通信量，并给出与实测步时的比值。
- [ ] 能说明单卡时优化器的哪些分支被跳过。

## 参考来源

- Karpathy, *nanochat*（commit 92d63d4），`nanochat/optim.py` —— 对应本篇第 3 至 7 节的全部通信逻辑与单卡退化。
- Karpathy, *nanochat*（commit 92d63d4），`nanochat/common.py` 与 `scripts/base_train.py` —— 对应进程组初始化、梯度累积与 fp16 inf 同步。
- Rajbhandari et al., *ZeRO: Memory Optimizations Toward Training Trillion Parameter Models*（1910.02054）—— 对应优化器状态分片（ZeRO-2）的定义与动机。
- Karpathy, *nanochat*（commit 92d63d4），`dev/LOG.md` 2026-01-08 条目 —— 对应「本仓库不使用 DDP，梯度同步在优化器中」的明确记录与梯度裁剪排错经验。
- Karpathy, *modded-nanogpt* —— 对应 Muon 优化器与通信/计算重叠设计的来源。
