---
tags: [nanochat, transformer, fp8, training]
阶段: 04-Transformer架构
难度: ★★★
created: 2026-10-22
related: "[[前馈层与激活函数]], [[训练脚本与speedrun]], [[从第一性看nanochat的gpt.py]], [[FLOPs与训练成本估算]]"
---

# FP8混合精度训练

## 定义

FP8 混合精度训练是用 8 位浮点格式存储并计算线性层的矩阵乘、同时保持 master 权重与优化器状态为高精度的训练方式。nanochat 的实现是 `nanochat/fp8.py` 中的 `Float8Linear`：权重仍以原始精度保存，前向与反向的三次矩阵乘在内部动态量化到 FP8，用 `torch._scaled_mm` 调用 cuBLAS 的 FP8 内核，再用逆缩放还原到高精度输出。

两种格式：**E4M3** 有 4 位指数、3 位尾数，最大有限值 448；**E5M2** 有 5 位指数、2 位尾数，最大有限值 57344。**缩放因子**（scale）是把张量映射到 FP8 量程的乘数；**amax** 是张量元素绝对值的最大值。**per-tensor** 量化对整个张量用一个 scale，**per-row** 量化对每一行用一个 scale。

符号约定：输入 $\mathbf{X}\in\mathbb{R}^{M\times K}$，权重 $\mathbf{W}\in\mathbb{R}^{N\times K}$，输出 $\mathbf{Y}\in\mathbb{R}^{M\times N}$，梯度 $\mathbf{G}\in\mathbb{R}^{M\times N}$。$s$ 为缩放因子，$q$ 为量化后的 FP8 张量，$\hat{\mathbf{X}}$ 为反量化结果。

## 为什么重要

H100 的 FP8 张量核心在理论吞吐上约为 bf16 的两倍，且 FP8 操作数只占一半字节。对 nanochat 这种以 Linear 矩阵乘为主的模型，FP8 直接作用在每层注意力的四个投影、MLP 的两个矩阵与 `lm_head` 上；`dev/LOG.md` 在 d26 上测得 tensorwise FP8 的训练吞吐从 630K tok/s 提升到 740K tok/s（1.17 倍），显存减少约 9 GB。speedrun 的 `--fp8` 开关就是为此存在。

但 FP8 不是「把模型换成 8 位」：master 权重、优化器状态、残差流、LayerNorm/RMSNorm、注意力 softmax 仍保持 bf16/fp32；只有 Linear 的三次 GEMM 在 FP8 中执行。收益也不是免费的：

- 每个矩阵乘前要计算 amax、缩放、clamp 与类型转换；没有 `torch.compile` 融合时，这些「胶水」操作会让 FP8 比 bf16 慢 4 倍（LOG 的微基准为 0.23 倍）。
- 每个 step 的数值精度略低，达到同样能力需要更多 step；LOG 估计能力匹配后的真实加速约为 5%，而不是 17%。
- 小模型不一定受益。LOG 记录 d12 仍然更慢，d26 以上才稳定获益；当前 speedrun 用 d24，收益接近 5% 量级。
- 评测必须回退 bf16。动态 FP8 量化会改变 logits，若直接用 FP8 跑 val bpb 或 CORE，指标与 bf16 基线不可比。

在「懂原理 / 能复现 / 懂工程」中，本篇偏工程：需要能解释格式取舍、缩放粒度、三个 GEMM 的量化位置，以及为什么 `disable_fp8` 必须在每个评测入口被调用。前置的线性层形状见 [[前馈层与激活函数]]，训练脚本的开关见 [[训练脚本与speedrun]]。

## 原理与推导

### 1. 两种 FP8 格式的取舍

| 格式 | 符号/指数/尾数 | 指数偏置 | 最大有限值 | 最小正规数 | 相对分辨率 | 典型用途 |
|---|---|---|---:|---:|---|---|
| E4M3 | 1/4/3 | 7 | 448 | $2^{-6}=0.015625$ | 约 $2^{-3}$ 的间隔 | 前向的输入与权重 |
| E5M2 | 1/5/2 | 15 | 57344 | $2^{-14}\approx6.1\times10^{-5}$ | 约 $2^{-2}$ 的间隔 | 反向的梯度 |

