---
tags: [AI, LLM, 注意力变体]
阶段: 05-Transformer与LLM原理
难度: ★★★
created: 2026-10-18
related: "[[KV缓存]], [[因果注意力与多头注意力]], [[Llama-2架构复盘]]"
---

# 分组查询注意力GQA

## 定义

**分组查询注意力**（grouped-query attention，GQA）是把 $H$ 个查询头划分为 $G$ 个连续组、每组内所有查询头共享同一个键头与值头、且满足 $1<G<H$ 的注意力变体，其键值头数 $H_{kv}=G$，每个键值头服务于 $n_{\text{rep}}=H/H_{kv}$ 个查询头。

三种配置由 $H_{kv}$ 统一刻画：**多头注意力**（multi-head attention，MHA）取 $H_{kv}=H$，每个查询头有独立的键与值；**多查询注意力**（multi-query attention，MQA）取 $H_{kv}=1$，全部查询头共享一份键与值；GQA 取中间值，$1<H_{kv}<H$。

本篇符号约定如下。

| 符号 | 含义 |
|---|---|
| $H$ | 查询头数，决定注意力矩阵的份数 |
| $H_{kv}$ | 键值头数，决定缓存与键值投影的规模 |
| $G$ | 组数，$G=H_{kv}$ |
| $n_{\text{rep}}$ | 每组包含的查询头数，$n_{\text{rep}}=H/H_{kv}$ |
| $d_h$ | 每头维度 |
| $d$ | 模型维度，$d=H d_h$ |
| $B$ | 批量大小 |
| $T$ | 序列长度 |
| $T_q,T_k$ | 查询长度与键长度，解码时 $T_q=1$、$T_k=t$ |
| $t$ | 解码时的缓存长度，即已有键值的位置数 |
| $L$ | 层数 |
| $b$ | 每元素字节数，fp16 为 2 |
| $M$ | 键值缓存字节数 |
| $g(h)$ | 查询头 $h$ 所属的组，$g(h)=\lfloor h/n_{\text{rep}}\rfloor$ |
| $r$ | 组内序号，$r=h\bmod n_{\text{rep}}$ |

术语定义：**查询头**（query head）是产生一组查询向量的投影子空间；**键值头**（key-value head）是产生一组键与值向量的投影子空间；**组**（group）是共享同一键值头的查询头集合；**uptraining** 指把已训练模型的注意力结构改为另一种头数配置后用少量继续预训练恢复质量的过程；**repeat_kv** 指把键值头沿头维复制 $n_{\text{rep}}$ 份、使头数与查询头对齐的张量操作；**张量并行分片**指把同一层的头分散到多张加速卡上的切分方式。

## 为什么重要

[[KV缓存]] 的显存与解码读取量都正比于键值头数。MHA 的每个查询头都有独立的键与值，缓存大小为 $2LHd_hTBb$；解码时每个 token 要把这份缓存完整读一遍，而计算量只有 $4Btd$，算术强度约为 1 FLOP/byte，处于显存带宽受限区。GQA 把键值头数从 $H$ 降到 $H_{kv}$，缓存大小与读取字节按 $n_{\text{rep}}$ 比例下降，而查询头数与注意力矩阵的规模不变，因此计算量基本不变。这是一条只改结构超参数、不改训练目标就能获得的效率收益。

MQA 把 $H_{kv}$ 降到 1，收益最大，但代价是质量退化与训练不稳定：全部查询头只能共用一份键空间，头间差异只能通过查询表达，键值投影还要同时承受所有头的梯度。对已经用 MHA 训练好的模型，重新按 MQA 训练一遍的代价不可接受，因此需要一条低成本的转换路径。GQA 的论文给出两条结论：用原预训练步数 5% 的继续预训练可以把 MHA 检查点转换为 GQA 或 MQA；转换后的 GQA 在质量接近 MHA 的同时，速度接近 MQA。

大模型更需要 GQA。头数随模型规模增长，MQA 把 $H$ 个头直接降为 1 个，容量削减的比例随 $H$ 增大而增大；GQA 固定 $H/H_{kv}$ 的比例，使削减幅度与模型规模无关。张量并行部署时，单个键值头会被复制到每个分区，MQA 的这份复制浪费在分区数增大时更明显，GQA 按组划分减少了重复。Llama-2 在 34B 与 70B 上采用 GQA，70B 的配置为 64 个查询头、8 个键值头，即 $n_{\text{rep}}=8$。

在本库中的位置：本篇承接 [[KV缓存]] 的显存与带宽分析，把其中的 $H$ 替换为可调参数 $H_{kv}$；[[因果注意力与多头注意力]] 给出 MHA 的拆分与拼接，本篇只改键值的头数。后续 [[Llama-2架构复盘]] 把 GQA 与 RMSNorm、SwiGLU、RoPE 组合成真实模型；[[超长上下文-无限注意力]] 处理缓存随上下文线性增长的另一种路线。对应学习目标：懂原理要求推出显存与带宽随 $H_{kv}$ 的变化并说明计算量为何不变；能复现要求写出 `repeat_kv` 与 GQA 前向并验证 $H_{kv}=H$ 时与 MHA 等价；会评估要求能根据质量与延迟数据判断组数取值。

