NeMo ASR API 参考指南：语音识别模型类、模块与解码子系统的源码级解读

NeMo ASR API 参考指南：语音识别模型类、模块与解码子系统的源码级解读

【免费下载链接】SpeechA scalable generative AI framework built for researchers and developers working on Large Language Models, Multimodal, and Speech AI (Automatic Speech Recognition and Text-to-Speech)项目地址: https://gitcode.com/GitHub_Trending/nem/Speech

本文基于仓库文档 NeMo ASR API 系统梳理 NVIDIA NeMo 语音识别（ASR）子包的公开 API 体系，覆盖模型类（CTC / RNNT / 混合 Transducer-CTC / 多说话人 / 分类与说话人标签）、编码器与解码器模块、Mixins 混入、数据集、音频预处理器与增强器、CTC/RNNT/TDT 三类解码后端，以及 Adapter 适配网络。读完后，你可以按类名快速定位到 nemo/collections/asr 下的具体源码文件，理解每个组件的职责边界与调用关系，并在自研 ASR 流水线中正确选型与组合这些组件。

API 文档的组织方式

docs/source/asr/api.rst 是 Sphinx autoclass 驱动的 API 参考页，本身不承载长篇教程，而是把 NeMo ASR 子包的公共接口按六大类组织：Model Classes（模型类）、Modules（网络模块）、Mixins（混入）、Datasets（数据集）、Audio Preprocessors / Augmentors（预处理与增强）、Miscellaneous Classes（解码器、假设对象、Adapter 等杂项）。页面中的每一项都对应源码中的一个具体类：

• 模型类位于 nemo/collections/asr/models，均以EncDec前缀命名，体现"编码器-解码器"结构；
• 网络模块位于 nemo/collections/asr/modules；
• 混入与解码逻辑位于 nemo/collections/asr/parts；
• 数据集位于 nemo/collections/asr/data。

这种分层是 NeMo 的典型设计：模型类只负责组装preprocessor + encoder + decoder/joint + loss + decoding，具体算子下沉到模块层，数据流封装在数据集层。对 LLM Agent 和检索工具而言，按“类名 → 文件路径”的映射即可直接索引实现。

模型类（Model Classes）

API 页共列出 9 个模型类，其继承关系可直接在源码中验证：

模型类	实现位置	继承链（源码验证）
EncDecCTCModel	ctc_models.py	ASRModel, ExportableEncDecModel, ASRModuleMixin, InterCTCMixin, ASRTranscriptionMixin
EncDecCTCModelBPE	ctc_bpe_models.py	EncDecCTCModel, ASRBPEMixin
EncDecRNNTModel	rnnt_models.py	ASRModel, ASRModuleMixin, ExportableEncDecModel, ASRTranscriptionMixin
EncDecRNNTBPEModel	rnnt_bpe_models.py	EncDecRNNTModel, ASRBPEMixin
EncDecRNNTBPEModelWithPrompt	rnnt_bpe_models_prompt.py	PromptStreamingMixin, EncDecRNNTBPEModel, ASRTranscriptionMixin
EncDecHybridRNNTCTCBPEModelWithPrompt	hybrid_rnnt_ctc_bpe_models_prompt.py	PromptStreamingMixin, EncDecHybridRNNTCTCBPEModel, ASRTranscriptionMixin
EncDecMultiTalkerRNNTBPEModel	multitalker_asr_models.py	EncDecRNNTBPEModel, SpeakerKernelMixin
EncDecSpeakerLabelModel	label_models.py	ModelPT, ExportableEncDecModel, VerificationMixin
EncDecClassificationModel	classification_models.py	EncDecSpeakerLabelModel, TranscriptionMixin

可以看出，BPE 版本模型（...BPE...）都是在对应字符版模型之上叠加ASRBPEMixin得到的，EncDecClassificationModel则复用了说话人标签模型的编码-分类骨架，API 页面中每个类重复列出的change_vocabulary / setup_training_data / setup_optimization / setup_validation_data / setup_test_data / register_artifact等成员，正是这些继承链共享的接口。

transcribe：统一推理入口

API 页对每个模型类都显式列出transcribe方法。以 EncDecCTCModel.transcribe 的源码签名为例，其参数集与 NeMo 其他 ASR 模型保持一致，可直接对照配置：

def transcribe( self, audio: Union[str, List[str], torch.Tensor, np.ndarray, DataLoader], batch_size: int = 4, return_hypotheses: bool = False, num_workers: int = 0, channel_selector: Optional[ChannelSelectorType] = None, augmentor: DictConfig = None, verbose: bool = True, timestamps: Optional[bool] = None, override_config: Optional[TranscribeConfig] = None, ) -> TranscriptionReturnType:

