---
tags: [nanochat, transformer, attention, flash-attention]
阶段: 04-Transformer架构
难度: ★★★
created: 2026-10-22
related: "[[自注意力机制]], [[多头注意力]], [[KV Cache原理]], [[分组查询注意力GQA]]"
---

# FlashAttention与高效注意力

## 定义

FlashAttention 是一种**精确**的注意力算法：它把查询、键、值切成能放进 GPU 片上 SRAM 的块，按块计算缩放点积注意力，并用 online softmax 维护每一行的运行最大值、分母与加权和，从而不在 HBM 中物化 $(T\times T)$ 的分数矩阵。**滑动窗口注意力**（sliding window attention）在此之上限制每个查询只能看到左侧 $W$ 个 token（含自身共 $W+1$ 个键），把注意力的计算与显存从 $O(T^2)$ 降到 $O(TW)$。

符号约定：批大小 $B$、序列长度 $T$、查询头数 $H$、KV 头数 $H_{kv}$、单头维度 $D$、左窗口 $W$。$\mathbf{Q}\in\mathbb{R}^{B\times T\times H\times D}$，$\mathbf{K},\mathbf{V}\in\mathbb{R}^{B\times T\times H_{kv}\times D}$。**HBM** 是 GPU 的高带宽显存，**SRAM** 是每个流式多处理器内部的片上存储；前者容量大但带宽有限，后者容量小但访问快。**online softmax** 指在不保存完整分数行的前提下，用运行最大值与运行分母增量地计算 softmax。

## 为什么重要

标准注意力要显式构造

$$
\mathbf{S}=\frac{\mathbf{Q}\mathbf{K}^{\top}}{\sqrt{D}},\qquad
\mathbf{P}=\operatorname{softmax}(\mathbf{S}+\mathbf{M}),\qquad
\mathbf{O}=\mathbf{P}\mathbf{V},
$$

其中 $\mathbf{S},\mathbf{P}$ 都是 $(B,H,T,T)$。d24 speedrun 的每卡批大小为 16、$T=2048$、$H=12$：单层分数矩阵有 $16\times12\times2048^2=805{,}306{,}368$ 个元素，bf16 下约 1.5 GiB。前向至少要把 $\mathbf{S}$ 写进 HBM 再读回做 softmax；反向若保存 $\mathbf{P}$，还要再存一份。24 层累加，显存与带宽都不可接受。

FlashAttention 消除的是这项物化，而不是注意力本身的二次计算。它让 2048 上下文在 8×H100 上可训练，也是 nanochat 能在约两小时内跑完 speedrun 的前提之一。FA3 在 Hopper 上进一步利用 TMA、warp specialization 与异步流水，`dev/LOG.md` 记录训练吞吐提升约 9%，在 batch=32、seq=2048 的基准上比 FA2 快约 2 倍。滑动窗口则直接减少计算：d24 的 `SSSL` 模式有 18 层用 512 窗口、6 层用 2048 全上下文，注意力项从每 token 约 $9.06\times10^8$ FLOPs 降到 $3.96\times10^8$，减少约 56%。

在没有 Hopper 的机器上，nanochat 回退到 PyTorch SDPA。数学等价，但 SDPA 没有原生的滑动窗口内核，需要构造 $(T,T)$ 布尔掩码，显存与带宽又回到二次量级；`base_train.py` 会打印警告，并建议在回退路径使用 `--window-pattern L`。这条回退路径决定了本库能在 CPU、MPS 与旧 CUDA 卡上跑通，但不是 performance 路径。

## 原理与推导

### 1. 标准注意力的瓶颈在哪里

对单个 $(B,H)$ 切片，标准实现分三步：矩阵乘得到 $\mathbf{S}$（$T\times T$），逐行 softmax 得到 $\mathbf{P}$，再乘 $\mathbf{V}$ 得到 $\mathbf{O}$。计算量是 $O(T^2D)$，这无法避免；问题在于中间结果的存放位置。

GPU 的算力增长快于 HBM 带宽，注意力在长序列下是**内存受限**的：每读一个 $\mathbf{S}$ 元素要做很少的乘加，大部分时间花在把 $\mathbf{S}$ 写回 HBM、再从 HBM 读出来做 softmax。算术强度（每字节访存对应的 FLOPs）低，张量核心吃不饱。分块的目标不是减少数学运算，而是把中间块留在 SRAM 中，减少 HBM 往返。