E4M3 多一位尾数，同样量级下能表示更细的间隔，适合数值范围可控的激活与权重；E5M2 多一位指数，量程从 448 扩到 57344，适合可能出现的梯度离群值。E4M3FN 没有无穷大，用保留编码表示 NaN；E5M2 保留无穷大与 NaN 编码。训练中越界值仍必须靠 clamp 饱和：直接 cast 可能得到 inf（E5M2）或 NaN（E4M3FN），而不是最大值。

格式选择不是绝对的。若梯度也被归一化得很紧，E4M3 也能用于反向；若前向激活有极端离群值，E5M2 更安全但精度更差。nanochat 采用「前向 E4M3、反向梯度 E5M2、反向权重 E4M3」的组合，是精度与量程的折中。

### 2. 缩放、量化与反量化

给定张量 $\mathbf{X}$ 与目标格式的最大值 $F_{\max}$（E4M3 为 448，E5M2 为 57344），per-tensor 动态量化为

$$
s=\frac{F_{\max}}{\max(|\mathbf{X}|)+\epsilon},\qquad
q=\operatorname{clamp}(\mathbf{X}s,\,-F_{\max},\,F_{\max}),\qquad
\hat{\mathbf{X}}=\frac{q}{s}.
$$

$\epsilon$ 防止全零张量除零；nanochat 取 `EPS=1e-12`。缩放后先 clamp 再 cast，因为 PyTorch 的默认 cast 可能回绕而不是饱和。反量化在 `_scaled_mm` 内部完成：它接收 FP8 数据与逆缩放 $1/s$，在矩阵乘累加后乘回。

per-row 量化把 $s$ 换成每行一个 $s_i=F_{\max}/\max_j|X_{ij}|$。它对行内动态范围更稳健：一行有一个极大值时，只影响该行的 scale，不会把其他行的小值压到 FP8 的最小正规数以下。代价是每行一个 scale，cuBLAS 的 tensorwise 内核不能直接用，需要 CUTLASS 或额外的逐行缩放内核；LOG 的 rowwise 全训练吞吐是 0.90 倍，低于 bf16。

nanochat 只实现 tensorwise。`fp8.py` 的模块文档明确说只支持 tensorwise，不需要 torchao 的 rowwise、FSDP、DTensor 等通用性；`Float8LinearConfig.from_recipe_name` 对 `"rowwise"` 直接抛出 `ValueError`。`base_train.py` 的 `--fp8-recipe` 虽然保留了 `rowwise` 选项，但自定义实现会在转换时失败，这是 CLI 与实现的一处不一致，实际可用值只有 `tensorwise`。

### 3. Linear 的三次 GEMM

一个无 bias 的 Linear 在训练时有三次矩阵乘：

$$
\mathbf{Y}=\mathbf{X}\mathbf{W}^{\top},\qquad
\mathbf{G}_X=\mathbf{G}\mathbf{W},\qquad
\mathbf{G}_W=\mathbf{G}^{\top}\mathbf{X}.
$$

前向：$\mathbf{X}$ 与 $\mathbf{W}$ 都量化到 E4M3，调用 `torch._scaled_mm`，`use_fast_accum=True` 让累加使用较低精度，换取吞吐；反向：$\mathbf{G}$ 量化到 E5M2（量程大），$\mathbf{W}$ 仍用前向保存的 E4M3 副本，分别计算 $\mathbf{G}_X$ 与 $\mathbf{G}_W$，两次都用 `use_fast_accum=False` 以提高梯度精度。

`torch._scaled_mm` 对内存布局有要求：第一个操作数必须是行主序（contiguous），第二个必须是列主序。$\mathbf{W}$ 的形状是 $(N,K)$ 且连续，$\mathbf{W}^{\top}$ 自然是 $(K,N)$ 列主序，不需要拷贝；$\mathbf{G}^{\top}$ 在 $\mathbf{G}_W$ 的计算中需要物理转置成 $(N,M)$ 行主序，代码用 `go_fp8.t().contiguous()`；其他情况用 `_to_col_major`（转置 → contiguous → 转置）构造列主序视图。