## 原理与推导

### 1 三种配置的统一参数化

设模型维度 $d=Hd_h$。GQA 一层的四个投影矩阵为

$$
\mathbf{W}_Q\in\mathbb{R}^{d\times Hd_h},\quad
\mathbf{W}_K,\mathbf{W}_V\in\mathbb{R}^{d\times H_{kv}d_h},\quad
\mathbf{W}_O\in\mathbb{R}^{Hd_h\times d}.
$$

查询投影与输出投影的参数量固定为 $d^{2}$ 与 $d^{2}$，与 $H_{kv}$ 无关；键与值投影的参数量各为 $d\cdot H_{kv}d_h=d^{2}/n_{\text{rep}}$。单层参数量为

$$
\underbrace{d^{2}}_{\mathbf{W}_Q}+\underbrace{2d^{2}/n_{\text{rep}}}_{\mathbf{W}_K,\mathbf{W}_V}+\underbrace{d^{2}}_{\mathbf{W}_O}+\underbrace{8d^{2}}_{\text{前馈}}
=10d^{2}+\frac{2d^{2}}{n_{\text{rep}}}.
$$

前馈网络的 $8d^{2}$ 来自两个矩阵 $d\times4d$ 与 $4d\times d$。三种配置的差别只在第二项。

| 配置 | $H_{kv}$ | $n_{\text{rep}}$ | 单层键值投影参数 | 单层总参数 |
|---|---|---|---|---|
| MHA | $H$ | 1 | $2d^{2}$ | $12d^{2}$ |
| GQA | $H/n_{\text{rep}}$ | $n_{\text{rep}}$ | $2d^{2}/n_{\text{rep}}$ | $10d^{2}+2d^{2}/n_{\text{rep}}$ |
| MQA | 1 | $H$ | $2d^{2}/H$ | $10d^{2}+2d^{2}/H$ |

以 Llama-2 70B 为例，$d=8192$，$H=64$，$d_h=128$。MHA 的单个键投影为 $8192\times8192=67.1$M 参数，键与值合计 $134.2$M；GQA-8 的单个键投影为 $8192\times1024=8.39$M，合计 $16.8$M。乘以 80 层，键值投影总量从 $10.74$B 降到 $1.34$B；若同宽度、同层数的模型改用 MHA，键值投影会多出约 $9.4$B 参数。

### 2 缓存显存随键值头数线性下降

缓存只保存键与值，且只为每个键值头保存一份。把 [[KV缓存]] 的公式中的 $H$ 换成 $H_{kv}$：

$$
M=2\cdot L\cdot H_{kv}\cdot d_h\cdot T\cdot B\cdot b
=\frac{2LHd_hTBb}{n_{\text{rep}}}.
$$

对固定的 $L,d_h,T,B,b$，$M$ 与 $H_{kv}$ 成正比，因此组数减半则缓存减半。以 70B 的 $H=64$ 为例，MHA 到 GQA-8 降为 $1/8$，到 MQA 降为 $1/64$；一般地，MQA 相对 MHA 的比值为 $1/H$。下表为 Llama-2 70B 在 $T=4096$、$B=1$、fp16 下的数值，$L=80$，$d_h=128$。

| 配置 | $H_{kv}$ | $n_{\text{rep}}$ | 每 token 字节 | $T=4096$ 缓存 | 相对 MHA |
|---|---|---|---|---|---|
| MHA | 64 | 1 | 2560 KiB | 10240 MiB | 1 |
| GQA-32 | 32 | 2 | 1280 KiB | 5120 MiB | 1/2 |
| GQA-16 | 16 | 4 | 640 KiB | 2560 MiB | 1/4 |
| GQA-8 | 8 | 8 | 320 KiB | 1280 MiB | 1/8 |
| MQA | 1 | 64 | 40 KiB | 160 MiB | 1/64 |

每 token 字节数由 $2LH_{kv}d_hb$ 给出，例如 $2\times80\times8\times128\times2=327680$ 字节 $=320$ KiB。同样的换算用于 7B 模型（$L=32$，$H=32$，$d_h=128$，$T=4096$）：MHA 为 $2$ GiB，GQA-8 为 $512$ MiB，MQA 为 $64$ MiB。缓存显存决定单卡可容纳的并发序列数与最大上下文长度，因此 $H_{kv}$ 的选择直接改变服务容量。

带宽的下降方向相同但需要区分构成。解码一步单层的显存流量由缓存读取 $4BtH_{kv}d_h$ 字节与权重读取 $24d^{2}$ 字节组成，两者之比为

$$
\frac{4BtH_{kv}d_h}{24d^{2}}=\frac{Bt}{6dn_{\text{rep}}}.
$$