### 2. tiling 与 online softmax

设查询块 $\mathbf{Q}_i$ 有 $B_q$ 行，键/值块 $\mathbf{K}_j,\mathbf{V}_j$ 有 $B_k$ 行。对每个查询块，初始化运行最大值 $m_i=-\infty$、运行分母 $\ell_i=0$、运行输出 $\mathbf{O}_i=0$。对每个键块：

$$
\mathbf{S}_{ij}=\frac{\mathbf{Q}_i\mathbf{K}_j^{\top}}{\sqrt{D}},
\qquad
\tilde m_{ij}=\max_{k}\mathbf{S}_{ij,k}.
$$

更新运行统计：

$$
m_i'=\max(m_i,\tilde m_{ij}),
$$

$$
\ell_i'=e^{m_i-m_i'}\ell_i+\sum_k e^{\mathbf{S}_{ij,k}-m_i'},
$$

$$
\mathbf{O}_i'=e^{m_i-m_i'}\mathbf{O}_i+
e^{\tilde m_{ij}-m_i'}\operatorname{softmax}(\mathbf{S}_{ij}-\tilde m_{ij})\mathbf{V}_j.
$$

处理完所有键块后，$\mathbf{O}_i=\mathbf{O}_i'/\ell_i'$。关键在于每一步都用新的最大值重新缩放旧的累加器；这与一次性对整个行做 softmax 的结果完全一致，不是近似。反向传播时，$\mathbf{S}$ 与 $\mathbf{P}$ 不保存，而是从 $\mathbf{Q},\mathbf{K},\mathbf{V}$ 在 SRAM 中重算；代价是额外的 FLOPs，收益是 $O(T)$ 而不是 $O(T^2)$ 的激活显存。

因果掩码只需跳过 $j>i$ 的块；滑动窗口只需跳过与当前查询块距离超过 $W$ 的键块。块内仍需逐元素掩码，块间可以直接跳过，这是 FA 能把窗口优势转化为实际吞吐的原因。

### 3. FA3 在 Hopper 上的收益

FlashAttention-3 针对 Hopper 的硬件特性重写：

- **TMA（Tensor Memory Accelerator）**：异步地在 HBM 与 SRAM 之间搬运整块张量，减少地址计算与寄存器压力。
- **WGMMA 与 warp specialization**：把矩阵乘、softmax、数据搬运分给不同的 warp 组，生产者与消费者重叠，隐藏 softmax 的延迟。
- **异步流水**：GEMM 与 softmax 交错执行，避免张量核心等待。
- **FP8 支持**：在支持 FP8 的张量核心上进一步提高吞吐；nanochat 的 FA3 路径以 bf16 为主。

收益分两部分。**字节**：不写不读 $(T,T)$ 的分数矩阵，HBM 流量从 $O(T^2)$ 降到 $O(T^2D/M)$ 量级（$M$ 为 SRAM 容量），长序列下差距更大。**算力**：分块与流水让张量核心利用率提高，FA3 在 Hopper 上比 FA2 快约 2 倍；nanochat 的端到端训练提升约 9%，因为注意力只占每步总时间的一部分。按 H100 约 3 TB/s 的 HBM 带宽粗算，单层 1.5 GiB 的分数矩阵写一次、读一次就约 1 ms；24 层累计是十毫秒量级，这正是端到端提升有限但不可忽略的原因。

### 4. nanochat 的双后端

`nanochat/flash_attention.py` 在导入时尝试加载 FA3：

```python
def _load_flash_attention_3():
    if not torch.cuda.is_available():
        return None
    major, _ = torch.cuda.get_device_capability()
    if major == 9:
        hf_kernel = "varunneal/flash-attention-3"
        return get_kernel(hf_kernel).flash_attn_interface
    else:
        hf_kernel = "kernels-community/flash-attn3"
        if has_kernel(hf_kernel):
            return get_kernel(hf_kernel).flash_attn_interface
        return None
```

选择规则是：没有 CUDA 就没有 FA3；Hopper（sm90）用 `varunneal/flash-attention-3`，该内核在 H100 上结果更好；其他 sm80/sm86/sm89 用 `kernels-community/flash-attn3`；Blackwell（sm100）没有可用的预编译内核，回退 SDPA。加载失败被 `except Exception` 吞掉，`HAS_FA3` 变为 `False`。

`USE_FA3` 还受 dtype 限制：FA3 的 Hopper 内核只支持 bf16 与 fp8，`COMPUTE_DTYPE` 不是 bf16 时强制回退。测试用的 `_override_impl` 可以强制 `'fa3'` 或 `'sdpa'`，`_resolve_use_fa3()` 在导入时解析一次；这就是 `tests/test_attention_fallback.py` 能在同一台机器上比较两条路径的机制。

两个公开函数的签名不同：

```python
# 训练路径（nanochat/gpt.py）：没有缓存，q/k/v 都是当前序列
y = flash_attn.flash_attn_func(q, k, v, causal=True, window_size=window_size)

# 推理路径（nanochat/gpt.py）：k_cache/v_cache 是预分配缓存，k/v 是当前步的新键值
y = flash_attn.flash_attn_with_kvcache(
    q, k_cache, v_cache, k=k, v=v,
    cache_seqlens=kv_cache.cache_seqlens,
    causal=True, window_size=window_size,
)
```

两个函数的签名差异可以归纳为：

| 函数 | 主要参数 | 缓存 | 返回 |
|---|---|---|---|
| `flash_attn_func` | `q,k,v,causal,window_size` | 无 | $(B,T,H,D)$ |
| `flash_attn_with_kvcache` | `q,k_cache,v_cache,k,v,cache_seqlens,causal,window_size` | 预分配 K/V，原地写 | $(B,T_{new},H,D)$ |

`flash_attn_func` 返回 $(B,T,H,D)$；`flash_attn_with_kvcache` 返回 $(B,T_{new},H,D)$，并把当前步的 $\mathbf{k},\mathbf{v}$ 原地写入 `k_cache/v_cache`（形状 $(B,T_{max},H_{kv},D)$）。`cache_seqlens` 是长度为 $B$ 的 int32 张量，记录每行当前写入位置；nanochat 的 `KVCache` 用 `get_pos()` 读取第一行的位置，用 `advance(T)` 在所有层处理完后推进一次。

SDPA 回退在 `_sdpa_attention` 中处理三种情况：

1. 全上下文且 $T_q=T_k$：直接 `is_causal=True`。
2. 单 token 解码（$T_q=1$）：若窗口小于缓存长度，只取最后 $W+1$ 个键/值，再走非因果 SDPA。
3. 分块推理（$T_q\ne T_k$）：显式构造布尔掩码，行索引从 $T_k-T_q$ 开始，列索引从 0 开始，掩码为 `col <= row`，窗口再加 `row - col <= W`。

第 3 种情况是 SDPA 回退最容易错的地方：`is_causal=True` 只对 $T_q=T_k$ 且从位置 0 开始的对齐成立；一旦查询是缓存中的一段，因果掩码必须按绝对位置重建。

### 5. `window_pattern` 到每层窗口的映射

`GPT._compute_window_sizes` 把模式串按层平铺，最后强制最后一层为全上下文：

```python
pattern = config.window_pattern.upper()
assert all(c in "SL" for c in pattern)
long_window = config.sequence_len
short_window = -(-long_window // 4 // 128) * 128
char_to_window = {"L": (long_window, 0), "S": (short_window, 0)}
window_sizes = []
for layer_idx in range(config.n_layer):
    char = pattern[layer_idx % len(pattern)]
    window_sizes.append(char_to_window[char])
window_sizes[-1] = (long_window, 0)
```

`short_window` 的表达式是「$\lceil T/4\rceil$ 向上取整到 128 的倍数」。对默认 $T=2048$，$T/4=512$ 已是 128 的倍数，结果是 **512**；对 $T=4096$ 是 1024。代码行内注释写的是「2048 -> 768」，与表达式不符；以表达式为准，可用下面的脚本复核。这个差异会影响 FLOPs 估算与 KV 读取量，写实验记录时不要照抄注释。

`SSSL` 在 d24 上平铺 6 次，得到 18 个 `S` 层与 6 个 `L` 层；最后一层本来就是 `L`，强制不改变结果。窗口元组 `(left, 0)` 表示每个查询看到左侧 `left` 个 token 与自身，共 `left+1` 个键。`(-1, 0)` 表示不限左侧。`GPT.estimate_flops` 用 `min(window, T)` 作为有效序列长度，正是基于这个语义。

### 6. SDPA 等价实现与形状检查

下面的参考实现用显式布尔掩码复现因果 + 滑动窗口，并与 `F.scaled_dot_product_attention` 对比。它处理 GQA 的方式是把 KV 头重复到与查询头相同，再走 SDPA；这与 FA3 内部的广播语义等价。

```python
import torch
import torch.nn.functional as F

def attention_with_window(q, k, v, window):
    B, T, H, D = q.shape
    Hk = k.size(2)
    rep = H // Hk
    qh = q.transpose(1, 2)
    kh = k.transpose(1, 2).repeat_interleave(rep, 1)
    vh = v.transpose(1, 2).repeat_interleave(rep, 1)
    scores = qh @ kh.transpose(-1, -2) / D ** 0.5
    # 显式掩码：先因果，再限制左侧窗口
    row = torch.arange(T).unsqueeze(1)
    col = torch.arange(T).unsqueeze(0)
    mask = col <= row
    if window >= 0:
        mask = mask & ((row - col) <= window)
    scores = scores.masked_fill(~mask, float("-inf"))
    probs = torch.softmax(scores, dim=-1)
    return (probs @ vh).transpose(1, 2)

torch.manual_seed(0)
B, T, H, Hk, D, W = 2, 8, 4, 2, 16, 3
q, k, v = torch.randn(B, T, H, D), torch.randn(B, T, Hk, D), torch.randn(B, T, Hk, D)
ref = attention_with_window(q, k, v, W)

kh = k.transpose(1, 2).repeat_interleave(H // Hk, 1)
vh = v.transpose(1, 2).repeat_interleave(H // Hk, 1)
row = torch.arange(T).unsqueeze(1)
col = torch.arange(T).unsqueeze(0)
mask = (col <= row) & ((row - col) <= W)
sdpa = F.scaled_dot_product_attention(
    q.transpose(1, 2), kh, vh, attn_mask=mask
).transpose(1, 2)

print("ref", tuple(ref.shape), "sdpa", tuple(sdpa.shape))
print("max_diff", (ref - sdpa).abs().max().item())
assert ref.shape == (B, T, H, D)
assert torch.allclose(ref, sdpa, atol=1e-5, rtol=1e-5)
```

预期输出：

```text
ref (2, 8, 4, 16) sdpa (2, 8, 4, 16)
max_diff 2.384185791015625e-07
```

`mask` 的布尔语义是 `True` 表示允许注意；`is_causal=True` 不能用在这里，因为参考实现已经显式加了窗口。若把 `window` 设为 `-1`，掩码退化为纯因果；若设为 `T-1`，等价于全上下文。单 token 解码时，$T_q=1$、$T_k$ 为缓存长度，行索引应从 $T_k-1$ 开始，不能从 0 开始。

### 7. 复杂度与显存对照

| 实现 | 时间（全上下文） | 额外显存 | HBM 中间量 | 滑动窗口 |
|---|---|---|---|---|
| 标准注意力 | $O(T^2D)$ | $O(T^2)$ | $\mathbf{S},\mathbf{P}$ | 显式掩码，仍算全矩阵 |
| FlashAttention | $O(T^2D)$ | $O(T)$ 统计量 | 无 | 跳过窗口外的键块 |
| FlashAttention + 窗口 | $O(TWD)$ | $O(T)$ 统计量 | 无 | 块级跳过 |
| SDPA 回退 + 窗口 | $O(T^2D)$ | $O(T^2)$ 掩码 | 掩码/分数 | 显式掩码 |

全上下文下，FlashAttention 的前向 FLOPs 与标准注意力同阶；它省的是显存与 HBM 流量，并通过分块提高张量核心利用率。反向传播会重算 $\mathbf{S}$，因此 FLOPs 略高于保存 $\mathbf{P}$ 的实现，但激活显存从 $O(T^2)$ 降到 $O(T)$；在长序列、显存受限的训练中，这个交换是值得的。滑动窗口才真正降低时间复杂度：每行只与 $W+1$ 个键交互，$T\gg W$ 时从二次降为线性。

### 在 nanochat 中的落地

| 文件/函数 | 关键语句 | 作用 |
|---|---|---|
| `nanochat/flash_attention.py` | `HAS_FA3 = _fa3 is not None` | 导入时探测 |
| `nanochat/flash_attention.py` | `USE_FA3 = _resolve_use_fa3()` | 结合 dtype 与 override 解析一次 |
| `nanochat/flash_attention.py` | `flash_attn_func` | 训练路径，无缓存 |
| `nanochat/flash_attention.py` | `flash_attn_with_kvcache` | 推理路径，原地写缓存 |
| `nanochat/gpt.py` | `flash_attn.flash_attn_func(q, k, v, causal=True, window_size=window_size)` | 注意力调用 |
| `nanochat/gpt.py` | `flash_attn.flash_attn_with_kvcache` | 缓存推理调用 |
| `scripts/base_train.py` | `if args.window_pattern != "L": print0("WARNING: SDPA has no support for sliding window attention")` | SDPA 回退的滑动窗口警告 |
| `tests/test_attention_fallback.py` | `run_both_impls` | 在同一输入上比较 FA3 与 SDPA |

## 关键直觉

> [!tip] FlashAttention 改变的是「在哪里算」，不是「算什么」
> 分块与 online softmax 不改变注意力的数学结果；它改变的是中间结果驻留在 SRAM 还是 HBM。把这一点与滑动窗口区分开：前者是精确的实现优化，后者是改变可见上下文的建模选择。FA3 与 SDPA 在相同 dtype 下应给出几乎相同的结果：`dev/LOG.md` 2026-01-16 记录通常完全一致，滑动窗口下最大差约 $4\times10^{-3}$；测试的容差是 $10^{-2}$。差异来自浮点顺序与窗口边界处理，不是算法定义。理解这个区分，才能判断「换内核」与「改窗口」对模型质量的不同影响。

## 例子与代码

下面的脚本复现 `_compute_window_sizes`，打印 d24 的 24 个窗口与计数。它只依赖标准库，可与 `GPT._compute_window_sizes` 对照：

```python
def window_sizes(L, pattern="SSSL", seq=2048):
    # 复现 GPT._compute_window_sizes：短窗口按 128 向上取整
    long = seq
    short = -(-long // 4 // 128) * 128
    table = {"L": (long, 0), "S": (short, 0)}
    ws = [table[pattern[i % len(pattern)]] for i in range(L)]
    ws[-1] = (long, 0)
    return ws

ws = window_sizes(24)
print("short =", ws[0][0], "long =", ws[3][0])
print("counts =", {w: ws.count(w) for w in sorted(set(ws))})
```

预期输出：

```text
short = 512 long = 2048
counts = {(512, 0): 18, (2048, 0): 6}
```

`ws[0]` 是 `S`，`ws[3]` 是 `L`；`ws[-1]` 被强制为 2048。若把 `seq` 改成 4096，`short` 变为 1024；若把 pattern 改成 `L`，所有层都是 2048，SDPA 回退也不会失去窗口收益。

第二个脚本是上文 SDPA 等价实现，输出已给出。两个脚本合起来覆盖两件事：窗口如何从配置变成每层的 `(left, 0)`，以及这个 `(left, 0)` 在显式掩码下如何与 SDPA 对齐。若要验证 FA3，需要 Hopper GPU 与 bf16；`tests/test_attention_fallback.py` 的 `TestFA3VsSDPA` 会在相同输入上比较两条路径，`TestSDPAOnly` 可在 CPU 上运行。

## 易错点

> [!warning] 七个可检验的错误
> 1. 把 `window_size=(W, 0)` 理解成「只看左侧 $W$ 个，不含当前」。FA3 的语义是含当前，共 $W+1$ 个键；SDPA 单 token 分支用 `start = Tk - (W + 1)` 正对应这一点。
> 2. 在 $T_q\ne T_k$ 的分块推理中使用 `is_causal=True`。因果掩码必须按绝对位置重建，行索引从 $T_k-T_q$ 开始，否则查询会看到不该看的键。
> 3. 把 SDPA 的布尔掩码方向写反。PyTorch 中 `True` 表示允许注意，`False` 表示屏蔽；写成 `col > row` 会得到相反的结果。
> 4. 在非 bf16 的 `COMPUTE_DTYPE` 下仍假设 FA3 可用。FA3 Hopper 内核只支持 bf16 与 fp8，fp16/fp32 会强制走 SDPA。
> 5. 在 Blackwell（sm100）上期待 `kernels-community/flash-attn3` 可用。当前预编译内核不覆盖 sm100，代码回退 SDPA。
> 6. 照抄 `_compute_window_sizes` 的行内注释「2048 -> 768」。表达式实际给出 512；两者的 FLOPs 与 KV 读取量不同。
> 7. 用 FA3 与 SDPA 的微小数值差异判断实现错误。测试容差是 `atol=rtol=1e-2`，滑动窗口的差异可达 $4\times10^{-3}$；关键是形状、掩码与窗口语义一致。

## 关联笔记

- 前置：[[自注意力机制]]、[[多头注意力]]。缩放点积、因果掩码、头拆分与合并的定义见这两篇；本篇只讲高效实现。
- 后续：[[KV Cache原理]]。`flash_attn_with_kvcache` 的缓存布局、prefill/decode 与显存公式在该篇展开。
- 对照：[[nanochat架构特化技巧]]。滑动窗口是架构选择，FlashAttention 是它的执行后端；两者不要混为一谈。
- 跨库：[[注意力机制与QKV]]、[[分组查询注意力GQA]]、[[模型推理优化]]。通用注意力、GQA 与推理优化的系统讨论见总纲，本篇只写 nanochat 的 FA3/SDPA 落地。

## 达标检测

- [ ] 写出标准注意力的三步计算与 $(B,H,T,T)$ 中间张量，估算 d24、$B=16$、$T=2048$ 下单层分数矩阵的字节数。
- [ ] 用自己的话解释 online softmax 的三个运行量 $m,\ell,\mathbf{O}$ 如何更新，并说明它为什么是精确的。
- [ ] 说明 FA3 在 Hopper 上利用的至少三项硬件特性，以及它们分别减少字节还是提高算力利用率。
- [ ] 复述 `HAS_FA3`、`USE_FA3` 的判定条件，解释 Blackwell 与 fp16 为什么会回退 SDPA。
- [ ] 写出 `SSSL` 在 d24 上的窗口计数，并计算 18 层 512、6 层 2048 的注意力 FLOPs 占比。
- [ ] 解释 `flash_attn_func` 与 `flash_attn_with_kvcache` 的签名差异，说明 `cache_seqlens` 与原地写入的作用。
- [ ] 手写滑动窗口的布尔掩码，验证 $T_q=1$ 解码时只保留最后 $W+1$ 个键。
- [ ] 运行窗口脚本，核对 `short=512`，并指出代码注释中 768 的错误。

## 参考来源

- Vaswani et al., *Attention Is All You Need*, arXiv:1706.03762 —— 缩放点积注意力与多头注意力的定义，对应本篇第 1 节。
- Dao et al., *FlashAttention: Fast and Memory-Efficient Exact Attention with IO-Awareness*, arXiv:2205.14135 —— tiling 与 online softmax 的原始算法，对应第 2 节。
- Shah et al., *FlashAttention-3: Fast and Accurate Attention with Asynchrony and Low-precision*, arXiv:2407.08608 —— Hopper 上的 TMA、warp specialization 与异步流水，对应第 3 节。
- Karpathy, *nanochat*（commit `92d63d4`），`nanochat/flash_attention.py`、`nanochat/gpt.py`、`scripts/base_train.py`、`tests/test_attention_fallback.py` —— 对应双后端、窗口映射与回退警告。
- Karpathy, *nanochat*，`dev/LOG.md` 的 2026-01-11（FA3 集成）与 2026-01-16（SDPA 回退）条目 —— 对应 9% 端到端提升、2 倍于 FA2 与测试差异的数值。
