Hugging Face's logo

Transformers documentation

NeuCodec

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 publicado no HF papers em 2025-09-11 e contribuído para o Hugging Face Transformers em 2026-09-02.

NeuCodec

SDPA

Visão geral

O modelo NeuCodec foi proposto em Finite Scalar Quantization Enables Redundant and Transmission-Robust Neural Audio Compression at Low Bit-rates.

NeuCodec é um codec de áudio neural que estende o XCodec2. Ele aproveita os seguintes recursos:

  • Quantização Escalar Finita (FSQ) resultando em um único codebook, tornando-a ideal para modelagem downstream com Speech Language Models.
  • Treinado com dados de CC de modo que não há restrições de dados não comerciais.
  • A 50 tokens/seg e 16 bits por token, a taxa de bits total é 0,8 kbps.
  • O codec recebe uma entrada de 16 kHz e produz uma saída de 24 kHz usando um decodificador de amostragem ascendente.
  • O esquema de codificação FSQ permite resistência a erros em nível de bit, adequado para canais não confiáveis e ruidosos.

O código de modelagem original pode ser encontrado aqui.

Exemplo de uso

Aqui está um exemplo rápido de como codificar e decodificar um áudio usando este modelo:

from datasets import Audio, load_dataset
from transformers import AutoFeatureExtractor, AutoModel

model_id = "neuphonic/neucodec"
model = AutoModel.from_pretrained(model_id, device_map="auto")
feature_extractor = AutoFeatureExtractor.from_pretrained(model_id)

dataset = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
dataset = dataset.cast_column("audio", Audio(sampling_rate=feature_extractor.sampling_rate))
audio = dataset[0]["audio"]["array"]
inputs = feature_extractor(audio=audio, sampling_rate=feature_extractor.sampling_rate, return_tensors="pt").to(
    model.device, model.dtype
)
print("Input waveform shape:", inputs["input_values"].shape)
# Input waveform shape: torch.Size([1, 1, 93760])

# encoder and decoder
audio_codes = model.encode(**inputs).audio_codes
print("Audio codes shape:", audio_codes.shape)
# Audio codes shape: torch.Size([1, 1, 292])
audio_values = model.decode(audio_codes).audio_values
print("Audio values shape:", audio_values.shape)

# Equivalently, you can do encoding and decoding in one step
model_output = model(**inputs)
audio_codes = model_output.audio_codes
audio_values = model_output.audio_values

Processamento em lote

Esta implementação também suporta entrada em lote!

from datasets import Audio, load_dataset
from transformers import AutoFeatureExtractor, AutoModel

batch_size = 2
model_id = "neuphonic/neucodec"
model = AutoModel.from_pretrained(model_id, device_map="auto")
feature_extractor = AutoFeatureExtractor.from_pretrained(model_id)

dataset = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
dataset = dataset.cast_column("audio", Audio(sampling_rate=feature_extractor.sampling_rate))
audios = [dataset[i]["audio"]["array"] for i in range(batch_size)]
inputs = feature_extractor(audio=audios, sampling_rate=feature_extractor.sampling_rate, return_tensors="pt").to(
    model.device, model.dtype
)
print("Input waveform shape:", inputs["input_values"].shape)
# Input waveform shape: torch.Size([2, 1, 93760])

# encoder and decoder
encoder_output = model.encode(**inputs)
audio_codes = encoder_output.audio_codes
print("Audio codes shape:", audio_codes.shape)
# Audio codes shape: torch.Size([2, 1, 292])
audio_values = model.decode(audio_codes).audio_values
print("Audio values shape:", audio_values.shape)

# Equivalently, you can do encoding and decoding in one step
model_output = model(**inputs)
audio_codes = model_output.audio_codes
audio_values = model_output.audio_values

Aceleração com torch.compile

Você pode acelerar a inferência com torch.compile. As primeiras chamadas serão mais lentas devido ao overhead de compilação, mas as chamadas subsequentes serão mais rápidas.

