WeNet 中的 Paraformer 落地实践:FunASR 权重转换、配置训练与解码评测全指南
WeNet 中的 Paraformer 落地实践:FunASR 权重转换、配置训练与解码评测全指南
本篇技术指南聚焦于开源语音识别工具包 WeNet 中对阿里 Paraformer(非自回归并行 Transformer 模型)的完整支持方案:如何将 FunASR 风格的 Paraformer 预训练权重转换为 WeNet 格式并微调、如何理解 SANM 编码器 / CIF 预测器 / 采样器构成的模型结构、如何解读 train_paraformer.yaml 全套配置、以及如何基于 AISHELL-1 数据完成训练、解码与 CER 评测。读完本文,你将能够在 WeNet 仓库中独立复现 Paraformer 的转换—微调—评测—导出完整链路,并掌握流式(dynamic chunk)与非流式两种模式的差异与性能对照。
一、方案总览:从 FunASR 权重到 WeNet 训练管线
WeNet 在 examples/aishell/paraformer 目录下提供了完整的 Paraformer 实战示例,其核心链路分为三步:
- 权重转换(Preliminary):把阿里开源(FunASR 风格)的 Paraformer-large 模型 checkpoint 转换成 WeNet 风格的配置(
train.yaml)与权重(wenet_paraformer.pt); - 微调(Fine-tuning):基于转换后的 checkpoint,用 AISHELL-1 数据在全参数下继续训练(
run.sh驱动); - 解码评测与导出:以多种解码模式(
ctc_greedy_search、ctc_prefix_beam_search、paraformer_greedy_search)评测 CER,并导出 JIT 模型用于生产部署。
该示例目录包含:转换脚本入口 README.md、两套训练配置 train_paraformer.yaml 与 train_paraformer_dynamic.yaml、checkpoint 修改工具 modify_ckpt.py,以及 GPU 版 run.sh 和昇腾 NPU 版 run_npu.sh。
模型侧的实现位于仓库 wenet/models/paraformer,包括 SANM 编码器/解码器 layers.py、CIF 预测器 cif.py、模型主体 paraformer.py、搜索解码 search.py 以及权重转换脚本 convert_paraformer_to_wenet_config_and_ckpt.py。
二、第一步:FunASR 风格权重转换(Preliminary)
2.1 转换命令详解
原文档给出的转换流程包含两条命令,第一条完成配置与权重的整体转换,第二条用本地脚本初始化 ctc 与 embed 模块:
output_dir=exp/paraformer/large
mkdir -p ${output_dir}
. ./path.sh && python wenet/paraformer/convert_paraformer_to_wenet_config_and_ckpt.py \
--output_dir ${output_dir}
# init ctc and embed(used in sampler)
python local/modify_ckpt.py \
--add_list "{\"ctc.ctc_lo.weight\": \"embed.weight\"}" \
--input_ckpt exp/paraformer/large/wenet_paraformer.pt \
--output_ckpt exp/paraformer/large/wenet_paraformer.init-ctc.init-embed.pt
要点说明:
output_dir=exp/paraformer/large:指定输出目录,需要先mkdir -p创建;所有转换产物(global_cmvn、units.txt、seg_dict、train.yaml、wenet_paraformer.pt)都会落在这里;path.sh:在 path.sh 中把WENET_DIR=$PWD/../../..指向仓库根目录,并设置PYTHONPATH,确保可以import wenet;- 第二条命令通过
--add_list把embed.weight(采样器所需)复制为ctc.ctc_lo.weight的初始值,得到用于微调的初始化权重wenet_paraformer.init-ctc.init-embed.pt。
2.2 转换脚本做了什么:源码级拆解
转换脚本 convert_paraformer_to_wenet_config_and_ckpt.py 的核心逻辑可通过 main() 与各 convert_to_* 函数梳理清楚:
| 步骤 | 实现函数 | 产物 |
|---|---|---|
| 下载/加载源资产 | may_get_assets_and_refine_args() |
原始 config.yaml、am.mvn、seg_dict、model.pt |
| CMVN 格式转换 | convert_to_wenet_json_cmvn() → _to_wenet_cmvn() |
JSON 格式 global_cmvn |
| 词典转换 | extract_dict() |
units.txt(含特殊符号映射) |
| Tokenizer 配置生成 | convert_to_wenet_tokenizer_conf() |
tokenizer: paraformer + 特殊符号表 |
| 训练配置生成 | convert_to_wenet_yaml() |
WeNet 风格 train.yaml |
| 权重名映射 | convert_to_wenet_state_dict() |
wenet_paraformer.pt |
值得注意的源码细节(这些可直接作为事实依据):
- CMVN 转换:
_load_paraformer_cmvn()解析 FunASR 的 kaldi 风格am.mvn,其中 Paraformer 的 mean 是负值,需要取反;方差则按1 / var^2 + mean^2重算(convert_paraformer_to_wenet_config_and_ckpt.py#L38-L43),再写入{'mean_stat': ..., 'var_stat': ..., 'frame_num': 1}结构的 JSON。这与 WeNet 侧load_cmvn()(见 cmvn.py)配合is_json_cmvn: true的读取方式对应。 - 词典转换:
extract_dict()遍历token_list,将<s>改写为<sos>、</s>改写为<eos>,按行写入units.txt,同时返回 vocab size 作为output_dim。 - 配置生成:
convert_to_wenet_yaml()设置了encoder: sanm_encoder、decoder: sanm_decoder、input_layer: paraformer_dummy、pos_enc_layer_type: abs_pos_paraformer,并写死lfr_conf: {lfr_m: 7, lfr_n: 6},从而input_dim = lfr_m * 80 = 560;同时删除 FunASR 侧不再使用的字段(如upsample_type、use_cif1_cnn、selfattention_layer_type、pos_enc_class),并把predictor_bias改名为add_eos、删除predictor_weight。 - 权重名映射:
convert_to_wenet_state_dict()将 FunASR checkpoint 中的键名映射为 WeNet 命名,例如predictor.cif*→predictor.predictor.cif*、predictor.blstm*→predictor.tp_*、predictor.cif_output2*→predictor.tp_output.*、decoder.embed.0.weight→embed.weight。
2.3 modify_ckpt.py:checkpoint 过滤与初始化工具
modify_ckpt.py 是一个通用的小工具,仅依赖 argparse 与 torch,提供两个参数:
--remove_list:逗号分隔的 name 前缀列表,命中的键会被跳过(用于剔除不需要的模块);--add_list:JSON 格式的键值映射,形如{"ctc.ctc_lo.weight": "embed.weight"},含义是把embed.weight的张量复制为ctc.ctc_lo.weight,从源码可见实现为new_state[k] = state[v](modify_ckpt.py#L61-L65);--input_ckpt/--output_ckpt:输入与输出 checkpoint 路径,均通过map_location="cpu"加载/保存。
在示例中,它被用来初始化 CTC 输出层权重(ctc.ctc_lo.weight),避免从随机初始化开始训练。
三、模型结构:SANM + CIF + 采样器的组合
Paraformer 是典型的非自回归(NAT)模型:编码器一次性编码整段语音,预测器(CIF)把编码器输出压缩成与目标长度对齐的声学嵌入,解码器基于这些嵌入并行解码。WeNet 的实现见 paraformer.py,类 Paraformer 继承自 ASRModel,其默认解码方法是 paraformer_greedy_search。
3.1 SANM 编码器与解码器(layers.py)
layers.py 中实现了 SanmEncoder(继承 BaseEncoder)与 SanmDecoder(继承 TransformerDecoder):
- SanmEncoder:首个编码层用
AliParaformerEncoderLayer把输入维度input_size(560,即 LFR 后的特征)映射到output_size(512),随后堆叠num_blocks - 1个标准层;自注意力采用MultiHeadedAttentionSANM,并支持gradient_checkpointing(forward_layers_checkpointed使用torch.utils.checkpoint)。编码器前处理是LFR模块(lfr_m=7, lfr_n=6,即低帧率:每 6 帧叠 7 帧并跳 6 帧)。 - SanmDecoder:
SanmDecoderLayer的 LayerNorm 使用eps=1e-12(源码注释标明这是对齐 Ali-Paraformer 的细节),每个解码层包含 SANM 自注意力(DummyMultiHeadSANM)与跨注意力(MultiHeadAttentionCross);解码器尾部还有一个额外的decoders3模块(源码注释为“Paraformer has a decoder3”)。配置中的att_layer_num必须等于num_blocks(layers.py#L435有断言)。 - LFR 低帧率:
LFR.forward()实现堆帧跳帧,input_dim = lfr_m * 80 = 560正是 LFR 叠 7 帧 80 维 fbank 的结果。
3.2 CIF 预测器(cif.py 与 Predictor)
CIF(Continuous Integrate-and-Fire)是 Paraformer 的定长到变长对齐模块。cif.py 中的 Cif 通过 cif_conv1d 卷积(带 l_order/r_order 上下文与 cnn_groups 分组)、cif_output 线性层与 sigmoid 输出每帧的 alpha 权重;cif() 函数按阈值(threshold=1.0)积分累加、触发射出 acoustic embedding,cif_without_hidden() 则只计算触发位置(用于解码阶段生成时间戳)。
Predictor(paraformer.py)在 Cif 之外还有一条精确时间戳分支(accurate timestamp branch):tp_upsample_cnn(转置卷积,upsample_times=3 上采样)、tp_blstm(双向 LSTM)与 tp_output 线性层,输出 tp_alphas 与 tp_token_num,用于预测逐 token 的触发权重。
3.3 训练前向与采样器(Sampler)
Paraformer.forward() 的流程(paraformer.py#L153-L218):
- 编码器:
_forward_encoder依次执行 LFR → SANM Encoder; - 预测器:
self.predictor(encoder_out, ys_pad, ...)得到acoustic_embd与 token 数量;若add_eos=true,训练标签会通过add_sos_eos在尾部拼接<eos>,即ys_pad_lens = text_lengths + 1; - 采样器:
_sampler()在torch.no_grad()下用当前解码器预测结果与真实标签对比,统计预测正确的 token 数,再按sampling_ratio(0.75)随机掩盖部分正确 token,用ys_pad_embed(self.embed词嵌入)替换对应位置的声学嵌入——这就是微调时用到embed.weight的原因;该机制也被称为“可学习采样(sampler)”,用于缓解 NAT 模型的暴露偏差; - 损失:解码器损失 +
ctc_weight * loss_ctc(CTC 分支)+loss_quantity(CIF 数量损失,L1)+loss_quantity_tp(时间戳分支的数量损失)。
四、配置文件深度解读
示例提供了两套配置,均位于 examples/aishell/paraformer/conf/:
- train_paraformer.yaml:非流式(full chunk) 微调配置;
- train_paraformer_dynamic.yaml:在编码器上额外开启
use_dynamic_chunk: true的动态分块(dynamic chunk) 配置,训练出的模型可同时用于流式(chunk 16)与非流式(full)解码。
两套配置差异仅有编码器的 use_dynamic_chunk 一行,其余完全一致。完整配置项说明如下:
4.1 前端与编码器
input_dim: 560
encoder: sanm_encoder
encoder_conf:
attention_dropout_rate: 0.0
attention_heads: 4
dropout_rate: 0.0
input_layer: paraformer_dummy
kernel_size: 11
linear_units: 2048
normalize_before: true
num_blocks: 50
output_size: 512
pos_enc_layer_type: abs_pos_paraformer
positional_dropout_rate: 0.0
sanm_shfit: 0
use_dynamic_chunk: true # 仅 dynamic 配置
gradient_checkpointing: true
| 参数 | 含义 |
|---|---|
input_dim: 560 |
LFR(m=7, n=6)叠加后的输入维度,即 lfr_m * 80 |
num_blocks: 50 |
编码器层数(SANM),Paraformer-large 的典型配置 |
output_size: 512 |
编码器输出维度 |
attention_heads: 4 |
多头注意力头数 |
linear_units: 2048 |
FFN 中间层维度 |
kernel_size: 11 |
SANM 注意力卷积核大小 |
sanm_shfit: 0 |
SANM 偏移量(源码参数名为 sanm_shfit,默认 0) |
pos_enc_layer_type: abs_pos_paraformer |
Paraformer 专用绝对位置编码,对应 embedding.py 中的 ParaformerPositinoalEncoding |
input_layer: paraformer_dummy |
编码器首层为“dummy”子采样(即不做下采样,IdentitySubsampling) |
use_dynamic_chunk: true |
开启动态分块,支持流式/非流式统一训练(dynamic 配置独有) |
gradient_checkpointing: true |
用梯度检查点换显存,50 层编码器在 8×3090 上训练的关键配置 |
4.2 解码器
decoder: sanm_decoder
decoder_conf:
att_layer_num: 16
attention_heads: 4
dropout_rate: 0.0
kernel_size: 11
linear_units: 2048
num_blocks: 16
positional_dropout_rate: 0.0
sanm_shfit: 0
self_attention_dropout_rate: 0.0
src_attention_dropout_rate: 0.0
gradient_checkpointing: true
解码器为 16 层 SANM 解码器(att_layer_num == num_blocks == 16,源码有断言),自带 decoders3 尾部模块。由于是非自回归并行解码,解码器直接以预测器输出的声学嵌入为输入。
4.3 Tokenizer、CTC 与 CMVN
tokenizer: paraformer
tokenizer_conf:
seg_dict_path: exp/paraformer/large/seg_dict
special_tokens:
<blank>: 0
<eos>: 2
<sos>: 1
<unk>: 8403
symbol_table_path: exp/paraformer/large/units.txt
ctc: ctc
ctc_conf:
ctc_blank_id: 0
cmvn: global_cmvn
cmvn_conf:
cmvn_file: exp/paraformer/large/global_cmvn
is_json_cmvn: true
- ParaformerTokenizer:见 paraformer_tokenizer.py,继承
CharTokenizer,用seg_dict(英文分段词典)把英文词切分为子词(tokenize_by_seg_dict,实现见 tokenize_utils.py),tokens2text则复用 search.py 中的paraformer_beautify_result做中英混合美化输出; - 特殊符号含义:
<blank>=0(CTC 空白)、<sos>=1、<eos>=2、<unk>=8403; ctc_blank_id: 0与<blank>对齐;CMVN 文件是转换脚本生成的 JSON 格式(is_json_cmvn: true)。
4.4 模型超参与预测器
model: paraformer
model_conf:
ctc_weight: 0.3
length_normalized_loss: false
lsm_weight: 0.1
sampling_ratio: 0.75
predictor: paraformer_predictor
predictor_conf:
cnn_groups: 1
idim: 512
l_order: 1
noise_threshold2: 0.01
r_order: 1
residual: false
smooth_factor2: 0.25
tail_threshold: 0.45
threshold: 1.0
upsample_times: 3
| 参数 | 含义 |
|---|---|
ctc_weight: 0.3 |
CTC 分支在总损失中的权重 |
lsm_weight: 0.1 |
标签平滑权重 |
sampling_ratio: 0.75 |
采样器掩盖正确 token 的比例(_sampler 中 target_num = (len - same_num) * sampling_ratio) |
length_normalized_loss: false |
是否对损失做长度归一化 |
idim: 512 |
预测器输入维度,等于编码器 output_size |
threshold: 1.0 |
CIF 触发阈值(积分达到 1.0 即“开火”) |
tail_threshold: 0.45 |
尾部触发阈值,解码时保证最后一个 token 被触发 |
l_order / r_order: 1 |
CIF 卷积左右上下文帧数 |
cnn_groups: 1 |
CIF 卷积分组数 |
residual: false |
CIF 卷积是否带残差 |
upsample_times: 3 |
时间戳分支上采样倍数 |
smooth_factor2 / noise_threshold2 |
时间戳分支的 alpha 平滑与噪声阈值(对应 Predictor 中 relu(tp_alphas * smooth_factor2 - noise_threshold2)) |
4.5 数据集与训练策略
dataset: asr
dataset_conf:
filter_conf:
max_length: 40960
min_length: 0
token_max_length: 200
token_min_length: 1
resample_conf:
resample_rate: 16000
speed_perturb: true
fbank_conf:
num_mel_bins: 80
frame_shift: 10
frame_length: 25
dither: 0.1
spec_aug: true
spec_aug_conf:
num_t_mask: 2
num_f_mask: 2
max_t: 50
max_f: 10
shuffle: true
shuffle_conf:
shuffle_size: 1500
sort: true
sort_conf:
sort_size: 500 # sort_size should be less than shuffle_size
batch_conf:
batch_type: 'static' # static or dynamic
batch_size: 28
grad_clip: 5
accum_grad: 1
max_epoch: 60
log_interval: 100
optim: adam
optim_conf:
lr: 0.0005
scheduler: warmuplr
scheduler_conf:
warmup_steps: 12000
- 数据侧:16kHz 重采样、80 维 fbank(10ms 帧移 / 25ms 帧长)、速度扰动、SpecAugment(时间掩码 2 处 × 50 帧、频率掩码 2 处 × 10 帧)、shuffle(1500)+ sort(500,注意注释要求
sort_size小于shuffle_size)、静态 batch size 28; - 优化侧:
grad_clip=5、accum_grad=1、max_epoch=60、Adam(lr 5e-4)配合warmuplr调度器(warmup 12000 步)。
模型注册关系可参考 init_model.py:sanm_encoder → SanmEncoder、sanm_decoder → SanmDecoder、paraformer_predictor → Predictor、paraformer → Paraformer,且 model: paraformer 分支会用 tokenizer_conf.special_tokens 构造模型(init_model.py#L155-L168)。
五、训练、解码与导出:run.sh 全流程
5.1 脚本参数速览
run.sh 以 AISHELL-1 为例,默认 stage=0, stop_stage=2,关键变量:
data_type=shard:训练数据使用 shard 格式(data/train/data.list、data/dev/data.list、data/test/data.list);train_config=conf/train_paraformer_dynamic.yaml:默认用动态分块配置;checkpoint=exp/paraformer/large/wenet_paraformer.init-ctc.init-embed.pt:即 2.1 节转换 + 初始化后的权重;dir=exp/finetune_paraformer_dynamic:输出目录;num_workers=8、prefetch=500;average_checkpoint=true、average_num=5、max_epoch=100:训练完成后取 5 个最优 epoch 平均权重;decode_modes="ctc_greedy_search ctc_prefix_beam_search paraformer_greedy_search":三种解码模式;decode_device=0、decoding_chunk_size=-1(全 chunk 非流式)、decode_batch=16、ctc_weight=0.3、reverse_weight=0.5;train_engine=torch_ddp:DDP 引擎(注释也提示可用 deepspeed,deepspeed_config指向../whisper/conf/ds_stage1.json);- GPU 数量自动检测:有
nvidia-smi时自动把全部 GPU 写入CUDA_VISIBLE_DEVICES。
5.2 各 stage 行为
Stage 0 —— 训练:通过 torchrun 启动 wenet/bin/train.py,传入 --train_engine torch_ddp --config $train_config --checkpoint $checkpoint --model_dir $dir 等。训练脚本会把 train_config 改写为 $dir/train.yaml(补全 input_dim/output_dim),该文件随后用于推理与导出。dist_backend="nccl"(源码注释提醒 deepspeed 与 gloo 不兼容)。
Stage 1 —— deepspeed 状态合并:若使用 deepspeed 且 deepspeed_save_states="model+optimizer",遍历 $dir 下的分片目录,用自动生成的 zero_to_fp32.py 合并为完整 .pt。
Stage 2 —— 平均权重 + 解码 + 评测:
average_model.py生成avg_${average_num}_maxepoch_${max_epoch}.pt(--val_best按验证集最优选取);recognize.py(见 wenet/bin/recognize.py)以--modes指定的模式解码,结果写入$result_dir/$mode/text,其中--modes支持的 Paraformer 相关模式为paraformer_greedy_search与paraformer_beam_search(recognize.py#L79-L93);- 用
tools/compute-wer.py --char=1 --v=1计算字级 CER,输出到$result_dir/$mode/wer。
Stage 3 —— 模型导出:export_jit.py 导出 final.zip(JIT 脚本化模型)与 final_quant.zip(量化模型),供 runtime 侧 C++ 部署使用。
5.3 昇腾 NPU 版本
run_npu.sh 与 GPU 版流程一致,差异在于:
- 通过
npu-smi info自动检测 NPU 数量并设置ASCEND_RT_VISIBLE_DEVICES; data_type=raw(小数据集用 raw 格式);train_engine=torch_fsdp,dist_backend="hccl",训练与解码均加--device "npu";- 解码评测脚本使用
data/test/data.list(raw 列表)而非 shard。
六、解码模式与 AISHELL-1 性能记录
6.1 三种解码模式的含义
- ctc_greedy search:在编码器输出上做 CTC 贪心解码(取每帧概率最大的 token,去 blank 与重复);
- ctc_prefix beam search:CTC 前缀束搜索(
ctc_prefix_beam_search),支持 beam; - paraformer greedy search:Paraformer 专属非自回归解码——
_forward_paraformer得到解码器 log 概率后,paraformer_greedy_search(search.py)直接对解码器输出按长度截断取 argmax,并用forward_cif_peaks计算 CIF 峰值位置,输出逐 token 时间戳(result.times)。
此外 search.py 还提供 paraformer_beam_search(批式束搜索,_batch_beam_search)与 paraformer_beautify_result(中英混排输出美化)、gen_timestamps_from_peak(由 CIF 峰值生成起止时间戳)。
6.2 官方性能记录(AISHELL-1 test,CER%)
下表完整继承自 README.md,其中“full”指全 chunk 非流式解码,“16”指 chunk size 为 16 的流式解码;N/C/S/D/I 分别为总字数、正确、替换、删除、插入统计。
Paraformer(原始模型)结果:
| decoding mode | full | 16 |
|---|---|---|
| paraformer greedy search | 1.95 | N/A |
Paraformer 全参数微调(full-parameter tuning)结果:
- 训练信息:torch_ddp fp32,batch size 28,ctc_weight: 0.3,acc_grad 1,8 × 3090 GPU,60 epochs(约 8 小时)
- 解码信息:ctc_weight 0.3,average_num 5
- Git hash:TBD
| decoding mode | full | 16 |
|---|---|---|
| ctc greedy search | 3.45%(N=104765 C=101244 S=3406 D=115 I=91) | N/A |
| ctc prefix beam search | 3.44%(N=104765 C=101247 S=3407 D=111 I=83) | N/A |
| paraformer greedy search | 2.19%(N=104765 C=102643 S=1959 D=163 I=172) | N/A |
Paraformer-dynamic 训练(全参数微调)结果:
- 训练信息:torch_ddp fp32,batch size 28,ctc_weight: 0.3,acc_grad 1,8 × 3090 GPU,60 epochs(约 8 小时)
- 解码信息:ctc_weight 0.3,average_num 5
- Git hash:TBD
| decoding mode | full | 16 |
|---|---|---|
| ctc greedy search | 3.46%(N=104765 C=101235 S=3409 D=121 I=98) | 4.18%(N=104765 C=100495 S=4149 D=121 I=107) |
| ctc prefix beam search | 3.45%(N=104765 C=101239 S=3413 D=113 I=91) | 4.17%(N=104765 C=100500 S=4150 D=115 I=103) |
| paraformer greedy search | 2.15%(N=104765 C=102640 S=1977 D=148 I=132) | 2.40%(N=104765 C=102409 S=2220 D=136 I=161) |
从结果可以观察到:paraformer_greedy_search 是 Paraformer 的最优解码方式(全参微调 full 模式 2.19%,dynamic 训练 full 模式 2.15%);开启 use_dynamic_chunk 训练后,模型以 16 chunk 流式解码仍能保持 2.40% 的 CER,与 full 模式差距很小,实现了“一套模型、流式/非流式两用”。
七、小结
WeNet 对 Paraformer 的支持是完整的“开箱即用”闭环:convert_paraformer_to_wenet_config_and_ckpt.py 负责把 FunASR 预训练权重无损转换为 WeNet 格式(含 CMVN、词典、tokenizer、配置与权重名映射),modify_ckpt.py 初始化 CTC 与 embed 模块,train_paraformer.yaml 与 train_paraformer_dynamic.yaml 分别覆盖非流式与动态分块微调,run.sh(GPU)/ run_npu.sh(NPU)一键串联训练—平均—解码—评测—导出。配合 wenet/models/paraformer 下源码级实现,开发者既可以复现 AISHELL-1 上的 CER 记录,也可以据此进一步定制采样策略、CIF 阈值或扩展自己的非自回归模型实验。