---
tags: [nanochat, math, softmax]
阶段: 02-数学与工程基础
难度: ★★☆
created: 2026-10-22
related: "[[交叉熵与困惑度]], [[自回归生成与采样]], [[矩阵与线性代数速查]]"
---

# softmax与softmax温度

## 定义

给定 logits 向量 $\mathbf{z}\in\mathbb{R}^{V}$（$V$ 为词表大小），softmax 把它映射为概率单纯形上的点：

$$
\mathrm{softmax}(\mathbf{z})_i=\frac{\exp(z_i)}{\sum_{j=1}^{V}\exp(z_j)},\qquad i=1,\dots,V .
$$

带温度的 softmax 先在 logits 上除以温度参数再归一化：

$$
p_i(T)=\frac{\exp(z_i/T)}{\sum_{j=1}^{V}\exp(z_j/T)},\qquad T>0 .
$$

符号与术语：

- $\mathbf{z}$：模型 `lm_head` 输出的未归一化打分，称为 logits，$z_i$ 是第 $i$ 个 token 的打分。
- $T$：**温度**（temperature），无量纲正数；$T=1$ 为原始分布，$T<1$ 使分布更尖锐，$T>1$ 使分布更平坦。
- $p_i$：第 $i$ 个 token 被采样的概率，$\sum_i p_i=1$，$p_i\ge0$。
- **熵**（entropy）：$H(\mathbf{p})=-\sum_{i}p_i\ln p_i$，单位 nat；除以 $\ln 2$ 得 bit。熵衡量分布的分散程度，均匀分布取最大值 $\ln V$。
- **top-$k$ 采样**：只保留 logits 最大的 $k$ 个 token，其余置为 $-\infty$（或在采样时丢弃），再在保留集合上归一化后采样。
- **softcap**：nanochat 的 logit 压缩函数 $\mathrm{softcap}(z)=c\tanh(z/c)$，$c=15$，把 logits 限制在 $(-15,15)$ 内。

## 为什么重要

- 生成阶段的唯一随机性来源就是 softmax 加采样。温度取 0.3 与取 1.5 得到的是两种不同的模型行为：前者近似贪心、重复度高，后者熵接近上限、容易偏离主题。nanochat 的 `Engine` 与 `GPT.generate` 都把 `temperature`、`top_k` 暴露为命令行参数，默认分别为 1.0 与 `None`（CLI 侧常用 50）。
- softmax 是交叉熵的内部结构。$\mathrm{CE}=-\ln p_{y}$ 中的 $p_y$ 就是 softmax 的一个分量，所以「数值稳定的 softmax」与「数值稳定的交叉熵」是同一件事的两种写法，见 [[交叉熵与困惑度]]。
- 数值稳定性不是理论问题而是真实故障：logits 未做平移直接取 exp，在 fp16 下 $z>11.09$ 就溢出为 `inf`，随后 `inf/inf` 得到 `nan`，训练损失立刻变成 `nan`。
- nanochat 在 softmax 之前多了一步 softcap，这使「温度」的语义与教科书略有偏差：温度作用在有界 logits 上，低温时分布无法无限尖锐。这一点在高温/低温两端的解释上必须区分。
- 在全书中的位置：前置是 [[矩阵与线性代数速查]] 中的向量与内积，后续被 [[交叉熵与困惑度]]、[[自回归生成与采样]]（跨库）、09 阶段的推理 Engine 引用。

## 原理与推导

### 1. 定义与三条基本性质

由定义直接得到三条性质。

**平移不变性**：对任意标量 $c$，

$$
\mathrm{softmax}(\mathbf{z}+c\mathbf{1})_i=\frac{e^{z_i+c}}{\sum_j e^{z_j+c}}=\frac{e^{c}e^{z_i}}{e^{c}\sum_j e^{z_j}}=\mathrm{softmax}(\mathbf{z})_i .
$$

这条性质是数值稳定实现的基础：取 $c=-\max_j z_j$ 可以把最大指数变成 1，其余指数落在 $(0,1]$，不会溢出。

**保序性**：$z_i>z_j\iff p_i>p_j$，因为指数函数严格单调。因此在 logits 上取 top-$k$ 与在概率上取 top-$k$ 得到同一个集合；温度为正时也成立，因为 $z\mapsto z/T$ 仍是严格单调的。

**归一性**：$\sum_i p_i=1$，$p_i>0$（有限 logits 时严格正）。这意味着 softmax 的输出永远不含 0，任何「概率为 0」的结论都来自数值下溢而不是数学。

