直接用 nn.Transformer 是可行的，但必须自己补全输入预处理、位置编码、掩码逻辑和输出解码——它不包含任何嵌入层或位置编码，也不是开箱即用的“模型”，而是一个纯注意力块堆叠器。
为什么 nn.Transformer 不能直接喂原始文本或序列ID？
问题就出在它的设计定位上。nn.Transformer 模块本质上是一个“注意力引擎”，它默认你已经完成了所有前置的准备工作。它的输入必须是严格的三维张量 (seq_len, batch_size, embed_dim)。这意味着，词嵌入、位置编码以及各种掩码逻辑，都需要你手动添加并组合好，再喂给它。
更棘手的是，它内部不做任何形状校验。如果你传错了维度，得到的往往是一些含义模糊的运行时错误，比如 RuntimeError: expected tensor to ha ve size 1 at dimension 2，排查起来相当费劲。
实践中，新手常踩的坑包括：
- 把常见的
(batch_size, seq_len, embed_dim)格式直接传进去（忘了转置）→ 导致size mismatch。 - 漏掉了为解码器构造
tgt_mask（因果掩码）→ 模型在训练时“偷看”了未来信息，导致输出全是重复或无意义的词元。 - 误将
nn.TransformerEncoder当作完整的 Transformer 模型使用 → 缺少解码器部分，无法完成序列到序列的任务。
如何正确构造一个可训练的 Seq2Seq Transformer？
以机器翻译这类经典任务为例，你需要像搭积木一样，显式地组装以下核心组件：
立即学习“Python免费学习笔记（深入）”；
- 两个独立的嵌入层：分别对应源语言和目标语言的词表（
nn.Embedding）。 - 位置编码：通常是一个可学习的参数矩阵（
nn.Parameter，形状为(max_len, embed_dim)），直接加到词嵌入的输出上。 - Transformer 核心：实例化
torch.nn.Transformer，并配置好编码器、解码器的层数等超参数。 - 解码器输入与掩码：解码器的输入（
tgt）需要右移一位（使用tgt[:-1]），同时必须调用nn.Transformer.generate_square_subsequent_mask()来生成因果掩码，防止信息泄露。 - 输出层：最后接一个线性层和 log_softmax 激活，以匹配目标词表的大小。
一段关键的结构化代码示例如下：
model = nn.Transformer(
d_model=512,
nhead=8,
num_encoder_layers=6,
num_decoder_layers=6,
dim_feedforward=2048,
dropout=0.1
)
# 注意：输入要转置！
src = src_emb(src_ids).transpose(0, 1) # (seq_len, batch, 512)
tgt = tgt_emb(tgt_ids[:-1]).transpose(0, 1)
tgt_mask = model.generate_square_subsequent_mask(tgt.size(0))
output = model(src, tgt, tgt_mask=tgt_mask) # (seq_len, batch, 512)
logits = output.transpose(0, 1) @ lm_head_weight.t() # 或用 nn.Linear
训练时最容易崩的三个地方
模型写对只是第一步，训练崩盘往往源于数据流或掩码的细微偏差。以下几个地方需要格外警惕：
- 维度顺序：
src和tgt的序列长度维度（seq_len）必须是第一维。这是nn.Transformer的硬性规定（采用 time-major 格式），而非更常见的 batch-first 格式。 - 因果掩码：为解码器生成的
tgt_mask必须是严格的上三角矩阵（上三角部分用float('-inf')填充，下三角和对角线为 0）。否则，解码器就会“作弊”，导致训练失败。 - 填充掩码：用于忽略 padding 位置的
src_key_padding_mask和tgt_key_padding_mask，必须使用布尔类型（bool）张量（True表示需要被掩蔽的填充位置）。如果误用int或float类型，可能会静默失败，不报错但效果异常。
一个实用的调试技巧是，在模型的前向传播开头加入断言检查，例如 assert src.dim() == 3 and src.size(0) > 1，这样可以提前避免因单词元输入而触发的内部维度重塑错误。
想快速验证结构，别碰 nn.Transformer ——改用 Hugging Face Transformers
如果你的目标是快速验证一个标准 Transformer 模型（例如 BERT 或 T5）的效果，那么自己从头组装 nn.Transformer 的性价比极低。你需要编写的“胶水代码”量远超模型本身。
此时，Hugging Face 的 Transformers 库是更明智的选择。它的 AutoModelForSeq2SeqLM 等类已经封装了全部预处理、注意力缓存、生成逻辑，并且提供了友好的 generate() 接口：
from transformers import AutoModelForSeq2SeqLM
model = AutoModelForSeq2SeqLM.from_pretrained("t5-small")
outputs = model.generate(input_ids, max_length=50)
而要使用 nn.Transformer 实现与之等效的完整功能，你至少还需要额外实现束搜索（beam search）、过去键值缓存（past_key_values）、以及复杂的填充处理逻辑——这些其实已经超出了“模型架构”的范畴。
所以说，真正需要手动编写 nn.Transformer 的场景并不多，主要集中于高度定制化的研究，例如设计稀疏注意力机制、替换前馈网络结构，或者进行底层的机制探索。对于日常的建模任务而言，它更像一个提供基础组件的“乐高底座”，而非一个拿起来就能玩的“成品玩具”。