### 4. `Float8Linear` 的实际实现

`fp8.py` 没有使用 torchao 的张量子类，而是一个自定义 `autograd.Function`：

```python
@torch._dynamo.allow_in_graph
class _Float8Matmul(torch.autograd.Function):
    @staticmethod
    def forward(ctx, input_2d, weight):
        input_fp8, input_inv = _to_fp8(input_2d, torch.float8_e4m3fn)
        weight_fp8, weight_inv = _to_fp8(weight, torch.float8_e4m3fn)
        ctx.save_for_backward(input_fp8, input_inv, weight_fp8, weight_inv)
        output = torch._scaled_mm(input_fp8, weight_fp8.t(),
                                  scale_a=input_inv, scale_b=weight_inv,
                                  out_dtype=input_2d.dtype,
                                  use_fast_accum=True)
        return output
```

`_to_fp8` 每次调用都重新计算当前张量的 amax，**没有 amax history**。这一点与 torchao 的静态/延迟缩放不同：torchao 会维护历史 amax 以稳定 scale，nanochat 的 scale 随每个 batch、每个张量即时变化。好处是实现短、无需校准；代价是 scale 可能抖动，且 `torch.compile` 需要把整个函数视为不透明节点（`allow_in_graph`），无法把 amax 与前一层融合。

`Float8Linear` 继承 `nn.Linear`，只重写 `forward`：

```python
class Float8Linear(nn.Linear):
    def forward(self, input):
        input = input.to(COMPUTE_DTYPE)
        orig_shape = input.shape
        input_2d = input.reshape(-1, orig_shape[-1])
        output = _Float8Matmul.apply(input_2d, self.weight)
        output = output.reshape(*orig_shape[:-1], output.shape[-1])
        if self.bias is not None:
            output = output + self.bias.to(output.dtype)
        return output
```

权重与 bias 保持原始精度；只有 `_Float8Matmul` 内部的三个 GEMM 用 FP8。`from_float` 用 `torch.device("meta")` 构造模块壳，避免分配临时权重，再把 `weight`/`bias` 指向原模块的参数，因此转换不复制、不增加显存。nanochat 的 Linear 都是 `bias=False`，bias 分支实际不会走到。

### 5. 转换与过滤

`convert_to_float8_training` 后序遍历模块树，把每个满足过滤条件的 `nn.Linear` 替换为 `Float8Linear`：

```python
def _convert(mod, prefix=""):
    for name, child in mod.named_children():
        fqn = f"{prefix}.{name}" if prefix else name
        _convert(child, fqn)
        if isinstance(child, nn.Linear) and not isinstance(child, Float8Linear):
            if module_filter_fn is None or module_filter_fn(child, fqn):
                setattr(mod, name, Float8Linear.from_float(child))
```

`base_train.py` 的过滤条件是：

```python
def fp8_module_filter(mod, fqn):
    if not isinstance(mod, nn.Linear):
        return False
    if mod.in_features % 16 != 0 or mod.out_features % 16 != 0:
        return False
    if min(mod.in_features, mod.out_features) < 128:
        return False
    return True
```

两个条件分别对应硬件与收益：FP8 张量核心要求矩阵维度能被 16 整除；太小的层（最小维度小于 128）的缩放与布局开销超过矩阵乘收益，直接跳过。d24 的 `nn.Linear` 总数是 $24\times6+12+2=158$（每层 6 个投影、12 个 `ve_gate`、1 个 `lm_head`、1 个 `smear_gate`），其中 145 个被转换，13 个被跳过（12 个 `ve_gate` 与 1 个 `smear_gate`）。d12 是 80 个中转换 73 个。转换发生在 `torch.compile` 之前，否则编译图里仍是 bf16 Linear。

### 6. `disable_fp8`：评测必须回 bf16

`base_train.py` 定义了一个上下文管理器，在进入时把所有 `Float8Linear` 换成自定义 `Linear`，退出时换回：

