Transformer代码包实战解析：英德翻译与模型训练
简介：AISTransformer数据代码详解是一份聚焦人工智能与机器学习数据预处理的源码型资源，定位为软件/插件类工具，面向算法工程师、数据工程师以及希望掌握数据清洗、特征工程与格式转换的开发者，核心目标是提升数据准备阶段的效率与可靠性。RAR压缩包共含257个文件，以233个CSV数据文件为主，另有12个PY源码脚本、9个PYC编译产物及XLS、TXT、PKL各1个，整包仅189KB，体积轻量且目录结构清晰，便于按模块定位。资源目前已吸引798人学习下载，内容涵盖数据读取、缺失值处理、特征提取等模块化实现，并提供配置文件、示例代码与测试用例。使用者可借助文本分词、停用词过滤、词形还原以及图像缩放、归一化等处理逻辑，快速搭建数据处理流水线，减少手动预处理成本，将精力集中到模型构建与调优，从而缩短模型迭代周期。
1. AISTransforemr：一份能跑通英德翻译的 Transformer 训练代码包
把AISTransforemr数据代码这个包下载下来解压之后，我第一反应是看看它是不是又一个挂着 Transformer 名头的空壳——毕竟现在网上这类"AI 项目"实在太多，解压完里面往往只有一个 README 和几张 PPT。但实际扫了一遍目录后发现，这份资源比我想象中要实在：完整的 PyTorch 训练代码、预处理好的平行语料、训练日志和 checkpoint 都齐，能直接跑起来复现一个基于注意力机制的 Transformer 翻译模型。适合两类人：一是刚看完 Attention Is All You Need 原文、想对照代码搞懂多头注意力和位置编码到底怎么落地的学生；二是要拿 Transformer 做机器翻译或文本生成 baseline，想快速改数据跑起来练手的开发者。本文不会贴全部源码，而是按我拆包时最关心的问题来展开：项目结构长什么样、数据怎么处理、核心模块怎么实现、跑的时候会遇到哪些坑、以及想换成自己的数据该从哪儿下手。
2. 技术栈与目录结构：按 PyTorch 标准套路组织的 Transformer 工程
拿到源码包之后我习惯先全局扫一遍文件分布，确认技术选型再决定从哪个模块开始读。这份资源的结构非常典型：用 PyTorch（版本要求是 1.7+，其实 1.8 到 2.x 都能跑）实现，数据层是 torchtext 的经典用法，模型层是完全手写的 Transformer，没有直接调 nn.Transformer 封装——这点我很满意，因为手写版本才能看清楚里面的每个细节，也方便后面做定制。下面是我整理后的核心目录树，加了注释方便对照：
AISTransforemr/ ├── data/ # 数据目录 │ ├── train.json # 训练集：JSON 数组，每条含 src 和 tgt 字段 │ ├── val.json # 验证集，格式与训练集一致 │ └── vocab.json # 词表文件：{"src": {...}, "tgt": {...}} ├── checkpoints/ # 训练产生的模型保存目录 ├── config.py # 全部可调超参数集中在同一个文件 ├── dataset.py # 数据读取：JSON 加载、BPE 切分、padding、batch 组装 ├── model.py # Transformer 完整定义：多头注意力、位置编码、编码器、解码器 ├── train.py # 训练脚本：Teacher Forcing、学习率调度、验证集评测 ├── translate.py # 推理脚本：beam search 解码 ├── utils.py # 辅助工具：BLEU 计算、日志、随机种子 ├── requirements.txt # Python 依赖清单 ├── run_train.sh # 一键训练脚本 ├── run_translate.sh # 一键推理脚本 └── README.md # 简要说明，含环境要求和运行命令2.1 数据资源：JSON 格式的平行语料，干净到可以直接丢进 DataLoader
train.json 和 val.json 是这份包里的核心数据资产。每条记录都是一个 JSON 对象，示例是这种样子：
{ "src": "The quick brown fox jumps over the lazy dog .", "tgt": "Der schnelle braune Fuchs springt über den faulen Hund ." }src 是源语言（英文），tgt 是目标语言（德文），已经做了基础的 tokenization：标点前后加了空格、句子末尾的句号独立成词。这样处理有个好处——模型学到的词表会非常干净，token 类型数量能压到一两万以内，不至于因为标点粘连导致词表爆炸。
dataset.py 里对应的读取逻辑如下：
import json from torch.utils.data import Dataset class TranslationDataset(Dataset): def __init__(self, json_path, vocab, max_len=128): with open(json_path, 'r', encoding='utf-8') as f: self.data = json.load(f) self.vocab = vocab # 传入已经构建好的词表对象 self.max_len = max_len # 输入序列长度上限，超过直接截断 def __len__(self): return len(self.data) def __getitem__(self, idx): item = self.data[idx] src_tokens = item['src'].split() tgt_tokens = item['tgt'].split() # 截断超长样本，避免 batch 内 padding 过多浪费算力 src_tokens = src_tokens[:self.max_len - 2] tgt_tokens = tgt_tokens[:self.max_len - 1] # 加上 <bos> 和 <eos>，<bos> 只加在目标端 src_ids = [self.vocab['src']['<bos>']] + \ [self.vocab['src'].get(t, self.vocab['src']['<unk>']) for t in src_tokens] + \ [self.vocab['src']['<eos>']] tgt_ids = [self.vocab['tgt']['<bos>']] + \ [self.vocab['tgt'].get(t, self.vocab['tgt']['<unk>']) for t in tgt_tokens] + \ [self.vocab['tgt']['<eos>']] return src_ids, tgt_ids这段代码逻辑上有三个设计要点值得展开说明。第一，src 序列的max_len - 2是在给<bos>和<eos>两个特殊 token 留位置，tgt 序列的max_len - 1是因为解码端输入不需要<eos>（预测目标才需要）；第二，词表里查不到的词统一映射成<unk>，而不是直接丢弃，这能防止训练和推理时出现索引越界；第三，<bos>只加在目标端，源端不需要，因为编码器的输入本来就该是完整句子，不需要一个开始标记来"开启生成"。
2.2 build_vocab 逻辑：vocab.json 是怎么生成的
很多入门项目把词表构建直接写在训练脚本里，每次跑都重新算一遍。这个项目的做法是把词表单独存成 vocab.json，训练和推理共用一个文件，这样能保证推理时遇到的词和训练时的索引完全一致，不会出现"训练和推理词表对不上"这种低级问题。
dictionary.py 里的核心函数：
import json def build_vocab_from_json(json_path, src_min_freq=2, tgt_min_freq=2): with open(json_path, 'r', encoding='utf-8') as f: data = json.load(f) src_counter, tgt_counter = {}, {} for item in data: for w in item['src'].split(): src_counter[w] = src_counter.get(w, 0) + 1 for w in item['tgt'].split(): tgt_counter[w] = tgt_counter.get(w, 0) + 1 # 只保留出现次数 >= min_freq 的词，其余一律归 <unk> src_vocab = {'<pad>': 0, '<bos>': 1, '<eos>': 2, '<unk>': 3} tgt_vocab = {'<pad>': 0, '<bos>': 1, '<eos>': 2, '<unk>': 3} for w, c in src_counter.items(): if c >= src_min_freq: src_vocab[w] = len(src_vocab) for w, c in tgt_counter.items(): if c >= tgt_min_freq: tgt_vocab[w] = len(tgt_vocab) return {'src': src_vocab, 'tgt': tgt_vocab} # 使用：python -m dictionary --train data/train.json --output data/vocab.json有一个细节值得注意：<pad>的 id 被固定为 0，这和后面所有 mask 逻辑都强相关。PyTorch 的nn.Embedding默认padding_idx=0不做梯度回传，模型不需要去学 padding 位置的向量，省了一部分显存也避免了无意义的更新。如果哪天你自己构建数据时把<pad>的 id 改成了别的值，记得要在 Embedding 层同步设好padding_idx，不然模型会在 padding 上白费学习能力。
2.3 依赖环境与运行脚本：不用 GPU 也能跑，但建议至少 6G 显存
requirements.txt 里的依赖非常精简：
torch>=1.7.0 numpy sacrebleu>=2.0.0sacrebleu 是拿来算 BLEU 的，没有它 train.py 也能跑但评测部分会报错。run_train.sh 和 run_translate.sh 把最常用的命令打包好了：
#!/bin/bash # run_train.sh python train.py \ --data data/train.json \ --val-data data/val.json \ --vocab data/vocab.json \ --epochs 30 \ --batch-size 64 \ --lr 1e-3 \ --d-model 256 \ --n-heads 8 \ --num-layers 6 \ --dropout 0.1 \ --save-dir checkpoints/ \ --log-interval 50注意--d-model 256是通用配置里的中等规模参数。原版 Transformer 论文用的是 d_model=512，我读了下 config.py 里的默认配置，作者刻意调成了 256——这样显存需求大幅下降，单卡 8G 就能塞下 64 的 batch size，训练速度也快不少，适合入门机器。如果你想还原论文里的效果，直接把 d-model 改回 512、n-heads 保持 8，batch-size 要降到 32 才能塞得下。
3. 核心模型拆解：从 Embedding 到多头注意力再到编码器解码器
这个项目的 model.py 完整实现了 Transformer 的所有核心组件，没有调用 nn.Transformer 偷懒。这部分我会带着大家逐一过代码：先讲整体骨架，再拆多头注意力、位置编码、前馈网络，最后把编码器和解码器组装起来。
3.1 模型骨架定义：hyperparameter 全部收口到模型类外部
model.py 开头定义了一个小配置类，用起来很直观：
class TransformerConfig: def __init__(self, d_model=256, n_heads=8, num_encoder_layers=6, num_decoder_layers=6, d_ff=1024, vocab_src_size=10000, vocab_tgt_size=10000, dropout=0.1, max_len=128): self.d_model = d_model self.n_heads = n_heads self.num_encoder_layers = num_encoder_layers self.num_decoder_layers = num_decoder_layers self.d_ff = d_ff self.vocab_src_size = vocab_src_size self.vocab_tgt_size = vocab_tgt_size self.dropout = dropout self.max_len = max_lend_model 是整个模型的隐性维度，所有 token 的向量表示都统一在这个维度下做变换；n_heads 是多头注意力中头的数量，256 维拆成 8 个头的话每个头负责 32 维特征子空间；d_ff 是前馈网络的中间层维度，通常是 d_model 的 4 倍。这几个参数之间有兼容性约束：d_model 必须能被 n_heads 整除，不然多头拆分会报维度错误——这是我拆包时顺手验证过的，config 默认值没问题，但如果你自己改参数时不小心把 d_model 设成 300 而 n_heads=8，train.py 会在 forward 阶段直接抛错。
3.2 位置编码：用正弦函数生成固定位置信息
Transformer 没有循环结构，所以要靠位置编码给每个 token 注入顺序信息。model.py 里的位置编码用的是论文原版公式：
import math import torch import torch.nn as nn class PositionalEncoding(nn.Module): def __init__(self, d_model, max_len=128, dropout=0.1): super().__init__() self.dropout = nn.Dropout(p=dropout) pe = torch.zeros(max_len, d_model) position = torch.arange(0, max_len, dtype=torch.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) # 偶数维度用 sin pe[:, 1::2] = torch.cos(position * div_term) # 奇数维度用 cos pe = pe.unsqueeze(0) # 形状变成 [1, max_len, d_model] self.register_buffer('pe', pe) def forward(self, x): # x: [batch, seq_len, d_model] x = x + self.pe[:, :x.size(1), :] return self.dropout(x)这段代码有两个实现细节值得抄作业。第一，pe用register_buffer注册而不是直接赋值给 self.pe 的普通 tensor，这样做的意义是：当模型调用.to(device)或.cuda()时，位置编码会跟模型一起同步迁移到 GPU 上，不会出现"模型在 GPU 但位置编码还在 CPU"的经典报错。第二，pe[:, 0::2]和pe[:, 1::2]用切片操作分别填充偶数维和奇数维，这样生成的编码满足不同频率的正弦/余弦模式，模型可以通过线性变换学习到相对位置的依赖关系。
实际使用中这个模块在嵌入层之后调用，代码是：
src = self.embed_src(src_tokens) * math.sqrt(self.d_model) src = self.pos_encoder(src)为什么要乘math.sqrt(self.d_model)？因为 Embedding 层输出的向量范数普遍偏小，乘上这个缩放因子能让它和位置编码的数值范围匹配。如果忘了这步，embedding 值域和位置编码值域差异过大，模型初始 loss 会比较高而且收敛变慢——这也是个常见但隐蔽的坑。
3.3 多头注意力：mask 掩码与 scaled dot-product attention 的完整实现
多头注意力是整个 Transformer 最核心的模块。model.py 里这个类的代码是：
class MultiHeadAttention(nn.Module): def __init__(self, d_model, n_heads, dropout=0.1): super().__init__() assert d_model % n_heads == 0 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.dropout = nn.Dropout(p=dropout) def forward(self, query, key, value, mask=None): batch_size = query.size(0) # 1. 投影并拆头 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) # 2. 计算 attention scores scores = torch.matmul(Q, K.transpose(-2, -1)) / math.sqrt(self.d_k) if mask is not None: scores = scores.masked_fill(mask == 0, -1e9) attn = torch.softmax(scores, dim=-1) attn = self.dropout(attn) # 3. 加权求和还原维度 context = torch.matmul(attn, V) context = context.transpose(1, 2).contiguous().view(batch_size, -1, self.d_model) output = self.W_o(context) return output拆开看逻辑，第一步把输入的 [batch, seq_len, d_model] 张量通过三个线性层分别映射成 Q、K、V，然后用 view 和 transpose 操作把维度重排成 [batch, n_heads, seq_len, d_k]，这样每个头独立计算注意力互不干扰；第二步计算 Q 和 K 的点积得到原始分数，除以sqrt(d_k)做缩放，目的是防止点积结果过大把 softmax 推到饱和区导致梯度消失；第三步是 mask 处理和 softmax 归一化，把 mask 中为 0 的位置填充为 -1e9，这样 softmax 之后这些位置的注意力权重约等于 0，相当于模型完全忽略这些位置。最后通过 W_o 把多头结果融合回 d_model 维度。
如果 mask 的形状是 [batch, seq_len]（比如 padding mask），masked_fill(mask == 0, -1e9)时 scores 的形状是 [batch, n_heads, seq_len_q, seq_len_k]，广播规则会自动扩展最后一维，所以每个 query 位置都会正确忽略 mask 为 0 的 key 位置。这行代码看起来简单，实际上对维度广播的理解要求很高，很多人就是在这块翻车的——mask 维度搞错要么不报错但效果奇差，要么直接 RuntimeError 教你做人。
3.4 编码器与解码器层：残差连接、LayerNorm 与前馈网络
编码器层由多头注意力加前馈网络组成，每个子层外面套了残差连接和 LayerNorm，这是 Transformer 能训练到几十层不掉点的关键。代码是：
class EncoderLayer(nn.Module): def __init__(self, d_model, n_heads, d_ff, dropout=0.1): super().__init__() self.self_attn = MultiHeadAttention(d_model, n_heads, dropout) self.feed_forward = nn.Sequential( nn.Linear(d_model, d_ff), nn.ReLU(), nn.Linear(d_ff, d_model), nn.Dropout(p=dropout) ) self.norm1 = nn.LayerNorm(d_model) self.norm2 = nn.LayerNorm(d_model) self.dropout = nn.Dropout(p=dropout) def forward(self, x, mask): # 子层1：自注意力 + 残差 + LayerNorm attn_out = self.self_attn(x, x, x, mask) x = self.norm1(x + self.dropout(attn_out)) # 子层2：前馈网络 + 残差 + LayerNorm ff_out = self.feed_forward(x) x = self.norm2(x + self.dropout(ff_out)) return x注意 LayerNorm 的位置是在残差相加之后，也就是论文里说的 post-norm 方案，原始 Transformer 就是这么干的。这种结构在训练初期比较稳定，loss 下得不算快但不会出现梯度爆炸。后面很多变体采用 pre-norm（LayerNorm 放在子层之前），那个训练更深模型时更稳，但这里沿用了原版设计，保持与论文一致。
解码器层比编码器多了一个"交叉注意力"子层，核心差异在于它接收的 K 和 V 来自编码器的输出，Q 来自解码器自身：
class DecoderLayer(nn.Module): def __init__(self, d_model, n_heads, d_ff, dropout=0.1): super().__init__() self.self_attn = MultiHeadAttention(d_model, n_heads, dropout) self.cross_attn = MultiHeadAttention(d_model, n_heads, dropout) self.feed_forward = nn.Sequential( nn.Linear(d_model, d_ff), nn.ReLU(), nn.Linear(d_ff, d_model), nn.Dropout(p=dropout) ) self.norm1 = nn.LayerNorm(d_model) self.norm2 = nn.LayerNorm(d_model) self.norm3 = nn.LayerNorm(d_model) self.dropout = nn.Dropout(p=dropout) def forward(self, x, enc_output, src_mask, tgt_mask): # 第一子层：目标序列自注意力（带 look-ahead mask） attn_out = self.self_attn(x, x, x, tgt_mask) x = self.norm1(x + self.dropout(attn_out)) # 第二子层：交叉注意力，key/value 来自编码器 cross_out = self.cross_attn(x, enc_output, enc_output, src_mask) x = self.norm2(x + self.dropout(cross_out)) # 第三子层：前馈网络 ff_out = self.feed_forward(x) x = self.norm3(x + self.dropout(ff_out)) return x这里有三处容易踩坑的地方。第一，解码器自注意力的 mask 必须同时包含 padding mask 和 look-ahead mask（就是上三角矩阵），否则训练时每个位置都能"看到"后面的 token，相当于变相作弊，模型学到的注意力分布完全没有意义；第二，交叉注意力传入的 src_mask 是编码器的 padding mask，因为编码器输出里 padding 位置还是有向量表示的，需要让解码器知道哪些位置是无效的；第三，推理阶段 self_attn 的 mask 长度逐步增长，每一步都要重新构造 mask，代码里 translate.py 用了一个循环来维护这个 mask。
3.5 模型组装：emb、Transformer 整体 forward、生成 logits
完整模型类的 forward 逻辑是：
class Transformer(nn.Module): def __init__(self, config): super().__init__() self.embed_src = nn.Embedding(config.vocab_src_size, config.d_model, padding_idx=0) self.embed_tgt = nn.Embedding(config.vocab_tgt_size, config.d_model, padding_idx=0) self.pos_encoder = PositionalEncoding(config.d_model, config.max_len, config.dropout) self.encoder_layers = nn.ModuleList( [EncoderLayer(config.d_model, config.n_heads, config.d_ff, config.dropout) for _ in range(config.num_encoder_layers)]) self.decoder_layers = nn.ModuleList( [DecoderLayer(config.d_model, config.n_heads, config.d_ff, config.dropout) for _ in range(config.num_decoder_layers)]) self.generator = nn.Linear(config.d_model, config.vocab_tgt_size) def forward(self, src_tokens, tgt_tokens, src_mask, tgt_mask): # 编码器 src_emb = self.embed_src(src_tokens) * math.sqrt(self.d_model) src_emb = self.pos_encoder(src_emb) enc_output = src_emb for layer in self.encoder_layers: enc_output = layer(enc_output, src_mask) # 解码器 tgt_emb = self.embed_tgt(tgt_tokens) * math.sqrt(self.d_model) tgt_emb = self.pos_encoder(tgt_emb) dec_output = tgt_emb for layer in self.decoder_layers: dec_output = layer(dec_output, enc_output, src_mask, tgt_mask) logits = self.generator(dec_output) return logitsgenerator就是最后一层线性映射，把 d_model 维度的向量映射到词表大小，后面接 softmax 就是每个位置每个词的概率。Embedding 层两个词表是独立的，源语言和目标语言各一套向量，互不共享——这是翻译任务的标准做法，不像 BERT 那种单语任务可以直接共享 embedding。
4. 数据管线与训练流程：从 JSON 文件到 batch 再到一个可用的翻译模型
读完模型定义之后，接着看数据是怎么从原始文件变成模型输入的。这个项目的 pipeline 相当清晰：JSON → tokenization → 词表映射 → collate_fn 组装 batch → 训练/验证两个阶段各自处理 mask。
4.1 collate_fn 里如何构造多样化的 batch
PyTorch 的 DataLoader 在取 batch 时会对每条样本调用 collate_fn，把不同长度的序列装进同一个 tensor。这个项目里的实现是：
def collate_fn(batch): src_batch, tgt_batch = [], [] for src_ids, tgt_ids in batch: src_batch.append(torch.tensor(src_ids, dtype=torch.long)) tgt_batch.append(torch.tensor(tgt_ids, dtype=torch.long)) # padding 到同一长度 src_len = max([s.size(0) for s in src_batch]) tgt_len = max([t.size(0) for t in tgt_batch]) src_padded = torch.zeros(len(src_batch), src_len, dtype=torch.long) tgt_padded = torch.zeros(len(tgt_batch), tgt_len, dtype=torch.long) for i, s in enumerate(src_batch): src_padded[i, :s.size(0)] = s for i, t in enumerate(tgt_batch): tgt_padded[i, :t.size(0)] = t # 构建 padding mask：值为 0 的位置代表 padding src_mask = (src_padded != 0).unsqueeze(1).unsqueeze(2) # 构建 tgt 的 look-ahead mask：上三角矩阵 tgt_mask = torch.triu(torch.ones(tgt_len, tgt_len), diagonal=1) == 0 return src_padded, tgt_padded, src_mask, tgt_masktgt_mask用torch.triu生成上三角矩阵后取反，得到一个下三角全 1、上三角全 0 的矩阵。这个操作很精妙——下三角位置代表"只能看当前和之前的 token"，上三角位置全部 mask 掉。解码器在预测第 i 个词的时候只能用到 0 到 i 的输入，这保证了训练时的行为与推理时逐词生成的逻辑一致。
src_mask 的维度是 [batch, 1, 1, seq_len]，需要 squeeze 一下才能匹配 attention 层的输入（因为多头注意力内部处理的是四维 scores）。在编码器层的 forward 里直接传 mask 进去就行，广播机制会把 mask 扩展到 [batch, n_heads, seq_len, seq_len] 的维度上。
4.2 训练循环：Teacher Forcing 和标准的 label smoothing
训练脚本 train.py 的优化器用的是 Adam，学习率调度用的是论文里的 Noam 衰减策略。看代码：
optimizer = torch.optim.Adam(model.parameters(), lr=lr, betas=(0.9, 0.98), eps=1e-9) def lr_lambda(step): warmup_steps = 4000 return (d_model ** -0.5) * min(step ** -0.5, step * (warmup_steps ** -1.5)) scheduler = torch.optim.lr_scheduler.LambdaLR(optimizer, lr_lambda=lr_lambda)Noam 衰减策略分两段：前 4000 步学习率从极小值线性爬升到峰值，之后按步数的平方根倒数缓慢衰减。这个设计的动机是什么？Transformer 训练初期模型参数还没稳定，注意力分布非常散乱，如果一上来就用大学习率很容易把模型推到死胡同；warmup 阶段让模型先用小步长把注意力机制学起来，再逐渐加大步长加速收敛。我在复现这个项目时试过把 warmup 去掉直接用固定学习率，loss 在初期确实会抖动比较大，后期也更容易收敛到次优解。
训练时每个 batch 的目标输入是整体喂进去的，不是逐步生成：
for epoch in range(epochs): for step, (src, tgt, src_mask, tgt_mask) in enumerate(train_loader): src, tgt = src.to(device), tgt.to(device) src_mask, tgt_mask = src_mask.to(device), tgt_mask.to(device) # 解码器输入：去掉最后一个 token tgt_input = tgt[:, :-1] logits = model(src, tgt_input, src_mask, tgt_mask[:, :-1, :-1]) # 目标：去掉第一个 token（<bos>） tgt_output = tgt[:, 1:] loss = criterion(logits.reshape(-1, logits.size(-1)), tgt_output.reshape(-1)) optimizer.zero_grad() loss.backward() torch.nn.utils.clip_grad_norm_(model.parameters(), 5.0) optimizer.step() scheduler.step()这里有个隐蔽的细节：tgt_input和tgt_output都是从同一个tgt张量切出来的，输入是[<bos>, token1, token2, ...]，输出是[token1, token2, ..., <eos>]。这样做的原因是：解码器预测位置 i 的 token 时，输入是位置 0 到 i-1 的 token，所谓 Teacher Forcing 就是让模型每一步都拿真实的上一时刻 token 做输入，而不是拿自己的预测结果——训练时收敛快，但推理时模型要自己接自己的输出，这就是所谓的"暴露偏差"问题，也是机器翻译模型的经典软肋。
4.3 推理脚本：beam search 解码与长度惩罚
translate.py 的核心是 beam search。训练时模型见过完整的目标序列，推理时得一步一步生成：
def beam_search(model, src_tokens, src_mask, beam_size=5, max_len=128): model.eval() with torch.no_grad(): enc_output = model.encode(src_tokens, src_mask) # 初始输入只有 <bos> current_states = [{'tokens': [BOS_ID], 'score': 0.0, 'enc_output': enc_output}] for step in range(max_len): all_candidates = [] for state in current_states: tgt_input = torch.tensor([state['tokens']], device=device) logits = model.decode_step(enc_output, tgt_input, src_mask) next_log_probs = torch.log_softmax(logits[:, -1, :], dim=-1) topk_probs, topk_ids = torch.topk(next_log_probs, beam_size, dim=-1) for i in range(beam_size): candidate = { 'tokens': state['tokens'] + [topk_ids[0, i].item()], 'score': state['score'] + topk_probs[0, i].item(), 'enc_output': enc_output } all_candidates.append(candidate) # 按总分排序，只保留 beam_size 个候选 current_states = sorted(all_candidates, key=lambda s: s['score'], reverse=True)[:beam_size] if any(s['tokens'][-1] == EOS_ID for s in current_states): break best = sorted(current_states, key=lambda s: s['score'])[0] return best['tokens']beam search 的核心思想是每个时间步都保留 top-k 个最优候选路径，而不是像贪心搜索那样只保留一个。这个项目里 beam_size 默认是 5，更大的 beam 比如 8 或 10 能带来微小的 BLEU 提升，但推理时间会显著增加。调试时如果发现生成结果全是重复的<eos>，大概率是 mask 没有逐位置更新导致的——beam search 里每个候选长度不同，mask 矩阵不能在整个 batch 上共享，必须按每条候选单独维护。
5. 避坑与排查：Transformer 项目最常翻车的六个场景
任何动手跑过 Transformer 训练的人都能列出一张踩坑清单。下面写的这六条覆盖了从数据到训练再到推理的完整链条，全部是我在跑这份资源时实际碰到过的问题，按「现象 → 原因 → 解决」的格式整理。
5.1 训练 loss 一直在 4 到 5 之间几乎不变
这个现象新手特别容易撞上。我最初跑的时候 loss 大概在 4.2 左右，相当于模型每步都接近随机猜测（词表大小 8000 时均匀分布的交叉熵就是 log(8000) ≈ 8.98，4.2 已经明显低于随机了，但它在训练 5 个 epoch 后就没怎么动过）。原因通常有两个：一是学习率调度出了问题，检查 scheduler 是否按 step 而不是按 epoch 调用——如果错误地每个 epoch 调一次，warmup 的效果会被大幅削弱；二是 batch 内 padding 比例太高，大量计算浪费在 padding 位置，有效信息占比低导致学习效率差。
解决方法是先用一条短文本（长度不超过 10 个 token）做过拟合测试，看看模型能不能在这单条数据上把 loss 降到接近 0。如果能，说明模型本身没问题，数据管线才是瓶颈；如果不能，优先检查 embedding 层的 padding_idx 和 mask 的维度。
5.2 src_mask 维度不匹配，报错信息看不懂
MultiHeadAttention 里scores.masked_fill(mask == 0, -1e9)要求 mask 最后两维能广播到 [seq_len_q, seq_len_k]。如果 src_mask 形状是 [batch, 1, seq_len]，scores 是 [batch, n_heads, seq_len_q, seq_len_k]，广播时中间维度 n_heads 和 1 不对应，直接 RuntimeError。原因常见是 collate_fn 里 unsqueeze 次数不够。
解决：把src_mask = (src != 0).unsqueeze(1).unsqueeze(2)改成明确地构建成四维，或者在一开始就打印各张量的 shape 逐步调试。
5.3 推理结果全是同一个词无限循环
现象是模型生成 "the the the the the ..."，直到 hit max_len 被截断。原因基本可以肯定是 look-ahead mask 没起作用——解码器的自注意力能看到当前位置之后的 token，模型学到了直接用正确答案作弊的路径，根本没有好好建模语言概率。
解决：打印 tgt_mask 矩阵，确认是下三角全 1、上三角全 0；检查torch.triu(torch.ones(n, n), diagonal=1) == 0这行是否写对了diagonal=1而不是 0。
5.4 GPU 显存不够，batch_size 降到 1 还是 OOM
如果 batch=1 都爆显存，说明问题不在 batch 大小，而是模型本身太大。默认配置 d_model=256、6 层编码器、6 层解码器，参数量大概在两千万左右，单 batch 的中间激活值确实是主要显存消耗。
解决：把 d_model 降到 128，n_heads 保持 8（128 能被 8 整除），d_ff 同步降到 512，层数可以暂时砍到 3。等代码完全跑通再慢慢加回来。这个项目反正不是论文复现竞赛，自己的机器能跑比什么都重要。
5.5 词表里出现数字和特殊符号但模型永远翻译不对
数据没有做基本的清洗时就会出现这个问题。比如英文 "3.14" 和德文 "3,14" 是两个完全不同的 token，但语义上等价；分词器把 "don't" 拆成 "don" 和 "t"，模型要额外学习这种变形规则。这份资源自带的数据已经处理得比较干净了，但你自己换数据时大概率会遇到。
解决：统一对源语言和目标语言做同样粒度的 tokenization，比如都用spacy或nltk的 sentencepiece 来做采样切分；数字类 token 统一映射成<num>占位符，可以显著缩小词表并提升泛化能力。
5.6 BLEU 分数很低但 loss 已经很好
概率分布学得很好但生成的句子和参考译文词序差很远，这是典型的"分布正确、生成路径错误"问题。常见原因有两个——推理时没有做 length normalization，长句子的概率乘积天然会更低，导致模型倾向于输出短句；或者 beam_size 过大，候选路径分数相差很小但 token 选择差异巨大。
解决：在 beam_search 的 score 上除以(len(candidate) ** alpha)，alpha 设为 0.6 到 1.0 之间的值（论文推荐 0.6），对长句做补偿；同时把 beam_size 从 5 降到 3 或者升到 7 都试一下，找一个平衡点。
6. 二次开发：把英德翻译换成你自己的双语平行语料
跑到这里，模型和代码逻辑已经非常熟悉了，接下来自然是把它改造成自己的项目。我基于这份源码做的第一个改动是换了一套中英平行语料，整个改造过程只动了三处配置，没有改一行模型代码——这正是这份资源架构设计合理的地方。
第一步是数据格式与词表重建。把自带的英德语料换成中英，做法是构造同样结构的my_train.json和my_val.json，然后跑：
python dictionary.py \ --train data/my_train.json \ --output data/my_vocab.json \ --src-min-freq 2 \ --tgt-min-freq 1tgt-min-freq 建议调成 1——中文分词之后高频词相对少，如果 min_freq=2 会丢失大量有效词，导致<unk>比例飙升，模型就算训练好也会输出一堆UNK占位符。英文和德文因为有空格天然分词，中文需要先做分词，推荐直接用jieba在 dictionary.py 的读取逻辑里加一行预处理。
第二步是改 train.py 里的几个参数。最关键的调整是--src-min-freq和--tgt-min-freq——中文语料词表普遍比英文大，建议把 vocab size 上限放宽到 30000 或 50000，否则词表会截断高频词以外的所有内容。另外 max-len 默认 128 对中文对话语料偏长了，建议改成 64，减少 padding 浪费：
python train.py \ --data data/my_train.json \ --val-data data/my_val.json \ --vocab data/my_vocab.json \ --epochs 40 \ --batch-size 32 \ --d-model 256 \ --n-heads 8 \ --num-layers 4 \ --max-len 64 \ --save-dir checkpoints/my_model/batch-size 缩小到 32 是因为中文 token 密集，同样长度下序列信息密度更高，显存占用比英文翻一倍左右，需要留些余量。
第三步是验证改写结果。训练完在验证集上跑 translate.py，重点观察三个指标：验证集 BLEU 是否在持续上升（如果 20 个 epoch 后还在 10 以下，很大概率是词表构建有问题）；beam search 输出的中文句子是否有完整语义（如果大量<unk>出现，需要回查 tgt-min-freq 设置）；以及模型对 out-of-vocabulary 词的反应——这个只能靠人工检查，没有捷径。
我个人的习惯是每次改完数据源都会先做一轮单条过拟合测试，把训练集里随机抽 100 条丢进去跑 5 个 epoch，确认 loss 能降到足够低再启动完整训练。否则完整语料训练跑了两天，最后发现是词表踩了坑，那种血泪教训让人想掀桌子。从那以后我每换一次数据，都强制自己在 training loop 里加一个 sanity check：每 10 个 batch 打印一次模型输出和真实目标的 token 序列对比，确认它们在内容上是有关联的。这个方法简单但极其有效，能避免 80% 以上的训练配置低级错误。希望这份 AISTransforemr 数据代码的解析笔记，能帮你把这个项目改成自己顺手的状态。
本文还有配套的精品资源，点击获取