雅可比矩阵用于反向传播。记 $\mathbf{p}=\mathrm{softmax}(\mathbf{z})$，则

$$
\frac{\partial p_i}{\partial z_j}=p_i(\delta_{ij}-p_j)
\quad\Longleftrightarrow\quad
\frac{\partial\mathbf{p}}{\partial\mathbf{z}}=\mathrm{diag}(\mathbf{p})-\mathbf{p}\mathbf{p}^{\top}.
$$

该矩阵对称、半正定，零空间包含全 1 向量 $\mathbf{1}$：沿 $\mathbf{1}$ 方向平移 logits 不改变输出，这与平移不变性一致。带温度时整体乘 $1/T$：

$$
\frac{\partial p_i}{\partial z_j}=\frac{1}{T}\,p_i(\delta_{ij}-p_j).
$$

$T<1$ 放大梯度，$T>1$ 缩小梯度，这是低温采样在训练中容易不稳定的一层原因。

### 2. 数值稳定性

浮点格式能表示的最大指数决定了 exp 的溢出点：

| 格式 | 最大值 | $\ln(\text{max})$ | 说明 |
|---|---|---|---|
| fp32 | $3.40\times10^{38}$ | 88.72 | 超过约 88.7 的 logit 取 exp 即溢出 |
| fp16 | 65504 | 11.09 | 超过约 11.1 即溢出 |
| bf16 | $3.39\times10^{38}$ | 88.7 | 指数范围与 fp32 相同，但有效位只有 8 位，相对精度约 $2^{-8}$ |

nanochat 在 bf16 计算路径上跑前向，logits 却显式转成 fp32 再进损失与采样（`logits = logits.float()`），原因就是 bf16 的尾数不足以支撑 softmax 与 `logsumexp` 所需的相对精度。

稳定的写法只有一种：先减去最大值再取指数。

$$
p_i=\frac{\exp(z_i-z_{\max})}{\sum_j\exp(z_j-z_{\max})}.
$$

由于 $z_j-z_{\max}\le0$，分子分母都在 $(0,1]$ 内，求和最多为 $V$，不会溢出。代价是需要额外一次遍历求 $\max$ 与一次求和，工程上都由融合核完成。

交叉熵使用同一技巧的对数形式，即 log-sum-exp：

$$
\mathrm{CE}=\ln\sum_j e^{z_j}-z_{y}=\big(z_{\max}+\ln\sum_j e^{z_j-z_{\max}}\big)-z_{y}.
$$

PyTorch 的 `F.cross_entropy` 内部即按此实现，因此不需要手动归一化 logits。

### 3. 温度对分布与熵的影响

温度的两个极限可以直接看出：

$$
T\to0^{+}:\quad p_i\to\begin{cases}1,& i=\arg\max_j z_j\\ 0,&\text{否则}\end{cases}
\qquad
T\to\infty:\quad p_i\to\frac{1}{V}.
$$

中间区域的行为由熵对温度的导数刻画。令 $\beta=1/T$，$p_i(\beta)=e^{\beta z_i}/Z(\beta)$，$Z=\sum_j e^{\beta z_j}$。先算

$$
\frac{\partial\ln p_i}{\partial\beta}=z_i-\mathbb{E}_{p}[z],\qquad
\frac{\partial p_i}{\partial\beta}=p_i\big(z_i-\mathbb{E}_{p}[z]\big).
$$

再对熵求导。注意 $\sum_i\partial p_i/\partial\beta=0$，所以

$$
\frac{\mathrm{d}H}{\mathrm{d}\beta}
=-\sum_i\frac{\partial p_i}{\partial\beta}\big(\ln p_i+1\big)
=-\sum_i p_i\big(z_i-\mathbb{E}_p[z]\big)\big(\beta z_i-\ln Z\big)
=-\beta\,\mathrm{Var}_{p}(z)\le0 .
$$

最后一步用到 $\sum_i p_i(z_i-\mathbb{E}z)=0$ 消去 $-\ln Z$ 项。结论：**熵随 $\beta$ 单调不增、随 $T$ 单调不减**，且只要 $z$ 不全相等就严格单调；$H$ 的上界是 $\ln V$，在 $T\to\infty$ 时取到。

这条推导解释了工程经验：温度不是「随机性旋钮」，它是分布方差（更准确地说，logits 在分布下的方差）的倒数缩放。低温→方差大→熵小；高温→方差小→熵大。

### 4. 与 top-$k$ 的配合