import torch
from datasets import Audio, load_dataset
from transformers import AutoFeatureExtractor, AutoModel

batch_size = 4
model_id = "neuphonic/neucodec"
model = AutoModel.from_pretrained(model_id, device_map="auto")
feature_extractor = AutoFeatureExtractor.from_pretrained(model_id)

dataset = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
dataset = dataset.cast_column("audio", Audio(sampling_rate=feature_extractor.sampling_rate))
audios = [dataset[i]["audio"]["array"] for i in range(batch_size)]
inputs = feature_extractor(
    audio=audios, sampling_rate=feature_extractor.sampling_rate, padding=True, return_tensors="pt"
).to(model.device, model.dtype)

compiled_model = torch.compile(model, fullgraph=True)

# Warmup (includes compilation on first call)
for _ in range(10):
    with torch.inference_mode():
        _ = compiled_model(**inputs)

with torch.inference_mode():
    output = compiled_model(**inputs)
print("Audio values shape:", output.audio_values.shape)

NeuCodecConfig

classe transformers.NeuCodecConfig

< >

( 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 = 0is_encoder_decoder: bool = Falseid2label: 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 = Nonehidden_size: int = 1024intermediate_size: int = 4096num_hidden_layers: int = 12num_attention_heads: int = 16num_key_value_heads: int = 16hidden_act: str = 'silu'max_position_embeddings: int = 4096initializer_range: float = 0.02rms_norm_eps: float = 1e-06pad_token_id: int | None = Nonetie_word_embeddings: bool = Falserope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = Noneattention_bias: bool = Falseattention_dropout: int | float | None = 0.0head_dim: int = 64encoder_hidden_size: int = 48downsampling_ratios: list[int] | tuple[int, ...] = (2, 2, 4, 4, 5)semantic_model_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneactivation_dropout: float = 0.1quantization_dim: int = 2048quantization_levels: list[int] | tuple[int, ...] = (4, 4, 4, 4, 4, 4, 4, 4)input_sampling_rate: int = 16000output_sampling_rate: int = 24000 )

