Transformers documentation

Nemotron 3.5 ASR

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).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Este modelo foi contribuído para o Hugging Face Transformers em 27/06/2026.

Nemotron 3.5 ASR

Visão geral

Nemotron 3.5 ASR é um modelo de reconhecimento de fala multilíngue com 600M de parâmetros da NVIDIA, projetado para transcrição de alta qualidade tanto em configurações de streaming de baixa latência quanto em processamento em lote de alto rendimento, com pontuação e capitalização nativas. Para streaming, ele oferece tamanhos de chunk configuráveis — 80ms, 160ms, 560ms e 1120ms —, permitindo que os usuários equilibrem latência e precisão de acordo com a aplicação. Sua arquitetura FastConformer-RNNT com suporte a cache é central para essa capacidade: diferentemente do streaming com buffer tradicional, que reprocessa repetidamente janelas de áudio sobrepostas, o modelo processa apenas cada novo chunk recebido, reutilizando o contexto do encoder em cache dos chunks anteriores. Isso elimina cálculos redundantes, melhora significativamente a eficiência e minimiza o atraso de ponta a ponta sem sacrificar a precisão, tornando-o adequado para cargas de trabalho de transcrição em tempo real.

Uso

Transcrição offline

Pipeline
AutoModel
from transformers import pipeline

pipe = pipeline(
    "automatic-speech-recognition",
    model="nvidia/nemotron-3.5-asr-streaming-0.6b",
)
out = pipe("https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/bcn_weather.mp3")
print(out)

O pipeline usa o prompt de idioma padrão (índice 0, en-US). Para condicionamento explícito de idioma ou detecção automática, passe o argumento language do processador (veja a aba AutoModel).

Transcrição em streaming

Esta é uma funcionalidade experimental e a API está sujeita a alterações.

Para transcrição em tempo real, o áudio é dividido em blocos seguindo:

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()

Latência de streaming