```python
@contextmanager
def disable_fp8(model):
    fp8_locations = []
    for name, module in model.named_modules():
        if 'Float8' in type(module).__name__:
            if '.' in name:
                parent_name, attr_name = name.rsplit('.', 1)
                parent = model.get_submodule(parent_name)
            else:
                parent = model
                attr_name = name
            fp8_locations.append((parent, attr_name, module))
    for parent, attr_name, fp8_module in fp8_locations:
        linear = Linear(fp8_module.in_features, fp8_module.out_features,
                        bias=fp8_module.bias is not None,
                        device="meta", dtype=fp8_module.weight.dtype)
        linear.weight = fp8_module.weight
        linear.bias = fp8_module.bias
        setattr(parent, attr_name, linear)
    try:
        yield
    finally:
        for parent, attr_name, fp8_module in fp8_locations:
            setattr(parent, attr_name, fp8_module)
```

`Linear` 是 `gpt.py` 里的 cast 版本，`device="meta"` 避免再分配一份权重，随后直接共享 `fp8_module.weight`。进入与退出之间没有复制，只有模块替换。`base_train.py` 在 val bpb、CORE 评测与样本生成三处包裹它；`model.eval()` 本身不会关闭 FP8，因此只调用 `.eval()` 是不够的。

为什么必须回 bf16：FP8 是训练加速格式，不是推理格式；动态量化会让同一权重在不同 batch 上产生不同的舍入，导致 val bpb 与 CORE 的绝对值漂移，无法与 bf16 基线或历史检查点比较。评测的目标是可复现的指标，不是吞吐。

### 7. 收益与风险

`dev/LOG.md` 在 d26 上的全训练对比：

| 配置 | tok/s | 相对 bf16 |
|---|---:|---:|
| BF16 基线 | 630K | 1.00× |
| FP8 rowwise | 564K | 0.90× |
| FP8 tensorwise | 740K | 1.17× |

同一条目还给出 d26 MLP 微基准：BF16 + compile 前向 2.00 ms、前向+反向 4.79 ms；FP8 tensorwise + compile 为 1.45/4.06 ms（1.38×）；FP8 rowwise 无 compile 为 2.89/21.86 ms（0.23×）。结论是 **torch.compile 是硬前提**：没有它，缩放与 cast 的逐元素开销会吞掉矩阵乘收益。

收益的边界：

- 显存减少约 9 GB，因为反向保存的激活从 bf16 变成 FP8；但权重、优化器状态与 KV Cache 仍是高精度。
- 能力匹配后的真实加速约 5%，不是 17%；FP8 每步的损失略差，需要更多 step。
- d12 上 FP8 更慢；当前 speedrun 用 d24，处于「略有收益」的区间。
- 数值风险包括：离群值饱和、全零张量的 scale、`use_fast_accum` 的低精度累加、动态 scale 抖动。若出现 loss 尖峰，先回退 bf16 对照，再检查过滤条件与 `--fp8-recipe`。

### 在 nanochat 中的落地

| 文件/函数 | 关键语句 | 作用 |
|---|---|---|
| `nanochat/fp8.py` | `_to_fp8` | 动态 per-tensor 量化与逆缩放 |
| `nanochat/fp8.py` | `_Float8Matmul.forward/backward` | 三次 FP8 GEMM |
| `nanochat/fp8.py` | `Float8Linear.from_float` | 共享权重、无拷贝替换 |
| `nanochat/fp8.py` | `Float8LinearConfig.from_recipe_name` | 只接受 tensorwise |
| `scripts/base_train.py` | `--fp8`、`--fp8-recipe` | 开关与配方 |
| `scripts/base_train.py` | `fp8_module_filter` | 16 整除与 128 下限 |
| `scripts/base_train.py` | `disable_fp8` | 评测回 bf16 |

## 关键直觉

> [!tip] FP8 只替换矩阵乘的操作数，不替换训练状态
> 把一次 Linear 看成三个 GEMM；FP8 只在这三个 GEMM 的输入上做「缩放 → 饱和 → cast」，输出仍回到 bf16/fp32。master 权重、AdamW/Muon 状态、残差流、softmax 与损失都不在 FP8 中。因此它的精度损失是局部的、可回退的：把 `Float8Linear` 换回 `Linear` 就得到 bf16 路径。这个边界也解释了为什么 `disable_fp8` 只需替换模块，而不需要重训或重新保存检查点。

