---
tags: [nanochat, math, loss]
阶段: 02-数学与工程基础
难度: ★★☆
created: 2026-10-22
related: "[[softmax与softmax温度]], [[损失函数]], [[模型评估矩阵]]"
---

# 交叉熵与困惑度

## 定义

给定模型对第 $t$ 个位置输出的 logits 向量 $\mathbf{z}^{(t)}\in\mathbb{R}^{V}$ 与真实的下一个 token $y_t\in\{0,\dots,V-1\}$，**交叉熵**（cross-entropy, CE）定义为该 token 在模型分布下负对数似然：

$$
\ell_t=-\ln p_\theta(y_t\mid x_{<t})
=-\ln\frac{\exp(z^{(t)}_{y_t})}{\sum_{j=1}^{V}\exp(z^{(t)}_{j})}.
$$

符号与术语：

- $V$：词表大小，nanochat 为 32768。
- $z^{(t)}_{j}$：第 $t$ 个位置对第 $j$ 个 token 的 logit；$y_t$ 为目标 token 的编号。
- $\ell_t$：第 $t$ 个位置的损失，单位 nat；若目标位置被忽略（`ignore_index=-1`），约定 $\ell_t=0$。
- **负对数似然**（negative log-likelihood, NLL）：$-\ln p_\theta(y\mid x)$，与 CE 在 one-hot 目标下完全相同。
- **批次平均**：$\bar\ell=\frac{1}{N}\sum_{t=1}^{N}\ell_t$ 只对有效（非忽略）位置求和；训练时再除以梯度累积步数。
- **困惑度**（perplexity, PPL）：$\mathrm{PPL}=\exp(\bar\ell)$，单位无量纲，可理解为模型在每一步「等效犹豫的候选数」。
- **bpb**（bits per byte）：$\mathrm{bpb}=\dfrac{\sum_t\ell_t}{\ln 2\cdot\sum_t b(y_t)}$，其中 $b(y)$ 是 token $y$ 解码后的字节数；特殊 token 的 $b=0$。
- **token 字节表**：`token_bytes`，一维整型张量，长度为词表大小，第 $i$ 项是 token $i$ 的字节数，特殊 token 为 0。

## 为什么重要

- 预训练、SFT、RL 三个阶段的目标函数都建立在交叉熵或其变体上。nanochat 的 `base_train.py` 每一步计算的就是 `F.cross_entropy(logits, targets, ignore_index=-1)`，训练是否正常首先看这条曲线。
- 交叉熵的梯度有极简形式 $\partial\ell/\partial\mathbf{z}=\mathbf{p}-\mathbf{e}_y$；这一条同时解释了为什么 logits 需要用 fp32、为什么 softcap 会影响梯度尺度、以及为什么采样与训练共享同一套 softmax 实现，见 [[softmax与softmax温度]]。
- 词表大小可变意味着 per-token 损失不可比。把 token 级损失换算成字节级 bpb 之后，换分词器、换词表、换数据配比仍然可以比较。nanochat 用 val bpb 而不是 val loss 作为与 GPT-2 对比的指标，原因就在这里。
- `ignore_index=-1` 是 SFT 掩码的实现基础：只有 assistant 侧 token 参与损失，用户消息、特殊 token、工具输出与 padding 全部置 $-1$。不理解这一条就无法解释 SFT 的损失为何显著低于预训练。
- 在全书中的位置：前置是 [[softmax与softmax温度]]，后续被 05 阶段的训练脚本与 08 阶段的评测共用；通用推导见 [[损失函数]]（跨库），本篇只讲 nanochat 的落地与 bpb 的实现。

## 原理与推导

### 1. 从最大似然到交叉熵

设数据分布为 $p_{\text{data}}(y\mid x)$，模型分布为 $p_\theta(y\mid x)$。最大似然估计最大化训练集上的对数似然：