该比值随 $B$ 与 $t$ 增大而增大，随 $n_{\text{rep}}$ 增大而减小。以 $t=4096$ 为例，7B 的 GQA-8 模型在 $B=1$ 时缓存占单步流量的 $2.0\%$，$B=32$ 时为 $40.0\%$；70B 的 GQA-8 模型在 $B=1$ 时为 $1.0\%$，$B=32$ 时为 $25.0\%$。这说明在小批量下权重读取占主导，GQA 的主要作用是容量；批量增大使权重被摊薄后，缓存读取成为主要项，GQA 的带宽收益才充分体现。长上下文使 $t$ 增大，效果与增大批量相同。

### 3 计算量不变的原因

注意力的矩阵乘法代价为

$$
F_{\text{attn}}=2BHT_qT_kd_h+2BHT_qT_kd_h=4BHT_qT_kd_h,
$$

其中 $T_k$ 是全部键的位置数。该式只含 $H$，不含 $H_{kv}$。原因是每个查询头仍要产生自己的 $T_q\times T_k$ 分数矩阵，仍要与全部键做点积；共享键值不减少查询头与键的配对数，只减少键与值的来源份数。`repeat_kv` 把 $[B,H_{kv},T_k,d_h]$ 复制为 $[B,H,T_k,d_h]$，复制本身是 $O(BHT_kd_h)$ 个元素的访存操作。预填充阶段 $T_q\gg1$，它相对矩阵乘的 $O(BHT_qT_kd_h)$ 可忽略；解码阶段 $T_q=1$，两者同阶，但复制可由核函数在读取时广播完成而不物化，因此不会成为主要成本。

键值投影的代价确实下降：解码一步的键值投影为 $4BT_qd^{2}/n_{\text{rep}}$，MHA 为 $4BT_qd^{2}$。以 $d=4096$、$T_q=1$ 为例，该项从 $6.71\times10^{7}$ 降到 $8.39\times10^{6}$；解码单层总代价约 $4td+24d^{2}=4.70\times10^{8}$，该项占比从约 $14\%$ 降到约 $2\%$，合计节省约 $12.5\%$ 的浮点运算。因此推理加速的主要来源不是浮点运算减少，而是显存流量减少。

算术强度可以写成

$$
A(B,t)=\frac{B\left(4td+24d^{2}\right)}{4Btd/n_{\text{rep}}+24d^{2}}.
$$

| 配置 | $B=1$ | $B=8$ | $B=32$ |
|---|---|---|---|
| 7B，$t=4096$，MHA | 1.00 | 4.00 | 5.89 |
| 7B，$t=4096$，GQA-8 | 1.14 | 8.00 | 22.40 |
| 70B，$t=4096$，MHA | 1.00 | 5.20 | 9.45 |
| 70B，$t=4096$，GQA-8 | 1.07 | 8.00 | 26.00 |

单位为 FLOP/byte。当 $B\to\infty$ 时 $A\to n_{\text{rep}}(1+6d/t)$，在 $d=t=4096$ 时 MHA 的上限为 7，GQA-8 为 56，仍低于 A100 的算力带宽比约 156 FLOP/byte。因此 GQA 缩小了算术强度与算力带宽比之间的差距，但在常见上下文长度下解码仍处于带宽受限区，只是每秒可处理的 token 数按字节减少的比例上升。

### 4 组内共享机制与前向实现

头与组的对应关系由张量的头维顺序决定。查询张量经 `view(B, T, H, d_h)` 后，第 $h$ 个头占据头维的第 $h$ 个切片；键张量经 `view(B, T, H_{kv}, d_h)` 后，第 $g$ 个键值头占据第 $g$ 个切片。定义

$$
g(h)=\left\lfloor \frac{h}{n_{\text{rep}}}\right\rfloor,\qquad r=h\bmod n_{\text{rep}} ,
$$

即编号相邻的 $n_{\text{rep}}$ 个查询头共用同一个键值头：查询头 $0,\dots,n_{\text{rep}}-1$ 用键值头 0，查询头 $n_{\text{rep}},\dots,2n_{\text{rep}}-1$ 用键值头 1，依此类推。这一分组是连续的，因此可以直接用重塑实现，不需要收集索引。

`repeat_kv` 的实现分三步：在头维之后插入长度为 1 的组维，沿该维广播 $n_{\text{rep}}$ 份，再把组维并入头维。设输入形状 $[B,H_{kv},T,d_h]$，第一步得 $[B,H_{kv},1,T,d_h]$，第二步得 $[B,H_{kv},n_{\text{rep}},T,d_h]$，第三步按行优先展平前两个非批量维，得到头编号

$$
g\cdot n_{\text{rep}}+r,
$$

与式中的 $h$ 一致。顺序不能颠倒：若在头维之前插入组维，展平后头编号变为 $r\cdot H_{kv}+g$，键值头与查询头的对应关系整体错位，形状仍然正确，输出不会报错，但每个查询头读到的键值来自错误的组。

广播得到的视图不连续，不能直接 `view`；应使用 `reshape`（必要时自动复制）或先 `contiguous()`。较新版本的 `torch.nn.functional.scaled_dot_product_attention` 提供 `enable_gqa` 参数，可直接接受 $[B,H,T_q,d_h]$ 的查询与 $[B,H_{kv},T_k,d_h]$ 的键值，在核内完成广播而不物化复制，显存与带宽更省。