在 logits 上做 top-$k$ 过滤，等价于把分布条件化在「得分最高的 $k$ 个 token」这一事件上：

$$
p_i^{(k)}=\frac{p_i\,\mathbb{1}[i\in S_k]}{\sum_{j\in S_k}p_j},\qquad S_k=\mathrm{topk}(\mathbf{z},k).
$$

由于保序性，$S_k$ 与温度无关（$T>0$）。因此「先 top-$k$ 再除以温度」与「先除以温度再 top-$k$」得到完全相同的分布，只在实现上有差别：前者只需对 $k$ 个数做 exp 与求和，后者要对 $V$ 个数做一遍。

熵的上界相应收紧为 $\ln k$。这是 top-$k$ 的主要作用：即使温度很高，也不会从长尾里抽到明显不合适的 token。代价是 $k$ 小时分布被截断，重复度上升。

置 $-\infty$ 的做法在数学上等价于乘以指示函数，但要求后续没有「除以 0」或「$-\infty$ 减 $-\infty$」的操作。若先置 $-\infty$ 再减去最大值，最大的那个仍是有限值，其余为 $-\infty$，$\exp(-\infty)=0$，安全；若整行都是 $-\infty$（$k=0$），则会得到 $-\infty-(-\infty)=\mathrm{nan}$。

### 5. softcap 对温度语义的影响

nanochat 的 `GPT.forward` 在算损失与采样之前对 logits 做压缩：

$$
\ell=\mathrm{softcap}\cdot\tanh\!\Big(\frac{z}{\mathrm{softcap}}\Big),\qquad \mathrm{softcap}=15 .
$$

性质：$\ell$ 严格单调、奇函数、$|\ell|<15$，且在 $z=0$ 处斜率为 1：

$$
\frac{\mathrm{d}\ell}{\mathrm{d}z}=1-\tanh^{2}\!\Big(\frac{z}{15}\Big)=1-\Big(\frac{\ell}{15}\Big)^{2}.
$$

于是 softcap 在原点附近几乎恒等，在 $|z|$ 接近 15 时把斜率压到 0。后果有两层：

1. 温度作用在 $\ell$ 而不是 $z$ 上。低温（$T\to0$）时分布逼近 $\ell$ 的 argmax，而 $\ell$ 的最大差值被限制在 30 以内，因此低温分布的最尖锐程度有上界；这与「直接对原始 logits 降温」不同。
2. 压缩是非线性的，两套 logits 的差值在饱和区被显著缩小，等价于在高置信度区域自动升温。这抑制了模型对单个 token 的过度自信，也限制了采样时的极端尖锐分布。

### 在 nanochat 中的落地

**`GPT.forward` 的 logits 处理链**（`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 与损失
logits = softcap * torch.tanh(logits / softcap)
```

三步缺一不可：切片去掉 pad 的词表项（32768 已对齐 64，当前不触发填充，但代码保留该路径）；转 fp32 保证 tanh 与 logsumexp 的相对精度；softcap 把 logits 限制在 $(-15,15)$。

**`GPT.generate`（朴素自回归）**：

```text
logits = self.forward(ids)[:, -1, :]                 # (B, vocab)
v, _ = torch.topk(logits, min(top_k, vocab))
logits[logits < v[:, [-1]]] = -inf                   # 先 top-k，在原始 logits 上
logits = logits / temperature                        # 再除温度（T > 0 分支）
probs = F.softmax(logits, dim=-1)                    # 全词表 softmax
next_ids = torch.multinomial(probs, 1, generator=rng)
```

顺序是 top-$k$ → 温度 → 全词表 softmax → 多项式采样。`temperature <= 0` 走 `argmax` 分支，且不创建随机数生成器。

**`Engine.sample_next_token`（推理引擎）**：

```text
if temperature == 0.0: return argmax(logits)
if top_k: vals, idx = topk(logits, k)
          vals = vals / temperature
          probs = softmax(vals)                      # 只在 k 个值上做 softmax
          return idx.gather(1, multinomial(probs))
else:     softmax(logits / temperature) → multinomial
```

两处实现的差别集中在「softmax 的计算域」与「返回值的表示」：

| 项目 | `GPT.generate` | `Engine.sample_next_token` |
|---|---|---|
| top-$k$ 位置 | 采样的 logits 上先过滤（置 $-\infty$） | 先取 top-$k$ 值，再在 $k$ 个值上归一化 |
| 温度作用位置 | 全词表 logits 除以 $T$ | 只对 $k$ 个值除以 $T$ |
| softmax 定义域 | $V$（含 $-\infty$） | $k$（或 $V$，视分支） |
| 返回值 | token id | token id（由 `gather` 从局部索引映射回去） |
| `temperature = 0` | 走 `else` 分支的 `argmax` | 显式断言并 `argmax` |
| 负数温度 | 静默按贪心处理 | 断言失败 |

