文章目录
-
- [01 本篇要解决什么问题](#01 本篇要解决什么问题)
- [02 核心原理、公式与条件](#02 核心原理、公式与条件)
- [03 手写实现、实验与真实结果](#03 手写实现、实验与真实结果)
- [04 工程场景与排错思路](#04 工程场景与排错思路)
- [05 面试问答与追问](#05 面试问答与追问)
- [06 本篇回顾与练习](#06 本篇回顾与练习)
01 本篇要解决什么问题
注意力公式只有几项矩阵运算,真正容易出错的是缩放、Softmax轴、mask和数值边界。本篇先把投影与注意力核心分开,手写缩放点积,再用循环计算、PyTorch参考接口和梯度检查逐步验收。
02 核心原理、公式与条件
(1)Q、K、V表达的是计算角色
给定输入X,常用不同可训练投影得到Q、K、V。query表示当前要匹配的查询,key参与匹配分数,value被加权汇总;它们不是人工标注好的三个语义数据库。
Self-Attention的QKV来自同一序列,Cross-Attention可以来自不同来源。为核对核心算子,本例直接构造独立Q、K、V,查询长2、键长4;这也是验证不能把所有长度都当T的好方法,完整自注意力投影将在下一篇组合。
(2)每一行是一条query对key的分布
设 Q ∈ R L q × d k Q\in\mathbb R^{L_q\times d_k} Q∈RLq×dk, K ∈ R L k × d k K\in\mathbb R^{L_k\times d_k} K∈RLk×dk, V ∈ R L k × d v V\in\mathbb R^{L_k\times d_v} V∈RLk×dv:
S = Q K T / d k , A = Softmax ( S + M ) , O = A V . S=QK^T/\sqrt{d_k},\quad A=\operatorname{Softmax}(S+M),\quad O=AV. S=QKT/dk ,A=Softmax(S+M),O=AV.
得分与权重为Lq×Lk,输出为Lq×dv。Softmax沿key轴归一,所以每个query的合法权重和为1;若沿query归一,也许shape完全正确,却回答了另一个计算问题。
(3)缩放为什么是平方根
在分量独立、零均值和相应方差假设下,点积方差随dk增长。除以平方根让初始尺度不至于仅因维度增加就大幅扩张,减少Softmax进入尖锐区域的倾向。
这不是任何输入都会保持方差1的保证;训练后的QK可能相关,模型还可能采用不同归一与缩放。省略缩放有时也能训练,不代表它与标准目标等价,应先明确所实现的架构。
(4)稳定Softmax要减行最大值
对同一行加减一个常数不改变Softmax。用 e s i − s m a x / ∑ j e s j − s m a x e^{s_i-s_{max}}/\sum_je^{s_j-s_{max}} esi−smax/∑jesj−smax可避免对很大正数直接指数,PyTorch的标准Softmax会采用相应稳定策略。
稳定公式也无法解决所有输入错误。得分本身含NaN或所有位置被禁止时,仍需明确处理。小精度、点积溢出和融合核误差要另行评估,本例double核对不能代替GPU半精度验收。
(5)先统一自己的mask语义
本系列手写attention统一True表示允许,禁止位置在Softmax前填负无穷,使其权重为0。不能先Softmax再随便把部分位置清零,否则通常破坏行和为1的归一关系。
本实现明确拒绝整行全禁止,避免对全负无穷行给出未定义期望。其他系统可以定义零输出等策略,但必须同步处理导数和下游,不能依赖某版本偶然返回的值。
(6)参考接口也要对齐条件
F.scaled_dot_product_attention的布尔mask中True表示参与,与某些MHA接口的禁止语义不同;本例因此直接传入allowed。dropout_p固定0,矩阵大小、dtype和缩放一致,才比较输出与Q/K/V梯度。SDPA接口
函数式SDPA的dropout由传入参数决定,不能以外层eval自动假定概率变为0。不同后端可能产生数值差异,比较应使用合理容差;正确性参考不等于宣称调用了某个GPU融合实现。
(7)用独立表达降低自证风险
代码既有矩阵版本,也逐query计算点积、稳定归一并累加value。再与库接口比较,并对输出平方和求导,核对Q、K、V各自梯度,最后用gradcheck做数值检查。
只比较前向还可能遗漏反向或mask问题,单一随机样本通过也不是一般性证明。本篇额外验证禁止权重为0、行和为1、极端有限分数可稳定归一,以及全禁止输入会被拒绝。
(8)权重不是因果解释证书
注意力权重显示当前计算怎样加权value,不直接证明某个词是最终答案的原因。投影、其他头、残差和后续层都参与输出,不能仅看热力图就给出完整解释。
标准稠密得分矩阵含Lq·Lk项,除了矩阵乘法,保存权重与反向中间量也需要空间。后续多头与融合算法会改变组织方式,本篇只测数学与CPU数值,没有吞吐、显存节省或任务准确率比较。

03 手写实现、实验与真实结果
核心组件
以下与examples/transformer_core.py中的实现一致;完整模块也收录在公共代码附录。正文入口从该模块导入,按目录保留文件即可运行。
python
import math
import torch
from torch import nn
def attention(q,k,v,allowed=None):
scores=q@k.transpose(-1,-2)/math.sqrt(q.shape[-1])
if allowed is not None:
allowed=torch.broadcast_to(allowed,scores.shape)
if not allowed.any(dim=-1).all(): raise ValueError('all-masked query row is outside this implementation contract')
scores=scores.masked_fill(~allowed,float('-inf'))
weights=torch.softmax(scores,dim=-1)
return weights@v,weights
完整实验入口
在解压根目录运行python examples/lesson_15.py,保留tf_common.py与transformer_core.py。先按README安装CPU依赖,之后无需联网或下载权重;不使用会关闭断言的python -O。
python
import math,torch
from torch.nn import functional as F
from transformer_core import attention
from tf_common import output_dir,finish,table,figure,plt
def main():
out=output_dir(15); torch.manual_seed(1515); torch.set_num_threads(1)
q=torch.randn(1,2,3,dtype=torch.double,requires_grad=True)
k=torch.randn(1,4,3,dtype=torch.double,requires_grad=True)
v=torch.randn(1,4,5,dtype=torch.double,requires_grad=True)
allowed=torch.tensor([[[True,False,True,True],[True,True,False,True]]])
actual,weights=attention(q,k,v,allowed)
loop=torch.zeros_like(actual)
for i in range(2):
values=torch.stack([(q[0,i]*k[0,j]).sum()/math.sqrt(3) for j in range(4)])
values=values.masked_fill(~allowed[0,i],float('-inf')); probabilities=(values-values.max()).exp(); probabilities=probabilities/probabilities.sum()
for j in range(4): loop[0,i]=loop[0,i]+probabilities[j]*v[0,j]
reference=F.scaled_dot_product_attention(q,k,v,attn_mask=allowed,dropout_p=0)
assert torch.allclose(actual,loop,atol=1e-12) and torch.allclose(actual,reference,atol=1e-12)
grad=torch.autograd.grad(actual.square().sum(),(q,k,v),retain_graph=True)
ref_grad=torch.autograd.grad(reference.square().sum(),(q,k,v),retain_graph=True)
errors=[(a-b).abs().max().item() for a,b in zip(grad,ref_grad)]; assert max(errors)<1e-10
assert torch.autograd.gradcheck(lambda a,b,c:attention(a,b,c,allowed)[0],(q,k,v))
rejected=False
try: attention(q,k,v,torch.zeros_like(allowed))
except ValueError: rejected=True
assert rejected and torch.equal(weights[~allowed],torch.zeros_like(weights[~allowed]))
assert torch.allclose(weights.sum(-1),torch.ones_like(weights.sum(-1)))
z=torch.tensor([1000.,1001.],dtype=torch.double); assert torch.isinf(z.exp()).any() and torch.isfinite(z.softmax(-1)).all()
table(out/'attention_weights.csv',['query','key','allowed','weight'],[(i,j,allowed[0,i,j].item(),weights[0,i,j].item()) for i in range(2) for j in range(4)])
fig,ax=plt.subplots(figsize=(7,4),constrained_layout=True); im=ax.imshow(weights[0].detach(),vmin=0,vmax=1,cmap='Blues'); fig.colorbar(im,ax=ax)
ax.set(xlabel='key index',ylabel='query index',title='Handwritten attention probabilities'); figure(fig,out)
finish(out,{'output_shape':list(actual.shape),'loop_max_error':(actual-loop).abs().max().item(),'SDPA_max_error':(actual-reference).abs().max().item(),
'gradient_errors_Q_K_V':errors,'gradcheck':True,'all_masked_rows_rejected':rejected,
'scope':'CPU double, non-square attention, dropout=0; all-masked rows explicitly unsupported; no fused-kernel benchmark'})
if __name__=='__main__': main()
非方形缩放点积同时对照显式循环与SDPA,检查QKV梯度和gradcheck;禁止权重为0、行和为1,全禁止行按约定拒绝。无dropout或融合核性能测量。
本次实际运行
json
{
"output_shape": [
1,
2,
5
],
"loop_max_error": 2.220446049250313e-16,
"SDPA_max_error": 2.220446049250313e-16,
"gradient_errors_Q_K_V": [
8.881784197001252e-16,
5.551115123125783e-16,
8.881784197001252e-16
],
"gradcheck": true,
"all_masked_rows_rejected": true,
"scope": "CPU double, non-square attention, dropout=0; all-masked rows explicitly unsupported; no fused-kernel benchmark"
}

图由实际CSV和程序生成,未平滑或补造;SVG、JSON与明细保留在实验结果目录。前向、梯度、结构与最终任务表现是不同结论,误差小不代表任意设备逐位相同。
04 工程场景与排错思路
写新注意力变体时,先在小double张量上确定接口契约,再比较参考和梯度。若模型loss异常好,检查mask是否在正确轴与正确阶段应用;若出现NaN,检查全禁止行与输入有限性,而不是只给分母加epsilon。
05 面试问答与追问
问题1:Q、K、V必须形状一样吗?
QK最后维度要匹配,K与V的键长度要一致,但查询长度和value宽度可以不同。Self-Attention只是其中一个常见组合。
问题2:Softmax为什么沿key轴?
每条query要得到对可读取key的分布,再对对应value加权,归一轴由这一语义决定。
问题3:减最大值改变权重吗?
在有限正常输入的数学表达中不改变Softmax,却改善指数计算稳定性;不能保证NaN或全禁止行自动变合法。
问题4:mask之后权重和为零可以吗?
取决于事先定义。本实现拒绝全禁止行,其他合法行应归一为1;不能随意后清零再宣称和标准注意力相同。
问题5:eval会自动关闭函数式SDPA的dropout吗?
不能依赖这一点,函数使用传入dropout_p。本例显式设0,真实模块应按训练状态选择参数。
问题6:参考输出相等就证明实现完全正确吗?
仍需对齐参数、梯度、掩码和异常输入。小样本检查增加证据,不替代一般推导和真实环境验收。
06 本篇回顾与练习
复习时先明确轴、目标、精度和接口语义,再推导运算并预测小例子的输出。实现通过后仍需独立验收数据、评价与部署条件;不能把合成记忆或数值一致性当成真实语言能力。
| 练习 | 思路与验收重点 |
|---|---|
| 手算一条query | 给出三个key和value,标出缩放、归一与汇总。 |
| 构造非方形注意力 | 让Lq不同于Lk,核对得分与输出形状。 |
| 比较前后mask | 展示Softmax后清零为何改变归一,并定义全禁止策略。 |
延伸阅读:缩放点积接口。练习提示不等于额外完整题解,接口与默认值按实际版本核对。