不需要手动写掩码逻辑，但必须正确传入src_key_padding_mask（bool型、(batch_size, seq_len)）或mask（float型、(seq_len, seq_len)），二者语义不同、不可混用。
PyTorch 2.0 中 nn.TransformerEncoder 还需要手动写掩码逻辑吗？
不需要——但得写对。PyTorch 2.0 的 nn.TransformerEncoder 本身不自动处理序列长度变化或填充（padding）掩码，它只接受一个 src_key_padding_mask 或 mask 参数，且两者语义不同、不能混用。很多人卡在“明明传了 mask 却没生效”，其实是传错了类型或形状。
-
mask是 attention 矩阵掩码：shape 为(seq_len, seq_len)，用于防止位置 i 看到 j > i（即 causal 掩码），或任意自定义的成对屏蔽；值为float('-inf')或True（bool 类型时会自动转为float('-inf')） -
src_key_padding_mask是 key-padding 掩码：shape 为(batch_size, seq_len)，True表示该位置是 padding，对应 key 应被忽略；必须是torch.bool - 两个参数可同时传，但作用层级不同：
mask在 QK^T 后加，src_key_padding_mask在 softmax 前扩展到(batch_size, 1, seq_len)再广播应用
如何正确构造 src_key_padding_mask 处理变长 batch？
这是最常出错的地方：直接用 pad_sequence 拼接后，忘记生成对应 mask，或用 == pad_token_id 时数据类型不匹配（比如 float tensor 里和 int 比）。
- 假设你用
torch.nn.utils.rnn.pad_sequence得到src: (seq_len, batch_size, embed_dim)，那么src_key_padding_mask必须是(batch_size, seq_len)且 dtype=torch.bool - 推荐构造方式：
src_key_padding_mask = (src == pad_value).all(dim=-1).t()
——但仅当 embedding 维度全为 pad_value 才安全；更稳妥的是在 pad 时额外记录原始长度：lengths = torch.tensor([len(x) for x in unpaded_list])<br>src_key_padding_mask = torch.arange(src.size(0))[:, None] >= lengths[None, :]
- 注意：
src_key_padding_mask传入前必须.to(device)，否则和src设备不一致会报RuntimeError: expected self and mask to be on the same device
nn.TransformerEncoder 在 PyTorch 2.0 里要不要加 torch.compile？
要，但有前提。PyTorch 2.0 的 torch.compile 对 nn.TransformerEncoder 支持良好，尤其在训练时能显著加速，但需确保输入张量 shape 不含动态 batch 维度（即 batch_size 不能是 symbolic）。
- 编译前建议固定 batch size 或使用
dynamic_shapes=False（默认）；若用torch.compile(model, dynamic=True)，首次运行会触发多轮 recompilation，延迟明显 - 注意
src_key_padding_mask若每 step 都变（如不同长度的句子），会导致 compile cache miss；可考虑预生成常见长度 mask 并缓存，或改用mask+causal=True简化场景 - 验证是否生效：编译后第一次 forward 较慢，第二次起应明显快于未编译版本；也可查
model._compiled_call是否存在
为什么用了 mask 还能看到未来 token？
大概率是 mask 形状或值填错了。PyTorch 的 nn.MultiheadAttention（TransformerEncoder 底层）对 mask 要求极严格：必须是 (seq_len, seq_len)，且上三角（含对角）为 0 或 False，下三角为 -inf 或 True 才实现 causal。
立即学习“Python免费学习笔记（深入）”；
- 标准 causal mask 写法：
mask = torch.triu(torch.full((seq_len, seq_len), float('-inf')), diagonal=1)——注意是triu+diagonal=1，不是tril - 如果手写
mask[i, j] = float('-inf') if j > i else 0.，务必确认i是 query 位置、j是 key 位置（即 mask 行是 query，列是 key） - 调试技巧：打印
mask[0]看前几列是否全为-inf（表示第一个 token 看不到任何后续 token），再 printmask[-1]看最后一行是否全为0.（表示最后一个 token 可看到全部）
forward 里反复计算；建议在 dataloader 侧预生成，或用 functools.lru_cache 缓存固定长度的 mask。复杂点永远不在模型结构，而在掩码和长度对齐的边界上。 