两者在数学上等价（同一 $S_k$ 上的同一条件分布），但 `Engine` 的写法少算 $V-k$ 个 exp，且避免了 `-inf` 参与后续运算；`GPT.generate` 的写法更接近教科书，便于对照。

**采样参数的实际取值。** `scripts/chat_rl.py` 的 rollout 使用 `--temperature 1.0`、`--top-k 50`（默认值），每例采样 16 条；评测侧的 `run_gsm8k_eval` 以 `temperature=1.0` 调用 `Engine.generate`。也就是说，RL 阶段并没有刻意降低温度，探索主要靠 top-$k$ 截断与组内比较。

## 关键直觉

> [!tip] 温度是 logits 的方差缩放，softcap 是 logits 的幅度上界
> 对固定 logits，$p_i(T)$ 只通过 $\beta=1/T$ 依赖温度，而 $H$ 对 $\beta$ 的导数恰为 $-\beta\,\mathrm{Var}_p(z)$：温度旋钮实际在改「logits 在分布下的离散程度」。softcap 则把 $z$ 压进 $(-15,15)$，从而给这个方差加上天花板。两者叠加的净效果是：nanochat 的采样分布在低温端不可能无限尖锐，在高温端仍可逼近均匀分布。与严格定义的关系：前者是熵的导数公式，后者是 tanh 的有界性，都不是近似结论。

## 例子与代码

### 例 1：softmax、平移与温度

```python
import numpy as np

def softmax(z, T=1.0, shift=True):
    z = z / T
    if shift:
        z = z - z.max()          # 平移不改变结果，但避免 exp 溢出
    e = np.exp(z)
    return e / e.sum()

logits = np.array([2.0, 1.0, 0.2, -0.5, 3.0])
print(np.round(softmax(logits, 1.0), 4))   # T = 1
print(np.round(softmax(logits, 0.5), 4))   # 低温：更尖锐
print(np.round(softmax(logits, 2.0), 4))   # 高温：更平坦

# 不平移时的溢出：fp32 下 exp(1000) 直接变 inf
z32 = np.array([1000.0, 999.0], dtype=np.float32)
with np.errstate(over="ignore", invalid="ignore"):
    e = np.exp(z32)
    print(e, e / e.sum())                  # [inf inf] [nan nan]
    e = np.exp(z32 - z32.max())
    print(e / e.sum())                     # [0.7310586 0.2689414]
```

预期输出：

```text
[0.2308 0.0849 0.0381 0.0189 0.6273]
[1.168e-01 1.580e-02 3.200e-03 8.000e-04 8.634e-01]
[0.2533 0.1536 0.103  0.0726 0.4176]
[inf inf] [nan nan]
[0.7310586 0.2689414]
```

$T=0.5$ 时最大概率从 0.6273 升到 0.8634，$T=2$ 时降到 0.4176，方向与第 3 节的单调性一致。

### 例 2：熵的数值表与 top-$k$ 条件化

```python
import numpy as np

logits = np.array([2.0, 1.0, 0.2, -0.5, 3.0])

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

for T in (0.25, 0.5, 1.0, 2.0, 4.0, 10.0):
    p = softmax(logits, T)
    H = -(p * np.log(p)).sum()
    print(f"T={T:5.2f} pmax={p.max():.4f} H={H:.4f} nats = {H / np.log(2):.4f} bits")

print("ln(5) =", round(float(np.log(5)), 4))          # 均匀分布上界
k = 3
idx = np.argsort(logits)[::-1][:k]
pk = softmax(logits[idx])
print("top3 idx", idx, "cond p", np.round(pk, 4),
      "H =", round(float(-(pk * np.log(pk)).sum()), 4))
```

预期输出（$V=5$，熵上界 $\ln5=1.6094$）：

| $T$ | $p_{\max}$ | $H$（nats） | $H$（bit） |
|---|---|---|---|
| 0.25 | 0.9817 | 0.0932 | 0.1345 |
| 0.50 | 0.8634 | 0.4672 | 0.6741 |
| 1.00 | 0.6273 | 1.0400 | 1.5004 |
| 2.00 | 0.4176 | 1.4247 | 2.0554 |
| 4.00 | 0.3031 | 1.5605 | 2.2513 |
| 10.00 | 0.2390 | 1.6016 | 2.3106 |