Parâmetros

  • hidden_size (int, opcional, padrão 1024) — Dimensão das representações ocultas.
  • intermediate_size (int, opcional, padrão 4096) — Dimensão das representações do MLP.
  • num_hidden_layers (int, opcional, padrão 12) — Número de camadas ocultas no decodificador do Transformer.
  • num_attention_heads (int, opcional, padrão 16) — Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer.
  • num_key_value_heads (int, opcional, padrão 16) — Este é o número de cabeças de key_value que devem ser usadas para implementar Grouped Query Attention. Se num_key_value_heads=num_attention_heads, o modelo usará Multi Head Attention (MHA); se num_key_value_heads=1, o modelo usará Multi Query Attention (MQA); caso contrário, será usado GQA. Ao converter um checkpoint multi-head para um checkpoint GQA, cada grupo de cabeças de key e value deve ser construído por meio do meanpooling de todas as cabeças originais dentro desse grupo. Para mais detalhes, consulte este artigo. Se não for especificado, o valor padrão será num_attention_heads.
  • hidden_act (str, opcional, padrão silu) — A função de ativação não linear (função ou string) no decodificador. Por exemplo, "gelu", "relu", "silu", etc.
  • max_position_embeddings (int, opcional, padrão 4096) — O comprimento máximo de sequência com o qual este modelo pode ser utilizado.
  • initializer_range (float, opcional, padrão 0.02) — O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.
  • rms_norm_eps (float, opcional, padrão 1e-06) — O epsilon usado pelas camadas de normalização rms.
  • pad_token_id (int, opcional) — ID do token usado para preenchimento no vocabulário.
  • tie_word_embeddings (bool, opcional, padrão False) — Se deve vincular as embeddings de pesos de acordo com o mapeamento tied_weights_keys do modelo.
  • rope_parameters (Union[~modeling_rope_utils.RopeParameters, dict], opcional) — Dicionário contendo os parâmetros de configuração para os embeddings RoPE. O dicionário deve conter um valor para rope_theta e, opcionalmente, parâmetros usados para escalonamento, caso você queira usar RoPE com max_position_embeddings maiores.
  • attention_bias (bool, opcional, padrão False) — Indica se deve ser usado um viés nas camadas de projeção de query, key, value e output durante a autoatenção.
  • attention_dropout (Union[int, float], opcional, padrão 0.0) — A taxa de dropout para as probabilidades de atenção.
  • head_dim (int, opcional, padrão 64) — A dimensão da cabeça de atenção. Se for None, o valor padrão será hidden_size // num_attention_heads
  • encoder_hidden_size (int, opcional, padrão 48) — Dimensão das representações ocultas.
  • downsampling_ratios (list[int], opcional, padrão [2, 2, 4, 4, 5]) — Razões para redução de amostragem no codificador.
  • semantic_model_config (Union[Dict, Wav2Vec2BertConfig], opcional) — Uma instância do objeto de configuração para o modelo semântico (Wav2Vec2BertConfig).
  • activation_dropout (float, opcional, padrão 0.1) — A taxa de dropout para as ativações dentro da camada totalmente conectada.
  • quantization_dim (int, opcional, padrão 2048) — Dimensão do codebook de quantização vetorial.
  • quantization_levels (list[int], opcional, padrão [4, 4, 4, 4, 4, 4, 4, 4]) — Níveis para o codebook de quantização vetorial.
  • input_sampling_rate (int, opcional, padrão 16000) — Taxa de amostragem, em hertz (Hz), da forma de onda de áudio de entrada do codificador.
  • output_sampling_rate (int, opcional, padrão 24000) — Taxa de amostragem, em hertz (Hz), da forma de onda de áudio de saída do decodificador.

Esta é a classe de configuração para armazenar a configuração de um NeuCodecModel. Ela é usada para instanciar um modelo Neucodec 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 neuphonic/neucodec

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 NeuCodecConfig, NeuCodecModel

>>> # Initializing configuration
>>> configuration = NeuCodecConfig()

>>> # Initializing a model (with random weights) from the configuration
>>> model = NeuCodecModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

NeuCodecFeatureExtractor

classe transformers.NeuCodecFeatureExtractor

< >

( feature_size = 80sampling_rate = 16000padding_value = 1.0hop_length = 320**kwargs )

Parâmetros

  • feature_size (int, opcional, padrão 80) — A dimensão dos recursos das características extraídas.
  • sampling_rate (int, opcional, padrão 16000) — A taxa de amostragem na qual os arquivos de áudio devem ser digitalizados, expressa em hertz (Hz).
  • padding_value (float, opcional, padrão 1.0) — O valor usado para preencher os vetores de padding do espectrograma mel.
  • hop_length (int, opcional, padrão 320) — Número de amostras de áudio codificadas por quadro. Equivale ao produto das taxas de redução de amostragem. Necessário para o preenchimento da entrada do codificador acústico.

Constrói um extrator de recursos NeuCodec, que calcula recursos de banco de filtros mel para o codificador semântico e áudio com preenchimento para o codificador acústico.

Este extrator de características herda de SequenceFeatureExtractor, que contém a maioria dos métodos principais. Os usuários devem consultar essa superclasse para obter mais informações sobre esses métodos.

__call__

< >