$$
\hat\theta=\arg\max_\theta\frac{1}{N}\sum_{t=1}^{N}\ln p_\theta(y_t\mid x_{<t})
=\arg\min_\theta\Big(-\frac{1}{N}\sum_{t=1}^{N}\ln p_\theta(y_t\mid x_{<t})\Big),
$$

括号内即平均交叉熵。把它写成期望形式：

$$
\mathbb{E}_{p_{\text{data}}}\big[-\ln p_\theta(y\mid x)\big]
=\underbrace{\mathbb{E}_{p_{\text{data}}}\big[-\ln p_{\text{data}}(y\mid x)\big]}_{H(p_{\text{data}})}
+\underbrace{\mathbb{E}_{p_{\text{data}}}\Big[\ln\frac{p_{\text{data}}(y\mid x)}{p_\theta(y\mid x)}\Big]}_{D_{\mathrm{KL}}(p_{\text{data}}\,\|\,p_\theta)} .
$$

第一项是数据自身的熵，与 $\theta$ 无关；因此最小化交叉熵等价于最小化 KL 散度。这条分解也说明交叉熵的下界是数据熵：损失降到 $H(p_{\text{data}})$ 以下意味着模型在记忆训练集。

### 2. one-hot 目标下的化简

设目标写成 one-hot 向量 $\mathbf{y}\in\{0,1\}^{V}$，$\sum_j y_j=1$，则交叉熵的一般形式

$$
\ell=-\sum_{j=1}^{V}y_j\ln p_j
$$

只剩一项 $-\ln p_{y}$。把 softmax 代入并取对数：

$$
\ell=-\ln\frac{e^{z_y}}{\sum_j e^{z_j}}
=\ln\sum_{j=1}^{V}e^{z_j}-z_y .
$$

这就是「log-sum-exp 减目标 logit」的写法，也是 `F.cross_entropy` 的数值实现形式。它不需要显式构造概率向量，因此不会出现 $p_y$ 下溢为 0 导致 $\ln0=-\infty$ 的情况。

对 logits 求梯度，把 softmax 的雅可比 $\partial p_i/\partial z_j=p_i(\delta_{ij}-p_j)$ 代入 $\ell=-\ln p_y$：

$$
\frac{\partial\ell}{\partial z_j}=-\frac{1}{p_y}\frac{\partial p_y}{\partial z_j}
=-\frac{1}{p_y}\,p_y(\delta_{yj}-p_j)=p_j-\delta_{yj},
$$

即

$$
\nabla_{\mathbf{z}}\ell=\mathbf{p}-\mathbf{e}_y .
$$

梯度是「预测分布减 one-hot 目标」，范数上限为 $\sqrt2$，与 logits 的绝对尺度无关。这一点很重要：无论 logits 被 softcap 压缩到多小，CE 对 logits 的梯度都不会爆炸，爆炸只可能来自上游的反向传播。

### 3. 批次平均与忽略位置

长度为 $T$ 的序列会产生 $T$ 个位置（`targets` 是 `inputs` 右移一位），一个 batch 共 $BT$ 个损失。训练使用平均：

$$
\mathcal{L}=\frac{1}{|\mathcal{V}|}\sum_{t\in\mathcal{V}}\ell_t,\qquad
\mathcal{V}=\{t:\ y_t\ne-1\},
$$

$|\mathcal{V}|$ 是有效位置数。PyTorch 的 `reduction='mean'` 在设置 `ignore_index` 时按有效位置数取平均，而不是按全部位置数；可核对的行为是：三个位置中一个被忽略时，`mean` 等于 `sum/2` 而不是 `sum/3`。

nanochat 的 SFT 数据加载器正是依赖这一点：`mask[1:]` 与 `targets`（右移一位）对齐，掩码为 0 的位置写入 $-1$，padding 位置同样写入 $-1$。

**梯度累积**下的平均要分两层：每个 micro-batch 先算自己的平均损失，再除以 `grad_accum_steps` 后反向，使累积梯度等于整个大批次的平均梯度。