$T=10$ 时熵为 1.6016，与 $\ln5=1.6094$ 相差不到 0.5%，说明高温端已接近均匀。代码的末两行输出为 `ln(5) = 1.6094` 与 `top3 idx [4 0 1] cond p [0.6652 0.2447 0.09 ] H = 0.8324`：top-3 条件化后保留的是下标 $\{4,0,1\}$，条件概率为 $[0.6652,0.2447,0.0900]$，熵 0.8324 nats，落在 $\ln3=1.0986$ 之下，与第 4 节的上界一致。

## 易错点

> [!warning] 具体、可检验的错误
> - 先 softmax 再除以温度。温度必须作用在 logits 上：$\mathrm{softmax}(\mathbf{z})/T$ 的和为 $1/T\ne1$，采样会得到非法概率，且熵的行为完全不同。
> - 用 fp16 直接对未平移的 logits 取 exp。fp16 的上限是 65504，$z>11.09$ 即溢出，随后 `inf/inf` 产生 `nan`；必须减去行最大值。
> - 把 `temperature=0` 传给除法。`Engine.sample_next_token` 用显式分支返回 `argmax`，自己实现循环时要复现这个分支，否则得到除零。
> - 把 softcap 之后的 logits 当成原始 logits 来解释温度。$\ell=15\tanh(z/15)$ 使 $|z|>15$ 的区域被压缩，$T=0.1$ 也得不到原始 logits 上 $T=0.1$ 的尖锐度。
> - 在 top-$k$ 过滤后直接报告「概率」，却忘记重新归一化。若权重和不为 1，`torch.multinomial` 内部仍会归一化，但据此算出的熵与联合概率都是错的。
> - 混淆熵的 nat 与 bit。nanochat 的损失以 nat 计（`F.cross_entropy` 默认），bpb 指标才换到 bit，见 [[交叉熵与困惑度]]。
> - 认为 top-$k$ 与温度的顺序会改变采样分布。集合与条件分布都不变，变的只是 exp 的计算量。

## 关联笔记

- 前置：[[矩阵与线性代数速查]]——logits 是 `lm_head` 的输出向量，理解其形状与计算量需要矩阵乘法的形状规则。
- 后续：[[交叉熵与困惑度]]——softmax 与 log-sum-exp 是交叉熵的实现内核，两篇共用同一套数值稳定技巧。
- 后续：[[自回归生成与采样]]（跨库）——通用原理见该篇，本篇只讲 nanochat 的两处实现差异。
- 对照：[[概率与统计]]（跨库）——熵、方差与条件分布的通用定义，本篇只取与采样相关的部分。

## 达标检测

- [ ] 写出 softmax 与带温度 softmax 的定义，并证明平移不变性。
- [ ] 推导 $H$ 对 $\beta=1/T$ 的导数，说明为什么熵随温度单调不减。
- [ ] 手算 logits $[2,1,0]$ 在 $T=0.5$ 与 $T=2$ 下的概率分布与熵，判断数值方向是否与单调性一致。
- [ ] 说明 fp32、fp16、bf16 三种格式下 exp 的溢出阈值差异，并给出规避方法。
- [ ] 解释 `GPT.generate` 与 `Engine.sample_next_token` 在 top-$k$ 与温度的顺序、softmax 定义域、返回值上的三点差别。
- [ ] 判断「先 softmax 再 top-$k$ 再除以温度」这个写法错在哪里，给出正确写法。
- [ ] 解释 softcap 为什么使低温采样的尖锐度存在上界，写出其导数的表达式。

## 参考来源

- Karpathy, *nanochat* `nanochat/engine.py`（commit 92d63d4）—— 对应 `sample_next_token` 的温度与 top-$k$ 分支实现。
- Karpathy, *nanochat* `nanochat/gpt.py`—— 对应 `forward` 中的 `logits.float()`、softcap 与 `generate` 的采样循环。
- Karpathy, *nanochat* `scripts/chat_rl.py`—— 对应 rollout 的 `temperature=1.0`、`top_k=50` 默认值。
- Goodfellow, Bengio, Courville, *Deep Learning*（2016），第 4 章数值计算 —— 对应 log-sum-exp 技巧与上溢/下溢的处理。
- PyTorch 文档，`torch.nn.functional.softmax` 与 `torch.multinomial` —— 对应 softmax 的数值实现与按权重采样的行为。
