Transformers 中的 Wav2Vec2-Conformer 完全指南：Conformer 块架构、三种位置编码与 ASR 微调实战

Transformers 中的 Wav2Vec2-Conformer 完全指南Conformer 块架构、三种位置编码与 ASR 微调实战【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformersWav2Vec2-Conformer 是 MetaFAIR基于原版 Wav2Vec2 推出的改进语音模型它保留 Wav2Vec2 的整体自监督训练框架但把标准 Transformer 的 Self-Attention 层替换为Conformer 块卷积增强的 Transformer在参数量相近的情况下显著改善词错误率WER。本文基于当前仓库 docs/source/en/model_doc/wav2vec2-conformer.md 及其源码实现系统讲解该模型的架构设计、position_embeddings_type三种位置编码的取舍、Wav2Vec2ConformerConfig关键超参数以及面向 CTC 语音识别、音频分类、X-Vector 说话人识别等任务的加载与微调方法。阅读本文后你将能准确回答Conformer 块与 Wav2Vec2 原始自注意力层的差异是什么relative / rotary / 无位置编码三种模式如何切换以及如何用facebook/wav2vec2-conformer-rel-pos-large-960h-ft这类公开权重完成推理与微调等问题并具备直接阅读 Wav2Vec2ConformerModel 源码 与 配置源码 的能力。模型背景与定位Wav2Vec2-Conformer 于 2020-10-11 随论文fairseq S2T: Fast Speech-to-Text Modeling with fairseq作者 Changhan Wang、Yun Tang、Xutai Ma、Anne Wu、Sravya Popuri、Dmytro Okhonko、Juan Pino发布其官方结果见论文 Table 3 与 Table 4模型权重由 Meta AI 团队在 Fairseq 库中发布2022-05-17 起正式合入本仓库由 patrickvonplaten 贡献原始参考实现位于 fairseq 的examples/wav2vec目录。从工程归属上看当前仓库以模块化方式管理该模型src/transformers/models/wav2vec2_conformer/下包含配置类、模型主体、fairseq 权重转换脚本与 modular 定义configuration_wav2vec2_conformer.pyWav2Vec2ConformerConfigmodel_type wav2vec2-conformermodeling_wav2vec2_conformer.py全部模型类约 1800 行convert_wav2vec2_conformer_original_pytorch_checkpoint_to_pytorch.py把 fairseq 权重转换为 transformers 格式modular_wav2vec2_conformer.pymodular 开发入口方便与 Wav2Vec2 家族代码保持同步。官方文档模型说明同时提示Meta 后续发布了 Wav2Vec2-BERT 2.0在 450 万小时音频上预训练尤其推荐在微调任务如 ASR中优先考虑它。说明本文所有关于参数的默认值、类的定义与训练行为均以当前仓库源码为准性能结论仅引用官方文档明确陈述的内容不做臆测。架构核心用 Conformer 块替换 Attention 块根据官方文档的 Usage tipsWav2Vec2-Conformer采用与 Wav2Vec2 完全相同的整体架构唯一区别是把 Wav2Vec2 的 Self-Attention 块替换为 Conformer 论文Conformer: Convolution-augmented Transformer for Speech Recognition提出的Conformer 块。相同的层数下Conformer 需要更多参数量但能带来更好的 WER。在源码中单个 Conformer 块对应 Wav2Vec2ConformerEncoderLayer其前向顺序为 Macro/Large 版 Conformer 的half-step设计Feed-Forward 1half-stepffn1_layer_norm→ffn1Wav2Vec2ConformerFeedForward内部为Linear(hidden→intermediate) 激活默认 GELU dropout再Linear(intermediate→hidden)输出乘以0.5后与残差相加Self-Attentionself_attn_layer_norm→ Wav2Vec2ConformerSelfAttention → dropout → 残差相加卷积模块Wav2Vec2ConformerConvolutionModule实现 Conformer 中最有特色的局部建模其内部流水线是LayerNorm沿特征维逐点卷积pointwise_conv1hidden_size → 2 * hidden_sizeGLU 门控将通道减半回hidden_size深度可分离卷积depthwise_convkernel 为conv_depthwise_kernel_size默认 31groupshidden_size逐通道卷积SAME padding 需要核尺寸为奇数否则构造时直接抛ValueErrorBatchNorm1d → 激活默认 GELU→ 逐点卷积pointwise_conv2还原维度 →conformer_conv_dropoutFeed-Forward 2half-stepffn2_layer_norm→ffn2输出乘0.5加残差最后过final_layer_norm。因此一个 Conformer 块 两个各占一半权重的 FFN 多头自注意力 卷积模块这一组合使模型既能通过注意力捕获长距离全局依赖又能通过深度可分离卷积显式建模局部音频模式是它相对纯注意力架构 Wav2Vec2 的改进来源。整个 Encoder 由 Wav2Vec2ConformerEncoder 堆叠num_hidden_layers默认 12个这样的块并支持论文 LayerDrop训练中以layerdrop概率随机跳过整层。前端的特征提取仍与 Wav2Vec2 一致在 Encoder 之前原始波形先经过与 Wav2Vec2 相同的两段处理对应 Wav2Vec2ConformerModel 的组装顺序特征编码器Wav2Vec2ConformerFeatureEncoder由len(conv_dim)默认 7层 1D 卷积构成各层通道数conv_dim、步长conv_stride、核大小conv_kernel逐一对应源码在 配置校验 中强制要求三者长度一致否则报错。归一化方式由feat_extract_norm决定group只在第一层用 GroupNorm、其余层不加归一化layer则每层都用 LayerNorm。默认 7 层卷积累计步长为5×2×2×2×2×2×2 320与配置类提供的只读属性inputs_to_logits_ratio一致——即约每 320 个采样点输出一个时间步的特征特征投影Wav2Vec2ConformerFeatureProjectionLayerNorm 后经Linear(conv_dim[-1] → hidden_size)投影到模型隐藏维度同时返回未投影的norm_hidden_states供预训练量化使用。三种位置编码relative / rotary / 无官方文档明确指出Wav2Vec2-Conformer可以完全不使用相对位置嵌入也可以选用 Transformer-XL 风格的相对位置嵌入或旋转位置嵌入RoPE切换的唯一入口就是配置项config.position_embeddings_type取值relative、rotary或None。Encoder 层在 Wav2Vec2ConformerEncoder.init中根据该值实例化不同的位置嵌入模块relative默认对应 Wav2Vec2ConformerRelPositionalEmbedding采用 Transformer-XL 式、支持 shifting trick 的相对位置编码参考论文 Self-Attention with Relative Position Representations。自注意力模块为此额外引入linear_pos、可学习偏置pos_bias_u/pos_bias_v把注意力分数拆成内容项 位置项矩阵 ac 与 bd具体实现 中先投影位置向量、再用 padding reshape 完成 skew 移位索引最后以head_size ** -0.5缩放并加到 query 上。相关超参数是max_source_positions默认 5000定义最大源输入位置。rotary对应 Wav2Vec2ConformerRotaryPositionalEmbedding实现 RoPE参考论文 RoFormer。其inv_freq由rotary_embedding_base默认 10000与头维度计算并在运行时对长度为sequence_length的序列缓存 cos/sin 表自注意力的_apply_rotary_embedding会把 q/k 的前后半维旋转拼接后加权。Noneembed_positions NoneEncoder 只保留卷积位置嵌入pos_conv_embedWav2Vec2ConformerPositionalConvEmbedding核大小由num_conv_pos_embeddings128决定、分组数num_conv_pos_embedding_groups16不做任何 Transformer 级相对/旋转位置编码。三种模式在测试中均有覆盖见 tests/models/wav2vec2_conformer/test_modeling_wav2vec2_conformer.py 中的test_model_with_relative、test_model_with_rotary、test_model_with_no_rel_pos、test_model_float16_with_relative等用例。命名习惯上Hugging Face Hub 上的权重通过rel-pos、rope后缀标识位置编码类型例如集成测试使用的两个 CTC 微调检查点facebook/wav2vec2-conformer-rel-pos-large-960h-ft与facebook/wav2vec2-conformer-rope-large-960h-ft。另外编码器输出的注意力实现走统一的 ALL_ATTENTION_FUNCTIONS 分发接口默认 eager 实现eager_attention_forward不升到 fp32 计算 softmax、不使用 GQA以保持与原版 Conformer 数值等价模型类同时声明_supports_sdpa True与_supports_flex_attn True见 Wav2Vec2ConformerPreTrainedModel因此可切换 SDPA / FlexAttention 实现官方文档页的 SDPA 徽章即对应此能力。配置类与关键超参数详解Wav2Vec2ConformerConfig定义于 configuration_wav2vec2_conformer.py官方示例检查点为facebook/wav2vec2-conformer-rel-pos-large。它继承PreTrainedConfig其默认字段除wav2vec2家族共享的hidden_size768、num_hidden_layers12、num_attention_heads12、intermediate_size3072、hidden_actgelu、各类 dropout 默认0.1、initializer_range0.02等之外还包括以下 Wav2Vec2-Conformer 专属参数。特征编码器与位置编码参数默认值含义与影响feat_extract_normgroup特征卷积归一化方式可选group仅首层 GroupNorm或layer每层 LayerNorm其余值在编码器构造时抛错feat_extract_activationgelu特征卷积激活函数支持gelu/relu/selu/gelu_newconv_dim(512,)×77 层 1D 卷积的输出通道数元组长度即卷积层数conv_stride(5,2,2,2,2,2,2)各卷积层步长必须与conv_dim等长累乘结果即时间维度下采样倍率 320conv_kernel(10,3,3,3,3,2,2)各卷积层核大小必须与conv_dim等长conv_biasFalse特征卷积是否带偏置num_conv_pos_embeddings128卷积位置嵌入的核大小num_conv_pos_embedding_groups16卷积位置嵌入的分组数position_embeddings_typerelative三种位置编码选型relative/rotary/Nonerotary_embedding_base10000仅在rotary时生效的 RoPE 基频max_source_positions5000仅在relative时生效的最大源输入位置Conformer 块结构参数参数默认值含义与影响conv_depthwise_kernel_size31Conformer 卷积模块中深度可分离卷积的核大小必须为奇数SAME padding 约束违反则构造抛ValueErrorconformer_conv_dropout0.1Conformer 块内所有卷积层的 dropout 概率SpecAugment 与自监督掩码预训练相关当apply_spec_augmentTrue默认时模型在训练中对特征序列沿时间/特征轴做 SpecAugment 式随机掩码掩码算法位于 src/transformers/models/wav2vec2_conformer/modeling_wav2vec2_conformer.py#L951 的_compute_mask_indices其span 数 mask_prob * length / mask_length εε 用于概率取整并受min_masks约束的随机逻辑在 test_compute_mask_indices 一组用例中被逐项验证mask_time_prob0.05、mask_time_length10、mask_time_min_masks2时间轴掩码比例、掩码跨度长度、最少掩码段数mask_feature_prob0.0、mask_feature_length10、mask_feature_min_masks0特征轴掩码比例、跨度、最少段数若mask_time_prob 0或mask_feature_prob 0基座模型会创建一个可学习的masked_spec_embed参数用于替换被掩码的向量见 Wav2Vec2ConformerModel.init。注意mask_feature_prob只对特征编码后、进入 transformer 之前的中间表示生效因此通常只在预训练阶段开启微调时一般设apply_spec_augmentFalse或把时间/特征掩码概率置零。模型也提供了两个便捷冻结方法freeze_feature_encoder()关闭特征编码器梯度由Wav2Vec2ConformerModel及各任务头继承微调时默认应冻结特征提取层部分任务头分类类额外提供freeze_base_model()。量化与预训练Gumbel参数用于预训练分支Wav2Vec2ConformerForPreTraining的产品码本量化Gumbel softmax与对比损失由 Wav2Vec2ConformerGumbelVectorQuantizer 实现num_codevectors_per_group320、num_codevector_groups2每个码本组的条目数与组数乘积码本codevector_dim256、proj_codevector_dim256量化向量维度、量化与 transformer 特征共同投影的目标维度contrastive_logits_temperature0.1对比损失温度 κ、num_negatives100负样本数、diversity_loss_weight0.1码本多样性损失权重。下游任务头相关参数参数默认值所属任务ctc_loss_reductionsumCTC 损失的归约方式该字段在基座类中即存在ctc_zero_infinityFalse是否将torch.nn.CTCLoss的无穷损失/梯度置零输入过短无法对齐到目标时常见仅影响Wav2Vec2ConformerForCTC训练final_dropout0.1Wav2Vec2ConformerForCTC最终投影层前的 dropoutuse_weighted_layer_sumFalse序列分类时是否对各层输出做可学习加权求和classifier_proj_size256分类任务在 token 均值池化前的投影维度tdnn_dim/tdnn_kernel/tdnn_dilation(512,512,512,512,1500)/(5,3,3,1,1)/(1,2,3,1,1)X-Vector 中 TDNN 模块各层输出通道、核大小与膨胀系数三者长度必须一致xvector_output_dim512X-Vector 说话人嵌入向量维度add_adapterFalse是否在 Encoder 顶部叠加下采样卷积网络对 warm-start 语音 Encoder-Decoder 模型有用adapter_kernel_size/adapter_stride/num_adapter_layers3/2/3适配器卷积核、步长与层数仅add_adapterTrue时生效output_hidden_sizeNone缺省 hidden_size适配器输出维度仅add_adapterTrue时相关配置对象还会在__post_init__中自动计算num_feat_extract_layers len(conv_dim)、填充output_hidden_size并提供inputs_to_logits_ratio只读属性若conv_dim/conv_stride/conv_kernel长度不一致会立刻被validate_architecture拒绝。用脚本创建随机权重模型的最小示例与 配置类 docstring 一致from transformers import Wav2Vec2ConformerConfig, Wav2Vec2ConformerModel # 按 facebook/wav2vec2-conformer-rel-pos-large 风格初始化配置 configuration Wav2Vec2ConformerConfig() # 用该配置实例化一个随机权重模型 model Wav2Vec2ConformerModel(configuration) # 查看配置 print(model.config)模型家族基座模型与五个任务头官方文档页依次列出如下类对应src/transformers/models/wav2vec2_conformer/modeling_wav2vec2_conformer.py中各类的forward签名它们都共享Wav2Vec2ConformerPreTrainedModel基座base_model_prefix wav2vec2_conformer、main_input_name input_values即主输入是音频波形值而非 token。Wav2Vec2ConformerModel纯编码器基座输出last_hidden_state默认不返回各层 hidden_states/attentions用于特征提取或作为自定义头的底座。Wav2Vec2ConformerForPreTraining带 Gumbel 量化器与对比损失投影的预训练版本其输出对象为 Wav2Vec2ConformerForPreTrainingOutput包含loss、projected_states、projected_quantized_states、codevector_perplexity、codevector_probs等字段另提供set_gumbel_temperature()控制 Gumbel softmax 温度。Wav2Vec2ConformerForCTC在基座上接随机初始化的线性层输出 vocab 维 logits用于 ASR 的 CTC 训练/推理构造时还接受target_lang参数多语言模型可选目标语言。Wav2Vec2ConformerForSequenceClassification对 Encoder 各层输出做可学习加权use_weighted_layer_sum→classifier_proj_size投影 → token 均值池化 → 分类头用于整段音频的意图/情感等分类。Wav2Vec2ConformerForAudioFrameClassification输出每个时间帧的标签 logits用于音素分类、声音事件检测等帧级任务。Wav2Vec2ConformerForXVectorX-Vector 说话人识别/验证头由 TDNNLayer时间延迟神经网络堆叠 统计池化构成配合 AMSoftmaxLoss 训练输出xvector说话人嵌入维度xvector_output_dim代码中还提供_get_tdnn_output_lengths用于换算 TDNN 后序列长度。此外模型对可变长度输入的处理同样沿用 Wav2Vec2 方案Wav2Vec2ConformerPreTrainedModel._get_feat_extract_output_lengths按卷积核/步长公式逐层计算下采样后的序列长度若add_adapter则额外按adapter_stride缩短_get_feature_vector_attention_mask据此把 padding 位置正确反映到特征空间。在自定义适配器应用场景下模型还内置一个 Wav2Vec2ConformerAdapter叠加多层步长为adapter_stride的下采样卷积便于把 Wav2Vec2-Conformer 作为SpeechEncoderDecoder的编码器 warm-start。实测加载公开权重做语音识别推理官方 Usage tips 特别强调Wav2Vec2-Conformer 使用与 Wav2Vec2 完全相同的 tokenizer 和 feature extractor因此可以直接复用Wav2Vec2Processor/Wav2Vec2FeatureExtractor/Wav2Vec2Tokenizer无需任何新处理器。仓库的集成测试test_modeling_wav2vec2_conformer.py给出了可直接复现的用法加载facebook/wav2vec2-conformer-rel-pos-large-960h-ft相对位置编码版或facebook/wav2vec2-conformer-rope-large-960h-ftRoPE 版CTC 微调权重对两段 LibriSpeech 样本批量解码并逐条断言转写文本如a man said to the universe sir i exist。对应推理流程可概括为import torch from transformers import Wav2Vec2ForCTC, Wav2Vec2Processor # 相对位置编码的 Wav2Vec2-Conformer CTC 微调模型 model Wav2Vec2ForCTC.from_pretrained(facebook/wav2vec2-conformer-rel-pos-large-960h-ft) processor Wav2Vec2Processor.from_pretrained( facebook/wav2vec2-conformer-rel-pos-large-960h-ft, do_lower_caseTrue ) # audio_array: 单声道 16kHz 采样率波形numpy 数组此处略去加载步骤 inputs processor([audio_array], return_tensorspt, paddingTrue) with torch.no_grad(): logits model(inputs.input_values).logits predicted_ids torch.argmax(logits, dim-1) print(processor.batch_decode(predicted_ids))要点与注意事项通过from_pretrained加载权重时须确保position_embeddings_type与权重的实际训练配置一致rel-pos↔relativerope↔rotaryHub 上的配置文件已自动携带该字段一般无需手动干预Wav2Vec2ConformerForCTC默认的final_dropout为0.1、ctc_loss_reductionsum若输入过短导致 CTC 对齐出现无穷损失可在训练时开启ctc_zero_infinityTrue集成测试使用的输入为 16kHz 音频接入其他采样率时应先通过 feature extractor 的resampling能力重采样。微调与工程建议基于官方文档的 tips 与源码结构可整理出如下实践建议任务头与主干绝大多数下游任务应使用Wav2Vec2ConformerForCTC/ForSequenceClassification/ForAudioFrameClassification/ForXVector等现成任务头。训练前调用freeze_feature_encoder()冻结底层 7 层特征卷积这是 Wav2Vec2 家族的标准微调范式可以在 基座方法定义 中确认其实现为遍历参数置requires_gradFalse。正则与数据增强取舍预训练时保留apply_spec_augment相关掩码可提升鲁棒性微调阶段建议关闭 SpecAugment设apply_spec_augmentFalse并把mask_time_prob/mask_feature_prob归零以避免干扰有监督信号。位置编码选型默认relative与绝大多数官方 rel-pos 权重对齐追求与长序列/外推场景更友好、与 Flash/SDPA 生态集成更顺滑时可选rotary仅在需要与原版无相对位置模型对齐时才设None。注意力实现默认 eager 实现刻意不把 softmax 上浮到 fp32、不使用 GQA以与原版 Conformer 保持数值等价模型同时支持 SDPA 与 FlexAttention如需加速可在推理阶段切换_attn_implementation。编码器-解码器复用若把 Wav2Vec2-Conformer 当作SpeechEncoderDecoder编码器 warm-start可开启add_adapterTrueadapter_stride2、num_adapter_layers3此时输出的时间步会按适配器进一步压缩注意用output_hidden_size对齐解码器维度。权重迁移fairseq 官方权重可通过仓库提供的 convert_wav2vec2_conformer_original_pytorch_checkpoint_to_pytorch.py 转换后接入 transformers 生态。延伸阅读资源官方文档为该模型关联了两个任务指南可进一步阅读音频分类任务指南Wav2Vec2ConformerForSequenceClassification与ForAudioFrameClassification的完整微调流水线自动语音识别ASR任务指南基于Wav2Vec2ConformerForCTC的 CTC 微调、评估与解码细节。同族的 Wav2Vec2 模型文档 可作为 tokenizer / feature extractor 与预训练原理的对照参考Wav2Vec2-BERT 文档 则对应官方推荐的更新一代预训练模型所有模型类、配置与转换脚本的当前实现分别位于 src/transformers/models/wav2vec2_conformer/modeling_wav2vec2_conformer.py、configuration_wav2vec2_conformer.py 与 convert_wav2vec2_conformer_original_pytorch_checkpoint_to_pytorch.py模型级测试见 tests/models/wav2vec2_conformer/可作为自行扩展与验证的行为规范。【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考