( audio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor']]padding: bool | str | transformers.utils.generic.PaddingStrategy = Truemax_length: int | None = Nonetruncation: bool = Falsereturn_tensors: str | transformers.utils.generic.TensorType | None = Nonesampling_rate: int | None = Nonedevice: str = 'cpu'**kwargs )

Parâmetros

  • audio (np.ndarray, torch.Tensor, list[np.ndarray], list[torch.Tensor]) — Array NumPy ou tensor torch com forma (num_channels, sequence_length). Também é possível fornecer uma lista desses arrays ou tensors para um lote de entradas.
  • padding (bool, str ou PaddingStrategy, opcional, padrão é True) — Selecione uma estratégia para aplicar padding às sequências retornadas (de acordo com o lado de padding e o índice de padding do modelo) entre:
    • True ou 'longest': Preenche até a sequência mais longa do lote (ou não aplica preenchimento se apenas uma sequência for fornecida).
    • 'max_length': Preenche até o comprimento máximo especificado com o argumento max_length ou até o comprimento máximo aceitável de entrada para o modelo, caso esse argumento não seja fornecido.
    • False ou 'do_not_pad' (padrão): Sem padding (ou seja, pode gerar um lote com sequências de comprimentos diferentes).
  • max_length (int, opcional) — Comprimento máximo da lista retornada e, opcionalmente, o comprimento do padding (veja acima).
  • truncation (bool) — Ativa a truncagem para cortar sequências de entrada com comprimento maior que max_length para max_length.
  • return_tensors (str ou TensorType, opcional) — Se definido, retornará tensors em vez de uma lista de inteiros do Python. Os valores aceitos são:
    • 'tf': Retorna objetos tf.constant do TensorFlow.
    • 'pt': Retorna objetos torch.Tensor do PyTorch.
    • 'np': Retorna objetos np.ndarray do Numpy.
  • sampling_rate (int, opcional) — A taxa de amostragem na qual a entrada de audio foi amostrada. É fortemente recomendável passar sampling_rate na chamada de forward para evitar erros silenciosos.
  • device (str, opcional, padrão "cpu") — Dispositivo para tensores do PyTorch durante a extração de recursos do banco de filtros mel.
  • kwargs (opcional) — Dicionário restante de argumentos por palavra-chave que será passado para o tokenizer ou o extrator de recursos.

NeuCodecModel

classe transformers.NeuCodecModel

< >

( config: NeuCodecConfig )

Parâmetros

  • config (NeuCodecConfig) — 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.

Modelo de codec de áudio neural NeuCodec.

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.

decode

< >

( audio_codes: typing.Optional[torch.Tensor] = Nonelatents: typing.Optional[torch.Tensor] = Noneaudio_codes_mask: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → NeuCodecDecoderOutput or tuple(torch.Tensor)

Parâmetros

  • audio_codes (torch.LongTensor de forma (batch_size, 1, codes_length)) — Índices de códigos discretos calculados usando model.encode.
  • latents (torch.Tensor de forma (batch_size, dimension, time_steps), opcional) — Representação contínua quantizada da entrada.
  • audio_codes_mask (torch.Tensor de forma (batch_size, codes_length), opcional) — Máscara que marca as posições válidas (sem preenchimento), conforme retornado por model.encode. Necessária para a decodificação em lote correta de áudios de comprimento variável.

Retorna

NeuCodecDecoderOutput ou tuple(torch.Tensor)

Um NeuCodecDecoderOutput 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.

  • audio_values (torch.Tensor de forma (batch_size, 1, segment_length), opcional) — Valores da forma de onda de áudio decodificada no domínio do tempo, obtidos convertendo os códigos discretos de volta em sinais de áudio contínuos. Isso representa o áudio reconstruído que pode ser reproduzido.

encode

< >

( input_values: Tensorinput_features: Tensorpadding_mask: typing.Optional[torch.Tensor] = Noneinput_features_mask: typing.Optional[torch.Tensor] = Noneoutput_latents: bool = False**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → NeuCodecEncoderOutput or tuple(torch.Tensor)

Parâmetros

  • input_values (torch.Tensor de forma (batch_size, 1, sequence_length)) — Forma de onda de áudio de entrada.
  • input_features (torch.Tensor de forma (batch_size, mel_bins, time_steps)) — Espectrograma mel de áudio de entrada para codificação semântica.
  • padding_mask (torch.Tensor de forma (batch_size, 1, sequence_length)) — Máscara de preenchimento usada para preencher input_values.
  • input_features_mask (torch.Tensor de forma (batch_size, time_steps), opcional) — Máscara de atenção para a entrada do espectrograma no codificador semântico. 1 para quadros válidos, 0 para preenchimento.
  • output_latents (bool, opcional, padrão False) — Se deve retornar a representação latente contínua do quantizador.

Retorna

NeuCodecEncoderOutput ou tuple(torch.Tensor)

Uma NeuCodecEncoderOutput 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.

  • audio_codes (torch.LongTensor de forma (batch_size, 1, codes_length), opcional) — Embebidings de códigos discretos calculados usando model.encode. Esses representam a forma comprimida e quantizada do sinal de áudio de entrada que pode ser usada para armazenamento, transmissão ou geração.
  • latents (torch.Tensor de forma (batch_size, dimension, time_steps)) — Representação contínua quantizada do embedding de entrada.
  • audio_codes_mask (torch.int32 de forma (batch_size, 1, codes_length), opcional) — padding_mask reduzido para indicar os códigos de áudio válidos em audio_codes.

forward

< >

( input_values: Tensorinput_features: Tensorpadding_mask: typing.Optional[torch.Tensor] = Noneinput_features_mask: typing.Optional[torch.Tensor] = Noneoutput_latents: bool = False**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → NeuCodecOutput or tuple(torch.Tensor)

Parâmetros

  • input_values (torch.Tensor de forma (batch_size, 1, sequence_length)) — Forma de onda de áudio de entrada, amostrada em config.input_sampling_rate.
  • input_features (torch.Tensor de forma (batch_size, mel_bins, time_steps)) — Espectrograma mel de áudio de entrada para codificação semântica.
  • padding_mask (torch.Tensor de forma (batch_size, 1, sequence_length)) — Máscara de preenchimento usada para preencher input_values.
  • input_features_mask (torch.Tensor de forma (batch_size, time_steps), opcional) — Máscara de atenção para a entrada do espectrograma no codificador semântico. 1 para quadros válidos, 0 para preenchimento.
  • output_latents (bool, opcional, padrão False) — Se deve retornar a representação latente contínua do quantizador.

Retorna

NeuCodecOutput ou tuple(torch.Tensor)

Um NeuCodecOutput 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 do NeuCodecModel sobrescreve 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.

  • audio_values (torch.Tensor de forma (batch_size, 1, sequence_length), opcional) — Valores da forma de onda de áudio decodificados no domínio do tempo, obtidos usando a parte decodificadora do NeuCodec. Esses valores representam o sinal de áudio reconstruído.
  • audio_codes (torch.LongTensor de forma (batch_size, 1, codes_length), opcional) — Embebidings de códigos discretos calculados usando model.encode. Estas são as representações quantizadas do áudio de entrada usadas para processamento ou geração adicionais.
  • latents (torch.Tensor de forma (batch_size, dimension, time_steps)) — Representação contínua quantizada do embedding de entrada.
  • audio_codes_mask (torch.int32 de forma (batch_size, 1, codes_length), opcional) — padding_mask reduzido para indicar os códigos de áudio válidos em audio_codes.

Exemplos:

>>> from datasets import load_dataset
>>> from transformers import AutoFeatureExtractor, NeuCodecModel

>>> dataset = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> audio = dataset["train"]["audio"][0]["array"]

>>> model_id = "neuphonic/neucodec"
>>> model = NeuCodecModel.from_pretrained(model_id)
>>> feature_extractor = AutoFeatureExtractor.from_pretrained(model_id)

>>> inputs = feature_extractor(audio=audio, sampling_rate=feature_extractor.sampling_rate, return_tensors="pt")

>>> outputs = model(**inputs)
>>> audio_codes = outputs.audio_codes
>>> audio_values = outputs.audio_values  # sampled at 24kHz
Update on GitHub

←Nemotron ASR Streaming Parakeet→