因为TensorFlow Layer默认不自动传播mask，必须在call(self, inputs, mask=None)中显式声明mask参数，否则padding位置会参与计算导致softmax和梯度错误。
为什么 call 方法里必须显式传入 mask 参数？
TensorFlow 的 Layer 默认不自动接收或传播 mask，即使上游层（如 Embedding）生成了 mask，它也不会自动流入自定义 Attention 层。如果你没在 call 签名里声明 mask=None，那 mask 就直接丢了——导致 padding 位置参与计算，softmax 结果歪掉，梯度也出错。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 在自定义层的
call(self, inputs, mask=None)中必须接收mask，哪怕暂时不用 - 如果
inputs是 query/key/value 三元组，mask 通常对应 query 和 key 的序列长度维度，比如query_mask和key_mask，需拆解：if mask is not None:<br> query_mask, key_mask = mask[0], mask[1]
- 不要依赖
self.supports_masking = True自动生效——它只影响是否把 mask 传下来，不解决你怎么用
如何用 tf.where + tf.float32.min 实现 soft mask？
Attention score 矩阵（shape: [batch, heads, q_len, k_len]）需要把 padding 位置的 score 设为极小值，让 softmax 后趋近于 0。直接赋 -inf 在某些 GPU 设备上可能触发 NaN，更稳妥的是用 tf.float32.min。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 先扩展 mask：把
key_mask（shape[batch, k_len]）扩成[batch, 1, 1, k_len]，再广播到 score 维度 - 构造 boolean mask：
padding_mask = tf.expand_dims(tf.expand_dims(key_mask, 1), 1) # [b,1,1,k]
- 应用 mask：
score_masked = tf.where(padding_mask, score, tf.float32.min)
- 注意：
tf.where的 condition 必须和两个分支 tensor shape 兼容，否则报Incompatible shapes
MultiHeadAttention 的 mask 传参方式和自定义层有何不同？
TF 内置 tf.keras.layers.MultiHeadAttention 把 mask 当作独立参数，不是通过 call(..., mask=...)，而是显式写成 attention_mask=... 或 causal_mask=...。这意味着你不能靠继承它并重写 call 来“复用 mask 逻辑”，除非你手动转发。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 若想基于内置 MHA 加 mask，直接调用时传
attention_mask=key_mask（注意是attention_mask，不是mask） - 若要完全自定义（比如带 relative position bias），别套壳 MHA，从
tf.keras.layers.Layer重写，自己管理query/key/value投影和 mask 应用时机 - 内置层对
attention_mask的处理是逐 head 广播的，但不会校验 shape；如果传入[batch, q_len, k_len]外形的 mask，它能 work；但传[batch, k_len]就会报错
训练时 mask 正确但推理出错，常见原因是什么？
最常踩的坑是：训练时用了 Embedding + mask_zero=True，所以 mask 自动产生；但推理时输入是完整序列（比如全 1 的 batch），没 padding，mask 全 True，导致 attention 全关掉。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 永远检查
mask是否为None，而不是假设它存在：if mask is not None and query_mask is not None:
- 推理阶段若无 padding，可传
tf.ones_like(query_ids, dtype=tf.bool)避免 mask 干预 - 用
tf.debugging.assert_equal在开发期验证 mask shape：tf.debugging.assert_equal(tf.shape(score_masked), tf.shape(score))
mask 的 shape 对齐和 dtype（必须是 bool）比逻辑更重要；错一个维度，整个 batch 的 attention 就塌缩成单个 token 的响应。