$n_{\text{rep}}=1$ 时 `repeat_kv` 返回原张量，GQA 退化为 MHA，这是验证实现正确性的基准：用同一组权重分别走 GQA 路径与显式 MHA 路径，输出应逐元素相等。

### 5 从 MHA 检查点 uptraining 到 GQA

论文给出的流程分两步：转换检查点，再用少量继续预训练让模型适应新结构。

转换步骤。设原 MHA 第 $\ell$ 层第 $h$ 个键头为 $\mathbf{W}_K^{(\ell,h)}$，$h=g\cdot n_{\text{rep}}+r$，$g=0,\dots,H_{kv}-1$，$r=0,\dots,n_{\text{rep}}-1$，每组的新键投影取组内均值：

$$
\mathbf{W}_K^{(\ell,g)}=\frac{1}{n_{\text{rep}}}\sum_{r=0}^{n_{\text{rep}}-1}\mathbf{W}_K^{(\ell,g n_{\text{rep}}+r)},\qquad
\mathbf{W}_V^{(\ell,g)}=\frac{1}{n_{\text{rep}}}\sum_{r=0}^{n_{\text{rep}}-1}\mathbf{W}_V^{(\ell,g n_{\text{rep}}+r)} .
$$

均值池化的依据是最小化组内偏差：对固定的 $n_{\text{rep}}$ 个矩阵，使 $\sum_r\lVert\mathbf{W}-\mathbf{W}_r\rVert_F^{2}$ 最小的 $\mathbf{W}$ 就是算术平均。它保留了组内键方向的平均分量，比只取第一个头或随机初始化保留更多已训练信息；论文的消融显示均值池化优于这两种做法。查询投影、输出投影、前馈网络与归一化参数保持不变，因为它们的形状与语义没有改变；若把输出投影也做池化，会破坏残差通路的尺度与已学到的输出组合。

继续预训练。用原预训练配方继续训练原步数的 $\alpha$ 比例，论文取 $\alpha=0.05$。对 T5-XXL 规模，这一步约需 600 TPUv3 chip-days，是完整的继续预训练而非从头训练。论文的消融有两点结论：转换后的 GQA 已具备可用质量，MQA 则需要继续预训练才有竞争力；$\alpha$ 从 $0.05$ 增到 $0.1$ 的收益递减。转换适用于解码器自注意力与交叉注意力，不适用于编码器自注意力，因为编码器表示并行计算，带宽不是主要瓶颈。

也可以直接用 GQA 结构从零训练，此时不需要转换与 uptraining，但需要完整的预训练预算。uptraining 的价值在于复用已有 MHA 检查点，把结构改造成本压到原预训练的 $5\%$ 量级。

### 6 质量与效率的实验结论

GQA 论文在 T5-XXL 上比较了 MHA、5% uptraining 的 MQA 与 GQA-8，结果如下表。推理时间为每样本每 TPUv4 芯片的秒数，平均性能是摘要、翻译与问答各任务指标的混合平均，只能用于相对比较。

| 模型 | 推理时间（s） | 平均性能 |
|---|---|---|
| MHA-Large | 0.37 | 46.0 |
| MHA-XXL | 1.51 | 47.2 |
| MQA-XXL | 0.24 | 46.6 |
| GQA-8-XXL | 0.28 | 47.1 |

三组对比给出主要结论。GQA-8 相对 MHA-XXL 把推理时间从 $1.51$ s 降到 $0.28$ s，降幅约 $81\%$，平均性能从 $47.2$ 降到 $47.1$。GQA-8 相对 MQA-XXL 多花 $0.04$ s，约 $17\%$，换回 $0.5$ 的平均性能。组数消融显示，从 MQA 增加组数时，初期速度损失很小而质量上升较快；接近 MHA 时，每增加一组的速度代价上升。论文据此选择 8 组作为折中。

Llama-2 的选择与此一致：7B 与 13B 使用 MHA，34B 与 70B 使用 GQA。规模越大，缓存的绝对量越大，GQA 的容量收益越明显；同时大模型的头数更多，MQA 的相对容量损失更大。需要注意 T5 是编码器-解码器结构且使用相对位置偏置，Llama-2 是解码器结构并使用 RoPE，上述数值不能直接迁移到 Llama-2，可迁移的是「GQA-8 接近 MHA 质量、接近 MQA 速度」这一相对关系。

### 7 MQA 质量退化的机制

MQA 是 GQA 在 $H_{kv}=1$ 处的端点，其退化原因可以分解为三条。

键空间的秩受限。MHA 中一层内所有键头拼接后的键矩阵，其列空间至多 $H d_h=d$ 维；每个头可以学习不同的键子空间，用于匹配不同类型的查询。MQA 只有一组键，键空间被限制在 $d_h$ 维子空间内，维度降为原来的 $1/H$。需要同时表达词法相似、位置邻近、句法依赖等多种关系的键，只能在这个低维子空间内折中。