要点（均来自源码 docstring 与实现）：

• audio支持单路径 / 路径列表 / 波形张量 / manifest 文件 / DataLoader 五种输入，docstring 建议单文件长度 5～25 秒，长音频在显存充足时也可传入；
• batch_size默认 4，调大提升吞吐但增加显存占用；
• timestamps=True时会自动把self.cfg.decoding.compute_timestamps置为True并调用change_decoding_strategy重建解码器，时间戳随后写入返回的Hypothesis.timestep['word'/'segment'/'char']（见 Hypothesis 类）；
• override_config传参后其余参数全部被忽略，这是批量改写推理配置（beam size、timestamps、logprobs 等）的正规入口，其结构由 TranscribeConfig 定义。

change_vocabulary：微调时换词表

EncDecCTCModel.change_vocabulary 是跨语言微调的关键方法。源码显示它的行为边界非常明确：

1. 若新词表与旧词表一致则直接跳过；新词表至少需包含 2 个元素；
2. 只重建 decoder、CTCLoss 与解码器（CTCDecoding/WER），encoder 和 preprocessor 保持不动——这正是"用预训练编码器 + 新语言文本侧"微调场景的设计目的；
3. 会自动把decoder.num_classes同步为新词表长度，并刷新cfg.decoding与已注册的train_ds / validation_ds / test_ds相关字段。

setup_training_data / setup_validation_data / setup_test_data

以 EncDecCTCModel 为例，三个 setup 方法都接收Optional[Union[DictConfig, Dict]]参数：传入配置时按配置构建 DataLoader，不传则复用模型构建时注册的数据集。RNNT 侧的对应实现见 rnnt_models.py。EncDecClassificationModel额外提供use_feat形参（classification_models.py），用于直接从特征文件读取测试数据。

setup_optimization 与 register_artifact

• setup_optimization相关的优化器/调度器构建逻辑集中在基类 ASRModel.setup_optimization_flags 及 NeMo core 的优化模块中，模型类通过组合方式继承；
• register_artifact属于 NeMo core 类机制（nemo/core/classes），允许在 Hydra 配置中以persist/download方式注册文件类工件（如预处理器、分词器路径），API 页将这两个方法并列列出，正是因为它们在配置驱动的微调流程中总是成对出现。

Prompt 模型扩展的推理接口

EncDecRNNTBPEModelWithPrompt与EncDecHybridRNNTCTCBPEModelWithPrompt在 API 页比其他模型多出set_inference_prompt与initialize_prompt_feature两个成员，对应其继承的PromptStreamingMixin：前者在推理前为每个批样本注入文本 prompt 序列，后者在模型加载阶段完成 prompt 特征的初始化。配套的训练/推理脚本可参考 examples/asr/asr_transducer/transcribe.py 与 examples/asr/conf 下的 RNNT / hybrid 配置。

多说话人分类与说话人标签模型

• EncDecMultiTalkerRNNTBPEModel叠加 SpeakerKernelMixin，为每个说话人维护一个 kernel，实现多说话人并行转写；
• EncDecSpeakerLabelModel与EncDecClassificationModel用于说话人/事件级分类任务，二者复用 conv_asr.py 中的ConvASRDecoderClassification作为分类头。

Modules：编码器、解码器与 Joint 网络

API 页 Modules 一节列出的类都位于 nemo/collections/asr/modules，是模型类的"积木件"：

编码器

• ConformerEncoder：当前 NeMo ASR 的主力编码器，ConformerEncoder同时实现StreamingEncoder接口，是 FastConformer 系列（含流式与混合 RNNT-CTC 模型）的默认 backbone；
• TransformerEncoder 与 StreamingTransformerEncoder：前者为通用 Transformer 编码实现，后者通过继承前者并实现流式状态管理，支持分块（chunk）推理；
• ConvASREncoder：基于 CNN 的经典编码器，早期 WaveNet-ASR 风格模型沿用；
• RNNEncoder：LSTM/GRU 编码器，主要服务小模型与历史 checkpoint 兼容。

解码器与 Joint

• ConvASRDecoder：CTC 字符版线性投影解码器；
• SpeakerDecoder：说话人/标签分类任务的解码头；
• RNNTDecoder：Transducer 的语言模型侧（prediction 网络），同时支持字符与 BPE 词表；
• StatelessTransducerDecoder：无状态版本，面向流式推理场景的缓存管理；
• RNNTJoint：Transducer 的 joint 网络，融合声学帧与语言模型状态输出标签分布；EncDecRNNTModel初始化时会从cfg.joint动态注入num_classes、vocabulary以及encoder_hidden / pred_hidden（见 rnnt_models.py）；
• SampledRNNTJoint：RNNTJoint的采样变体，继承链SampledRNNTJoint(RNNTJoint)表明其在 joint 前向中引入标签采样近似以加速训练。