A latência é definida por num_lookahead_tokens, o contexto de atenção à direita (lookahead, em quadros de codificador subsampleados) que cada chunk aguarda antes de ser emitido. Um valor maior permite que cada chunk veja mais áudio futuro: melhor precisão ao custo de maior latência. Inspecione os trade-offs suportados, selecione um e leia de volta a latência resultante:

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 define o tamanho dos blocos emitidos pelo processador, e o correspondente num_lookahead_tokens deve chegar até generate (no trecho acima, ele é transmitido por meio de **inputs/**first_chunk_inputs, que carrega num_lookahead_tokens). O generate em streaming gera um erro se ele for omitido.

Nemotron3_5AsrConfig

classe transformers.Nemotron3_5AsrConfig

< >

( 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 )

Parâmetros

  • is_encoder_decoder (bool, opcional, padrão True) — Indica se o modelo é usado como encoder/decoder ou não.
  • vocab_size (int, opcional, padrão 13088) — Tamanho do vocabulário da saída da rede conjunta (incluindo o token em branco).
  • decoder_hidden_size (int, opcional, padrão 640) — Tamanho oculto da rede de previsão LSTM (pred_hidden do NeMo).
  • num_decoder_layers (int, opcional, padrão 2) — Número de camadas LSTM na rede de predição.
  • hidden_act (str, opcional, padrão "relu") — Função de ativação na rede conjunta.
  • max_symbols_per_step (int, opcional, padrão 10) — Número máximo de símbolos não vazios emitidos por passo de tempo do codificador durante a decodificação gulosa.
  • encoder_config (Union[dict, NemotronAsrStreamingEncoderConfig], opcional) — O objeto de configuração ou dicionário do encoder. Reutiliza diretamente NemotronAsrStreamingEncoderConfig, pois o encoder é idêntico ao de NemotronAsrStreaming.
  • pad_token_id (int, opcional, padrão 0) — ID do token usado para preenchimento no vocabulário.
  • blank_token_id (int, opcional, padrão 13087) — ID do token em branco para decodificação RNN-T.
  • num_prompts (int, opcional, padrão 128) — Número de slots de prompt de linguagem. O idioma alvo é codificado como um vetor one-hot deste tamanho, transmitido ao longo do eixo temporal do codificador e concatenado com a saída do codificador antes do MLP de fusão prompt_kernel.
  • prompt_intermediate_size (int, opcional, padrão 2048) — Tamanho oculto do MLP de fusão prompt_kernel (Linear(hidden + num_prompts -> intermediate) -> ReLU -> Linear(intermediate -> hidden)).
  • default_prompt_id (int, opcional, padrão 101) — Índice do prompt usado para condicionar o modelo quando prompt_ids não é fornecido. O padrão é o slot de detecção de idioma auto (índice 101 no dicionário de prompts do NeMo), correspondendo ao padrão do NeMo de target_lang="auto": o modelo detecta o idioma por conta própria e emite uma tag <xx-XX>.

Esta é a classe de configuração para armazenar a configuração de um Nemotron3_5AsrForRNNT. Ela é usada para instanciar um modelo Nemotron3 5 Asr de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do nvidia/nemotron-3.5-asr-streaming-0.6b

Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.

Exemplo:

>>> from transformers import Nemotron3_5AsrForRNNT, Nemotron3_5AsrConfig

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

Nemotron3_5AsrProcessor

classe transformers.Nemotron3_5AsrProcessor

< >

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

Parâmetros

  • feature_extractor (NemotronAsrStreamingFeatureExtractor) — O extrator de recursos é uma entrada obrigatória.
  • tokenizer (ParakeetTokenizer) — O tokenizer é uma entrada obrigatória.
  • blank_token (str, opcional, padrão "<blank>") — Token em branco para decodificação RNN-T.
  • decoder_type (str, opcional) — Modo de decodificação/emissão de timestamps (por exemplo, "ctc", "rnnt", "tdt"). Se None, o tipo de decodificador é inferido automaticamente para compatibilidade reversa.
  • supported_num_lookahead_tokens (list[int], opcional) — Contextos de atenção à direita suportados (lookaheads, em quadros de codificador subsampleados), espelhando NemotronAsrStreamingEncoderConfig.supported_num_lookahead_tokens. Usado para validar streaming_latency_ms e para derivar o num_lookahead_tokens retornado.
  • default_num_lookahead_tokens (int, opcional) — O contexto à direita usado quando streaming_latency_ms não é fornecido. O valor padrão é a primeira entrada de supported_num_lookahead_tokens.
  • prompt_dictionary (dict[str, int], opcional) — Mapeamento de uma string de idioma de destino (por exemplo, "en-US", "de-DE", o código simples "de" ou "auto") para o índice do prompt. O padrão é o dicionário de prompts do checkpoint do NeMo.
  • num_prompts (int, opcional, padrão 128) — Número de slots de prompt de linguagem (tamanho do vetor one-hot de prompt), espelhando Nemotron3_5AsrConfig.num_prompts.

Constrói um Nemotron3_5AsrProcessor que encapsula um extrator de recursos e um tokenizador em um único processador.

Nemotron3_5AsrProcessor oferece todas as funcionalidades de NemotronAsrStreamingFeatureExtractor e ParakeetTokenizer. Consulte ~NemotronAsrStreamingFeatureExtractor e ~ParakeetTokenizer para mais informações.

decode

< >

( *argsdurations = None**kwargs )

Encaminha os argumentos para decode() e faz o pós-processamento dos timestamps no nível de tokens (se durations forem fornecidos), conforme na biblioteca NeMo.

set_num_lookahead_tokens

< >

( num_lookahead_tokens: int )

Selecione o contexto de atenção adequado (lookahead, em quadros de codificador subsampleados) usado para streaming.

Define default_num_lookahead_tokens, de modo que todas as propriedades de streaming derivadas (num_mel_frames_first_audio_chunk, num_mel_frames_per_audio_chunk, num_samples_first_audio_chunk, num_samples_per_audio_chunk) sejam rederivadas a partir do novo valor. num_lookahead_tokens deve ser um dos valores de supported_num_lookahead_tokens.

Passe o mesmo num_lookahead_tokens para model.generate para que o contexto à direita da atenção usado no forward corresponda aos tamanhos de bloco produzidos aqui; caso contrário, o generate em streaming resultará em erro.

Nemotron3_5AsrRNNTOutput

classe transformers.Nemotron3_5AsrRNNTOutput

< >

( 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 )

Parâmetros

  • last_hidden_state (torch.Tensor de forma (batch_size, sequence_length, hidden_size)) — Sequência de estados ocultos na saída da última camada do modelo.
  • pooler_output (torch.Tensor de forma (batch_size, hidden_size)) — Estado oculto da última camada do primeiro token da sequência (token de classificação) após processamento adicional através das camadas usadas para a tarefa de pré-treinamento auxiliar. Por exemplo, para a família de modelos BERT, isso retorna o token de classificação após o processamento através de uma camada linear e uma função de ativação tanh. Os pesos da camada linear são treinados a partir do objetivo de previsão da próxima sentença (classificação) durante o pré-treinamento.
  • hidden_states (tuple(torch.Tensor), opcional, retornado quando output_hidden_states=True é passado ou quando config.output_hidden_states=True) — Tupla de torch.Tensor (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) de forma (batch_size, sequence_length, hidden_size).

    Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.

  • attentions (tuple(torch.Tensor), opcional, retornado quando output_attentions=True é passado ou quando config.output_attentions=True) — Tupla de torch.Tensor (um para cada camada) com a forma (batch_size, num_heads, sequence_length, sequence_length).

    Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nos cabeçalhos de autoatenção.

  • loss (torch.Tensor, opcional, retornado quando labels é fornecido) — Perda do transdutor RNN-T.
  • logits (torch.Tensor de forma (batch_size, encoder_length, decoder_length, vocab_size + 1)) — Pontuações da rede conjunta sobre o vocabulário mais o símbolo vazio, para cada par de quadros de codificador/decodificador.
  • decoder_cache (Nemotron3_5AsrRNNTDecoderCache, opcional) — Cache atualizado do LSTM do decoder. Reutilizado em previsões de blank para pular a etapa do LSTM.
  • encoder_past_key_values (Cache, optional) — Updated encoder attention K/V sliding-window cache, returned when encoding audio with use_cache=True (cache-aware streaming). Pass it to the next chunk’s forward.
  • padding_cache (NemotronAsrStreamingEncoderCausalConvPaddingCache, opcional) — Cache unificado de streaming conv atualizado (subsampling Conv2d + conformer depthwise Conv1d), retornado ao codificar áudio com use_cache=True. Passe-o para o próximo chunk no forward.

Nemotron3_5AsrForRNNT

classe transformers.Nemotron3_5AsrForRNNT

< >

( config: Nemotron3_5AsrConfig )

Parâmetros

  • config (Nemotron3_5AsrConfig) — Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método from_pretrained() para carregar os pesos do modelo.

Nemotron3_5Asr Encoder com uma cabeça RNN-T (Recurrent Neural Network Transducer) e condicionamento por prompt de ID de idioma.

Este modelo herda de PreTrainedModel. Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.)

Este modelo também é uma subclasse de torch.nn.Module do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso geral e ao comportamento.

forward

< >

( 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)

Parâmetros

  • input_features (torch.Tensor de forma (batch_size, sequence_length, feature_dim), opcional) — Os tensores correspondentes às características de áudio de entrada. As características de áudio podem ser obtidas usando feature_extractor_class. Consulte feature_extractor_class.__call__ para mais detalhes (processor_class usa feature_extractor_class para processar áudios).
  • attention_mask (torch.Tensor de forma (batch_size, sequence_length), opcional) — Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em [0, 1]:
    • 1 para tokens que não estão mascarados,
    • 0 para tokens que estão mascarados.

    O que são máscaras de atenção?

  • decoder_input_ids (torch.LongTensor de forma (batch_size, 1), opcional) — IDs de tokens de entrada do decodificador para inferência em etapa única.
  • decoder_cache (Nemotron3_5AsrRNNTDecoderCache, opcional) — Cache do LSTM do decodificador. Reutilizado em previsões de espaço em branco para pular a etapa do LSTM.
  • use_decoder_cache (bool, opcional) — Se deve alocar e usar um cache do decodificador quando nenhum for fornecido.
  • encoder_outputs (tuple(torch.Tensor), opcional) — Saídas pré-computadas do codificador (last_hidden_state, pooler_output, …).
  • labels (torch.Tensor de forma (batch_size, sequence_length), opcional) — Rótulos para o cálculo da perda de modelagem de linguagem mascarada. Os índices devem estar em [0, ..., config.vocab_size] ou ser -100 (veja a docstring de input_ids). Tokens com índices definidos como -100 são ignorados (mascarados); a perda é calculada apenas para os tokens com rótulos em [0, ..., config.vocab_size].
  • num_lookahead_tokens (int, opcional) — Contexto de atenção à direita (lookahead, em quadros do codificador subsampleados) encaminhado ao codificador. Padrão: config.encoder_config.default_num_lookahead_tokens.
  • prompt_ids (torch.LongTensor de forma (batch_size,), opcional) — Índices do prompt de linguagem para condicionamento de ID de linguagem. Gerados pelo processador a partir de language. Convertidos em one-hot broadcast consumido por prompt_projector.

Retorna

Nemotron3_5AsrRNNTOutput ou tuple(torch.Tensor)

Um Nemotron3_5AsrRNNTOutput ou uma tupla de torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários elementos, dependendo da configuração (None) e das entradas.

O método forward de Nemotron3_5AsrForRNNT substitui o método especial __call__.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de Module em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

  • last_hidden_state (torch.Tensor de forma (batch_size, sequence_length, hidden_size)) — Sequência de estados ocultos na saída da última camada do modelo.

  • pooler_output (torch.Tensor de forma (batch_size, hidden_size)) — Estado oculto da última camada do primeiro token da sequência (token de classificação) após processamento adicional através das camadas usadas para a tarefa de pré-treinamento auxiliar. Por exemplo, para a família de modelos BERT, isso retorna o token de classificação após o processamento através de uma camada linear e uma função de ativação tanh. Os pesos da camada linear são treinados a partir do objetivo de previsão da próxima frase (classificação) durante o pré-treinamento.

  • hidden_states (tuple(torch.Tensor), opcional, retornado quando output_hidden_states=True é passado ou quando config.output_hidden_states=True) — Tupla de torch.Tensor (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) de forma (batch_size, sequence_length, hidden_size).

    Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.

  • attentions (tuple(torch.Tensor), opcional, retornado quando output_attentions=True é passado ou quando config.output_attentions=True) — Tupla de torch.Tensor (um para cada camada) com forma (batch_size, num_heads, sequence_length, sequence_length).

    Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nos cabeçalhos de autoatenção.

  • loss (torch.Tensor, opcional, retornado quando labels é fornecido) — Perda do transdutor RNN-T.

  • logits (torch.Tensor de forma (batch_size, encoder_length, decoder_length, vocab_size + 1)) — Pontuações da rede conjunta sobre o vocabulário mais o símbolo blank, para cada par de frames de encoder/decoder.

  • decoder_cache (Nemotron3_5AsrRNNTDecoderCache, opcional) — Cache atualizado do LSTM do decoder. Reutilizado em previsões em branco para pular a etapa do LSTM.

  • encoder_past_key_values (Cache, optional) — Updated encoder attention K/V sliding-window cache, returned when encoding audio with use_cache=True (cache-aware streaming). Pass it to the next chunk’s forward.

  • padding_cache (NemotronAsrStreamingEncoderCausalConvPaddingCache, opcional) — Cache unificado de streaming conv atualizado (subsampling Conv2d + conformer depthwise Conv1d), retornado ao codificar áudio com use_cache=True. Passe-o para o próximo forward do chunk.

Exemplo:

>>> 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

< >

( inputs = Nonegeneration_config = None**kwargs )

Update on GitHub