头间差异只能由查询表达。全部查询头读取同一组键与值，注意力分布的差异完全来自查询投影。若两个头需要不同的相似度度量（例如一个关注前一个 token，另一个关注句法中心词），它们的查询必须在这组共享键上产生不同的分数分布，这比各自拥有键子空间时更难实现。头专门化的自由度因此下降。

共享参数的梯度冲突。键投影与值投影由全部 $H$ 个头共享，反向传播时它们的梯度是 $H$ 个头梯度之和。各头的目标不完全一致，共享参数的最优解是加权折中，训练损失高于各自独立时的损失；这也是论文报告 MQA 可能出现训练不稳定的原因之一。若共享参数取组内平均即可近似各头所需，则折中损失小，GQA 的中间组数正是利用这一点：组内头的需求相近，组间保留差异。

以上是机制性解释，不是定理。可检验的证据是组数消融：$H_{kv}$ 从 $H$ 降到 1 的过程中质量单调下降，且下降在接近 1 时更陡；容量与梯度的两种解释都与这一形状一致。

## 关键直觉

> [!tip] 机制表述
> GQA 只改变键与值的来源份数，不改变查询的份数与注意力矩阵的规模：$H$ 个查询头仍然各自产生 $T_q\times T_k$ 的分数矩阵，但每 $n_{\text{rep}}$ 个头共享一组键值。因此浮点运算量基本不变，而缓存字节、缓存读取字节与键值投影参数按 $n_{\text{rep}}$ 下降。定义中的 $H_{kv}$ 是这条折中曲线上的位置：$H_{kv}=H$ 时容量最大、字节最多，$H_{kv}=1$ 时字节最少、容量最小；GQA 在两端之间按组数取值，把「每组一份键值」作为可调的结构超参数。

## 例子与代码

### 手算：4 个查询头、2 个键值头、$d_h=2$

取 $H=4$，$H_{kv}=2$，$n_{\text{rep}}=2$，$d_h=2$，缩放因子 $1/\sqrt{2}$。查询头 0 与 1 属于组 0，共用键值头 0；查询头 2 与 3 属于组 1，共用键值头 1。

组 0 的键与值为 $\mathbf{k}_1=(1,0)$、$\mathbf{k}_2=(0,1)$、$\mathbf{v}_1=(1,0)$、$\mathbf{v}_2=(0,1)$。查询头 0 的查询为 $\mathbf{q}_0=(1,0)$，查询头 1 的查询为 $\mathbf{q}_1=(1,1)$。两个头读取同一组键值，分数分别为

$$
\mathbf{q}_0:\ \frac{(1,0)}{\sqrt2},\qquad
\mathbf{q}_1:\ \frac{(1,1)}{\sqrt2},
$$

即 $(0.7071,0)$ 与 $(0.7071,0.7071)$。softmax 后头 0 的权重为 $(0.670,0.330)$，头 1 为 $(0.5,0.5)$，输出分别为 $(0.670,0.330)$ 与 $(0.5,0.5)$。共享键值不使两个头产生相同输出，差异来自查询；但两个头无法使用不同的键子空间，这是容量损失的来源。

缓存元素数对比：MHA 每层每 token 的键值元素为 $2Hd_h=16$，GQA-2 为 $2H_{kv}d_h=8$，降为一半。

### PyTorch 实现：repeat_kv、GQA 注意力与缓存

```python
import math

import torch
import torch.nn as nn
import torch.nn.functional as F


def repeat_kv(k, n_rep):
    """[B, H_kv, T, d_h] -> [B, H_kv*n_rep, T, d_h]，头序为 g*n_rep + r。"""
    if n_rep == 1:
        return k
    B, H_kv, T, dh = k.shape
    k = k[:, :, None, :, :].expand(B, H_kv, n_rep, T, dh)
    return k.reshape(B, H_kv * n_rep, T, dh)  # expand 后不连续，用 reshape 而非 view


class GQAttention(nn.Module):
    """H 个查询头、H_kv 个键值头的因果自注意力，可选 KV 缓存。"""

    def __init__(self, d_model: int, n_head: int, n_kv_head: int):
        super().__init__()
        assert n_head % n_kv_head == 0, "查询头数必须能被键值头数整除"
        assert d_model % n_head == 0
        self.n_head = n_head
        self.n_kv_head = n_kv_head
        self.n_rep = n_head // n_kv_head
        self.dh = d_model // n_head
        self.wq = nn.Linear(d_model, n_head * self.dh, bias=False)
        self.wk = nn.Linear(d_model, n_kv_head * self.dh, bias=False)
        self.wv = nn.Linear(d_model, n_kv_head * self.dh, bias=False)
        self.wo = nn.Linear(n_head * self.dh, d_model, bias=False)

    def forward(self, x, past=None):
        B, T, _ = x.shape
        q = self.wq(x).view(B, T, self.n_head, self.dh).transpose(1, 2)      # [B,H,T,dh]
        k = self.wk(x).view(B, T, self.n_kv_head, self.dh).transpose(1, 2)   # [B,Hkv,T,dh]
        v = self.wv(x).view(B, T, self.n_kv_head, self.dh).transpose(1, 2)
        if past is not None:
            k = torch.cat([past[0], k], dim=2)
            v = torch.cat([past[1], v], dim=2)
        present = (k, v)                     # 缓存保留 H_kv 个头，不复制
        k = repeat_kv(k, self.n_rep)         # 广播到 H 个头
        v = repeat_kv(v, self.n_rep)
        Tk = k.size(2)
        s = (q @ k.transpose(-2, -1)) / math.sqrt(self.dh)
        mask = torch.triu(torch.ones(T, Tk, device=x.device), diagonal=Tk - T + 1).bool()
        s = s.masked_fill(mask, float("-inf"))
        y = (F.softmax(s, dim=-1) @ v).transpose(1, 2).reshape(B, T, -1)
        return self.wo(y), present
```