## 例子与代码

`_to_fp8` 的完整逻辑如下。注意 scale 用 `double()` 计算再转回 float，目的是让 eager 与 `torch.compile` 的除法结果一致；`EPS` 防止全零张量除零：

```python
@torch.no_grad()
def _to_fp8(x, fp8_dtype):
    fp8_max = torch.finfo(fp8_dtype).max
    amax = x.float().abs().max()
    scale = fp8_max / amax.double().clamp(min=1e-12)
    scale = scale.float()
    x_scaled = x.float() * scale
    x_clamped = x_scaled.clamp(-fp8_max, fp8_max)
    x_fp8 = x_clamped.to(fp8_dtype)
    inv_scale = scale.reciprocal()
    return x_fp8, inv_scale
```

下面的最小实验用 `torch.float8_e4m3fn` 比较 per-tensor 与 per-row 的误差。矩阵前三行是 0.1–0.9 的小值，最后一行有一个 $10^6$ 的离群值；这正是 per-tensor 最不利的情形。

```python
import torch

# 前三行是小值，最后一行有一个极端离群值
x = torch.tensor([
    [0.10, 0.20, 0.30, 0.40, 0.50, 0.60, 0.70, 0.80],
    [0.15, 0.25, 0.35, 0.45, 0.55, 0.65, 0.75, 0.85],
    [0.20, 0.30, 0.40, 0.50, 0.60, 0.70, 0.80, 0.90],
    [0.10, 0.20, 0.30, 0.40, 0.50, 0.60, 0.70, 1_000_000.0],
], dtype=torch.float32)

def fake_quant(x, scale):
    q = (x * scale).clamp(-448.0, 448.0).to(torch.float8_e4m3fn)
    return q.float() / scale

s_tensor = 448.0 / x.abs().max()
s_row = 448.0 / x.abs().amax(dim=1, keepdim=True)
for name, y in (("per-tensor", fake_quant(x, s_tensor)),
                ("per-row", fake_quant(x, s_row))):
    err = (y - x).abs()
    small = err[:3]
    print(name,
          "max_all", round(err.max().item(), 4),
          "rel_all", round((err.norm() / x.norm()).item(), 6),
          "max_first3rows", round(small.max().item(), 6),
          "rel_first3rows", round((small.norm() / x[:3].norm()).item(), 6))
print("per-tensor first row:", fake_quant(x, s_tensor)[0].tolist())
print("per-row    first row:", fake_quant(x, s_row)[0].tolist())
```

预期输出：

```text
per-tensor max_all 0.9 rel_all 3e-06 max_first3rows 0.9 rel_first3rows 1.0
per-row max_all 0.7 rel_all 1e-06 max_first3rows 0.028571 rel_first3rows 0.02457
per-tensor first row: [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
per-row    first row: [0.10000000149011612, 0.20000000298023224, 0.2857142984867096, 0.4000000059604645, 0.5142857432365417, 0.5714285969734192, 0.6857143044471741, 0.800000011920929]
```

per-tensor 的 scale 约为 $448/10^6$，前三行的小值缩到 0.1 以下，低于 E4M3 的最小正规数，全部被压成 0；per-row 给每一行独立 scale，前三行的小值保留下来，最大相对误差约 2.5%。全张量的 `rel_all` 之所以看起来接近，是因为 $10^6$ 的离群值主导了范数；评估量化误差时必须分开看小值行。这个例子不是典型 LLM 激活的分布，但说明了 per-tensor 的失效模式，以及为什么 torchao 等实现会提供 per-row 选项。nanochat 选择 tensorwise 并用 clamp 饱和，是在「实现简单、cuBLAS 快」与「极端离群值风险」之间的取舍。

## 易错点

