Wav2Vec2 语音识别全流程实战：基于 Transformers 的微调、预训练与强制对齐指南

推理引擎大模型【免费下载链接】FlexGenRunning large language models on a single GPU for throughput-oriented scenarios.项目地址https://gitcode.com/gh_mirrors/fl/FlexGen点击查看免费下载导读本文围绕 Transformers 仓库中wav2vec2研究项目位于benchmark/third_party/transformers/examples/research_projects/wav2vec2/展开系统讲解如何使用run_asr.py对预训练 Wav2Vec2 模型做语音识别ASR微调、使用run_pretrain.py从零预训练、借助 DeepSpeed ZeRO 优化器并行扩展以及利用alignment.py完成字符级强制对齐。读完本文你将掌握从数据清洗Orthography 正字法、参数调优到多 GPU 分布式训练与推理对齐的完整技能链。注意原 README 明确标注本示例已过时且不再积极维护新版微调指引已迁移至examples/pytorch/speech-recognition/目录。本文基于当前仓库快照中的代码与配置讲解若用于生产环境请以仓库中实际存在的脚本与配置为准。一、项目结构总览当前wav2vec2研究项目目录包含以下核心文件文件作用run_asr.pyASR 微调主脚本基于Trainer支持 CTC 损失与 WER 评估run_pretrain.pyWav2Vec2 从零预训练脚本对比学习目标run_common_voice.py面向 Common Voice 数据集的微调入口alignment.py字符级强制对齐工具配合run_alignment.shds_config_wav2vec2_zero2.json/ds_config_wav2vec2_zero3.jsonDeepSpeed ZeRO-2 / ZeRO-3 配置vocab/buckwalter.json阿拉伯语 Buckwalter 转写词表finetune_*.sh多个数据集/模型的现成微调脚本test_wav2vec2_deepspeed.pyDeepSpeed 集成冒烟测试二、使用run_asr.py微调 Wav2Vec2run_asr.py允许用户基于 Hugging Face 上任意facebook/wav2vec2*系列预训练模型进行微调。脚本通过HfArgumentParser同时解析三组参数见 run_asr.pyModelArguments模型路径、是否冻结特征提取器、是否开启详细日志DataTrainingArguments数据集名称、划分、列名、重采样、时长过滤、正字法方案TrainingArgumentsTransformers 标准训练参数学习率、批次、步数、混合精度等。微调流程在main()中依次完成构建Orthography→ 创建Wav2Vec2Processor→ 加载Wav2Vec2ForCTC→ 加载并预处理数据集 → 构造DataCollatorCTCWithPadding→ 初始化CTCTrainer→ 训练。2.1 案例一用 TIMIT 微调 wav2vec2-basefinetune_base_timit_asr.sh展示了以 TIMIT 语音库微调wav2vec2-base的完整命令完整脚本见 finetune_base_timit_asr.sh#!/usr/bin/env bash python run_asr.py \ --output_dir./wav2vec2-base-timit-asr \ --num_train_epochs30 \ --per_device_train_batch_size20 \ --per_device_eval_batch_size20 \ --evaluation_strategysteps \ --save_steps500 \ --eval_steps100 \ --logging_steps50 \ --learning_rate5e-4 \ --warmup_steps3000 \ --model_name_or_pathfacebook/wav2vec2-base \ --fp16 \ --dataset_nametimit_asr \ --train_split_nametrain \ --validation_split_nametest \ --orthographytimit \ --preprocessing_num_workers$(nproc) \ --group_by_length \ --freeze_feature_extractor \ --verbose_logging \关键参数解读--num_train_epochs30训练 30 个 epochTIMIT 语料规模小需要较多轮次--evaluation_strategysteps按步数触发评估与--eval_steps100配合每 100 步在验证集上算一次 WER--learning_rate5e-4--warmup_steps3000配合预热warmup的较高学习率是 Wav2Vec2 微调的常用组合--fp16开启混合精度训练节省显存并加速--group_by_length按音频时长分组减少 batch 内填充浪费--freeze_feature_extractor冻结 CNN 特征提取器只训练 Transformer 编码器与分类头显著降低显存占用对应ModelArguments.freeze_feature_extractor默认即为True--preprocessing_num_workers$(nproc)用满本机 CPU 核心并行预处理--verbose_logging开启 DEBUG 级别日志预处理阶段会逐条打印文本更新评估时打印参考与预测文本。2.2 案例二用 Arabic Speech Corpus 微调 wav2vec2-large-xlsr-53阿拉伯语数据集的预处理远比英语复杂完整脚本见 finetune_large_xlsr_53_arabic_speech_corpus.sh#!/usr/bin/env bash python run_asr.py \ --output_dir./wav2vec2-large-xlsr-53-arabic-speech-corpus \ --num_train_epochs50 \ --per_device_train_batch_size1 \ --per_device_eval_batch_size1 \ --gradient_accumulation_steps8 \ --evaluation_strategysteps \ --save_steps500 \ --eval_steps100 \ --logging_steps50 \ --learning_rate5e-4 \ --warmup_steps3000 \ --model_name_or_pathelgeish/wav2vec2-large-xlsr-53-arabic \ --fp16 \ --dataset_namearabic_speech_corpus \ --train_split_nametrain \ --validation_split_nametest \ --max_duration_in_seconds15 \ --orthographybuckwalter \ --preprocessing_num_workers$(nproc) \ --group_by_length \ --freeze_feature_extractor \ --target_feature_extractor_sampling_rate \ --verbose_logging \三个值得注意的点--per_device_train_batch_size1--gradient_accumulation_steps8xlsr-53 模型参数量大单卡装不下大 batch因此采用小 batch 加梯度累积模拟大 batch 效果--target_feature_extractor_sampling_rate将音频重采样到特征提取器目标采样率 16kHz对应源码中target_sr processor.feature_extractor.sampling_rate由librosa.load(..., srtarget_sr)实现--max_duration_in_seconds15过滤时长超过 15 秒的样本用于控制 GPU 显存峰值。源码中该过滤通过datasets的filter实现过滤前后会打印样本数量变化见 run_asr.py 中filter_by_max_duration相关逻辑。三、Orthography 正字法数据清洗的灵魂阿拉伯语数据集采用Buckwalter 转写Buckwalter transliteration表示文本只包含 ASCII 字符部分非字母符号映射到阿拉伯字母如映射为أ。原始转写文本无法直接作为 CTC 标签因此脚本引入Orthography类统一处理。Orthography定义于 run_asr.pyOrthographydataclass核心字段包括字段默认值含义do_lower_caseFalse是否忽略大小写解码时输出小写vocab_fileNone自定义词表文件路径word_delimiter_token\|词分隔 token必须存在于词表中translation_table{}用于str.translate()的字符替换表words_to_removeset()预处理时需要移除的词如静音标记untransliteratorNone将转写文本还原为原生书写系统的函数Orthography.from_name()支持三种预设librispeech默认空配置、timit、buckwalter未知名称会抛出ValueError。3.1 TIMIT 正字法Orthography( do_lower_caseTrue, # break compounds like quarter-century-old and replace pauses -- translation_tablestr.maketrans({-: }), )其作用链条与源码preprocess_for_training一一对应构建do_lower_caseTrue的 tokenizer输入忽略大小写解码输出转小写将-替换为空格拆解quarter-century-old这类复合词并清理悬挂连字符与停顿符号压缩连续空白为单个空格移除词表中不存在的字符源码用正则vocabulary_text_cleaner实现允许空格及词表中的单字符。3.2 Buckwalter 正字法阿拉伯语Orthography( vocab_filepathlib.Path(__file__).parent.joinpath(vocab/buckwalter.json), word_delimiter_token/, # | is Arabic letter alef with madda above words_to_remove{sil}, # fixing sil in arabic_speech_corpus dataset untransliteratorarabic.buckwalter.untransliterate, translation_tablestr.maketrans(translation_table { -: , # sometimes used to represent pauses ^: v, # fixing tha in arabic_speech_corpus dataset }), )要点说明词表来自 vocab/buckwalter.json内含pad、s、/s、unk等特殊 token 以及按音素/字母组织的 Buckwalter 字符word_delimiter_token/不能用|因为|在阿拉伯语中是带 Madda 上标的 alef 字母会与词分隔语义冲突words_to_remove{sil}修正arabic_speech_corpus数据集中表示静音的sil标记translation_table中^→v修正数据集里tha的书写untransliteratorarabic.buckwalter.untransliterate来自lang-trans包用于在日志中把 Buckwalter 还原为阿拉伯文abjad便于人工核对。3.3 预处理在源码中的执行顺序prepare_examplerun_asr.py中的顺序不可颠倒先orthography.preprocess_for_training()做替换与去词再用vocabulary_text_cleaner正则剔除不在词表中的字符若文本发生更新会记录(原文, 更新后)对在 DEBUG 日志下逐条输出便于排查数据问题。四、DeepSpeed 集成多 GPU 与大规模预训练微调大模型时可将Trainer与 DeepSpeed 结合。原文档指向官方 DeepSpeed-Trainer 集成指南快速上手只需两步安装pip install deepspeed然后使用本目录自带的两个配置ds_config_wav2vec2_zero2.jsonZeRO-2优化器状态分片 CPU offloadds_config_wav2vec2_zero3.jsonZeRO-3在 ZeRO-2 基础上进一步分片模型参数offload_param也放到 CPU显存上限更低。两个配置均以auto方式继承TrainingArguments中的学习率、batch size、梯度累积等设定optimizer、scheduler、train_batch_size等字段均为auto避免重复配置。4.1 ZeRO-2 微调示例PYTHONPATH../../../src deepspeed --num_gpus 2 \ run_asr.py \ --output_diroutput_dir --num_train_epochs2 --per_device_train_batch_size2 \ --per_device_eval_batch_size2 --evaluation_strategysteps --save_steps500 --eval_steps100 \ --logging_steps5 --learning_rate5e-4 --warmup_steps3000 \ --model_name_or_pathpatrickvonplaten/wav2vec2_tiny_random_robust \ --dataset_namehf-internal-testing/librispeech_asr_dummy --dataset_config_nameclean \ --train_split_namevalidation --validation_split_namevalidation --orthographytimit \ --preprocessing_num_workers1 --group_by_length --freeze_feature_extractor --verbose_logging \ --deepspeed ds_config_wav2vec2_zero2.json请根据实际 GPU 数量修改--num_gpus。示例选用的是微型随机权重模型与小规模 dummy 数据集仅用于验证链路。多 GPU ZeRO-2 必配项find_unused_parameters: true已包含在示例配置的zero_optimization块中。Wav2Vec2 的 CTC 头可能产生未使用参数DeepSpeed 默认会因参数未使用而报错必须显式开启该项。4.2 ZeRO-3 微调示例PYTHONPATH../../../src deepspeed --num_gpus 2 \ run_asr.py \ --output_diroutput_dir --num_train_epochs2 --per_device_train_batch_size2 \ --per_device_eval_batch_size2 --evaluation_strategysteps --save_steps500 --eval_steps100 \ --logging_steps5 --learning_rate5e-4 --warmup_steps3000 \ --model_name_or_pathpatrickvonplaten/wav2vec2_tiny_random_robust \ --dataset_namehf-internal-testing/librispeech_asr_dummy --dataset_config_nameclean \ --train_split_namevalidation --validation_split_namevalidation --orthographytimit \ --preprocessing_num_workers1 --group_by_length --freeze_feature_extractor --verbose_logging \ --deepspeed ds_config_wav2vec2_zero3.jsonZeRO-3 配置的zero_optimization额外包含offload_param参数 offload 到 CPU、stage3_gather_16bit_weights_on_model_save保存模型时聚合 fp16 权重以及stage3_prefetch_bucket_size、stage3_max_live_parameters等微调项。PYTHONPATH../../../src的作用是让脚本 import 到本仓库内嵌的transformers源码相对目录benchmark/third_party/transformers/src。4.3 其他微调脚本中的 DeepSpeed 用法仓库还提供了面向 Common Voice 的 finetune_wav2vec2_xlsr_turkish.sh使用run_common_voice.py微调土耳其语其中--layerdrop0.1、--feat_proj_dropout0.0、--gradient_checkpointing都是控制正则化与显存的关键参数可作为超参调优参考。五、Pretraining从零预训练 Wav2Vec2run_pretrain.py允许从零预训练 Wav2Vec2训练目标为论文中提出的对比损失contrastive loss。官方建议在预训练阶段同样使用 Trainer DeepSpeed示例为 ZeRO-2 四卡预训练小模型完整脚本见 run_pretrain.pyPYTHONPATH../../../src deepspeed --num_gpus 4 run_pretrain.py \ --output_dir./wav2vec2-base-libri-100h \ --num_train_epochs3 \ --per_device_train_batch_size32 \ --per_device_eval_batch_size32 \ --gradient_accumulation_steps2 \ --save_total_limit3 \ --save_steps500 \ --logging_steps10 \ --learning_rate5e-4 \ --weight_decay0.01 \ --warmup_steps3000 \ --model_name_or_pathpatrickvonplaten/wav2vec2-base-libri-100h \ --dataset_namelibrispeech_asr \ --dataset_config_nameclean \ --train_split_nametrain.100 \ --preprocessing_num_workers4 \ --max_duration_in_seconds10.0 \ --group_by_length \ --verbose_logging \ --fp16 \ --deepspeed ds_config_wav2vec2_zero2.json \与微调脚本不同预训练脚本的ModelArguments增加了 Gumbel softmax 温度控制参数max_gumbel_temperature2.0、min_gumbel_temperature0.5、gumbel_temperature_decay0.999995。这是因为 Wav2Vec2 预训练采用量化模块quantization其中量化码本的选择通过 Gumbel softmax 实现温度随训练衰减以逐步从探索转向利用模型侧加载的是Wav2Vec2ForPreTraining。六、Forced Alignment字符级强制对齐完成 ASR 微调后alignment.py可对指定语言的音频-文本对做字符级强制对齐思路源自 PyTorch 官方的 torchaudio 对齐教程。运行入口为 run_alignment.sh 对应的alignment.py。6.1 输入格式在wavs目录中放置音频并提供一个script.txt二者通过前缀 ID 关联输入格式script.txt 输入格式wavs 目录 0000 sentence1 0000.wav 0001 sentence2 0001.wav6.2 输出格式输出目录中为每个样本生成同名.txt每行一个字符的时间定位char score start_ms end_ms h 0.25 1440 15206.3 运行命令python alignment.py \ --model_namearijitx/wav2vec2-xls-r-300m-bengali \ --wav_dir./wavs --text_filescript.txt \ --input_wavs_sr48000 \ --output_dir./out_alignment \ --cuda对齐原理对应 alignment.py 源码Wav2Vec2Aligner加载 CTC 模型与AutoProcessor将输入采样率重采样到 16kHztorchaudio.transforms.Resample(input_wavs_sr, 16_000)并识别 blank token[PAD]或pad前向得到帧级 logits 后取log_softmax得到发射概率emission构建trellis 网格形状(帧数1, token数1)用动态规划回溯最优路径将路径映射回时间戳输出每个字符的分数与起止毫秒。七、从源码看训练关键机制7.1 CTC 动态填充DataCollatorCTCWithPadding音频与标签长度不同不能统一 padding。DataCollatorCTCWithPadding将输入与标签分开处理input_values按最长序列填充labels单独填充后将填充位置替换为-100从而在 CTC 损失中自动忽略这些位置见 run_asr.py 中masked_fill逻辑。7.2 CTCTrainer 的多 GPU 损失处理CTCTrainer重写了training_step在多 GPU 时依据模型配置的ctc_loss_reduction决定损失聚合方式mean取平均、sum则除以有效标签数同时兼容混合精度原生 AMP / Apex与 DeepSpeed 三种反向传播路径。7.3 评估指标compute_metrics对预测 logits 取argmax得到 token id 序列解码为文本后与参考文本计算WER词错误率当存在untransliterator时DEBUG 日志还会同时输出还原为阿拉伯文等原生文字的参考与预测方便非转写格式读者核对。八、常见问题与注意事项示例已过时本目录 README 声明该示例不再积极维护新用户应优先参考examples/pytorch/speech-recognition/下的新指引多 GPU 报参数未使用错误ZeRO-2 多卡下务必保留find_unused_parameters: true阿拉伯语词分隔符冲突切勿把word_delimiter_token设为|它在 Buckwalter 词表中对应真实字母音频采样率不一致数据集预处理会断言 batch 内采样率一致assert len(set(batch[sampling_rate])) 1务必配合--target_feature_extractor_sampling_rate重采样显存不足优先组合使用--max_duration_in_seconds、--gradient_accumulation_steps、--freeze_feature_extractor与--gradient_checkpointing依赖requirements.txt中包含了librosa、lang-trans、torchaudio等关键依赖运行前请确认已安装。九、延伸阅读微调相关更多脚本finetune_base_100.sh、finetune_large_lv60_100.sh、finetune_large_lv60_timit_asr.shDeepSpeed 配置详解ds_config_wav2vec2_zero2.json、ds_config_wav2vec2_zero3.json冒烟测试test_wav2vec2_deepspeed.py本项目所处的完整 Transformers 示例树examples赞分享推理引擎大模型【免费下载链接】FlexGenRunning large language models on a single GPU for throughput-oriented scenarios.项目地址https://gitcode.com/gh_mirrors/fl/FlexGen点击查看免费下载相关推荐opencode-anthropic-auth请求调试指南如何观察被拦截改写的fetchopencode anthropic auth请求调试指南如何观察被拦截改写的fetch opencode anthropic auth 是一个 openco如何在 Windows 上 3 分钟装好 RedisInsightRedis 可视化工具安装与使用完整指南如何在 Windows 上 3 分钟装好 RedisInsightRedis 可视化工具安装与使用完整指南 RedisInsight 是 Redis 官方出品数据库客户端桌面应用后端前端数据可视化Shortcircuit XT音频线程零内存分配如何实现实时安全设计全解析Shortcircuit XT音频线程零内存分配如何实现实时安全设计全解析 Shortcircuit XT 是一款开源的专业级创意采样器Sampler由上一篇【亲测免费】 MassTransit 开源项目教程下一篇三步搞定微信聊天记录永久保存WeChatMsg免费工具终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考