这段代码的关键点是 `present` 在 `repeat_kv` 之前保存。若把复制后的张量写入缓存，缓存形状会变成 $[B,H,T,d_h]$，与 $H_{kv}$ 个键值头的设定不符：下一轮拼接时头数不匹配会报错；若恰好在下游按 $H$ 解释，则每轮缓存按 $n_{\text{rep}}$ 倍膨胀，显存估算全部失效。

下面的函数是不含 GQA 的显式 MHA 参考实现，用于等价性检验。

```python
def mha_reference(x, wq, wk, wv, wo, n_head):
    """用同一组权重执行标准多头注意力，作为 GQA 在 H_kv=H 时的参照。"""
    B, T, C = x.shape
    dh = C // n_head
    q = wq(x).view(B, T, n_head, dh).transpose(1, 2)
    k = wk(x).view(B, T, n_head, dh).transpose(1, 2)
    v = wv(x).view(B, T, n_head, dh).transpose(1, 2)
    s = (q @ k.transpose(-2, -1)) / math.sqrt(dh)
    mask = torch.triu(torch.ones(T, T, device=x.device), diagonal=1).bool()
    s = s.masked_fill(mask, float("-inf"))
    y = (F.softmax(s, dim=-1) @ v).transpose(1, 2).reshape(B, T, C)
    return wo(y)


torch.manual_seed(0)
x = torch.randn(2, 8, 64)
gqa = GQAttention(d_model=64, n_head=8, n_kv_head=8)  # H_kv = H，应退化为 MHA
with torch.no_grad():
    y_gqa, _ = gqa(x)
    y_mha = mha_reference(x, gqa.wq, gqa.wk, gqa.wv, gqa.wo, 8)
print("H_kv=H 最大绝对误差:", (y_gqa - y_mha).abs().max().item())  # 0.0
```

两路径使用同一组投影权重，且 $n_{\text{rep}}=1$ 时 `repeat_kv` 直接返回输入，因此二者执行的是同一串运算，输出逐元素相等。需要注意，`repeat_kv` 的维度顺序错误在 $n_{\text{rep}}=1$ 时不会暴露，因为此时不复制；顺序错误只在 $n_{\text{rep}}>1$ 时改变键与查询的对应关系。因此等价性检验必须与头序检验配合，后者的方法见下一小节的 NumPy 版本。

下面的代码打印不同配置的键值头数、每 token 字节数与 $T=4096$ 的缓存大小，模型参数取 Llama-2 70B 的 $L=80$、$d_h=128$。

```python
def cache_mib(n_layer, n_kv_head, head_dim, seq_len, batch=1, nbytes=2):
    return 2 * n_layer * n_kv_head * head_dim * seq_len * batch * nbytes / 2 ** 20


for name, H, H_kv in [("MHA", 64, 64), ("GQA-32", 64, 32), ("GQA-16", 64, 16),
                      ("GQA-8", 64, 8), ("MQA", 64, 1)]:
    per_token = 2 * 80 * H_kv * 128 * 2
    print(f"{name:7s} H_kv={H_kv:2d} n_rep={H // H_kv:2d} "
          f"每 token {per_token / 1024:6.0f} KiB  T=4096 {cache_mib(80, H_kv, 128, 4096):7.1f} MiB")
```

输出为

```text
MHA     H_kv=64 n_rep= 1 每 token   2560 KiB  T=4096 10240.0 MiB
GQA-32  H_kv=32 n_rep= 2 每 token   1280 KiB  T=4096  5120.0 MiB
GQA-16  H_kv=16 n_rep= 4 每 token    640 KiB  T=4096  2560.0 MiB
GQA-8   H_kv= 8 n_rep= 8 每 token    320 KiB  T=4096  1280.0 MiB
MQA     H_kv= 1 n_rep=64 每 token     40 KiB  T=4096   160.0 MiB
```

### NumPy 版本：头序与等价性检查

以下代码用 NumPy 复现同一组张量操作，检查 `repeat_kv` 的头序，并验证 $H_{kv}=H$ 时的等价性。

