torch.nn.MultiheadAttention需显式传入query=key=value=x、设batch_first=True、手动缩放、加位置编码、LayerNorm置于残差后、causal mask需手写且注意形状与dtype。
为什么 torch.nn.MultiheadAttention 不能直接当“自注意力层”用
它默认做的是 query-key-value 三者分离的注意力，而标准 Transformer 自注意力要求 query、key、value 全部来自同一输入。如果你直接把输入 x 塞进去却不重设权重，MultiheadAttention 会用三套独立初始化的投影矩阵，破坏“自”这个前提。
实操建议：
- 显式传入
query=x、key=x、value=x，避免依赖默认行为 - 务必设置
batch_first=True，否则MultiheadAttention默认按(seq_len, batch, embed_dim)处理，容易引发 shape 错误 - 如果想复现原始论文结构（比如每头单独缩放），注意
scale参数：PyTorch 默认不除以sqrt(d_k)，得手动在forward中补上或改写_scaled_dot_product_attention
位置编码必须加在 embedding 后、进 attention 前
位置信息不是可选插件，而是自注意力能识别序列顺序的唯一依据。漏加、加错位置、或加在归一化之后，都会让模型彻底失去时序感知能力——训练 loss 不降、生成结果乱序，但错误本身不报异常。
常见错误现象：
立即学习“Python免费学习笔记（深入）”；
- 训练初期 loss 下降极慢，且 attention 权重图全是一片均匀灰（没聚焦）
- 验证集 perplexity 突然卡住，比随机 baseline 还差
- 用
torch.sin/cos实现位置编码时，忘记把pos和i转成float，导致广播失败
关键点：
- 位置编码张量形状必须和 token embedding 完全一致：
(batch_size, seq_len, d_model) - 别用
nn.Embedding学习位置编码——除非你明确要适配不同长度，否则固定 sinusoidal 更稳定、更省显存 - 加法操作必须是 element-wise，确保
embedding + pos_encoding不触发自动广播变形
LayerNorm 放在哪？顺序错了模型根本学不动
原始 Transformer 论文里每个 sub-layer 后都跟一个 LayerNorm，而且是“残差 + norm”，不是“norm + 残差”。顺序颠倒会导致梯度在 early layers 几乎消失，尤其在 deep 模型中，loss 会卡在高位不动。
正确流程（以 attention 子层为例）：
- 输入
x - 算 attention 输出
attn_out - 执行
x + attn_out（残差连接） - 再做
LayerNorm(x + attn_out)
容易踩的坑：
- 把
LayerNorm放在Linear或Dropout前面——这会让 dropout 丢掉 norm 后的分布，破坏稳定性 - 在
forward中重复调用self.norm(x)两次（比如误写成 norm→attn→norm→ffn），造成隐式 double-norm - 用
nn.BatchNorm1d替代LayerNorm：batch 维度不稳定，小 batch 下效果剧烈波动
为什么你的 mask 总是不起作用
自回归解码（如语言建模）必须用 causal mask，否则模型偷看未来 token，训练 loss 虚低、推理时崩溃。但 PyTorch 的 nn.TransformerDecoder 默认 mask 是 None，不会自动帮你生成上三角掩码。
实操要点：
- 手写 causal mask 用
torch.tril(torch.ones(seq_len, seq_len))，再转成bool或float（-inf/0）格式 - 传给
MultiheadAttention的attn_mask必须是(seq_len, seq_len)或(batch, seq_len, seq_len)，形状错一位就静默失效 - 训练时若用 packed sequence 或变长 batch，mask 得按最大长度 pad，且 padding 位置也要屏蔽（额外加
key_padding_mask）
最常被忽略的一点：mask 的 dtype 必须和 attention score 一致。用 float mask 就得确保 attention 计算中没做 .softmax() 前的类型转换，否则 NaN 会悄无声息地污染梯度。
