PaddleNLP Transformer 序列生成模型全解析：modeling 模块架构与实战指南

PaddleNLP Transformer 序列生成模型全解析modeling 模块架构与实战指南【免费下载链接】PaddleNLPEasy-to-use and powerful LLM and SLM library with awesome model zoo.项目地址: https://gitcode.com/gh_mirrors/pa/PaddleNLP导读本文聚焦 PaddleNLP 中面向机器翻译等序列到序列Seq2Seq任务的经典 Transformer 实现即paddlenlp.transformers.transformer.modeling模块API 参考入口见 docs/zh/source/paddlenlp.transformers.transformer.modeling.rst模块源码位于 paddlenlp/transformers/transformer/modeling.py。文章将系统拆解该模块的词嵌入、位置编码、损失函数、编码器-解码器主干以及两套 Beam Search 推理实现并结合仓库内机器翻译示例slm/examples/machine_translation/transformer给出可直接运行的训练、推理与配置方案。读完本文你将掌握在 PaddleNLP 中从零训练一个 Transformer 翻译模型、加载权重并完成束搜索解码的完整链路并理解 v1/v2 两代 Beam Search 的实现差异与选型要点。模块定位与整体结构paddlenlp.transformers.transformer是一个面向序列生成任务的 Transformer 完整实现它并非对 Paddle 官方paddle.nn.Transformer的简单封装而是在其上叠加了 PaddleNLP 特有的工程化能力正弦位置编码表的自动生成position_encoding_init带缩放与 padding 处理的词嵌入WordEmbedding、PositionalEmbedding训练期损失函数CrossEntropyCriterion、LabelSmoothedCrossEntropyCriterion推理期自回归解码单元与束搜索解码器TransformerDecodeCell、TransformerBeamSearchDecoder训练模型与推理模型两个对外入口TransformerModel、InferTransformerModel。模块的顶层导出定义见 modeling.py__all__共包含 8 个公开对象__all__ [ position_encoding_init, WordEmbedding, PositionalEmbedding, CrossEntropyCriterion, TransformerDecodeCell, TransformerBeamSearchDecoder, TransformerModel, InferTransformerModel, LabelSmoothedCrossEntropyCriterion, ]这些对象均可通过from paddlenlp.transformers import ...直接导入。从源码结构看该模块采用「Paddle 官方 Transformer 层 PaddleNLP 定制组件」的分层策略底层编码器/解码器复用paddle.nn.TransformerEncoder、paddle.nn.TransformerDecoder等官方层PaddleNLP 负责数据形态适配注意力 mask、位置 id、训练损失和束搜索编排。词嵌入与位置编码序列输入的两种信号position_encoding_init正弦位置编码表生成position_encoding_init(n_position, d_pos_vec, dtypefloat32)用于生成正弦位置编码表返回形状为[n_position, d_pos_vec]的numpy.array。实现参考 tensor2tensor与原始论文《Attention Is All You Need》的写法略有差异按时间尺度对数递减的方式构造频率每个位置由sin与cos交替拼接而成最后对奇数维度做补零np.pad以对齐通道数见 modeling.py。核心参数n_position序列的最大长度即源/目标序列长度上限d_pos_vec位置向量维度dtype输出数据类型默认float32。最小调用示例from paddlenlp.transformers import position_encoding_init max_length 256 emb_dim 512 pos_table position_encoding_init(max_length, emb_dim) # shape: [256, 512]WordEmbedding带缩放与 padding 掩码的词嵌入层WordEmbedding(vocab_size, emb_dim, bos_id0)基于paddle.nn.Embedding构建二维词嵌入矩阵关键点有三缩放前向时将查表结果乘以sqrt(emb_dim)即Out embedding(word) * sqrt(emb_dim)对应论文中的sqrt(d_model)缩放权重初始化嵌入权重使用Normal(0.0, emb_dim ** (-0.5))正态初始化见 modeling.pypadding 语义bos_id同时作为padding_idx即bos位置的梯度不会参与回传。import paddle from paddlenlp.transformers import WordEmbedding word_embedding WordEmbedding(vocab_size30000, emb_dim512, bos_id0) batch_size, sequence_length 5, 10 src_words paddle.randint(low3, high30000, shape[batch_size, sequence_length]) src_emb word_embedding(src_words) # shape: [5, 10, 512]PositionalEmbedding可查表的固定位置编码层PositionalEmbedding(emb_dim, max_length)将position_encoding_init生成的编码表通过Assign初始化器写入一个nn.Embedding见 modeling.py前向时按位置 id 查表并设置stop_gradient True使位置编码在训练中保持固定、不参与梯度更新。import paddle from paddlenlp.transformers import PositionalEmbedding pos_embedding PositionalEmbedding(emb_dim512, max_length256) batch_size 5 pos paddle.tile(paddle.arange(start0, end50), repeat_times[batch_size, 1]) pos_emb pos_embedding(pos) # shape: [5, 50, 512]需要特别说明的是在TransformerModel.forward中位置 id 并不是直接传入arange而是通过paddle.cast(src_word ! pad_id, ...) * arange构造padding 位置的位置 id 被置 0配合词嵌入的padding_idx从信号源头保证了 padding 位置不携带有效信息见 modeling.py。损失函数交叉熵与标签平滑CrossEntropyCriterion训练期标准损失CrossEntropyCriterion(label_smooth_epsNone, pad_idx0)是训练期的主力损失层。其forward(predict, label)接收模型输出的 logits形状[batch_size, seq_len, vocab_size]与标签形状[batch_size, seq_len, 1]返回三元组(sum_cost, avg_cost, token_num)sum_cost当前 batch 的损失总和token_num非 padding 的有效 token 数对label ! pad_idx求和并设置stop_gradientavg_cost sum_cost / token_num即按有效 token 平均的损失。实现细节见 modeling.py先用label ! pad_idx构造权重 mask 过滤 padding 位置的损失若设置label_smooth_eps则先对 one-hot 标签执行F.label_smooth再做软标签交叉熵从而在训练中引入正则化。import paddle from paddlenlp.transformers import CrossEntropyCriterion criterion CrossEntropyCriterion(label_smooth_eps0.1, pad_idx0) predict paddle.rand(shape[1, 2, 30000]) label paddle.randint(low3, high30000, shape[1, 2, 1]) sum_cost, avg_cost, token_num criterion(predict, label)LabelSmoothedCrossEntropyCriterionfairseq 风格损失LabelSmoothedCrossEntropyCriterion(label_smoothing, padding_idx0)提供另一套等价实现先对 logits 做log_softmax并展平再通过label_smoothed_nll_loss计算 NLL 损失与平滑损失的加权和权重为eps_i epsilon / (vocab_size - 1)见 modeling.py。该实现与 fairseq 的损失公式对齐适合需要与 fairseq 基线结果直接对比的场景。TransformerModel编码器-解码器主干TransformerModel是训练与验证阶段使用的完整模型直接继承paddle.nn.Layer对外暴露与经典 Transformer 对齐的超参体系见 modeling.py参数含义默认值src_vocab_size/trg_vocab_size源/目标词表大小必填max_length序列最大长度位置编码表尺寸必填num_encoder_layers/num_decoder_layers编码器/解码器堆叠层数必填n_head多头注意力头数必填d_model嵌入与注意力输出维度必填d_inner_hid前馈网络隐藏层维度必填dropout全局限定 dropout 率必填weight_sharing是否共享源/目标嵌入与输出层权重必填attn_dropout注意力内 dropout为None时取dropoutNoneact_dropoutFFN 激活后 dropout为None时取dropoutNonebos_id/eos_id起始/结束符 id0/1pad_idpadding id为None时取bos_idNoneactivationFFN 激活函数relunormalize_before是否使用 Pre-NormTrue几个值得注意的实现细节权重共享当weight_sharingTrue时要求src_vocab_size trg_vocab_size源码中有显式断言目标侧词嵌入直接复用源侧self.trg_word_embedding self.src_word_embedding输出层则用paddle.matmul(x, embedding.weight, transpose_yTrue)代替独立的nn.Linear实现经典 weight tying见 modeling.py。Pre-Norm / Post-Norm 双路径当normalize_beforeTrue时直接使用paddle.nn.Transformer默认的归一化策略当normalize_beforeFalse时构造带normalize_beforeFalse的TransformerEncoderLayer/TransformerDecoderLayer并通过custom_encoder/custom_decoder注入见 modeling.py使训练结果可与经典 post-norm Transformer 基线对齐。三路 attention mask前向时自动构造src_slf_attn_biaspadding mask值为-1e4、trg_slf_attn_biasgenerate_square_subsequent_mask生成的因果 mask以及trg_src_attn_bias交叉注意力 mask三路 mask 均设置stop_gradient见 modeling.py。FP16 支持整个前向包裹在paddle.static.amp.fp16_guard()中可无缝配合混合精度训练。最小调用示例import paddle from paddlenlp.transformers import TransformerModel transformer TransformerModel( src_vocab_size30000, trg_vocab_size30000, max_length257, num_encoder_layers6, num_decoder_layers6, n_head8, d_model512, d_inner_hid2048, dropout0.1, weight_sharingTrue, bos_id0, eos_id1) batch_size, seq_len 5, 10 predict transformer( src_wordpaddle.randint(low3, high30000, shape[batch_size, seq_len]), trg_wordpaddle.randint(low3, high30000, shape[batch_size, seq_len]))推理链路从解码单元到束搜索TransformerDecodeCell单步解码单元TransformerDecodeCell(decoder, word_embeddingNone, pos_embeddingNone, linearNone, dropout0.1)将解码器、词嵌入、位置嵌入与输出层组合为一个「单步产生 logits」的单元见 modeling.py。它接收(inputs, states, static_cache, trg_src_attn_bias, memory)inputs目标侧 id 与位置组成的元组或直接是解码器输入张量states/static_cache由paddle.nn.TransformerDecoder.gen_cache生成的增量缓存与静态缓存用于避免重复计算已解码位置的 attentionmemory编码器输出形状[batch_size, source_length, d_model]。前向时词嵌入与位置嵌入相加后经 dropout喂给解码器输出 logits 与更新后的new_statesnew_states相比输入长度多 1因为拼上了当前步的中间结果。TransformerBeamSearchDecoder适配 Transformer 的束搜索TransformerBeamSearchDecoder(cell, start_token, end_token, beam_size, var_dim_in_state)继承自paddle.nn.decode.BeamSearchDecoder专门处理 Transformer 解码的 3D 数据形态见 modeling.py。与 RNN 类解码器不同Transformer 每一步的解码状态是 3D 的因此该类重写了_merge_batch_beams_with_var_dim/_split_batch_beams_with_var_dim在 batch 与 beam 维度之间做特殊的 reshape/transpose正确处理长度随时间增长的缓存张量var_dim_in_state2即指定第 2 维为可变维tile_beam_merge_with_batch将[batch_size, ...]张量按 beam 复制为[batch_size * beam_size, ...]step单步执行「cell 计算 logits → 束搜索打分 → 选 top-k token」并通过force_decoding支持用参考译文强制解码在trg_word提供的场景下用真实 token 覆盖预测 token常用于评估时的 teacher forcing 对比。InferTransformerModel自回归推理模型InferTransformerModel继承自TransformerModel在构造时自动组装TransformerDecodeCell与TransformerBeamSearchDecoder见 modeling.py对外只接收src_word可选trg_word触发强制解码返回形状为[batch_size, seq_len, beam_size]output_time_majorFalse或[seq_len, batch_size, beam_size]output_time_majorTrue的 int64 预测序列。推理专属参数参数含义默认值beam_size束搜索宽度4max_out_len最大输出长度256output_time_major输出按时间主序还是 batch 主序Falsebeam_search_versionv1或v2v1rel_lenkwargsmax_out_len是否为相对源文长度仅 v2Falsealphakwargs长度惩罚幂指数仅 v2参考 GNMT 论文0.6Beam Search v1 流程forward中对应分支见 modeling.py先跑编码器得到enc_output调用decoder.gen_cache(enc_output, do_zipTrue)生成增量缓存与静态缓存将缓存、编码器输出、交叉注意力 mask 一并按 beam 复制再交给paddle.nn.decode.dynamic_decode循环解码。Beam Search v2 流程beam_search_v2见 modeling.py采用「alive 队列 finished 队列」双队列设计每步执行三个子步骤grow_topk从当前 alive 序列扩展出 top2 * beam_size候选避免候选全部落入 EOSgrow_alive从扩展候选中挑选 topbeam_size个未结束候选作为下一步输入grow_finished将新结束候选与 finished 队列合并保留 topbeam_size个已结束序列。v2 还实现了长度惩罚(5 len) / 6) ** alpha与early_finish提前终止判定并支持rel_len相对长度模式当max_lenNone且未显式设置时默认取enc_output.shape[1] 20。整体采用paddle.static.nn.while_loop组织循环兼具动态图调试便利与静态图编译能力。端到端实战以 WMT14 英德翻译为例仓库在 slm/examples/machine_translation/transformer 提供了完整的训练、预测与配置示例是上述模块最直接的落地参照。训练train.py训练脚本 train.py 展示了TransformerModelCrossEntropyCriterion的标准用法见 train.pytransformer TransformerModel( src_vocab_sizeargs.src_vocab_size, trg_vocab_sizeargs.trg_vocab_size, max_lengthargs.max_length 1, num_encoder_layersargs.n_layer, num_decoder_layersargs.n_layer, n_headargs.n_head, d_modelargs.d_model, d_inner_hidargs.d_inner_hid, dropoutargs.dropout, weight_sharingargs.weight_sharing, bos_idargs.bos_idx, eos_idargs.eos_idx, pad_idargs.pad_idx, normalize_beforeargs.get(normalize_before, True), ) criterion CrossEntropyCriterion(args.label_smooth_eps, args.bos_idx if args.pad_idx is None else args.pad_idx)配套要点学习率使用paddle.optimizer.lr.NoamDecay(d_model, warmup_steps, learning_rate)与 Transformer 论文的 warmup 调度一致支持 AMP 混合精度paddle.amp.decorateGradScalerO1/O2两级见 train.py支持多卡DataParallel与断点续训init_from_checkpoint加载transformer.pdparams与transformer.pdopt训练日志中会输出normalized loss与ppl其中 loss 归一化基准按标签平滑公式计算见 train.py。推理predict.py预测脚本 predict.py 中TransformerGeneratorpaddlenlp.ops会自动选择使用 FastGeneration 加速推理或回退到InferTransformerModel见 predict.pytransformer TransformerGenerator( src_vocab_sizeargs.src_vocab_size, trg_vocab_sizeargs.trg_vocab_size, max_lengthargs.max_length 1, num_encoder_layersargs.n_layer, num_decoder_layersargs.n_layer, n_headargs.n_head, d_modelargs.d_model, d_inner_hidargs.d_inner_hid, dropoutargs.dropout, weight_sharingargs.weight_sharing, bos_idargs.bos_idx, eos_idargs.eos_idx, pad_idargs.pad_idx, beam_sizeargs.beam_size, max_out_lenargs.max_out_len, use_ftnot args.without_ft, beam_search_versionargs.beam_search_version, normalize_beforeargs.get(normalize_before, True), rel_lenargs.use_rel_len, alphaargs.alpha, diversity_rateargs.diversity_rate, use_fp16_decodingFalse, ) transformer.load(os.path.join(args.init_from_params, transformer.pdparams)) transformer.eval()解码完成后通过post_process_seq按bos_idx/eos_idx截断并过滤特殊符号再由to_tokens映射回词表输出译文见 predict.py。配置文件transformer.big.yamlconfigs/transformer.big.yaml 给出了一个完整的 Big 规模配置同目录另有 transformer.base.yaml 小规模版本核心片段如下# Hyparams for training: epoch: 30 learning_rate: 2.0 beta1: 0.9 beta2: 0.997 eps: 1e-9 warmup_steps: 4000 label_smooth_eps: 0.1 # Hyparams for generation: beam_search_version: v1 beam_size: 4 max_out_len: 1024 use_rel_len: False alpha: 0.6 n_best: 1 # Hyparams for model: src_vocab_size: 10000 trg_vocab_size: 10000 bos_idx: 0 eos_idx: 1 unk_idx: 2 max_length: 1024 d_model: 1024 d_inner_hid: 4096 n_head: 16 n_layer: 6 dropout: 0.1 weight_sharing: True normalize_before: True # Mixed precision training use_amp: False use_pure_fp16: False scale_loss: 128.0配置中关于beam_search_version的注释非常关键见 transformer.big.yamlv1每步只保留 topbeam_size个束且 alive/finished 混合在一起遇到 EOS 后 alive 束数量会减少v2始终维持beam_size个 alive 束并单独维护 finished 队列搜索更充分、结果通常更好但生成的序列更长、计算量更大、速度更慢。选型时可按「质量优先选 v2速度优先选 v1」的原则权衡。常见命令行用法训练使用 big 配置GPU 多卡或单卡均可cd slm/examples/machine_translation/transformer python -m paddle.distributed.launch --gpus 0,1,2,3 train.py --config ./configs/transformer.big.yaml预测python predict.py --config ./configs/transformer.big.yaml \ --without_ft \ --init_from_params ./trained_models/step_final/其中--without_ft用于关闭 FastGeneration 加速、走纯InferTransformerModel路径便于调试与对比。测试与验证仓库对上述实现提供了双重验证tests/transformer/modeling.py 是核心单测覆盖了position_encoding_init、WordEmbedding、PositionalEmbedding、CrossEntropyCriterion、TransformerDecodeCell、TransformerBeamSearchDecoder、TransformerModel等主要对象其__all__与主模块保持一致可用于核对 API 的稳定性tests/test_tipc/transformer/modeling.py 是 TIPC飞桨训推一体链路测试用于验证「训练→导出→推理」全流程的可复现性。小结paddlenlp.transformers.transformer.modeling以「官方 Transformer 层 PaddleNLP 定制组件」的方式把序列生成任务从训练到推理的完整能力收敛在一个模块内WordEmbedding/PositionalEmbedding负责输入信号构造CrossEntropyCriterion负责带标签平滑的损失计算TransformerModel提供与论文对齐的训练主干TransformerDecodeCellTransformerBeamSearchDecoder组成自回归解码单元InferTransformerModel则以 v1/v2 两代 Beam Search 对外提供开箱即用的推理入口。配合 slm/examples/machine_translation/transformer 下的训练脚本、预测脚本与双份配置文件你可以快速完成从 WMT 数据集训练到译文生成的完整闭环在需要更高推理吞吐的场景下还可借助paddlenlp.ops.TransformerGenerator无缝切换到 FastGeneration 加速路径。【免费下载链接】PaddleNLPEasy-to-use and powerful LLM and SLM library with awesome model zoo.项目地址: https://gitcode.com/gh_mirrors/pa/PaddleNLP创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考