```python
import math

import numpy as np

rng = np.random.default_rng(1)


def softmax(x):
    e = np.exp(x - x.max(-1, keepdims=True))
    return e / e.sum(-1, keepdims=True)


def repeat_kv(k, n_rep):
    """k: [B, Hkv, T, dh] -> [B, Hkv*n_rep, T, dh]。"""
    B, Hkv, T, dh = k.shape
    if n_rep == 1:
        return k
    return np.repeat(k[:, :, None, :, :], n_rep, axis=2).reshape(B, Hkv * n_rep, T, dh)


def attend(q, k, v):
    dh = q.shape[-1]
    s = q @ k.transpose(0, 1, 3, 2) / math.sqrt(dh)
    mask = np.triu(np.ones((q.shape[2], k.shape[2]), dtype=bool), k=1)
    return softmax(np.where(mask, -1e30, s)) @ v


def attention(q, k, v, n_rep):
    """GQA 路径：先 repeat_kv 再计算。"""
    return attend(q, repeat_kv(k, n_rep), repeat_kv(v, n_rep))


def attention_gather(q, k, v, n_rep):
    """独立实现：按组下标收集键值，不使用 repeat_kv。"""
    idx = np.arange(q.shape[1]) // n_rep
    return attend(q, k[:, idx], v[:, idx])


B, T, D, H, n_rep = 2, 8, 64, 8, 2
Hkv, dh = H // n_rep, D // H
x = rng.normal(0, 1, (B, T, D))
wq = rng.normal(0, 0.1, (D, D))
wk = rng.normal(0, 0.1, (D, D))
wv = rng.normal(0, 0.1, (D, D))

q = (x @ wq).reshape(B, T, H, dh).transpose(0, 2, 1, 3)
k_mha = (x @ wk).reshape(B, T, H, dh).transpose(0, 2, 1, 3)
v_mha = (x @ wv).reshape(B, T, H, dh).transpose(0, 2, 1, 3)

wk_gqa = wk.reshape(D, Hkv, n_rep, dh).mean(2).reshape(D, Hkv * dh)  # 键：组内均值
wv_gqa = wv.reshape(D, Hkv, n_rep, dh).mean(2).reshape(D, Hkv * dh)  # 值：组内均值
k_gqa = (x @ wk_gqa).reshape(B, T, Hkv, dh).transpose(0, 2, 1, 3)
v_gqa = (x @ wv_gqa).reshape(B, T, Hkv, dh).transpose(0, 2, 1, 3)

out_gqa = attention(q, k_gqa, v_gqa, n_rep)
out_gather = attention_gather(q, k_gqa, v_gqa, n_rep)
print("q, k, repeat_kv(k):", q.shape, k_gqa.shape, repeat_kv(k_gqa, n_rep).shape)
print("头序检查:", np.allclose(repeat_kv(k_gqa, n_rep)[:, 5], k_gqa[:, 2]))
print("GQA 与按组收集的最大绝对误差:", np.abs(out_gqa - out_gather).max())

out_eq = attention(q, k_mha, v_mha, 1)            # H_kv = H
out_mha = attention_gather(q, k_mha, v_mha, 1)    # 显式 MHA 参照
print("H_kv=H 最大绝对误差:", np.abs(out_eq - out_mha).max())
```

输出为

```text
q, k, repeat_kv(k): (2, 8, 8, 8) (2, 4, 8, 8) (2, 8, 8, 8)
头序检查: True
GQA 与按组收集的最大绝对误差: 0.0
H_kv=H 最大绝对误差: 0.0
```

`attention` 与 `attention_gather` 是两条独立实现：前者先复制再按头计算，后者用整数除法得到每个查询头所属的组下标，直接索引键值。两者输出相同，说明 `repeat_kv` 产生的是正确的组内对应关系，而不是把 $n_{\text{rep}}$ 份键值按错误的顺序拼接。头序检查进一步比较复制后的第 5 个头与原始第 2 个键值头：$5=2\times2+1$，属于组 2，与 $g\cdot n_{\text{rep}}+r$ 一致。$H_{kv}=H$ 时 $n_{\text{rep}}=1$，两条路径都退化为普通多头注意力，误差为 0。

## 易错点