Mixins：把能力“混入”模型

API 页 Mixins 一节列出 6 个混入，它们解释了许多模型类为何"长得像却能力不同"：

• ASRBPEMixin：BPE 词表、分词器加载与change_vocabulary的 BPE 版本实现，所有*BPE*模型的能力来源；
• ASRModuleMixin：提供forward统一前向（输入音频→logprobs）与 Adapter 注入入口（其基类为ASRAdapterModelMixin）；
• TranscriptionMixin：transcribe的通用实现，处理 manifest/DataLoader 解析、批次循环与结果归并；
• TranscribeConfig：推理覆盖配置的 dataclass，transcribe(override_config=...)的结构定义；
• InterCTCMixin：在 RNNT/Transducer 训练中加入中间层 CTC 辅助损失（interCTC），EncDecCTCModel.__init__末尾的self.setup_interctc(...)调用即来自该混入（见 ctc_models.py）；
• SpeakerKernelMixin：多说话人转写所需的 speaker kernel 管理与并行解码逻辑。

Datasets：四类音频-文本数据管道

API 页按词元粒度把数据集分为四组，全部位于 nemo/collections/asr/data：

1. 字符编码（Character Encoding）AudioToCharDataset 与 TarredAudioToCharDataset：基于 manifest 的字符级数据集，Tarred 版本读取 sharded/tarred 音频用于大规模训练；
2. 子词编码（Subword Encoding）AudioToBPEDataset 与 TarredAudioToBPEDataset：结构同字符版，文本侧换成 BPE 词元，与ASRBPEMixin配套；
3. Text-to-Text 数据集TextToTextDataset（map-style）与 TextToTextIterableDataset（iterable）：用于语言模型重打分等纯文本任务，后者适合流式分片数据；
4. 多说话人数据集（Speaker-Tagged）
   • LhotseSpeechToTextSpkBpeDataset：基于 Lhotse 的多说话人 ASR 数据集，供EncDecMultiTalkerRNNTBPEModel训练；
   • LhotseAudioToSpeechE2ESpkDiarDataset：端到端说话人日志数据集；
   • MultiSpeakerSimulator 与 RIRMultiSpeakerSimulator：多说话人音频模拟工具，后者叠加 RIR（房间脉冲响应）混响模拟；仓库同时提供独立入口 tools/speech_data_simulator/multispeaker_simulator.py 与配置 conf。

Audio Preprocessors 与 Audio Augmentors

预处理器

• AudioToMelSpectrogramPreprocessor：梅尔谱特征提取，FastConformer/Parakeet 系列模型的默认 preprocessor，其配置 dataclass AudioToMelSpectrogramPreprocessorConfig 覆盖n_fft、sample_rate、窗函数等参数；
• AudioToMFCCPreprocessor：MFCC 特征提取，面向传统 RNN/LSTM 模型。

两个 preprocessor 均实现 NeMo 的Exportable接口，因此可在模型导出时一并打包。

增强器（Augmentors）

增强器分为谱图级与波形级两类：

• 谱图级：SpectrogramAugmentation（频带掩码 + 时间掩码，即 SpecAugment）与 CropOrPadSpectrogramAugmentation（对谱图做裁剪/补齐以统一时长）；
• 波形级扰动位于 nemo/collections/asr/parts/preprocessing/perturb.py，API 页列出的 9 个扰动类各司其职：

扰动类	行号	作用
SpeedPerturbation	L102	变速（改变语速）
TimeStretchPerturbation	L175	时域拉伸/压缩（保持音调）
GainPerturbation	L323	随机增益
ImpulsePerturbation	L343	脉冲（爆音）注入
ShiftPerturbation	L423	时移（延迟）
NoisePerturbation	L457	噪声文件混合
WhiteNoisePerturbation	L850	白噪声叠加
RirAndNoisePerturbation	L871	RIR 混响 + 噪声联合模拟
TranscodePerturbation	L1002	有损转码模拟（电话/低码率场景）

在线增强的示例可参考教程 Online_Noise_Augmentation.ipynb。

Miscellaneous Classes：解码子系统与假设对象

这是 API 页信息量最大的一节，对应parts/submodules下的解码管理器（*Decoding）与推理后端（*Infer）两层结构。

解码管理器：CTC / RNNT / TDT

• CTC：CTCDecoding 与 CTCPEDecoding（BPE 版）负责按decoding配置（greedy / beam / flashlight）实例化推理后端，并在词表变化后重建；
• RNNT：RNNTDecoding 与 RNNTBPEDecoding，构造时接收decoder与joint实例（见 rnnt_models.py），是 Transducer 解码的统一入口；
• TDT（Transducer-Data-Driven / TDT 变体损失）：GreedyTDTInfer等 TDT 推理后端复用 RNNT 的联合解码框架，用于训练损失为 TDT 的模型。

