尧图网页设计 
Transformer 已经不只是 NLP 领域的模型结构而是当前深度学习里最值得花时间吃透的基础组件。无论是 BERT、GPT、ViT还是各类多模态模型底层都能看到多头自注意力、前馈网络、残差连接和 LayerNorm 的组合。很多人在使用现成库时感觉不难一旦需要修改结构、调试显存、排查 Loss 不下降才发现自己对它的理解停留在 API 层。这篇内容会沿着一条完整路径展开先解释 Transformer 解决什么问题再逐层拆解架构然后用 PyTorch 从零实现一个最小可训练的 Transformer跑一个复制序列任务验证正确性最后延伸到 Vision Transformer、Swin Transformer 和 TCNTransformer 时间序列预测等工程方向。读完以后你不仅能看懂源码还能自己修改结构也能在遇到 Loss 不下降、维度报错、Mask 失效这类问题时知道从哪里切入排查。1. 先搞清楚 Transformer 解决的原始问题1.1 循环网络处理序列的方式与瓶颈在 Transformer 出现之前处理序列任务的主流结构是 RNN、LSTM 和 GRU。它们的基本思路是一致的按时间步逐个读入 token维护一个隐状态h_t把历史信息压缩到向量里再传给下一步。这种机制有两个明显问题。第一个问题是无法并行。第t步的计算依赖第t-1步的隐状态所以无论序列多长都只能一个 token 一个 token 往后算。GPU 的并行能力在这种顺序计算中被浪费了模型训练速度受序列长度影响非常大。第二个问题是长距离信息衰减。RNN 每一步都会把历史信息“压”进一个固定大小的隐状态随着步数增加早期信息会逐渐被冲淡。LSTM 通过门控机制缓解了梯度消失但本质上仍然是顺序传递序列很长时远距离 token 之间的依赖关系依然难建。下面是一个最简 RNN 单元的计算示意h_t tanh(W_hh h_{t-1} W_xh x_t b)这里的h_t既要承担当前步的信息又要向后传递信息容量有限容易成为瓶颈。1.2 注意力机制从“记住全部”到“按需提取”注意力机制的核心思想是不要求网络把历史压缩在同一个向量里而是让每一步都能直接“回头看”所有历史位置按相关性加权提取信息。以机器翻译为例源语言句子里的每个 token 都有自己的向量表示。翻译目标语言第t个词时模型先计算当前状态与源语言每个 token 的匹配分数再用 softmax 转成权重最后对所有源语言向量做加权和。这样重要的词获得更大权重模型不必把全部信息塞进一个隐状态。这种机制在 Bahdanau 等人提出的注意力模型中被用于改进机器翻译后来逐渐演变成 Transformer 中的自注意力不仅查询和解码状态可以做注意力序列内部每个位置之间也可以做注意力。1.3 为什么最终是 TransformerTransformer 在 2017 年提出原本是为了解决机器翻译问题但它把“注意力”推到了极致整个模型完全抛弃循环结构只用自注意力、前馈网络和归一化层堆叠得到。它带来的直接收益有三个。第一是并行计算。自注意力对序列内部所有位置同时计算不再有 RNN 那样的时间步依赖。第二是长距离依赖建模。任意两个位置之间只隔一次矩阵乘法信息路径比 RNN 短得多。第三是统一的模块化结构。编码器和解码器都由相同的层堆叠而成方便扩展到不同任务。代价也很直接自注意力的计算复杂度是O(n^2 * d)其中n是序列长度d是特征维度。序列越长计算量和显存占用增长越快。很多后续工作都在围绕“如何降低自注意力的计算量”展开比如局部窗口注意力、稀疏注意力、线性注意力等。特性RNN/LSTMCNNTransformer并行能力差好好长距离依赖弱依赖卷积核感受野强计算复杂度O(n * d^2)与卷积核大小相关O(n^2 * d)局部归纳偏置无强弱输入顺序建模天然天然需加位置编码这组对比能解释很多工程选择时间序列不长时LSTM 仍可用图像任务中 CNN 的局部归纳偏置更省数据但数据量大、序列长、需要全局依赖时Transformer 结构更容易发挥优势。2. Transformer 核心架构拆解2.1 宏观结构Encoder 与 DecoderTransformer 原版是 Encoder-Decoder 结构适合序列到序列任务。Encoder 负责把输入序列编码成一组上下文表示Decoder 负责根据这些表示逐 token 生成输出序列。从模块构成看每一层都包含四个关键子模块多头自注意力多头交叉注意力Decoder 中特有前馈网络残差连接与 LayerNormEncoder 中的自注意力用于建模输入序列内部关系。Decoder 中的自注意力用于建模已生成 token 之间的关系再加上交叉注意力让当前生成位置能够从 Encoder 输出中提取信息。训练时Decoder 可以一次性输入完整目标序列通过掩码防止看到未来 token。推理时没有完整序列只能采用自回归方式每生成一个 token就把它拼到输入末尾再重新前向计算。2.2 自注意力与 QKV 的含义自注意力的输入是三个向量Query、Key、Value通常缩写为 Q、K、V。可以这样理解三者的分工Query 表示“我想找什么”。Key 表示“我有什么可被找到的信息”。Value 表示“找到之后应该取出什么内容”。计算过程是先算 Query 与每个 Key 的相似度得到注意力分数再通过 softmax 转为权重最后与 Value 加权求和。缩放点积注意力的公式是Attention(Q, K, V) softmax(Q * K^T / sqrt(d_k)) * V其中d_k是每个头的维度。除以sqrt(d_k)是因为当维度较大时点积结果方差也会变大softmax 会进入梯度极小的饱和区除以缩放因子可以让梯度更稳定。最小实现如下import math import torch import torch.nn as nn import torch.nn.functional as F class ScaledDotProductAttention(nn.Module): def __init__(self, dropout0.0): super().__init__() self.dropout nn.Dropout(dropout) def forward(self, q, k, v, maskNone): # q/k/v 形状: (batch, heads, seq_len, d_k) d_k q.size(-1) scores torch.matmul(q, k.transpose(-2, -1)) / math.sqrt(d_k) if mask is not None: # mask 中 False 表示需要掩码的位置 scores scores.masked_fill(mask 0, float(-inf)) attn F.softmax(scores, dim-1) attn self.dropout(attn) output torch.matmul(attn, v) return output, attn注意这里mask采用了“True 表示保留、False 表示掩码”的约定。scores.masked_fill(mask 0, -inf)会把需要掩码的位置变成负无穷经过 softmax 后权重接近 0。2.3 多头注意力为什么有效一个注意力头只能学到一种“相关性”模式。比如有的头偏向关注相邻词有的头偏向关注句法成分有的头关注共指关系。多头注意力把特征维度切分成多个子空间每个头独立计算注意力再把结果拼接在一起让模型能够同时学习多种关系。形式上多头注意力把d_model维的向量切分成n_heads个子向量每个子向量维度是d_k d_model / n_heads。每个头都有自己的 QKV 投影矩阵最后用W_o把拼接结果投影回d_model维。多头注意力还有一个工程上的好处它把矩阵乘法拆成多个更小的矩阵运算在 GPU 上同样可以利用并行计算并不比单头慢太多。2.4 位置编码与 token 顺序信息自注意力本身对位置是“无感”的。如果把输入序列任意打乱自注意力计算出的结果完全一样因为点积只考虑了内容相似度没有考虑位置先后。但语言和时序信号通常依赖顺序所以必须把位置信息注入模型。Transformer 原版使用固定公式的正弦位置编码class PositionalEncoding(nn.Module): def __init__(self, d_model, max_len512): super().__init__() pe torch.zeros(max_len, d_model) position torch.arange(0, max_len, dtypetorch.float).unsqueeze(1) div_term torch.exp( torch.arange(0, d_model, 2).float() * (-math.log(10000.0) / d_model) ) pe[:, 0::2] torch.sin(position * div_term) pe[:, 1::2] torch.cos(position * div_term) pe pe.unsqueeze(0) # (1, max_len, d_model) self.register_buffer(pe, pe) def forward(self, x): return x self.pe[:, : x.size(1)]register_buffer会把pe注册为模型的一部分随模型迁移到 GPU但不会作为参数参与梯度更新。位置编码直接加到 token 向量上而不是拼接是为了不改变特征维度让后续模块复杂度保持稳定。常见的替代方案还有可学习位置编码、RoPE、ALiBi 等。对于训练长度超过预设max_len的情况固定正弦编码会有一定外推能力可学习位置编码则通常处理不好需要提前预留足够长度。2.5 残差连接、LayerNorm 与前馈网络自注意力输出后会经历一个经典操作x x Dropout(Attention(LayerNorm(x)))对于 Post-LN 的原版结构顺序是x x Dropout(Attention(x)) x LayerNorm(x)残差连接让梯度可以跨层直接回传避免深层网络梯度消失。LayerNorm 则对每个 token 的特征维度做归一化让每一层的输入分布更稳定。前馈网络由两个线性层和一个激活函数组成class FeedForward(nn.Module): def __init__(self, d_model, d_ff, dropout0.1): super().__init__() self.net nn.Sequential( nn.Linear(d_model, d_ff), nn.ReLU(), nn.Dropout(dropout), nn.Linear(d_ff, d_model), ) def forward(self, x): return self.net(x)d_ff通常取4 * d_model。前馈网络的作用是对注意力输出的每个位置独立做非线性变换相当于在每个 token 表示上增加模型容量。Post-LN 是原版结构训练初期梯度可能不稳定。很多后续模型使用 Pre-LN也就是先归一化再进入注意力或前馈网络训练更稳定但深层表示能力略有变化。实际项目中如果发现深层 Transformer 训练波动大可以优先尝试 Pre-LN。3. 使用 PyTorch 从零实现一个最小 Transformer3.1 环境准备与依赖检查这个实现只需要 PyTorch不依赖 HuggingFace Transformers。建议在独立虚拟环境中运行。依赖项推荐版本说明Python3.8 及以上确保语法兼容PyTorch1.13 及以上自动求导和 GPU 加速CUDA可选有 GPU 时检查驱动与 PyTorch 匹配创建虚拟环境并安装依赖python -m venv transformer-demo source transformer-demo/bin/activate pip install torch如果使用 GPU需要先确认待安装的 PyTorch 版本是否匹配本机 CUDA 版本。CPU 环境也能跑通后面示例但训练速度会慢一些。验证环境python -c import torch; print(torch.__version__)没有报错即可继续。3.2 代码结构规划为了方便阅读把最小实现拆成 5 个模块transformer_demo/ ├── attention.py # 缩放点积注意力 多头注意力 ├── positional.py # 位置编码 ├── layers.py # EncoderLayer / DecoderLayer / FeedForward ├── transformer.py # 完整 Transformer 组装 └── train.py # 复制任务数据、训练和验证如果实际项目比较大可以再拆出data.py、config.py、utils.py。这里保持最小闭环重点是把每个组件讲清楚。3.3 编码隐藏层、解码隐藏层与多头注意力的实现先把多头注意力写完整。实现时需要注意维度变换尤其是view和transpose的配合这是新手最容易出错的地方。class MultiHeadAttention(nn.Module): def __init__(self, d_model, n_heads, dropout0.1): super().__init__() assert d_model % n_heads 0, d_model 必须能被 n_heads 整除 self.d_model d_model self.n_heads n_heads self.d_k d_model // n_heads self.w_q nn.Linear(d_model, d_model) self.w_k nn.Linear(d_model, d_model) self.w_v nn.Linear(d_model, d_model) self.w_o nn.Linear(d_model, d_model) self.attention ScaledDotProductAttention(dropout) def forward(self, query, key, value, maskNone): batch_size query.size(0) # 投影后拆头 Q self.w_q(query).view(batch_size, -1, self.n_heads, self.d_k).transpose(1, 2) K self.w_k(key).view(batch_size, -1, self.n_heads, self.d_k).transpose(1, 2) V self.w_v(value).view(batch_size, -1, self.n_heads, self.d_k).transpose(1, 2) x, attn self.attention(Q, K, V, mask) # 合并头 x x.transpose(1, 2).contiguous().view(batch_size, -1, self.d_model) return self.w_o(x), attnview把最后一维d_model拆成(n_heads, d_k)transpose(1, 2)让头的维度从第 1 维移到第 2 维之后。这样每个头可以独立进行批量矩阵乘法。合并头之前要先transpose回原来的排列再contiguous()确保内存连续否则view会报错。这个报错非常常见原因就是transpose之后张量的 stride 不再满足view要求。3.4 实现 Encoder 层与 Decoder 层Encoder 层包含一个自注意力和一个前馈网络。Decoder 层包含一个带因果掩码的自注意力、一个交叉注意力和一个前馈网络。class EncoderLayer(nn.Module): def __init__(self, d_model, n_heads, d_ff, dropout0.1): super().__init__() self.self_attn MultiHeadAttention(d_model, n_heads, dropout) self.feed_forward FeedForward(d_model, d_ff, dropout) self.norm1 nn.LayerNorm(d_model) self.norm2 nn.LayerNorm(d_model) self.dropout nn.Dropout(dropout) def forward(self, x, src_maskNone): x x self.dropout(self.self_attn(x, x, x, src_mask)[0]) x self.norm1(x) x x self.dropout(self.feed_forward(x)) x self.norm2(x) return xclass DecoderLayer(nn.Module): def __init__(self, d_model, n_heads, d_ff, dropout0.1): super().__init__() self.self_attn MultiHeadAttention(d_model, n_heads, dropout) self.cross_attn MultiHeadAttention(d_model, n_heads, dropout) self.feed_forward FeedForward(d_model, d_ff, dropout) self.norm1 nn.LayerNorm(d_model) self.norm2 nn.LayerNorm(d_model) self.norm3 nn.LayerNorm(d_model) self.dropout nn.Dropout(dropout) def forward(self, x, memory, tgt_maskNone, src_maskNone): x x self.dropout(self.self_attn(x, x, x, tgt_mask)[0]) x self.norm1(x) x x self.dropout(self.cross_attn(x, memory, memory, src_mask)[0]) x self.norm2(x) x x self.dropout(self.feed_forward(x)) x self.norm3(x) return x在交叉注意力中Query 来自 Decoder 当前层的输出Key 和 Value 都来自 Encoder 的输出memory。这样 Decoder 生成当前 token 时可以有效检索源序列相关信息。3.5 组装完整 Transformer完整模型需要包含 Embedding、位置编码、多层 Encoder、多层 Decoder 和输出投影。class Transformer(nn.Module): def __init__( self, src_vocab_size, tgt_vocab_size, d_model512, n_heads8, d_ff2048, num_layers6, dropout0.1, max_len512, ): super().__init__() self.encoder_embed nn.Embedding(src_vocab_size, d_model) self.decoder_embed nn.Embedding(tgt_vocab_size, d_model) self.pos_encoding PositionalEncoding(d_model, max_len) self.encoder_layers nn.ModuleList( [EncoderLayer(d_model, n_heads, d_ff, dropout) for _ in range(num_layers)] ) self.decoder_layers nn.ModuleList( [DecoderLayer(d_model, n_heads, d_ff, dropout) for _ in range(num_layers)] ) self.fc_out nn.Linear(d_model, tgt_vocab_size) self.dropout nn.Dropout(dropout) self._init_parameters() def _init_parameters(self): for p in self.parameters(): if p.dim() 1: nn.init.xavier_uniform_(p) def forward(self, src, tgt, src_maskNone, tgt_maskNone): src_embed self.dropout(self.pos_encoding(self.encoder_embed(src))) memory src_embed for layer in self.encoder_layers: memory layer(memory, src_mask) tgt_embed self.dropout(self.pos_encoding(self.decoder_embed(tgt))) out tgt_embed for layer in self.decoder_layers: out layer(out, memory, tgt_mask, src_mask) return self.fc_out(out)输出维度是(batch, tgt_seq_len, tgt_vocab_size)后面通过CrossEntropyLoss和 target 对齐即可。这里使用nn.ModuleList而不是 Python 列表是为了让子模块被 PyTorch 正确注册否则参数不会进入模型优化器。3.6 Mask 构造Padding Mask 与 Causal Mask实际项目中一个 batch 里序列长度往往不同需要 padding 到相同长度。Padding Mask 的作用是让注意力忽略 padding 位置。def make_padding_mask(seq, pad_idx0): # True 表示保留False 表示掩码 return seq ! pad_idxDecoder 还需要 Causal Mask也就是因果掩码。它的作用是保证位置i只能看到当前位置及之前的位置不能看到未来 token。def make_causal_mask(seq_len): return torch.tril(torch.ones(seq_len, seq_len, dtypetorch.bool))torch.tril保留下三角部分对角线及以下为 True。在注意力计算中掩码矩阵会广播到(batch, n_heads, tgt_len, src_len)。需要注意mask 0的判断方式会把False的位置替换为-inf。如果传入的 mask 类型不是 bool而是 0/1 整数需要约定好语义否则掩码方向很容易反。4. 跑通一个最小训练示例验证正确性4.1 构造复制序列任务为了快速验证实现是否正确这里使用一个非常简单的序列复制任务。输入是一串随机数字输出是同样的一串数字并在结尾加上 EOS 标记。例如输入: [5, 7, 2, 9, 4] 目标: [5, 7, 2, 9, 4, EOS] Decoder 输入: [SOS, 5, 7, 2, 9, 4]训练时Decoder 输入从 SOS 开始每个位置预测下一个真实 token。推理时模型逐步生成直到输出 EOS。定义词表0 表示 PAD1 表示 SOS2 表示 EOS3 到 11 表示数字 token构造数据import torch def make_batch(batch_size, seq_len, vocab_size12): # 随机生成输入序列 src torch.randint(3, vocab_size, (batch_size, seq_len)) # Decoder 输入: [SOS] src tgt_in torch.cat( [torch.full((batch_size, 1), 1, dtypetorch.long), src], dim1 ) # 目标输出: src [EOS] tgt_out torch.cat( [src, torch.full((batch_size, 1), 2, dtypetorch.long)], dim1 ) return src, tgt_in, tgt_outtgt_in和tgt_out长度一致保证交叉熵计算时 logits 和 target 对齐。4.2 训练循环模型使用小参数方便在 CPU 上快速演示import torch.nn as nn from transformer import Transformer vocab_size 12 model Transformer( src_vocab_sizevocab_size, tgt_vocab_sizevocab_size, d_model64, n_heads4, d_ff128, num_layers2, dropout0.1, max_len64, ) optimizer torch.optim.Adam(model.parameters(), lr1e-3) loss_fn nn.CrossEntropyLoss(ignore_index0) def train_step(model, optimizer, loss_fn): model.train() src, tgt_in, tgt_out make_batch(32, seq_len5) tgt_mask make_causal_mask(tgt_in.size(1)) logits model(src, tgt_in, tgt_masktgt_mask) loss loss_fn(logits.reshape(-1, vocab_size), tgt_out.reshape(-1)) optimizer.zero_grad() loss.backward() optimizer.step() return loss.item() for step in range(500): loss train_step(model, optimizer, loss_fn) if step % 100 0: print(fstep {step}, loss {loss:.4f})这里没有传入src_mask因为当前任务不涉及 padding。如果数据里有多个长度不同的序列必须同时构造 padding mask。4.3 预期结果与验证复制任务非常简单500 步后 Loss 应该降到 0.1 以下甚至更低。如果 Loss 没有下降优先检查 Mask 方向、Decoder 输入对齐、Embedding 维度和交叉熵 target 是否一致。下面是验证推理过程的代码def greedy_decode(model, src, max_len10): model.eval() src src.unsqueeze(0) # (1, seq_len) tgt torch.full((1, 1), 1, dtypetorch.long) # SOS with torch.no_grad(): for _ in range(max_len): tgt_mask make_causal_mask(tgt.size(1)) logits model(src, tgt, tgt_masktgt_mask) next_token logits[:, -1, :].argmax(-1, keepdimTrue) tgt torch.cat([tgt, next_token], dim1) if next_token.item() 2: # EOS break return tgt[0].tolist() sample_src torch.tensor([5, 7, 2, 9, 4]) print(输入:, sample_src.tolist()) print(输出:, greedy_decode(model, sample_src))正常输出类似输入: [5, 7, 2, 9, 4] 输出: [1, 5, 7, 2, 9, 4, 2]其中开头 1 是 SOS结尾 2 是 EOS。如果这个最小任务能跑通说明自注意力、多头、位置编码、残差、LayerNorm 和 Mask 的基本逻辑都是正确的。4.4 学习环境与训练性能提示上面的最小实现适合学习但不适合直接搬到生产环境。实际训练中还需要考虑更大的d_model、num_layers和训练步数。学习率预热和衰减策略。梯度裁剪防止 loss 突刺。使用torch.cuda.amp混合精度训练降低显存占用。使用 TensorBoard 或 wandb 记录 loss、梯度范数和学习率变化。CPU 环境跑小参数可以验证逻辑但真正评估模型能力、调优性能时需要 GPU 或至少减小 batch size。5. 参数、Mask 和训练中的常见坑5.1 高频错误现象与排查方向下面表格汇总手写 Transformer 时最常遇到的问题以及排查方向。问题现象可能原因检查方式处理建议view报错transpose后内存不连续查看张量 shape 和is_contiguous()合并头前调用.contiguous()Loss 不下降Mask 方向反了打印mask和scores确认 True 表示保留位置训练时看到未来信息没有使用 Causal Mask检查tgt_mask是否下三角用torch.tril生成掩码推理输出重复循环生成长度控制不足打印每步 token增加最大长度限制和 EOS 停止条件显存不断增长每个时间步保存了不必要梯度推理阶段确认torch.no_grad()评估时关闭梯度计算训练后期震荡学习率过高或没有预热观察 loss 曲线使用学习率预热和梯度裁剪不同 batch 长度不一致导致报错Mask 未正确广播检查 mask 维度padding mask 扩展为 4 维5.2 常见坑 1Mask 维度不匹配自注意力中scores的形状是(batch, n_heads, tgt_len, src_len)。如果 mask 是(batch, src_len)这种 2 维形状无法直接和 4 维 scores 广播。正确做法是把 padding mask 扩展为(batch, 1, 1, src_len)src_mask make_padding_mask(src, pad_idx0).unsqueeze(1).unsqueeze(2)这样mask形状是(batch, 1, 1, src_len)可以广播到(batch, n_heads, tgt_len, src_len)。5.3 常见坑 2注意力分数缩放遗漏如果不除以sqrt(d_k)当d_k较大时点积结果方差变大softmax 输出会接近 one-hot梯度容易消失。很多人会改成去掉缩放因子短序列上可能看不到差别但长序列或深层模型会明显出现梯度不稳定。建议把缩放写在注意力实现内部不要依赖外部手动缩放避免某个调用处漏掉。5.4 常见坑 3Post-LN 与 Pre-LN 顺序混淆Post-LN 是原版 Transformer 的顺序先残差后 LayerNorm。而很多现代实现采用 Pre-LN先 LayerNorm再进注意力最后残差。两种顺序写出来在短任务上可能差异不大但在深层模型上差异明显。修改结构时先确认你要采用哪种顺序前向代码和初始化策略要配套。6. 从 NLP 到图像和时间序列Transformer 的工程变体6.1 Vision Transformer把图像变成 token 序列ViT 的核心思路是把图像分割成固定大小的 patch然后把每个 patch 线性映射成向量再加上位置编码送入 Transformer Encoder。对于图像分类任务输入序列开头加一个[CLS]token最终用其对应输出接分类头。class PatchEmbed(nn.Module): def __init__(self, img_size224, patch_size16, in_channels3, embed_dim768): super().__init__() self.num_patches (img_size // patch_size) ** 2 self.proj nn.Conv2d( in_channels, embed_dim, kernel_sizepatch_size, stridepatch_size, ) def forward(self, x): # x: (batch, 3, img_size, img_size) x self.proj(x) # (batch, embed_dim, H/patch, W/patch) x x.flatten(2).transpose(1, 2) # (batch, num_patches, embed_dim) return xViT 相比 CNN 缺少局部归纳偏置在小数据集上训练容易过拟合。通常需要大规模预训练或者使用数据增强、蒸馏等手段。6.2 Swin Transformer 与安装方式Swin Transformer 针对图像任务做了两点关键改进。第一是窗口注意力。它在局部窗口内计算自注意力而不是全局计算计算复杂度从O(n^2)降到与图像尺寸线性相关。第二是层级特征。通过 Patch Merging 不断合并相邻 patch得到类似 CNN 的多尺度特征图方便用于检测、分割等密集预测任务。在工程中使用 Swin Transformer最直接的方式是安装timmpip install timm安装后可以加载常见预训练模型import timm model timm.create_model(swin_tiny_patch4_window7_224, pretrainedTrue) print(model)也可以使用 HuggingFace Transformers 中的 Swin 实现。具体模型名和预训练权重会随库版本变化落地前需要先确认目标版本是否支持对应模型。6.3 TCN Transformer 做时间序列预测的思路时间序列预测中TCN 负责提取局部时间模式Transformer 负责建模长程依赖。常见做法是用多个因果膨胀卷积层处理原始序列得到局部特征编码再送入 Transformer Encoder最后用回归头输出未来多个时间步。一个简化的流程如下对原始序列做归一化拆成训练集、验证集、测试集。构造滑动窗口样本输入是过去lookback步目标是未来horizon步。TCN 先处理局部模式输出作为 Transformer 的 token 序列。Transformer 建模全局依赖。用回归头输出预测值评估 MAE、RMSE、MAPE。需要注意预测类任务对数据泄漏非常敏感不能把未来信息混进特征。股票等金融数据的预测还要额外处理市场噪声和过拟合问题。这类实验适合用来学习方法不能作为投资决策依据。6.4 变体选型速查表场景推荐方向原因NLP 通用任务标准 Transformer / Pre-LN 变体结构成熟资料多图像分类ViT / Swin大规模数据效果好Swin 计算更友好目标检测Swin FPN 类结构层级特征利于多尺度检测长序列时间序列TCN Transformer / Informer局部特征和长程依赖配合小规模数据集优先 CNN 或轻量模型Transformer 数据效率较低7. 实践建议与可复用清单7.1 学习 Transformer 的推荐路径不要一上来就追求读完所有论文。建议按下面顺序推进读完原论文《Attention Is All You Need》理解 QKV、多头、位置编码和训练细节。动手实现最小模型跑通上面的复制任务。替换数据集尝试一个简单的文本翻译或文本摘要任务。阅读 HuggingFace Transformers 的源码学习 Pre-LN、参数初始化和推理优化。再看 ViT、Swin、Informer 等变体理解它们为解决什么问题而改动结构。每进入一步都要用“这个模块解决什么问题”来统领学习而不是背公式和代码。7.2 搭建 Transformer 前的检查清单在动手写代码前按照下面清单核对一遍能减少很多无效调试。是否确定d_model能被n_heads整除。是否明确使用 Post-LN 还是 Pre-LN。是否定义了PAD、SOS、EOS对应词表 id。是否确认tgt_in与tgt_out长度一致。是否已生成tgt_mask且方向是下三角。是否已处理 padding mask 的维度扩展。是否设置了 loss 的ignore_index指向PAD。是否在训练和推理模式下正确切换model.train()/model.eval()。推理循环是否设置了最大步数和 EOS 停止条件。7.3 实验环境与生产环境的差异维度实验环境生产环境模型规模小参数快速验证按任务调优结合部署资源数值精度FP32 为主可考虑 FP16 / INT8服务方式训练脚本推理服务 接口 监控日志print 足够结构化日志 指标采集数据加载内存加载DataLoader 分布式缓存回滚机制保存 checkpoint模型版本管理 灰度发布如果只是学习用上面的最小代码就可以如果要把 Transformer 应用到业务系统还需要额外考虑推理延迟、显存占用、动态长度输入、批处理策略和异常兜底。7.4 关键建议Transformer 的核心不在于模块多而在于“自注意力 位置编码 残差归一化 前馈网络”这套组合为什么能稳定训练深层模型。手写一遍最小实现比调用十次现成库更有价值。遇到问题不要先怀疑框架优先检查 Mask 是否生效、维度是否对齐、数据是否泄漏。把这几个问题想清楚后续学习任何 Transformer 变体都会轻松很多。 Transformer原理与PyTorch从零实现：从NLP到视觉与时序
Transformer 已经不只是 NLP 领域的模型结构而是当前深度学习里最值得花时间吃透的基础组件。无论是 BERT、GPT、ViT还是各类多模态模型底层都能看到多头自注意力、前馈网络、残差连接和 LayerNorm 的组合。很多人在使用现成库时感觉不难一旦需要修改结构、调试显存、排查 Loss 不下降才发现自己对它的理解停留在 API 层。这篇内容会沿着一条完整路径展开先解释 Transformer 解决什么问题再逐层拆解架构然后用 PyTorch 从零实现一个最小可训练的 Transformer跑一个复制序列任务验证正确性最后延伸到 Vision Transformer、Swin Transformer 和 TCNTransformer 时间序列预测等工程方向。读完以后你不仅能看懂源码还能自己修改结构也能在遇到 Loss 不下降、维度报错、Mask 失效这类问题时知道从哪里切入排查。1. 先搞清楚 Transformer 解决的原始问题1.1 循环网络处理序列的方式与瓶颈在 Transformer 出现之前处理序列任务的主流结构是 RNN、LSTM 和 GRU。它们的基本思路是一致的按时间步逐个读入 token维护一个隐状态h_t把历史信息压缩到向量里再传给下一步。这种机制有两个明显问题。第一个问题是无法并行。第t步的计算依赖第t-1步的隐状态所以无论序列多长都只能一个 token 一个 token 往后算。GPU 的并行能力在这种顺序计算中被浪费了模型训练速度受序列长度影响非常大。第二个问题是长距离信息衰减。RNN 每一步都会把历史信息“压”进一个固定大小的隐状态随着步数增加早期信息会逐渐被冲淡。LSTM 通过门控机制缓解了梯度消失但本质上仍然是顺序传递序列很长时远距离 token 之间的依赖关系依然难建。下面是一个最简 RNN 单元的计算示意h_t tanh(W_hh h_{t-1} W_xh x_t b)这里的h_t既要承担当前步的信息又要向后传递信息容量有限容易成为瓶颈。1.2 注意力机制从“记住全部”到“按需提取”注意力机制的核心思想是不要求网络把历史压缩在同一个向量里而是让每一步都能直接“回头看”所有历史位置按相关性加权提取信息。以机器翻译为例源语言句子里的每个 token 都有自己的向量表示。翻译目标语言第t个词时模型先计算当前状态与源语言每个 token 的匹配分数再用 softmax 转成权重最后对所有源语言向量做加权和。这样重要的词获得更大权重模型不必把全部信息塞进一个隐状态。这种机制在 Bahdanau 等人提出的注意力模型中被用于改进机器翻译后来逐渐演变成 Transformer 中的自注意力不仅查询和解码状态可以做注意力序列内部每个位置之间也可以做注意力。1.3 为什么最终是 TransformerTransformer 在 2017 年提出原本是为了解决机器翻译问题但它把“注意力”推到了极致整个模型完全抛弃循环结构只用自注意力、前馈网络和归一化层堆叠得到。它带来的直接收益有三个。第一是并行计算。自注意力对序列内部所有位置同时计算不再有 RNN 那样的时间步依赖。第二是长距离依赖建模。任意两个位置之间只隔一次矩阵乘法信息路径比 RNN 短得多。第三是统一的模块化结构。编码器和解码器都由相同的层堆叠而成方便扩展到不同任务。代价也很直接自注意力的计算复杂度是O(n^2 * d)其中n是序列长度d是特征维度。序列越长计算量和显存占用增长越快。很多后续工作都在围绕“如何降低自注意力的计算量”展开比如局部窗口注意力、稀疏注意力、线性注意力等。特性RNN/LSTMCNNTransformer并行能力差好好长距离依赖弱依赖卷积核感受野强计算复杂度O(n * d^2)与卷积核大小相关O(n^2 * d)局部归纳偏置无强弱输入顺序建模天然天然需加位置编码这组对比能解释很多工程选择时间序列不长时LSTM 仍可用图像任务中 CNN 的局部归纳偏置更省数据但数据量大、序列长、需要全局依赖时Transformer 结构更容易发挥优势。2. Transformer 核心架构拆解2.1 宏观结构Encoder 与 DecoderTransformer 原版是 Encoder-Decoder 结构适合序列到序列任务。Encoder 负责把输入序列编码成一组上下文表示Decoder 负责根据这些表示逐 token 生成输出序列。从模块构成看每一层都包含四个关键子模块多头自注意力多头交叉注意力Decoder 中特有前馈网络残差连接与 LayerNormEncoder 中的自注意力用于建模输入序列内部关系。Decoder 中的自注意力用于建模已生成 token 之间的关系再加上交叉注意力让当前生成位置能够从 Encoder 输出中提取信息。训练时Decoder 可以一次性输入完整目标序列通过掩码防止看到未来 token。推理时没有完整序列只能采用自回归方式每生成一个 token就把它拼到输入末尾再重新前向计算。2.2 自注意力与 QKV 的含义自注意力的输入是三个向量Query、Key、Value通常缩写为 Q、K、V。可以这样理解三者的分工Query 表示“我想找什么”。Key 表示“我有什么可被找到的信息”。Value 表示“找到之后应该取出什么内容”。计算过程是先算 Query 与每个 Key 的相似度得到注意力分数再通过 softmax 转为权重最后与 Value 加权求和。缩放点积注意力的公式是Attention(Q, K, V) softmax(Q * K^T / sqrt(d_k)) * V其中d_k是每个头的维度。除以sqrt(d_k)是因为当维度较大时点积结果方差也会变大softmax 会进入梯度极小的饱和区除以缩放因子可以让梯度更稳定。最小实现如下import math import torch import torch.nn as nn import torch.nn.functional as F class ScaledDotProductAttention(nn.Module): def __init__(self, dropout0.0): super().__init__() self.dropout nn.Dropout(dropout) def forward(self, q, k, v, maskNone): # q/k/v 形状: (batch, heads, seq_len, d_k) d_k q.size(-1) scores torch.matmul(q, k.transpose(-2, -1)) / math.sqrt(d_k) if mask is not None: # mask 中 False 表示需要掩码的位置 scores scores.masked_fill(mask 0, float(-inf)) attn F.softmax(scores, dim-1) attn self.dropout(attn) output torch.matmul(attn, v) return output, attn注意这里mask采用了“True 表示保留、False 表示掩码”的约定。scores.masked_fill(mask 0, -inf)会把需要掩码的位置变成负无穷经过 softmax 后权重接近 0。2.3 多头注意力为什么有效一个注意力头只能学到一种“相关性”模式。比如有的头偏向关注相邻词有的头偏向关注句法成分有的头关注共指关系。多头注意力把特征维度切分成多个子空间每个头独立计算注意力再把结果拼接在一起让模型能够同时学习多种关系。形式上多头注意力把d_model维的向量切分成n_heads个子向量每个子向量维度是d_k d_model / n_heads。每个头都有自己的 QKV 投影矩阵最后用W_o把拼接结果投影回d_model维。多头注意力还有一个工程上的好处它把矩阵乘法拆成多个更小的矩阵运算在 GPU 上同样可以利用并行计算并不比单头慢太多。2.4 位置编码与 token 顺序信息自注意力本身对位置是“无感”的。如果把输入序列任意打乱自注意力计算出的结果完全一样因为点积只考虑了内容相似度没有考虑位置先后。但语言和时序信号通常依赖顺序所以必须把位置信息注入模型。Transformer 原版使用固定公式的正弦位置编码class PositionalEncoding(nn.Module): def __init__(self, d_model, max_len512): super().__init__() pe torch.zeros(max_len, d_model) position torch.arange(0, max_len, dtypetorch.float).unsqueeze(1) div_term torch.exp( torch.arange(0, d_model, 2).float() * (-math.log(10000.0) / d_model) ) pe[:, 0::2] torch.sin(position * div_term) pe[:, 1::2] torch.cos(position * div_term) pe pe.unsqueeze(0) # (1, max_len, d_model) self.register_buffer(pe, pe) def forward(self, x): return x self.pe[:, : x.size(1)]register_buffer会把pe注册为模型的一部分随模型迁移到 GPU但不会作为参数参与梯度更新。位置编码直接加到 token 向量上而不是拼接是为了不改变特征维度让后续模块复杂度保持稳定。常见的替代方案还有可学习位置编码、RoPE、ALiBi 等。对于训练长度超过预设max_len的情况固定正弦编码会有一定外推能力可学习位置编码则通常处理不好需要提前预留足够长度。2.5 残差连接、LayerNorm 与前馈网络自注意力输出后会经历一个经典操作x x Dropout(Attention(LayerNorm(x)))对于 Post-LN 的原版结构顺序是x x Dropout(Attention(x)) x LayerNorm(x)残差连接让梯度可以跨层直接回传避免深层网络梯度消失。LayerNorm 则对每个 token 的特征维度做归一化让每一层的输入分布更稳定。前馈网络由两个线性层和一个激活函数组成class FeedForward(nn.Module): def __init__(self, d_model, d_ff, dropout0.1): super().__init__() self.net nn.Sequential( nn.Linear(d_model, d_ff), nn.ReLU(), nn.Dropout(dropout), nn.Linear(d_ff, d_model), ) def forward(self, x): return self.net(x)d_ff通常取4 * d_model。前馈网络的作用是对注意力输出的每个位置独立做非线性变换相当于在每个 token 表示上增加模型容量。Post-LN 是原版结构训练初期梯度可能不稳定。很多后续模型使用 Pre-LN也就是先归一化再进入注意力或前馈网络训练更稳定但深层表示能力略有变化。实际项目中如果发现深层 Transformer 训练波动大可以优先尝试 Pre-LN。3. 使用 PyTorch 从零实现一个最小 Transformer3.1 环境准备与依赖检查这个实现只需要 PyTorch不依赖 HuggingFace Transformers。建议在独立虚拟环境中运行。依赖项推荐版本说明Python3.8 及以上确保语法兼容PyTorch1.13 及以上自动求导和 GPU 加速CUDA可选有 GPU 时检查驱动与 PyTorch 匹配创建虚拟环境并安装依赖python -m venv transformer-demo source transformer-demo/bin/activate pip install torch如果使用 GPU需要先确认待安装的 PyTorch 版本是否匹配本机 CUDA 版本。CPU 环境也能跑通后面示例但训练速度会慢一些。验证环境python -c import torch; print(torch.__version__)没有报错即可继续。3.2 代码结构规划为了方便阅读把最小实现拆成 5 个模块transformer_demo/ ├── attention.py # 缩放点积注意力 多头注意力 ├── positional.py # 位置编码 ├── layers.py # EncoderLayer / DecoderLayer / FeedForward ├── transformer.py # 完整 Transformer 组装 └── train.py # 复制任务数据、训练和验证如果实际项目比较大可以再拆出data.py、config.py、utils.py。这里保持最小闭环重点是把每个组件讲清楚。3.3 编码隐藏层、解码隐藏层与多头注意力的实现先把多头注意力写完整。实现时需要注意维度变换尤其是view和transpose的配合这是新手最容易出错的地方。class MultiHeadAttention(nn.Module): def __init__(self, d_model, n_heads, dropout0.1): super().__init__() assert d_model % n_heads 0, d_model 必须能被 n_heads 整除 self.d_model d_model self.n_heads n_heads self.d_k d_model // n_heads self.w_q nn.Linear(d_model, d_model) self.w_k nn.Linear(d_model, d_model) self.w_v nn.Linear(d_model, d_model) self.w_o nn.Linear(d_model, d_model) self.attention ScaledDotProductAttention(dropout) def forward(self, query, key, value, maskNone): batch_size query.size(0) # 投影后拆头 Q self.w_q(query).view(batch_size, -1, self.n_heads, self.d_k).transpose(1, 2) K self.w_k(key).view(batch_size, -1, self.n_heads, self.d_k).transpose(1, 2) V self.w_v(value).view(batch_size, -1, self.n_heads, self.d_k).transpose(1, 2) x, attn self.attention(Q, K, V, mask) # 合并头 x x.transpose(1, 2).contiguous().view(batch_size, -1, self.d_model) return self.w_o(x), attnview把最后一维d_model拆成(n_heads, d_k)transpose(1, 2)让头的维度从第 1 维移到第 2 维之后。这样每个头可以独立进行批量矩阵乘法。合并头之前要先transpose回原来的排列再contiguous()确保内存连续否则view会报错。这个报错非常常见原因就是transpose之后张量的 stride 不再满足view要求。3.4 实现 Encoder 层与 Decoder 层Encoder 层包含一个自注意力和一个前馈网络。Decoder 层包含一个带因果掩码的自注意力、一个交叉注意力和一个前馈网络。class EncoderLayer(nn.Module): def __init__(self, d_model, n_heads, d_ff, dropout0.1): super().__init__() self.self_attn MultiHeadAttention(d_model, n_heads, dropout) self.feed_forward FeedForward(d_model, d_ff, dropout) self.norm1 nn.LayerNorm(d_model) self.norm2 nn.LayerNorm(d_model) self.dropout nn.Dropout(dropout) def forward(self, x, src_maskNone): x x self.dropout(self.self_attn(x, x, x, src_mask)[0]) x self.norm1(x) x x self.dropout(self.feed_forward(x)) x self.norm2(x) return xclass DecoderLayer(nn.Module): def __init__(self, d_model, n_heads, d_ff, dropout0.1): super().__init__() self.self_attn MultiHeadAttention(d_model, n_heads, dropout) self.cross_attn MultiHeadAttention(d_model, n_heads, dropout) self.feed_forward FeedForward(d_model, d_ff, dropout) self.norm1 nn.LayerNorm(d_model) self.norm2 nn.LayerNorm(d_model) self.norm3 nn.LayerNorm(d_model) self.dropout nn.Dropout(dropout) def forward(self, x, memory, tgt_maskNone, src_maskNone): x x self.dropout(self.self_attn(x, x, x, tgt_mask)[0]) x self.norm1(x) x x self.dropout(self.cross_attn(x, memory, memory, src_mask)[0]) x self.norm2(x) x x self.dropout(self.feed_forward(x)) x self.norm3(x) return x在交叉注意力中Query 来自 Decoder 当前层的输出Key 和 Value 都来自 Encoder 的输出memory。这样 Decoder 生成当前 token 时可以有效检索源序列相关信息。3.5 组装完整 Transformer完整模型需要包含 Embedding、位置编码、多层 Encoder、多层 Decoder 和输出投影。class Transformer(nn.Module): def __init__( self, src_vocab_size, tgt_vocab_size, d_model512, n_heads8, d_ff2048, num_layers6, dropout0.1, max_len512, ): super().__init__() self.encoder_embed nn.Embedding(src_vocab_size, d_model) self.decoder_embed nn.Embedding(tgt_vocab_size, d_model) self.pos_encoding PositionalEncoding(d_model, max_len) self.encoder_layers nn.ModuleList( [EncoderLayer(d_model, n_heads, d_ff, dropout) for _ in range(num_layers)] ) self.decoder_layers nn.ModuleList( [DecoderLayer(d_model, n_heads, d_ff, dropout) for _ in range(num_layers)] ) self.fc_out nn.Linear(d_model, tgt_vocab_size) self.dropout nn.Dropout(dropout) self._init_parameters() def _init_parameters(self): for p in self.parameters(): if p.dim() 1: nn.init.xavier_uniform_(p) def forward(self, src, tgt, src_maskNone, tgt_maskNone): src_embed self.dropout(self.pos_encoding(self.encoder_embed(src))) memory src_embed for layer in self.encoder_layers: memory layer(memory, src_mask) tgt_embed self.dropout(self.pos_encoding(self.decoder_embed(tgt))) out tgt_embed for layer in self.decoder_layers: out layer(out, memory, tgt_mask, src_mask) return self.fc_out(out)输出维度是(batch, tgt_seq_len, tgt_vocab_size)后面通过CrossEntropyLoss和 target 对齐即可。这里使用nn.ModuleList而不是 Python 列表是为了让子模块被 PyTorch 正确注册否则参数不会进入模型优化器。3.6 Mask 构造Padding Mask 与 Causal Mask实际项目中一个 batch 里序列长度往往不同需要 padding 到相同长度。Padding Mask 的作用是让注意力忽略 padding 位置。def make_padding_mask(seq, pad_idx0): # True 表示保留False 表示掩码 return seq ! pad_idxDecoder 还需要 Causal Mask也就是因果掩码。它的作用是保证位置i只能看到当前位置及之前的位置不能看到未来 token。def make_causal_mask(seq_len): return torch.tril(torch.ones(seq_len, seq_len, dtypetorch.bool))torch.tril保留下三角部分对角线及以下为 True。在注意力计算中掩码矩阵会广播到(batch, n_heads, tgt_len, src_len)。需要注意mask 0的判断方式会把False的位置替换为-inf。如果传入的 mask 类型不是 bool而是 0/1 整数需要约定好语义否则掩码方向很容易反。4. 跑通一个最小训练示例验证正确性4.1 构造复制序列任务为了快速验证实现是否正确这里使用一个非常简单的序列复制任务。输入是一串随机数字输出是同样的一串数字并在结尾加上 EOS 标记。例如输入: [5, 7, 2, 9, 4] 目标: [5, 7, 2, 9, 4, EOS] Decoder 输入: [SOS, 5, 7, 2, 9, 4]训练时Decoder 输入从 SOS 开始每个位置预测下一个真实 token。推理时模型逐步生成直到输出 EOS。定义词表0 表示 PAD1 表示 SOS2 表示 EOS3 到 11 表示数字 token构造数据import torch def make_batch(batch_size, seq_len, vocab_size12): # 随机生成输入序列 src torch.randint(3, vocab_size, (batch_size, seq_len)) # Decoder 输入: [SOS] src tgt_in torch.cat( [torch.full((batch_size, 1), 1, dtypetorch.long), src], dim1 ) # 目标输出: src [EOS] tgt_out torch.cat( [src, torch.full((batch_size, 1), 2, dtypetorch.long)], dim1 ) return src, tgt_in, tgt_outtgt_in和tgt_out长度一致保证交叉熵计算时 logits 和 target 对齐。4.2 训练循环模型使用小参数方便在 CPU 上快速演示import torch.nn as nn from transformer import Transformer vocab_size 12 model Transformer( src_vocab_sizevocab_size, tgt_vocab_sizevocab_size, d_model64, n_heads4, d_ff128, num_layers2, dropout0.1, max_len64, ) optimizer torch.optim.Adam(model.parameters(), lr1e-3) loss_fn nn.CrossEntropyLoss(ignore_index0) def train_step(model, optimizer, loss_fn): model.train() src, tgt_in, tgt_out make_batch(32, seq_len5) tgt_mask make_causal_mask(tgt_in.size(1)) logits model(src, tgt_in, tgt_masktgt_mask) loss loss_fn(logits.reshape(-1, vocab_size), tgt_out.reshape(-1)) optimizer.zero_grad() loss.backward() optimizer.step() return loss.item() for step in range(500): loss train_step(model, optimizer, loss_fn) if step % 100 0: print(fstep {step}, loss {loss:.4f})这里没有传入src_mask因为当前任务不涉及 padding。如果数据里有多个长度不同的序列必须同时构造 padding mask。4.3 预期结果与验证复制任务非常简单500 步后 Loss 应该降到 0.1 以下甚至更低。如果 Loss 没有下降优先检查 Mask 方向、Decoder 输入对齐、Embedding 维度和交叉熵 target 是否一致。下面是验证推理过程的代码def greedy_decode(model, src, max_len10): model.eval() src src.unsqueeze(0) # (1, seq_len) tgt torch.full((1, 1), 1, dtypetorch.long) # SOS with torch.no_grad(): for _ in range(max_len): tgt_mask make_causal_mask(tgt.size(1)) logits model(src, tgt, tgt_masktgt_mask) next_token logits[:, -1, :].argmax(-1, keepdimTrue) tgt torch.cat([tgt, next_token], dim1) if next_token.item() 2: # EOS break return tgt[0].tolist() sample_src torch.tensor([5, 7, 2, 9, 4]) print(输入:, sample_src.tolist()) print(输出:, greedy_decode(model, sample_src))正常输出类似输入: [5, 7, 2, 9, 4] 输出: [1, 5, 7, 2, 9, 4, 2]其中开头 1 是 SOS结尾 2 是 EOS。如果这个最小任务能跑通说明自注意力、多头、位置编码、残差、LayerNorm 和 Mask 的基本逻辑都是正确的。4.4 学习环境与训练性能提示上面的最小实现适合学习但不适合直接搬到生产环境。实际训练中还需要考虑更大的d_model、num_layers和训练步数。学习率预热和衰减策略。梯度裁剪防止 loss 突刺。使用torch.cuda.amp混合精度训练降低显存占用。使用 TensorBoard 或 wandb 记录 loss、梯度范数和学习率变化。CPU 环境跑小参数可以验证逻辑但真正评估模型能力、调优性能时需要 GPU 或至少减小 batch size。5. 参数、Mask 和训练中的常见坑5.1 高频错误现象与排查方向下面表格汇总手写 Transformer 时最常遇到的问题以及排查方向。问题现象可能原因检查方式处理建议view报错transpose后内存不连续查看张量 shape 和is_contiguous()合并头前调用.contiguous()Loss 不下降Mask 方向反了打印mask和scores确认 True 表示保留位置训练时看到未来信息没有使用 Causal Mask检查tgt_mask是否下三角用torch.tril生成掩码推理输出重复循环生成长度控制不足打印每步 token增加最大长度限制和 EOS 停止条件显存不断增长每个时间步保存了不必要梯度推理阶段确认torch.no_grad()评估时关闭梯度计算训练后期震荡学习率过高或没有预热观察 loss 曲线使用学习率预热和梯度裁剪不同 batch 长度不一致导致报错Mask 未正确广播检查 mask 维度padding mask 扩展为 4 维5.2 常见坑 1Mask 维度不匹配自注意力中scores的形状是(batch, n_heads, tgt_len, src_len)。如果 mask 是(batch, src_len)这种 2 维形状无法直接和 4 维 scores 广播。正确做法是把 padding mask 扩展为(batch, 1, 1, src_len)src_mask make_padding_mask(src, pad_idx0).unsqueeze(1).unsqueeze(2)这样mask形状是(batch, 1, 1, src_len)可以广播到(batch, n_heads, tgt_len, src_len)。5.3 常见坑 2注意力分数缩放遗漏如果不除以sqrt(d_k)当d_k较大时点积结果方差变大softmax 输出会接近 one-hot梯度容易消失。很多人会改成去掉缩放因子短序列上可能看不到差别但长序列或深层模型会明显出现梯度不稳定。建议把缩放写在注意力实现内部不要依赖外部手动缩放避免某个调用处漏掉。5.4 常见坑 3Post-LN 与 Pre-LN 顺序混淆Post-LN 是原版 Transformer 的顺序先残差后 LayerNorm。而很多现代实现采用 Pre-LN先 LayerNorm再进注意力最后残差。两种顺序写出来在短任务上可能差异不大但在深层模型上差异明显。修改结构时先确认你要采用哪种顺序前向代码和初始化策略要配套。6. 从 NLP 到图像和时间序列Transformer 的工程变体6.1 Vision Transformer把图像变成 token 序列ViT 的核心思路是把图像分割成固定大小的 patch然后把每个 patch 线性映射成向量再加上位置编码送入 Transformer Encoder。对于图像分类任务输入序列开头加一个[CLS]token最终用其对应输出接分类头。class PatchEmbed(nn.Module): def __init__(self, img_size224, patch_size16, in_channels3, embed_dim768): super().__init__() self.num_patches (img_size // patch_size) ** 2 self.proj nn.Conv2d( in_channels, embed_dim, kernel_sizepatch_size, stridepatch_size, ) def forward(self, x): # x: (batch, 3, img_size, img_size) x self.proj(x) # (batch, embed_dim, H/patch, W/patch) x x.flatten(2).transpose(1, 2) # (batch, num_patches, embed_dim) return xViT 相比 CNN 缺少局部归纳偏置在小数据集上训练容易过拟合。通常需要大规模预训练或者使用数据增强、蒸馏等手段。6.2 Swin Transformer 与安装方式Swin Transformer 针对图像任务做了两点关键改进。第一是窗口注意力。它在局部窗口内计算自注意力而不是全局计算计算复杂度从O(n^2)降到与图像尺寸线性相关。第二是层级特征。通过 Patch Merging 不断合并相邻 patch得到类似 CNN 的多尺度特征图方便用于检测、分割等密集预测任务。在工程中使用 Swin Transformer最直接的方式是安装timmpip install timm安装后可以加载常见预训练模型import timm model timm.create_model(swin_tiny_patch4_window7_224, pretrainedTrue) print(model)也可以使用 HuggingFace Transformers 中的 Swin 实现。具体模型名和预训练权重会随库版本变化落地前需要先确认目标版本是否支持对应模型。6.3 TCN Transformer 做时间序列预测的思路时间序列预测中TCN 负责提取局部时间模式Transformer 负责建模长程依赖。常见做法是用多个因果膨胀卷积层处理原始序列得到局部特征编码再送入 Transformer Encoder最后用回归头输出未来多个时间步。一个简化的流程如下对原始序列做归一化拆成训练集、验证集、测试集。构造滑动窗口样本输入是过去lookback步目标是未来horizon步。TCN 先处理局部模式输出作为 Transformer 的 token 序列。Transformer 建模全局依赖。用回归头输出预测值评估 MAE、RMSE、MAPE。需要注意预测类任务对数据泄漏非常敏感不能把未来信息混进特征。股票等金融数据的预测还要额外处理市场噪声和过拟合问题。这类实验适合用来学习方法不能作为投资决策依据。6.4 变体选型速查表场景推荐方向原因NLP 通用任务标准 Transformer / Pre-LN 变体结构成熟资料多图像分类ViT / Swin大规模数据效果好Swin 计算更友好目标检测Swin FPN 类结构层级特征利于多尺度检测长序列时间序列TCN Transformer / Informer局部特征和长程依赖配合小规模数据集优先 CNN 或轻量模型Transformer 数据效率较低7. 实践建议与可复用清单7.1 学习 Transformer 的推荐路径不要一上来就追求读完所有论文。建议按下面顺序推进读完原论文《Attention Is All You Need》理解 QKV、多头、位置编码和训练细节。动手实现最小模型跑通上面的复制任务。替换数据集尝试一个简单的文本翻译或文本摘要任务。阅读 HuggingFace Transformers 的源码学习 Pre-LN、参数初始化和推理优化。再看 ViT、Swin、Informer 等变体理解它们为解决什么问题而改动结构。每进入一步都要用“这个模块解决什么问题”来统领学习而不是背公式和代码。7.2 搭建 Transformer 前的检查清单在动手写代码前按照下面清单核对一遍能减少很多无效调试。是否确定d_model能被n_heads整除。是否明确使用 Post-LN 还是 Pre-LN。是否定义了PAD、SOS、EOS对应词表 id。是否确认tgt_in与tgt_out长度一致。是否已生成tgt_mask且方向是下三角。是否已处理 padding mask 的维度扩展。是否设置了 loss 的ignore_index指向PAD。是否在训练和推理模式下正确切换model.train()/model.eval()。推理循环是否设置了最大步数和 EOS 停止条件。7.3 实验环境与生产环境的差异维度实验环境生产环境模型规模小参数快速验证按任务调优结合部署资源数值精度FP32 为主可考虑 FP16 / INT8服务方式训练脚本推理服务 接口 监控日志print 足够结构化日志 指标采集数据加载内存加载DataLoader 分布式缓存回滚机制保存 checkpoint模型版本管理 灰度发布如果只是学习用上面的最小代码就可以如果要把 Transformer 应用到业务系统还需要额外考虑推理延迟、显存占用、动态长度输入、批处理策略和异常兜底。7.4 关键建议Transformer 的核心不在于模块多而在于“自注意力 位置编码 残差归一化 前馈网络”这套组合为什么能稳定训练深层模型。手写一遍最小实现比调用十次现成库更有价值。遇到问题不要先怀疑框架优先检查 Mask 是否生效、维度是否对齐、数据是否泄漏。把这几个问题想清楚后续学习任何 Transformer 变体都会轻松很多。