Transformers documentation

Nemotron 3.5 ASR

Transformers

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

该模型于 2026-06-27 贡献至 Hugging Face Transformers。

Nemotron 3.5 ASR

概述

Nemotron 3.5 ASR 是 NVIDIA 推出的一款 6 亿参数的多语言语音识别模型，专为低延迟流式和高吞吐量批处理场景下的高质量转录而设计，并原生支持标点符号和大小写。在流式处理方面，它提供可配置的块大小——80ms、160ms、560ms 和 1120ms，允许用户根据应用需求在延迟与准确性之间进行权衡。其缓存感知的 FastConformer-RNNT 架构是这一能力的核心：与反复重新处理重叠音频窗口的传统缓冲流式处理不同，该模型仅处理每个新传入的块，同时复用来自先前块的缓存编码器上下文。这消除了冗余计算，显著提升了效率，并在不牺牲准确性的前提下将端到端延迟降至最低，使其非常适合实时转录工作负载。

用法

离线转录

Pipeline

AutoModel

流式转录

这是一个实验性功能，API 可能会发生变化。

对于实时转录，音频将按照以下规则分块：

from threading import Thread
from transformers import AutoModelForRNNT, AutoProcessor, TextIteratorStreamer
from transformers.audio_utils import load_audio

model_id = "nvidia/nemotron-3.5-asr-streaming-0.6b"
processor = AutoProcessor.from_pretrained(model_id)
model = AutoModelForRNNT.from_pretrained(model_id, device_map="auto")

processor.set_num_lookahead_tokens(6)
print(f"Streaming latency: {processor.streaming_latency_ms} ms")

# The language prompt rides along on every chunk; use a locale (e.g. "de-DE") or "auto".
language = "en-US"

sampling_rate = processor.feature_extractor.sampling_rate
audio = load_audio(
    "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/obama.mp3",
    sampling_rate=sampling_rate,
)

first_chunk_inputs = processor(
    audio[: processor.num_samples_first_audio_chunk],
    sampling_rate=sampling_rate,
    is_streaming=True,
    is_first_audio_chunk=True,
    language=language,
    return_tensors="pt",
)
first_chunk_inputs = first_chunk_inputs.to(model.device, dtype=model.dtype)


def input_features_generator():
    yield first_chunk_inputs.input_features[:, : processor.num_mel_frames_first_audio_chunk, :]

    mel_frame_idx = processor.num_mel_frames_first_audio_chunk
    hop_length = processor.feature_extractor.hop_length
    n_fft = processor.feature_extractor.n_fft

    start_idx = mel_frame_idx * hop_length - n_fft // 2
    while (end_idx := start_idx + processor.num_samples_per_audio_chunk) < audio.shape[0]:
        inputs = processor(
            audio[start_idx:end_idx],
            sampling_rate=sampling_rate,
            is_streaming=True,
            is_first_audio_chunk=False,
            language=language,
            return_tensors="pt",
        )
        inputs = inputs.to(model.device, dtype=model.dtype)
        yield inputs.input_features

        mel_frame_idx += processor.num_mel_frames_per_audio_chunk
        start_idx = mel_frame_idx * hop_length - n_fft // 2


streamer = TextIteratorStreamer(processor.tokenizer, skip_special_tokens=True)
generate_kwargs = {
    **first_chunk_inputs,
    "input_features": input_features_generator(),
    "streamer": streamer,
}
thread = Thread(target=model.generate, kwargs=generate_kwargs)
thread.start()

# Iterate over the streamer to get text chunks as they are generated
print("Model output (streaming):", end=" ", flush=True)
for text_chunk in streamer:
    print(text_chunk, end="", flush=True)
thread.join()

流式延迟

延迟由 num_lookahead_tokens 决定，即每个块在输出前等待的右侧注意力上下文（在子采样编码器帧中的前瞻）。较大的值使每个块能看到更多的未来音频：以更高的延迟为代价换取更高的准确性。查看支持的权衡选项，选择其中一个，并读取由此产生的延迟：

from transformers import AutoProcessor

processor = AutoProcessor.from_pretrained("nvidia/nemotron-3.5-asr-streaming-0.6b")