> [!warning] 七个可检验的错误
> 1. 认为 `fp8.py` 使用的是 torchao。它只借用了 torchao 的 API 名称，核心是自定义 `_Float8Matmul` 与 `torch._scaled_mm`；`Float8LinearConfig` 只支持 tensorwise。
> 2. 以为权重被存成 FP8。`Float8Linear` 的 `weight` 仍是原始精度，只有 GEMM 的操作数被量化；master 权重与检查点不变。
> 3. 在评测时只调用 `model.eval()`。FP8 不会因 eval 模式关闭，必须用 `disable_fp8` 替换模块，否则 val bpb/CORE 与 bf16 不可比。
> 4. 把 `--fp8-recipe rowwise` 当作可用选项。CLI 接受该字符串，但自定义 `from_recipe_name` 会抛出 `ValueError`；当前实现只有 tensorwise。
> 5. 忽略 `torch._scaled_mm` 的布局要求。第一个操作数行主序、第二个列主序；`go_fp8.t().contiguous()` 与 `_to_col_major` 不是可选的优化。
> 6. 在过滤条件之外强行转换小层。`min(in,out)<128` 的层（如 `ve_gate`、`smear_gate`）缩放开销大于收益，而且维度不满足 16 的整除要求。
> 7. 用 FP8 的 tok/s 提升直接推断能力提升。LOG 的 1.17× 是吞吐，能力匹配后的真实加速约 5%；d12 上甚至更慢。

## 关联笔记

- 前置：[[前馈层与激活函数]]。FP8 作用在 MLP 的两个矩阵与注意力投影上，矩阵形状决定过滤条件是否满足。
- 前置：[[从第一性看nanochat的gpt.py]]。`Linear` 的 dtype cast 与 `Float8Linear` 的替换关系在该篇的组件选择中给出。
- 后续：[[训练脚本与speedrun]]。`--fp8`、`--fp8-recipe`、`disable_fp8` 在训练循环中的调用位置见该篇。
- 后续：[[分布式训练与优化器分片]]。FP8 只改计算精度，不改优化器状态与梯度同步；两者的边界在该篇展开。
- 跨库：[[模型推理优化]]、[[FLOPs与训练成本估算]]。FP8 的吞吐与成本换算、推理量化的通用讨论见总纲。

## 达标检测

- [ ] 写出 E4M3 与 E5M2 的位数、最大值、最小正规数，并解释为什么前向用 E4M3、反向梯度用 E5M2。
- [ ] 推导 per-tensor 的 scale、clamp、反量化公式，说明 `EPS` 与 `float64` 除法各自防什么问题。
- [ ] 解释 per-row 量化在什么分布下优于 per-tensor，以及为什么 nanochat 不实现 rowwise。
- [ ] 画出 Linear 的三次 GEMM，标出每次的 A/B 操作数、FP8 格式与 `use_fast_accum` 取值。
- [ ] 说明 `convert_to_float8_training` 的后序遍历、共享权重与过滤条件；计算 d24 转换/跳过数量。
- [ ] 解释 `disable_fp8` 为什么用 meta device 构造 `Linear`，以及为什么评测必须回 bf16。
- [ ] 复述 LOG 的 1.17× 吞吐与约 5% 能力匹配加速，说明两者的差别来自哪里。
- [ ] 运行 per-tensor/per-row 示例，解释为什么 per-tensor 的前三行会变成 0。

## 参考来源

- Micikevicius et al., *FP8 Formats for Deep Learning*, arXiv:2209.05433 —— E4M3/E5M2 的格式定义、量程与缩放动机，对应本篇第 1–2 节。
- Karpathy, *nanochat*（commit `92d63d4`），`nanochat/fp8.py` 的 `_to_fp8`、`_Float8Matmul`、`Float8Linear`、`convert_to_float8_training` —— 对应本篇全部实现细节。
- Karpathy, *nanochat*，`scripts/base_train.py` 的 `--fp8`、`fp8_module_filter`、`disable_fp8` —— 对应转换条件与评测回退。
- Karpathy, *nanochat*，`dev/LOG.md` 的 2026-02-02（torchao FP8）、2026-03-04（autocast 移除与 FP8 修复）条目 —— 对应吞吐、显存、d12/d26 差异与 compile 依赖。
- PyTorch 文档，`torch._scaled_mm` 与 `torch.float8_e4m3fn` —— 对应缩放矩阵乘的布局要求与 FP8 dtype 语义。