$$
\nabla\mathcal{L}=\frac{1}{A}\sum_{a=1}^{A}\nabla\mathcal{L}_a,\qquad A=\texttt{grad\_accum\_steps}.
$$

### 4. 困惑度

困惑度定义为平均损失的指数：

$$
\mathrm{PPL}=\exp(\bar\ell).
$$

若模型对每个位置都给出均匀分布，则 $\bar\ell=\ln V$，$\mathrm{PPL}=V$：模型在 $V$ 个候选之间完全无法区分。因此 PPL 可以读作「等效候选数」。$\bar\ell=\ln10$ 对应 $\mathrm{PPL}=10$，$\bar\ell=\ln100$ 对应 100。

PPL 的缺陷是依赖词表：换一个把常见词合并成单 token 的分词器，per-token 损失会下降，但模型并没有变好。这是第 5 节引入 bpb 的原因。

### 5. 从 nat 到 bit：bpb 的换算

信息量的两种单位满足

$$
1\ \text{nat}=\log_2 e\ \text{bit}=\frac{1}{\ln 2}\ \text{bit}\approx1.4427\ \text{bit}.
$$

设一段验证集共有 $N$ 个有效 token、总字节数 $B$、总损失 $S$（nat）。则

$$
\mathrm{bpb}=\frac{S}{\ln 2\cdot B}
=\frac{\bar\ell}{\ln 2\cdot (B/N)},
$$

其中 $B/N$ 是该语料上的平均字节数每 token。两种写法完全等价，前一种是 `loss_eval.py` 的实现（先累加再相除），后一种便于手算。

bpb 与词表无关的理由：同一段文本的字节数是固定的，把文本切成更多或更少的 token 只改变 $N$ 与 $\bar\ell$ 的分配方式，$S/(\ln 2\cdot B)$ 不变（严格地说，token 边界会带来极少量的信息损失，因此是「近似不变」）。bpb 也是算术编码意义下的压缩率：它等于用该模型做无损压缩时每个字节所需的平均比特数。

常用换算（取 $B/N=3.2$ 字节每 token）：

| 平均损失（nat/token） | PPL | bpb |
|---|---|---|
| 1.5 | 4.48 | 0.676 |
| 1.8 | 6.05 | 0.812 |
| 2.0 | 7.39 | 0.902 |
| 2.3026 | 10.00 | 1.038 |

表中 $\ln2\cdot3.2=2.2182$，故 bpb $=\bar\ell/2.2182$。bpb 在 1 附近意味着模型对每个字节平均只需约 1 bit 的描述长度。

### 在 nanochat 中的落地

**`GPT.forward` 的损失计算**（`nanochat/gpt.py`）：

```text
logits = self.lm_head(x)                        # (B, T, padded_vocab_size)
logits = logits[..., :self.config.vocab_size]   # 去掉词表填充
logits = logits.float()                         # fp32 才能支撑 softcap 与 logsumexp
logits = softcap * torch.tanh(logits / softcap) # 把 logits 压进 (-15, 15)
loss = F.cross_entropy(logits.view(-1, logits.size(-1)), targets.view(-1),
                       ignore_index=-1, reduction=loss_reduction)
```

三处细节值得逐条对照。第一，`logits.float()` 在 softcap 之前，原因是 bf16 只有 8 位有效位（含隐含位），不足以表达 tanh 在饱和区的差值，也不足以支撑 logsumexp 所需的有效位。第二，softcap 在损失之前，因此梯度经过 $1-(\ell/15)^2$ 的缩放，这是 04 阶段 `gpt.py` 的结构选择对优化器提出的隐性约束。第三，`targets.view(-1)` 把 $(B,T)$ 展平成 $BT$，与 `logits` 的行一一对应，`ignore_index=-1` 只在展平之后生效。

**`loss_eval.evaluate_bpb` 逐行**（`nanochat/loss_eval.py`）：