# Each supported `num_lookahead_tokens` mapped to its streaming latency in milliseconds:
print(processor.supported_streaming_latencies_ms)
# {3: 320, 0: 80, 6: 560, 13: 1120}

# Select a right attention context (this also re-derives the streaming chunk sizes used above):
processor.set_num_lookahead_tokens(6)

# Latency of the current selection:
print(processor.streaming_latency_ms)
# 560

set_num_lookahead_tokens 用于确定处理器输出的块大小，而对应的 num_lookahead_tokens 必须传递到 generate（在上面的代码片段中，它通过 **inputs/**first_chunk_inputs 传递，其中包含 num_lookahead_tokens）。流式 generate 在省略该参数时会抛出异常。

Nemotron3_5AsrConfig

class transformers.Nemotron3_5AsrConfig

< source >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0id2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Noneis_encoder_decoder: bool = Truevocab_size: int = 13088decoder_hidden_size: int = 640num_decoder_layers: int = 2hidden_act: str = 'relu'max_symbols_per_step: int = 10encoder_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonepad_token_id: int = 0blank_token_id: int = 13087num_prompts: int = 128prompt_intermediate_size: int = 2048default_prompt_id: int = 101 )

参数

is_encoder_decoder (bool，可选，默认为 True) — 指示该模型是否用作编码器/解码器。
vocab_size (int，可选，默认值为 13088) — 联合网络输出的词表大小（包含空白标记）。
decoder_hidden_size (int，可选，默认值为 640) — LSTM 预测网络的隐藏层大小（NeMo 的 pred_hidden）。
num_decoder_layers (int，可选，默认为 2) — 预测网络中 LSTM 层的数量。
hidden_act (str，可选，默认为 "relu") — 联合网络中的激活函数。
max_symbols_per_step (int，可选，默认为 10) — 在贪心解码过程中，每个编码器时间步输出的非空白符号的最大数量。
encoder_config (Union[dict, NemotronAsrStreamingEncoderConfig]，可选) — 编码器的配置对象或字典。由于编码器与 NemotronAsrStreaming 的完全相同，因此直接复用 NemotronAsrStreamingEncoderConfig。
pad_token_id (int, 可选，默认为 0) — 词表中用于填充的 token id。
blank_token_id (int，可选，默认为 13087) — 用于 RNN-T 解码的空白 token id。
num_prompts (int，可选，默认为 128) — 语言提示槽的数量。目标语言被编码为长度等于该值的 one-hot 向量，沿编码器时间轴进行广播，并在送入 prompt_kernel 融合 MLP 之前与编码器输出进行拼接。
prompt_intermediate_size (int，可选，默认为 2048) — prompt_kernel 融合 MLP 的隐藏层大小（Linear(hidden + num_prompts -> intermediate) -> ReLU -> Linear(intermediate -> hidden)）。
default_prompt_id (int, 可选，默认为 101) — 当未提供 prompt_ids 时，用于条件化模型的提示索引。默认使用 auto 语言检测槽位（在 NeMo 提示字典中索引为 101），与 NeMo 的默认值 target_lang="auto" 一致：模型自行检测语言并输出 <xx-XX> 标签。

这是用于存储 Nemotron3_5AsrForRNNT 配置的类。它根据指定的参数实例化 Nemotron3 5 Asr 模型，并定义模型架构。使用默认值实例化配置，将得到与 nvidia/nemotron-3.5-asr-streaming-0.6b 类似的配置。

配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。

示例：

>>> from transformers import Nemotron3_5AsrForRNNT, Nemotron3_5AsrConfig

>>> configuration = Nemotron3_5AsrConfig()
>>> model = Nemotron3_5AsrForRNNT(configuration)
>>> configuration = model.config

Nemotron3_5AsrProcessor

class transformers.Nemotron3_5AsrProcessor

< source >

( feature_extractortokenizerblank_token = '<blank>'decoder_type = Nonesupported_num_lookahead_tokens = Nonedefault_num_lookahead_tokens = Noneprompt_dictionary = Nonenum_prompts = 128 )

参数

feature_extractor（NemotronAsrStreamingFeatureExtractor）— 特征提取器是必需的输入。
tokenizer（ParakeetTokenizer）— 分词器是必需的输入。
blank_token (str，可选，默认为 "<blank>") — 用于 RNN-T 解码的空白标记。
decoder_type (str, 可选) — 解码/时间戳输出模式（例如 "ctc"、"rnnt"、"tdt"）。如果为 None，则会自动推断解码器类型以保持向后兼容。
supported_num_lookahead_tokens (list[int]，可选) — 支持的右侧注意力上下文（即子采样编码器帧中的前瞻），与 NemotronAsrStreamingEncoderConfig.supported_num_lookahead_tokens 保持一致。用于验证 streaming_latency_ms 并推导返回的 num_lookahead_tokens。
default_num_lookahead_tokens (int, 可选) — 当未提供 streaming_latency_ms 时使用的右侧上下文。默认值为 supported_num_lookahead_tokens 的第一个条目。
prompt_dictionary (dict[str, int], 可选) — 从目标语言字符串（例如 "en-US"、"de-DE"、纯代码 "de" 或 "auto"）到其提示索引的映射。默认使用 NeMo 检查点的提示字典。
num_prompts (int, 可选，默认为 128) — 语言提示槽的数量（one-hot 提示向量的大小），与 Nemotron3_5AsrConfig.num_prompts 保持一致。

构建一个 Nemotron3_5AsrProcessor，它将特征提取器和分词器封装为单个处理器。

Nemotron3_5AsrProcessor 提供了 NemotronAsrStreamingFeatureExtractor 和 ParakeetTokenizer 的所有功能。有关更多信息，请参阅 ~NemotronAsrStreamingFeatureExtractor 和 ~ParakeetTokenizer。

decode

< source >

( *argsdurations = None**kwargs )

将参数传递给 decode()，并像 NeMo 库那样对 token 级时间戳进行后处理（如果提供了 durations）。

set_num_lookahead_tokens

< source >

( num_lookahead_tokens: int )

选择用于流式处理的正确注意力上下文（前瞻，位于降采样编码器帧中）。

设置 default_num_lookahead_tokens，使所有派生的流式属性（num_mel_frames_first_audio_chunk、num_mel_frames_per_audio_chunk、num_samples_first_audio_chunk、num_samples_per_audio_chunk）均基于新值重新推导。num_lookahead_tokens 必须是 supported_num_lookahead_tokens 中的一个。

将相同的 num_lookahead_tokens 传递给 model.generate，以便前向传播中使用的注意力右侧上下文与此处生成的块大小相匹配；否则，流式 generate 会抛出异常。

Nemotron3_5AsrRNNTOutput

class transformers.Nemotron3_5AsrRNNTOutput

< source >

( last_hidden_state: typing.Optional[torch.Tensor] = Nonepooler_output: typing.Optional[torch.Tensor] = Nonehidden_states: tuple[torch.Tensor, ...] | None = Noneattentions: tuple[torch.Tensor, ...] | None = Noneloss: typing.Optional[torch.Tensor] = Nonelogits: typing.Optional[torch.Tensor] = Nonedecoder_cache: transformers.models.nemotron3_5_asr.generation_nemotron3_5_asr.Nemotron3_5AsrRNNTDecoderCache | None = Noneencoder_past_key_values: transformers.cache_utils.Cache | None = Nonepadding_cache: NemotronAsrStreamingEncoderCausalConvPaddingCache | None = None )

参数

last_hidden_state (torch.Tensor，形状为 (batch_size, sequence_length, hidden_size)) — 模型最后一层输出的隐藏状态序列。
pooler_output (torch.Tensor，形状为 (batch_size, hidden_size)) — 序列中第一个 token（分类 token）的最后一层隐藏状态，经过用于辅助预训练任务的层进一步处理后的结果。例如，对于 BERT 系列模型，这返回的是分类 token 经过线性层和 tanh 激活函数处理后的结果。线性层的权重在预训练期间通过下一句预测（分类）目标进行训练。
hidden_states (tuple(torch.Tensor), 可选, 当传入 output_hidden_states=True 或 config.output_hidden_states=True) — 的元组 torch.Tensor (（如果模型有嵌入层，则包含嵌入层输出的一个张量，加上每一层输出的一个张量），形状为 (batch_size, sequence_length, hidden_size).
模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
attentions (tuple(torch.Tensor), 可选, 在传入 output_attentions=True 或 config.output_attentions=True) — 的元组 torch.Tensor (（每层一个），形状为 (batch_size, num_heads, sequence_length, sequence_length).
注意力权重，即经过注意力 softmax 之后的权重，用于在自注意力头中计算加权平均值。
loss (torch.Tensor，可选，在提供 labels 时返回) — RNN-T 转换器损失。
logits (torch.Tensor，形状为 (batch_size, encoder_length, decoder_length, vocab_size + 1)) — 针对每个编码器/解码器帧对，联合网络在词汇表及空白符号上的得分。
decoder_cache (Nemotron3_5AsrRNNTDecoderCache, 可选) — 更新后的解码器 LSTM 缓存。在空白预测时复用，以跳过 LSTM 步骤。
encoder_past_key_values (Cache, 可选) — 更新后的编码器注意力 K/V 滑动窗口缓存，在使用 use_cache=True 对音频进行编码时返回（支持缓存的流式处理）。请将其传入下一个数据块的 forward。
padding_cache (NemotronAsrStreamingEncoderCausalConvPaddingCache，可选) — 更新后的统一流式卷积缓存（子采样 Conv2d + conformer 深度可分离 Conv1d），在通过 use_cache=True 对音频进行编码时返回。请将其传入下一个数据块的 forward。

Nemotron3_5AsrForRNNT

class transformers.Nemotron3_5AsrForRNNT

< source >

( config: Nemotron3_5AsrConfig )

参数

config (Nemotron3_5AsrConfig) — 模型的配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。

Nemotron3_5Asr 编码器，配备 RNN-T（循环神经网络转换器）头部以及语言 ID 提示条件。

该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch torch.nn.Module 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

forward

< source >

( input_features: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Nonedecoder_input_ids: typing.Optional[torch.LongTensor] = Nonedecoder_cache: transformers.models.nemotron3_5_asr.generation_nemotron3_5_asr.Nemotron3_5AsrRNNTDecoderCache | None = Noneuse_decoder_cache: bool | None = Noneencoder_outputs: transformers.modeling_outputs.BaseModelOutputWithPooling | None = Nonelabels: typing.Optional[torch.Tensor] = Nonenum_lookahead_tokens: int | None = Noneprompt_ids: typing.Optional[torch.LongTensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Nemotron3_5AsrRNNTOutput or tuple(torch.Tensor)

参数

input_features (torch.Tensor，形状为 (batch_size, sequence_length, feature_dim)，可选) — 与输入音频特征对应的张量。可以使用 feature_extractor_class 获取音频特征。有关详细信息，请参阅 feature_extractor_class.__call__（processor_class 使用 feature_extractor_class 来处理音频）。
attention_mask (torch.Tensor 形状为 (batch_size, sequence_length), ，可选) — 用于避免对填充 token 索引执行注意力机制的掩码。掩码值取自 [0, 1]:
- 1 表示未被屏蔽的 token，
- 对于被掩码的 token，值为 0。
什么是注意力掩码？
decoder_input_ids (torch.LongTensor，形状为 (batch_size, 1)，可选) — 用于单步推理的解码器输入 token id。
decoder_cache (Nemotron3_5AsrRNNTDecoderCache, 可选) — 解码器 LSTM 缓存。在空白预测时复用，以跳过 LSTM 步骤。
use_decoder_cache (bool，可选) — 在未提供解码器缓存时，是否分配并使用解码器缓存。
encoder_outputs (tuple(torch.Tensor)，可选) — 预计算的编码器输出（last_hidden_state、pooler_output、……）。
labels（形状为 (batch_size, sequence_length) 的 torch.Tensor，可选）— 用于计算掩码语言建模损失的标签。索引值应在 [0, ..., config.vocab_size] 范围内，或为 -100（参见 input_ids 的文档字符串）。索引值设为 -100 的 token 将被忽略（即被掩码），损失仅针对标签位于 [0, ..., config.vocab_size] 范围内的 token 进行计算。
num_lookahead_tokens (int, 可选) — 转发给编码器的右侧注意力上下文（前瞻，以子采样编码器帧为单位）。默认值为 config.encoder_config.default_num_lookahead_tokens。
prompt_ids（形状为 (batch_size,) 的 torch.LongTensor，可选） — 用于语言 ID 条件化的语言提示索引。由处理器根据 language 生成。随后转换为广播 one-hot 向量，供 prompt_projector 使用。

返回值

Nemotron3_5AsrRNNTOutput 或 tuple(torch.Tensor)

一个 Nemotron3_5AsrRNNTOutput 或 torch.Tensor 元组（当传入 return_dict=False 或 config.return_dict=False 时），其包含的元素取决于配置（None）和输入。

Nemotron3_5AsrForRNNT 的 forward 方法重写了 __call__ 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 Module 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者则会静默地忽略这些步骤。

last_hidden_state（形状为 (batch_size, sequence_length, hidden_size) 的 torch.Tensor）— 模型最后一层输出的隐藏状态序列。
pooler_output (torch.Tensor，形状为 (batch_size, hidden_size)) — 序列中第一个 token（分类 token）的最后一层隐藏状态，经过用于辅助预训练任务的层进一步处理后得到。例如，对于 BERT 系列模型，这返回的是分类 token 经过线性层和 tanh 激活函数处理后的结果。线性层的权重在预训练期间通过下一句预测（分类）目标进行训练。
hidden_states (tuple(torch.Tensor)，可选，当传入 output_hidden_states=True 或 config.output_hidden_states=True 时返回) — 一个 torch.Tensor 元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为 (batch_size, sequence_length, hidden_size)。

模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
attentions (tuple(torch.Tensor)，可选，当传入 output_attentions=True 或 config.output_attentions=True 时返回) — 一个 torch.Tensor 元组（每层一个），形状为 (batch_size, num_heads, sequence_length, sequence_length)。

注意力权重，即经过注意力 softmax 之后的权重，用于在自注意力头中计算加权平均值。
loss (torch.Tensor，可选，当提供 labels 时返回) — RNN-T 转换器损失。
logits（形状为 (batch_size, encoder_length, decoder_length, vocab_size + 1) 的 torch.Tensor）— 联合网络针对词表及空白符号的得分，对应每一对编码器/解码器帧。
decoder_cache (Nemotron3_5AsrRNNTDecoderCache，可选) — 更新后的解码器 LSTM 缓存。在预测为空白时复用，以跳过 LSTM 步骤。
encoder_past_key_values（Cache，可选）——更新后的编码器注意力 K/V 滑动窗口缓存，在使用 use_cache=True 对音频进行编码时返回（支持缓存的流式处理）。请将其传入下一个数据块的 forward 调用中。
padding_cache (NemotronAsrStreamingEncoderCausalConvPaddingCache，可选) — 更新后的统一流式卷积缓存（子采样 Conv2d + conformer 深度可分离 Conv1d），在通过 use_cache=True 对音频进行编码时返回。请将其传入下一个数据块的 forward 调用中。

示例：

>>> from transformers import AutoProcessor, Nemotron3_5AsrForRNNT
>>> from datasets import load_dataset, Audio

>>> model_id = "nvidia/nemotron-3.5-asr-streaming-0.6b"
>>> processor = AutoProcessor.from_pretrained(model_id)
>>> model = Nemotron3_5AsrForRNNT.from_pretrained(model_id)

>>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> ds = ds.cast_column("audio", Audio(sampling_rate=processor.feature_extractor.sampling_rate))

>>> inputs = processor(ds[0]["audio"]["array"], language="en-US")
>>> outputs = model(**inputs)

generate

< source >

( inputs = Nonegeneration_config = None**kwargs )

Update on GitHub

←Nemotron 3 说话人分离 Nemotron 3.5 Transcribe→