> [!warning] 常见错误
> 1. `repeat_kv` 的维度顺序错误。组维必须插在头维之后、位置维之前，即 `k[:, :, None, :, :]`；若插在头维之前或在位置维之后，展平后的头编号不再是 $g\cdot n_{\text{rep}}+r$，键与查询的对应关系错位。该错误不改变形状，也不抛出异常，只表现为质量下降。检验方法是比较 `repeat_kv(k, n_rep)[:, h]` 与 `k[:, h // n_rep]` 是否相等。
> 2. 组数不能整除。$H$ 不能被 $H_{kv}$ 整除时无法均匀分组，`n_rep = H // H_kv` 会静默向下取整，导致复制后的头数为 $H_{kv}\lfloor H/H_{kv}\rfloor<H$，与查询头数不匹配，矩阵乘法在头维上报错；若用向上取整再切片，则部分查询头对应的键值头编号越界。实现应在构造时断言 `H % H_kv == 0`。
> 3. 缓存头数写成查询头数。缓存形状应为 $[B,H_{kv},T,d_h]$，不是 $[B,H,T,d_h]$；写错时显存按 $n_{\text{rep}}$ 倍分配，下一轮 `repeat_kv` 又会把已有的 $H$ 个头再复制 $n_{\text{rep}}$ 份，形状变为 $H\cdot n_{\text{rep}}$ 并报错。正确做法是先把未复制的键值存入 `present`，再调用 `repeat_kv`。
> 4. 把复制后的张量写回缓存。复制是为了与查询头对齐，属于前向内部的临时量；写回会使缓存每步按 $n_{\text{rep}}$ 倍膨胀。缓存只需保留 $H_{kv}$ 个键值头，因为查询头与组的映射在每步都相同。
> 5. uptraining 时池化了不该池化的矩阵。只对 $\mathbf{W}_K$ 与 $\mathbf{W}_V$ 按组取均值；$\mathbf{W}_Q$、$\mathbf{W}_O$、前馈与归一化参数保持不变。池化 $\mathbf{W}_O$ 会把不同头的输出组合压成平均，破坏残差通路的尺度与已学到的表示，转换后的损失会显著高于仅池化键值的版本。
> 6. 认为 GQA 降低了注意力 FLOPs。查询头数不变，每个头仍要与全部键做点积，$4BHT_qT_kd_h$ 不变；下降的是键值投影参数、缓存字节与缓存读取带宽。把 GQA 当作算力优化会在算力受限的场景中得到与预期不符的加速比。

## 关联笔记

- 前置：[[KV缓存]]。缓存显存与解码带宽的公式给出 $H$ 的角色，本篇把 $H$ 替换为 $H_{kv}$，两篇的显存公式只在这一点上不同。
- 前置：[[因果注意力与多头注意力]]。MHA 的头拆分、缩放与掩码是本篇的实现基础；GQA 只在键值的头数上做修改。
- 对照：[[注意力机制与QKV]]。该篇给出单头注意力的完整推导，本篇的组内共享可以看作把头维的键值投影从 $H$ 份减为 $H_{kv}$ 份。
- 后续：[[Llama-2架构复盘]]。70B 的 64 查询头与 8 键值头是 GQA 的标准实例，该篇把这一配置放入完整模型。
- 后续：[[超长上下文-无限注意力]]。GQA 降低单位上下文的缓存成本，但不改变缓存随 $T$ 线性增长的性质；该篇讨论改变增长阶的路线。

## 达标检测

- [ ] 给出 MHA、GQA、MQA 的 $H_{kv}$ 取值，并用 $n_{\text{rep}}$ 写出三者的键值投影参数量。
- [ ] 用 $2LH_{kv}d_hTBb$ 计算 Llama-2 70B 在 $H_{kv}=64,8,1$、$T=8192$、$B=2$、fp16 下的缓存大小，并说明与 $H_{kv}$ 的比例关系。
- [ ] 写出 `repeat_kv` 的维度变换步骤，证明展平后的头编号为 $g\cdot n_{\text{rep}}+r$，并说明为何必须用 `reshape` 而不是 `view`。
- [ ] 证明 $H_{kv}=H$ 时 GQA 与 MHA 等价，并在代码中运行等价性检验，报告最大绝对误差。
- [ ] 写出 uptraining 的均值池化公式与继续预训练比例，说明为什么只池化 $\mathbf{W}_K$ 与 $\mathbf{W}_V$。
- [ ] 已知 $d=t=4096$、$B=8$，分别计算 MHA 与 GQA-8 的算术强度，判断两者是否已脱离带宽受限区。
- [ ] 解释 MQA 质量退化的两条机制（键空间秩、梯度冲突），并指出哪一条在 $H_{kv}$ 从 1 增到 8 时缓解最快。

## 参考来源

- Ainslie et al., *GQA: Training Generalized Multi-Query Transformer Models from Multi-Head Checkpoints*, arXiv:2305.13245, EMNLP 2023 —— 对应本篇第 1、2、5、6 节的定义与参数化、缓存收益、uptraining 流程与 T5-XXL 实验。
- Shazeer, *Fast Transformer Decoding: One Write-Head is All You Need*, arXiv:1911.02150, 2019 —— 对应 MQA 的提出与解码阶段带宽瓶颈的分析。
- Touvron et al., *Llama 2: Open Foundation and Fine-Tuned Chat Models*, arXiv:2307.09288, 2023 —— 对应 34B 与 70B 采用 GQA 的配置与推理可扩展性说明。
- Vaswani et al., *Attention Is All You Need*, arXiv:1706.03762, 2017 —— 对应第 1 节 MHA 的原始参数化与头数定义。
- PyTorch docs，`torch.Tensor.expand`、`torch.Tensor.reshape`、`torch.nn.functional.scaled_dot_product_attention` —— 对应 `repeat_kv` 的广播语义、复制与 `enable_gqa` 参数。