```python
def evaluate_bpb(model, batches, steps, token_bytes):
    total_nats = torch.tensor(0.0, dtype=torch.float32, device=model.get_device())
    total_bytes = torch.tensor(0, dtype=torch.int64, device=model.get_device())
    batch_iter = iter(batches)
    for _ in range(steps):
        x, y = next(batch_iter)
        loss2d = model(x, y, loss_reduction='none')   # (B, T)，被忽略位置为 0
        loss2d = loss2d.view(-1)
        y = y.view(-1)
        if (y.int() < 0).any():
            valid = y >= 0
            y_safe = torch.where(valid, y, torch.zeros_like(y))
            num_bytes2d = torch.where(valid, token_bytes[y_safe],
                                      torch.zeros_like(y, dtype=token_bytes.dtype))
            total_nats += (loss2d * (num_bytes2d > 0)).sum()
            total_bytes += num_bytes2d.sum()
        else:
            num_bytes2d = token_bytes[y]
            total_nats += (loss2d * (num_bytes2d > 0)).sum()
            total_bytes += num_bytes2d.sum()
    world_size = dist.get_world_size() if dist.is_initialized() else 1
    if world_size > 1:
        dist.all_reduce(total_nats, op=dist.ReduceOp.SUM)
        dist.all_reduce(total_bytes, op=dist.ReduceOp.SUM)
    total_nats = total_nats.item()
    total_bytes = total_bytes.item()
    if total_bytes == 0:
        return float('inf')
    bpb = total_nats / (math.log(2) * total_bytes)
    return bpb
```

逐行含义：

1. 两个累加器都用设备端张量，避免每步同步回 CPU；`total_nats` 用 fp32，因为它是 $10^{7}$ 量级的和（默认 160 步 × 262,144 token × 约 2 nat），fp32 的相对精度约 $10^{-7}$，配合张量求和的分块累加足够；`total_bytes` 用 int64，防止溢出。
2. `loss_reduction='none'` 让模型返回形状 $(B,T)$ 的逐位置损失，而不是标量。取标量再相加无法按字节加权。
3. `batch_iter = iter(batches)` 在循环外创建一次；若写在循环内，每个 step 都会重新取第一个 batch，验证集实际只被读了一遍的第一个批次。`loss2d.view(-1)` 与 `y.view(-1)` 把位置维展平，使损失与目标一一对应。
4. `if (y.int() < 0).any()` 一带是 MPS 兼容分支：MPS 没有 int64 的比较核，转 int32 再比较。当存在被忽略的位置时，不能直接用负数索引 `token_bytes`，必须先做 `y_safe` 替换再按有效掩码取值。
5. `total_nats += (loss2d * (num_bytes2d > 0)).sum()` 只累加字节数大于 0 的位置。这一步同时排除了特殊 token（字节数为 0）与被忽略的位置（字节数被替换为 0，且损失本身为 0）。
6. `total_bytes += num_bytes2d.sum()` 只累加真实字节数。
7. 多卡时对两个累加器做 `SUM` 的 `all_reduce`；若只 average 其中一个，比例会错。
8. 最终 `bpb = total_nats / (ln2 * total_bytes)`；若 `total_bytes == 0` 返回 `inf`，防止除零。

**调用侧**（`scripts/base_train.py`）：

```text
eval_steps = args.eval_tokens // (args.device_batch_size * args.max_seq_len * ddp_world_size)
val_loader = build_val_loader()
val_bpb = evaluate_bpb(model, val_loader, eval_steps, token_bytes)
```

默认 `--eval-tokens = 80*524288 = 41,943,040`，`device_batch_size=16`、`max_seq_len=2048`、8 卡时 `eval_steps = 41943040 // 262144 = 160`，即每次验证跑 160 个 micro-batch。`--eval-every=250` 步验证一次。