推理后端

后端	位置	说明
GreedyCTCInfer	ctc_greedy_decoding.py	CTC 贪心解码，支持置信度（ConfidenceMethodMixin）
BeamCTCInfer	ctc_beam_decoding.py	CTC 束搜索
GreedyRNNTInfer	rnnt_greedy_decoding.py	RNNT 贪心解码
GreedyBatchedRNNTInfer	rnnt_greedy_decoding.py	批量化贪心解码，实现WithOptionalCudaGraphs，可启用 CUDA Graphs 降低启动开销
BeamRNNTInfer	rnnt_beam_decoding.py	RNNT 束搜索
BeamBatchedRNNTInfer	rnnt_beam_decoding.py	批量化 RNNT 束搜索
GreedyTDTInfer	rnnt_greedy_decoding.py	TDT 贪心解码
GreedyBatchedTDTInfer	rnnt_greedy_decoding.py	TDT 批量贪心
BeamTDTInfer	tdt_beam_decoding.py	TDT 束搜索
BeamBatchedTDTInfer	tdt_beam_decoding.py	TDT 批量束搜索

从源码结构看，每个*Infer都有对应的*Configdataclass（如 GreedyRNNTInferConfig、BeamRNNTInferConfig），模型配置中decoding: {decoding_strategy: greedy|beam, ...}的字段最终就是由这些 Config 结构解析的——修改 examples/asr/conf 下 YAML 的 decoding 段即可切换策略，无需改代码。

Hypothesis 与 NBestHypotheses

Hypothesis 与 NBestHypotheses 是transcribe(return_hypotheses=True)的返回结构：前者承载单条假设的文本、置信度、时间戳（timestep中的 word/segment/char 粒度）与 logprobs，后者承载 N-best 候选列表。对需要下游重打分（rescoring）或对齐后处理的管线，这两个类是标准数据契约。

Adapter Networks 与 Adapter Strategies

API 页末尾列出的 Adapter 接口支撑"冻结大模型 + 轻量适配层"的微调范式：

• MultiHeadAttentionAdapter 与 RelPositionMultiHeadAttentionAdapter：注入到注意力层的 MHA Adapter 及其相对位置编码变体；
• PositionalEncodingAdapter与RelPositionalEncodingAdapter：对位置编码层做适配，与 MHA Adapter 组合使用；
• MHAResidualAddAdapterStrategy：Adapter 注入策略，ResidualAdd表示把 Adapter 输出以残差相加方式并入原前向；其adapter_module_names属性声明可注入的目标模块名。

模型侧由 ASRModuleMixin 提供的setup_adapters负责按配置实例化这些 Adapter（EncDecCTCModel.__init__末尾的self.setup_adapters()即此调用），相关实践可结合教程 ASR_Adapter 系列 与 examples/asr/asr_adapters 的线性/相对位置 MHA 示例脚本。

如何按 API 页定位源码并继续深入

1. 拿到类名后按上表的"文件 + 行号"直接跳转源码，每个类的 docstring 与__init__会说明其配置字段；
2. 关注模型配置基类 EncDecCTCModelConfig 与 nemo/collections/asr/models/configs，它是 YAML 中各字段（preprocessor/encoder/decoder/joint/decoding/loss）的类型定义；
3. 验证行为时参考测试目录 tests/collections/asr，其中 100+ 测试文件按模型类组织，覆盖 transcribe、change_vocabulary、解码切换等 API 行为的回归验证；
4. 端到端用法以 examples/asr 为入口：speech_to_text_finetune.py（训练）、transcribe_speech.py（推理）、export（导出），配合 docs/source/asr/inference.rst 等文档页可形成完整工作流。

小结

docs/source/asr/api.rst 所覆盖的 API 面可以概括为一句话：NeMo ASR 以 9 个EncDec*模型类为入口，向下组合编码器/解码器/joint 模块与 CTC-RNNT-TDT 三套可切换解码后端，向上通过 BPE、Prompt、InterCTC、多说话人等 Mixins 扩展能力，并以 Hypothesis/NBestHypotheses 作为统一的推理输出契约。理解这一分层后，无论是更换词表、切换 beam 策略、加入数据增强，还是注入 Adapter 做参数高效微调，都可以在不改动主干代码的前提下，通过模型配置与对应 setup 方法完成。

【免费下载链接】SpeechA scalable generative AI framework built for researchers and developers working on Large Language Models, Multimodal, and Speech AI (Automatic Speech Recognition and Text-to-Speech)项目地址: https://gitcode.com/GitHub_Trending/nem/Speech