ESPnet2 hubert1 配方全解析：基于 K-means 伪标签的 HuBERT 自监督预训练流水线

人工智能语音音频深度学习NLP【免费下载链接】espnetEnd-to-End Speech Processing Toolkit项目地址https://gitcode.com/gh_mirrors/es/espnet点击查看免费下载本篇技术指南围绕 ESPnet2 的hubert1配方以 egs2/TEMPLATE/hubert1/README.md 为骨架结合 hubert.sh 与 LibriSpeech 实例展开完整讲解从原始语料下载、K-means 伪标签生成、迭代式掩码预测预训练到模型打包、HuggingFace 发布与 SUPERB 下游评测的端到端流程。读完本文你将掌握 hubert1 配方的全部 9 个阶段与核心参数语义、迭代机制的运作方式、DiceHuBERT 蒸馏用法以及它与 ssl1 配方的定位差异。配方概述hubert1 是什么hubert1是 ESPnet2 中专门为 HuBERT 风格自监督学习SSL设计的配方模板位于 egs2/TEMPLATE/hubert1。HuBERTHidden-Unit BERT的核心思想是先用聚类如 K-means把连续语音特征离散化为隐藏单元hidden units再把离散序列当作伪标签用 BERT 式的掩码预测目标训练 Transformer 编码器。由于预训练过程中没有任何人工标注参与它属于自监督表征学习范畴。在 ESPnet2 中hubert1配方负责把上述整个离线流程工程化包括数据准备下载、Kaldi 风格目录组织语音扰动与音频格式化K-means 伪标签生成与质量评估迭代式 HuBERT 预训练模型打包与上传发布。该配方直接复用仓库中 espnet2/bin/hubert_train 训练入口并调用 scripts/feats/perform_kmeans.sh 完成特征抽取、聚类与打标。模板本身不绑定具体语料实际使用时需在egs2/语料/hubert1/下提供local/data.sh并配置运行参数仓库内现成的完整示例是 egs2/librispeech/hubert1LibriSpeech 960 小时。Recipe flow九个阶段的整体脉络hubert1配方的主控脚本是 egs2/TEMPLATE/hubert1/hubert.sh它通过--stage/--stop_stage控制执行范围整个流程分为 9 个阶段阶段名称功能关键参数1数据下载与预处理调用local/data.sh下载原始语料并整理成 Kaldi 风格data/目录local_data_opts2语速扰动按因子生成变速音频并合并增强数据多样性speed_perturb_factors3音频格式化重采样、切段、格式转换产出dump/raw/下的 wav.scpfeats_type、audio_format、fs4时长过滤剔除过短/过长音频min_wav_duration、max_wav_duration5伪标签生成特征抽取 → K-means 聚类 → 伪标签 → 质量评估 → 词典features_km、layers_km、n_clusters、portion_km等6统计量收集收集训练/验证集 input/output shapefeats_normalize7HuBERT 训练迭代式掩码预测预训练train_configs、train_start_iter、train_stop_iter8模型打包打包模型文件便于分发inference_ssl_model9上传 HuggingFace发布模型到 HF Hubhf_repo其中阶段 5~7 是迭代执行的hubert.sh中for ((iter${train_start_iter}; iter${train_stop_iter}; iter))循环逐迭代运行伪标签生成、统计收集与训练。以 LibriSpeech 的 run.sh 为例默认train_start_iter0、train_stop_iter1base 模型 1 次迭代足够注释明确说明但配置中为迭代 2 预留了参数见下文“迭代机制”一节。Stage 1数据下载与预处理本阶段调用local/data.sh ${local_data_opts}见 hubert.sh负责下载原始语料不同语料通过egs2/语料/hubert1/local/data.sh实现如 LibriSpeech 的 local/data.sh将语料组织为 Kaldi 风格的 data 目录即data/${train_set}、data/${valid_set}等目录内含wav.scp、utt2spk、text、utt2num_samples等元数据文件。由于hubert.sh强校验--train_set与--valid_set两个必填参数缺失直接报错退出模板中train_set、valid_set的默认值为空需要用户按语料实际划分显式指定例如 LibriSpeech 中--train_set train_960 --valid_set dev。Stage 2语速扰动若设置了speed_perturb_factors空格分隔的多个因子如0.9 1.0 1.1本阶段会对训练集做时间拉伸/压缩生成data/${train_set}_sp${factor}目录再通过utils/combine_data.sh合并为data/${train_set}_sp以提升数据多样性。源码细节hubert.sh对每个因子调用 scripts/utils/perturb_data_dir_speed.sh因子为 1.0 时直接复用原始data/${train_set}不额外生成副本若设置了扰动因子后续阶段使用的train_set会自动切换为data/${train_set}_sp脚本内train_set${train_set}_sp即扰动后的数据会贯穿后续特征、伪标签与训练全流程。Stage 3音频格式化hubert1配方只支持--feats_type rawhubert.sh中其他取值会直接报错退出。本阶段对每个数据集调用 scripts/audio/format_wav_scp.sh将 Kaldi 风格、可能带有 unix-pipe如cat /some/path |的 wav.scp 转成真实音频文件并可同时完成重采样、切段与格式转换结果写入dump/raw/。关键点--audio_format支持wav、flac、wav.ark、flac.arkark 表示 Kaldi 归档格式源码中训练/统计阶段会据此选择kaldi_ark还是sound的输入类型--fs默认16k决定重采样目标采样率若data/${dset}/segments存在则按segment_id record_id start_time end_time的格式把长音频切成句级片段处理完成后写feats_type标记文件内容为raw。Stage 4时长过滤本阶段基于--min_wav_duration默认 0.1 秒与--max_wav_duration默认 20 秒剔除过短/过长语句。实现上hubert.sh先把dump/raw/org/${dset}复制为dump/raw/${dset}保留原始副本用humanfriendly解析fs将秒数换算成采样点数再用 awk 按utt2num_samples过滤同时过滤掉只有 utt-id 的空文本行NF ! 1最后utils/fix_data_dir.sh只保留所有文件中同时存在的语句。注意此过滤只作用于训练集与验证集测试集保持原样以保留完整评测数据。Stage 5伪标签生成迭代核心HuBERT 训练是迭代式的阶段 5~7 每轮迭代都要重新生成伪标签。本阶段统一调用 scripts/feats/perform_kmeans.sh内部又细分为 5 个子步骤由hubert.sh按当前迭代将n_clusters、feature_type、layer、datadir、featdirdump/hubert_feats、km_direxp/下、dictdir等参数传入。5.1 特征抽取Feature Dumping抽取用于聚类的特征特征类型可以是 MFCC也可以是上一轮迭代训练出的 HuBERT 模型的中间层表征。用--features_km指定特征类型、--layers_km指定抽取层两者均为空格分隔的多值参数与迭代一一对应。默认 HuBERT 设置见 egs2/librispeech/hubert1/run.sh第 0 轮迭代用 MFCC无层概念layer0第 1 轮迭代用第 0 轮 HuBERT 模型的 transformer 第 6 层特征espnet_hubertlayer6第 2 轮迭代用第 1 轮模型的第 9 层特征espnet_hubertlayer9。对应参数写法为--features_km mfcc espnet_hubert espnet_hubert --layers_km 0 6 9抽取结果保存到dump/hubert_feats/。从 perform_kmeans.sh 源码看特征类型支持mfcc、espnet_hubert、fairseq_hubert后者可加载 legacy Fairseq 发布的 HuBERT checkpoint通过hubert_url/hubert_dir_path指定。实际抽取由pyscripts/feats/dump_ssl_feature.py完成--use_gpu默认 false可切换到 GPU 抽取hubert.sh会提示“推荐在 HuBERT 特征抽取时使用 GPU”。5.2 训练 K-means 聚类在抽取的特征上训练 K-means 模型。用--n_clusters设置簇数同样空格分隔、与迭代对应如--n_clusters 100 500 500用--portion_km控制训练聚类的数据比例LibriSpeech 默认 0.1即取训练集 10% 的语句用于聚类降低计算量。源码细节聚类基于 scikit-learn由pyscripts/utils/learn_kmeans.py执行perform_kmeans.sh通过--num_threads默认 20控制 CPU 线程--RVQ_layers默认 1支持多级残差矢量量化RVQ。注释提示该步骤典型内存需求较高约 120GB RAM。训练好的模型保存为exp/kmeans_iter${iter}_${feats_km}_${train_set}_portion${portion_km}/km_${nclusters}.mdl。5.3 生成 K-means 伪标签用训练好的 K-means 模型为每个特征向量分配簇 ID作为帧级伪标签由pyscripts/feats/dump_km_label.py完成。伪标签文件格式为utt_id 12 15 ...其中utt_id后每个数字代表一帧所属的簇 ID。这些伪标签随后会被写回数据目录命名为text.km.${km_tag}km_tag类似kmeans_iter0_mfcc_train_960_portion0.1与 wav.scp 一起作为后续训练的监督信号。5.4 评估伪标签质量若语料带有音素标注可用--alignment_phoneme_dir指向音素对齐目录tsv 文件格式utt_id a1,a2,a3,...评估伪标签与音素的对应质量。默认目录为data/mfa_phoneme_alignment当该选项未给出且默认目录不存在时本步骤自动跳过perform_kmeans.sh 中的日志会明确提示跳过原因。LibriSpeech 配方通过 run.sh 传入--alignment_phoneme_dir ./data/librispeech_phoneme_alignment评估脚本为local/measure_teacher_quality.py输出写入km_dir/phoneme_pseudo_label_quality.txt。5.5 准备训练词典按频次排序簇 ID生成训练用词典data/${lang}_token_list_kmeans_iter${iter}_${feats_km}_${nclusters}clusters/${token_type}/tokens.txt。从源码看perform_kmeans.sh词典按“token 频次”统计后按频次降序排列并追加unkOOV 符号与sos/eos特殊符号blank、pad同样被定义。Stage 6收集 HuBERT 统计量本阶段收集训练所需统计量在训练集与验证集上分别收集语音speech与文本text的 shape 文件供后续按batch_type如 numel/folded动态组 batch 使用。实现上通过python -m espnet2.bin.hubert_train --collect_stats true并行执行nj个任务再以espnet2.bin.aggregate_stats_dirs聚合。关键点均值/方差统计仅在--feats_normalize global_mvn时才计算默认路径下聚合命令会带--skip_sum_stats不生成 CMVN 统计。此外脚本还会把文本长度按词典大小拼接成text_shape.${token_type}追加 num-tokens 维度用于 batch-bins 计数。Stage 7训练 HuBERT本阶段用掩码预测目标训练 HuBERT 编码器。训练设置通过--train_configs指定 YAML 配置支持空格分隔的多个配置文件、每个迭代一个。LibriSpeech 示例--train_configs conf/tuning/train_ssl_torchaudiohubert_base_960h_pretrain_it0.yaml conf/tuning/train_ssl_torchaudiohubert_base_960h_pretrain_it1.yaml conf/tuning/train_ssl_torchaudiohubert_large_960h_pretrain_it2.yaml训练命令为python -m espnet2.bin.hubert_train经由espnet2.bin.launch分发到多 GPU/多节点并自动带上--num_classes ${n_clusters}、--token_list、--fold_lengthspeech_fold_length默认 800、text_fold_length默认 400等参数。输入特征类型取决于迭代mfcc或上一轮 HuBERT 模型输出_type为sound或kaldi_ark。以 base 模型第 0 轮配置 train_ssl_torchaudiohubert_base_960h_pretrain_it0.yaml 为例核心训练要素包括编码器为torchaudio_hubert模型为torchaudio复用 torchaudio 的 HuBERT 实现优化器 Adamlr0.0005 warmup lr 调度warmup_steps32000batch_type: numel、batch_bins: 48000000、accum_grad: 2collate_fn_conf中label_downsampling: 2第 0 轮标签每 2 帧一采样、rand_crop: True开启use_amp: true混合精度max_epoch: 250keep_nbest_models: 10该配置注释表明在 8×A100(40GB) 上约需 5 天。第 1 轮配置 train_ssl_torchaudiohubert_base_960h_pretrain_it1.yaml 与第 0 轮基本一致仅label_downsampling改为 1不再降采样。训练结果保存在exp/hubert_iter${iter}_${ssl_tag}/默认最优模型文件名为valid.loss.best.pth由inference_ssl_model指定。Stage 8模型打包本阶段调用python -m espnet2.bin.pack ssl将训练好的模型打成一个 zip 包默认skip_packingtrue需要显式关闭跳过打包内容包括SSL 训练配置config.yaml与模型权重valid.loss.best.pth训练过程图片exp/${ssl_exp}/images最后一轮迭代的 K-means 模型km_${n_clusters}.mdl若使用global_mvn还会附带feats_stats.npz。输出路径形如exp/hubert_iter1_tag/tag_valid.loss.best.zip可直接用于推理或上传发布。Stage 9上传 HuggingFace本阶段把打包模型上传到 HuggingFace Hub默认skip_upload_hftrue。使用时需设置--hf_repo 用户名/仓库名脚本会检查 git-lfs 是否安装git clone目标 HF 仓库解压 zip 包到仓库目录基于 scripts/utils/TEMPLATE_HF_Readme.md 模板生成 README填充hf_taskself-supervised-learning、espnet_taskSSL等字段git add / commit / push完成发布。LibriSpeech 的官方预训练模型即通过此流程发布在 HuggingFace如迭代 0、迭代 1 的 base 模型其微调表现记录在 egs2/librispeech/hubert1/README.md在 LibriLight-Limited 10h 微调设置下迭代 0 模型在 dev-clean 上 WER 15.5%、迭代 1 模型降至 10.4%体现了迭代式伪标签质量提升带来的收益。迭代机制与多值参数详解hubert1配方的核心工程技巧是“多值参数 迭代下标”train_configs、n_clusters、features_km、layers_km都是空格分隔的多值列表hubert.sh启动时会将它们拆分为数组并在进入训练循环前做严格校验hubert.sh每个列表长度必须大于train_stop_iter下标从 0 开始否则报错“# xxx is less than train_stop_iter”必须满足train_start_iter train_stop_iter。循环体内按iter取值feats_km${feature_list[iter]}、layer${layer_list[iter]}、n_clusters${n_clusters_list[iter]}、ssl_config${train_config_list[iter]}从而同一套脚本驱动多次迭代。此外hubert.sh还支持--download_model从 Model Zoo 下载已有预训练模型并解包到exp/${download_model}/用于“跳过本轮训练直接生成下一轮伪标签”的场景这也是 DiceHuBERT 蒸馏流程能省去从头训练的关键。各迭代目录命名规则如下统计目录exp/hubert_iter${iter}_stats_${feats_type}实验目录exp/hubert_iter${iter}_${ssl_tag}其中ssl_tag取配置文件名去 .yaml_raw词典目录data/${lang}_token_list_kmeans_iter${iter}_${feats_km}_${nclusters}clusters/${token_type}K-means 模型目录exp/kmeans_iter${iter}_${feats_km}_${train_set}_portion${portion_km}。DistillationDiceHuBERT 蒸馏hubert1配方原生支持 DiceHuBERT 蒸馏——一种将教师模型知识迁移到更小学生的蒸馏方法。与常规回归损失不同DiceHuBERT 直接复用标准 HuBERT 交叉熵损失做蒸馏因此几乎不用改动配方即可训练只需注意配置文件的替换。完整流程如下1. 标准数据准备前 4 个阶段./run.sh --stage 1 --stop-stage 42. 复用已有教师模型生成伪标签学生模型按 HuBERT 迭代 2 的流程训练但不必从头训练教师直接从 Model Zoo 下载迭代 1 的预训练模型./run.sh --stage 5 --stop-stage 5 --train_start_iter 2 --train_stop_iter 2 --download_model simpleoier/simpleoier_librispeech_hubert_iter1_train_ssl_torchaudiohubert_base_960h_pretrain_it1_raw--train_start_iter 2 --train_stop_iter 2保证只执行迭代 2。3. 用蒸馏配置训练学生模型./run.sh --stage 6 --stop-stage 7 --train_start_iter 2 --train_stop_iter 2 \ --train_configs conf/tuning/train_ssl_torchaudiohubert_base_960h_pretrain_it0.yaml \ conf/tuning/train_ssl_torchaudiohubert_base_960h_pretrain_it1.yaml \ conf/tuning/train_ssl_torchaudiohubert_distill_960h_pretrain_it2.yaml这里--train_configs必须显式给出run.sh硬编码了标准迭代 2 配置若不覆盖学生会错误地使用train_ssl_torchaudiohubert_large_960h_pretrain_it2.yaml而不是蒸馏配置。同时列表需要为到--train_stop_iter为止的每个迭代各提供一个条目因此虽然只用到最后一个也要全部给出。默认蒸馏配置位于 egs2/librispeech/hubert1/conf/tuning/train_ssl_torchaudiohubert_distill_960h_pretrain_it2.yaml。对比蒸馏配置与基础/大模型配置可发现关键差异蒸馏配置显式use_amp: false而迭代 1 基础配置为use_amp: true。注释说明这是有意为之该蒸馏设置下开启 AMP 会造成训练不稳定学生模型架构更小encoder_embed_dim: 384、encoder_num_layers: 12、encoder_num_heads: 6、encoder_ff_interm_features: 1536、final_dim: 128对比大模型配置 train_ssl_torchaudiohubert_large_960h_pretrain_it2.yamlencoder_embed_dim: 1024、24 层、16 头、final_dim: 768学生参数量大幅缩减同时保留grad_clip: 5.0、batch_type: numel、warmup 32000 步等一致的训练超参。Evaluation与 SUPERB/s3prl 集成hubert1配方本身不内置评测阶段但训练出的 HuBERT 模型与 SUPERB 基准完全兼容可通过 s3prl 工具包进行下游任务评测。s3prl 原生支持 HuBERT 模型只需把上游模型指定为espnet_hubert_local即可用 ESPnet 训练的 checkpoint 提取特征、训练下游模型cd s3prl/s3prl python run_downstream.py \ -m train \ -n ${TASK}_espnet_hubert \ -d $TASK \ -c downstream/$TASK/config.yaml \ -u espnet_hubert_local \ -k $CKPT \ -g $CONFIG其中$CKPT与$CONFIG分别指exp/目录下的 HuBERT 权重如valid.loss.best.pth与训练配置config.yaml命令需在s3prl/s3prl包目录下执行因为-c是相对工作目录解析的-n用于命名运行建议显式设置结果会写入result/downstream/$EXPNAME缺省时变成result/downstream/None不同任务会互相覆盖。运行后 s3prl 会使用你的 HuBERT 模型提取特征为指定任务训练并评测下游模型如说话人验证 ASV、音素识别等 SUPERB 任务评测细节可参考 s3prl 的 SUPERB 文档。与其他 SSL 配方ssl1的差异ESPnet2 提供两套自监督学习配方ssl1与本篇的hubert1二者定位不同可对比 egs2/TEMPLATE/ssl1 与 egs2/librispeech/ssl1。hubert1本文HuBERT 预训练框架的原始实现把预训练所需的全部离线步骤K-means 伪标签、离散 token 评估都收进配方对复现非常友好但由于 HuBERT 需要多个离线阶段脚本较为复杂难以快速改造以适配新的训练方法或新场景。ssl1为代码库“面向未来”而建的新配方旨在容纳纯端到端的新预训练技术如 DinoSR、SpeechFlow、w2v-BERT 等设计上更易定制、更利于大规模预训练扩展。补充说明ssl1代码库同样支持 HuBERT 预训练但伪标签生成步骤不在其配方内——用户要么先用hubert1配方产出标签要么自行生成后传入。小结hubert1配方是 ESPnet2 中复现 HuBERT 自监督预训练的一站式工程方案通过hubert.sh将数据准备、语速扰动、音频格式化、时长过滤、K-means 伪标签生成、统计收集、迭代训练、模型打包与 HF 发布串成可复现的 9 阶段流水线并以空格分隔的多值参数优雅支撑多轮迭代。无论是按模板复现 LibriSpeech 960h 预训练、基于 DiceHuBERT 做轻量化蒸馏还是将产出模型接入 SUPERB 下游评测都可以在本文所述框架内直接落地。对需要更灵活端到端自监督方案的用户可转向ssl1配方对比选型。赞分享人工智能语音音频深度学习NLP【免费下载链接】espnetEnd-to-End Speech Processing Toolkit项目地址https://gitcode.com/gh_mirrors/es/espnet点击查看免费下载相关推荐HuBERT 自监督语音预训练标签生成实战fairseq simple_kmeans 分片特征提取与 K-means 聚类全流程HuBERT 自监督语音预训练标签生成实战fairseq simple_kmeans 分片特征提取与 K means 聚类全流程 本文基于本仓库 kosmos人工智能大模型预训练深度学习NLP计算机视觉多模态语音音频微调NeMo TopIPL 实践指南基于迭代伪标签IPL的半监督 ASR 自训练流水线NeMo TopIPL 实践指南基于迭代伪标签IPL的半监督 ASR 自训练流水线 TopIPLTop N Pseudo Label Averaging人工智能语音音频大模型深度学习fairseq HuBERT 语音自监督预训练实战指南从伪标签数据准备到预训练、CTC 微调与三种解码模式fairseq HuBERT 语音自监督预训练实战指南从伪标签数据准备到预训练、CTC 微调与三种解码模式 本指南以 examples/hubert/READ人工智能深度学习预训练NLP语音上一篇Bilibili-Evolved集成测试模拟网络请求与定时器下一篇MyTinySTL文档翻译从中文到英文的本地化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考