**`token_bytes` 的来源**（`scripts/tok_train.py`）：遍历词表，特殊 token 记 0，其余用 `decode_single_token_bytes` 取字节长度，存成 `token_bytes.pt`。9 个特殊 token 是 `<|bos|>`、`<|user_start|>`、`<|user_end|>`、`<|assistant_start|>`、`<|assistant_end|>`、`<|python_start|>`、`<|python_end|>`、`<|output_start|>`、`<|output_end|>`。

**SFT 的掩码**（`scripts/chat_sft.py`）：`mask_tensor[:, 1:]` 与右移后的 `targets` 对齐，`targets[mask_targets == 0] = -1`；padding 位置再单独置 $-1$。`inputs` 以 int32 传给模型（兼容 FA3 的索引类型），`targets` 保持 int64。

## 关键直觉

> [!tip] 交叉熵是「以模型分布编码真实 token 的代价」，bpb 是把它换成「每字节代价」
> 单步损失 $-\ln p_y$ 就是算术编码对真实 token 的码长（以 nat 计）。整段语料的总码长除以总字节数，得到与分词方式无关的压缩率。因此 val bpb 不是「另一种 loss」，而是同一信息量的单位换算结果：$\bar\ell$ 是每 token 的 nat，bpb 是每字节的 bit。与严格定义的关系：$1\,\text{nat}=1/\ln2\,\text{bit}$ 是单位换算的恒等式，$B/N$ 是语料的统计量，两者都不含近似。

## 例子与代码

### 例 1：交叉熵、one-hot 等价与忽略位置

```python
import numpy as np

def softmax(z):
    z = z - z.max()
    e = np.exp(z)
    return e / e.sum()

z = np.array([2.0, 0.5, -1.0])
p = softmax(z)
print(np.round(p, 6))                 # [0.785597 0.17529  0.039113]
print(round(float(-np.log(p[0])), 6))                      # 直接按定义
print(round(float(np.log(np.exp(z).sum()) - z[0]), 6))     # log-sum-exp 写法

# 一个 batch：第二个位置的目标为 -1（忽略）
Z = np.array([[2.0, 0.5, -1.0], [0.1, 0.2, 0.3], [1.0, 0.0, -2.0]])
Y = np.array([0, -1, 2])
losses = np.array([-np.log(softmax(zi)[yi]) if yi >= 0 else 0.0
                   for zi, yi in zip(Z, Y)])
print(np.round(losses, 6))                                  # [0.241311 0. 3.349012]
print(round(float(losses.sum() / (Y >= 0).sum()), 6))       # 有效位置平均
print(round(float(losses.mean()), 6))                       # 全部位置平均（错误口径）
```

预期输出：

```text
[0.785597 0.17529  0.039113]
0.241311
0.241311
[0.241311 0.       3.349012]
1.795162
1.196775
```

直接按定义与按 log-sum-exp 写法的结果在 6 位小数内一致；`1.795162` 是 `sum/2`，与 PyTorch `ignore_index` 的 `mean` 行为一致；`1.196775` 是 `sum/3`，把被忽略位置也计入了分母，不能用它监控训练。

### 例 2：bpb 的手算与复现

```python
import numpy as np

# 四个位置的逐位置损失（nat）与对应目标 token 的字节数
nats = np.array([0.3365, 1.2040, 0.6931, 2.3026])
nbytes = np.array([3, 4, 1, 0])       # 最后一个是特殊 token，字节数为 0
print(round(float(nats.sum()), 4), int(nbytes.sum()))          # 总 nat、总字节
print(round(float(nats.sum() / (np.log(2) * nbytes.sum())), 6))
print(round(float(nats.mean()), 6))                            # 每 token nat
print(round(float(nats.mean() / (np.log(2) * nbytes.sum() / 4)), 6))
```

预期输出：

```text
4.5362 8
0.818044
1.13405
0.818044
```

第四行说明两种写法（总量相除、均值相除）得到同一个 bpb。特殊 token 的贡献必须为 0：它在 `nats` 中若不为 0，就必须靠 `num_bytes2d > 0` 这个掩码排除，这正是 `evaluate_bpb` 第 5 步的作用。

## 易错点

> [!warning] 具体、可检验的错误
> - 用 token 数而不是字节数归一。`bpb = sum_nats / (ln2 * token_count)` 得到的是「每 token 比特数」，换词表后不可比，也不是仓库里的指标。
> - 忘记除以 $\ln2$。把 nat 当 bit 会得到约 1.4427 倍的偏大值，且错误方向固定，容易在对比外部数字时被误认为模型更好。
> - 自己实现平均时把被忽略位置的 0 计入分母。PyTorch 的 `reduction='mean'` 已排除被忽略位置，人为写 `loss.mean()` 会得到 `sum/3` 一类的偏小损失。
> - 在 bf16 logits 上直接算 CE。softcap 与 logsumexp 都需要 fp32 尾数，仓库因此显式写了 `logits.float()`。
> - 把 `ignore_index` 设为 0。0 是合法 token 编号（BPE 的字节 token 或 BOS），会静默把一批真实目标排除或把 padding 计入损失。
> - 认为 bpb 可以跨验证集比较。$B/N$ 依赖语料与分词器的压缩率，只有当验证集与分词器都相同时 bpb 才严格可比。
> - 把 CORE（centered accuracy）与 bpb 混为一谈。前者是 22 个任务的准确率聚合，后者是压缩率，两者在训练日志里并列出现，含义完全不同。

## 关联笔记

- 前置：[[softmax与softmax温度]]——softmax、log-sum-exp 与温度的数值细节，本篇直接复用。
- 后续：[[损失函数]]（跨库）——通用原理见该篇，涵盖 KL、MSE、对比损失等；本篇只讲 next-token CE 与 bpb。
- 对照：[[模型评估矩阵]]（跨库）——bpb 属于哪一类指标、与准确率类指标的关系，在评测方法论中讨论。
- 后续：05 阶段的训练脚本把 bpb 作为验证指标，其调度与日志逻辑建立在本篇的换算之上。

## 达标检测

- [ ] 从最大似然出发推出交叉熵，并写出 CE 与 $H(p_{\text{data}})$、KL 的分解式。
- [ ] 手推 $\nabla_{\mathbf{z}}\ell=\mathbf{p}-\mathbf{e}_y$，说明「$-\ln p_y$ 的梯度上限与 logits 尺度无关」。
- [ ] 给定一段验证集的总 nat 与总字节，算出 bpb；并把一个 nat 级的损失换算成 bpb（给定每 token 字节数）。
- [ ] 说明 `evaluate_bpb` 中 `(num_bytes2d > 0)` 这个掩码同时排除了哪两类位置。
- [ ] 解释 `reduction='mean'` 在 `ignore_index=-1` 时按什么分母取平均，并给出一个反例说明写错会偏低。
- [ ] 说明 SFT 中 `mask[1:]` 为什么要相对 `targets` 右移一位，错一位会发生什么。
- [ ] 判断「bpb 更低等价于 CORE 更高」是否成立，并给出反例方向。

## 参考来源

- Karpathy, *nanochat* `nanochat/loss_eval.py`（commit 92d63d4）—— 对应 `evaluate_bpb` 的逐行实现与注释中列出的三条排除规则。
- Karpathy, *nanochat* `nanochat/gpt.py`—— 对应 `forward` 中 `logits.float()`、softcap 与 `ignore_index=-1` 的交叉熵调用。
- Karpathy, *nanochat* `scripts/tok_train.py` 与 `scripts/chat_sft.py`—— 对应 `token_bytes` 的构造与 SFT 损失掩码的对齐方式。
- Goodfellow, Bengio, Courville, *Deep Learning*（2016），第 5 章机器学习基础 —— 对应最大似然与交叉熵的等价性。
- Hoffmann et al., *Training Compute-Optimal Large Language Models*（Chinchilla, 2203.15556）—— 对应以 bits-per-byte 作为跨词表可比指标的做法。
