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

and get access to the augmented documentation experience

to get started

Ce modèle a été publié dans HF papers le 2025-09-11 et contribué à Hugging Face Transformers le 2026-09-02.

NeuCodec

SDPA

Aperçu

Le modèle NeuCodec a été proposé dans Finite Scalar Quantization Enables Redundant and Transmission-Robust Neural Audio Compression at Low Bit-rates.

NeuCodec est un codec audio neuronal qui s'appuie sur XCodec2. Il tire parti des fonctionnalités suivantes :

  • La quantification scalaire finie (FSQ) aboutit à un livre de codes unique, ce qui la rend idéale pour la modélisation en aval avec des modèles de langage vocaux.
  • Entraîné sur des données CC de sorte qu'il n'y a aucune restriction de données non commerciales.
  • À 50 jetons/s et 16 bits par jeton, le débit binaire global est de 0,8 kbit/s.
  • Le codec reçoit une entrée de 16 kHz et produit une sortie de 24 kHz à l'aide d'un décodeur de suréchantillonnage.
  • Le schéma d'encodage FSQ permet une résistance aux erreurs au niveau des bits, adaptée aux canaux non fiables et bruités.

Le code de modélisation original peut être trouvé ici.

Exemple d'utilisation

Voici un exemple rapide de l’encodage et du décodage d’un audio à l’aide de ce modèle :

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

Traitement par lots

Cette prise en charge prend également en charge les entrées par lots !

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

Accélération avec torch.compile

Vous pouvez accélérer l'inférence avec torch.compile. Les premiers appels seront plus lents en raison du surcoût de compilation, mais les appels suivants seront plus rapides.

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 )

Paramètres

  • hidden_size (int, facultatif, par défaut 1024) — Dimension des représentations cachées.
  • intermediate_size (int, facultatif, par défaut 4096) — Dimension des représentations du MLP.
  • num_hidden_layers (int, facultatif, par défaut 12) — Nombre de couches cachées dans le décodeur Transformer.
  • num_attention_heads (int, facultatif, valeur par défaut 16) — Nombre de têtes d'attention pour chaque couche d'attention du décodeur Transformer.
  • num_key_value_heads (int, facultatif, valeur par défaut 16) — Ceci est le nombre de têtes key_value à utiliser pour implémenter l'attention Grouped Query. Si num_key_value_heads=num_attention_heads, le modèle utilisera l'attention Multi Head (MHA), si num_key_value_heads=1 le modèle utilisera l'attention Multi Query (MQA), sinon l'attention GQA est utilisée. Lors de la conversion d'un checkpoint multi-têtes en checkpoint GQA, chaque tête clé et valeur de groupe doit être construite en effectuant un meanpooling de toutes les têtes d'origine au sein de ce groupe. Pour plus de détails, consultez ce papier. S'il n'est pas spécifié, la valeur par défaut sera num_attention_heads.
  • hidden_act (str, facultatif, par défaut silu) — La fonction d'activation non linéaire (fonction ou chaîne de caractères) du décodeur. Par exemple, "gelu", "relu", "silu", etc.
  • max_position_embeddings (int, facultatif, par défaut 4096) — La longueur de séquence maximale avec laquelle ce modèle pourrait être utilisé.
  • initializer_range (float, facultatif, par défaut 0.02) — L'écart-type de la truncated_normal_initializer utilisé pour initialiser toutes les matrices de poids.
  • rms_norm_eps (float, facultatif, valeur par défaut 1e-06) — L'épsilon utilisé par les couches de normalisation rms.
  • pad_token_id (int, facultatif) — Identifiant du jeton utilisé pour le bourrage dans le vocabulaire.
  • tie_word_embeddings (bool, facultatif, valeur par défaut False) — Indique s'il faut lier les embeddings de poids selon la correspondance tied_weights_keys du modèle.
  • rope_parameters (Union[~modeling_rope_utils.RopeParameters, dict], facultatif) — Dictionnaire contenant les paramètres de configuration pour les embeddings RoPE. Le dictionnaire doit contenir une valeur pour rope_theta et, le cas échéant, les paramètres utilisés pour le mise à l’échelle si vous souhaitez utiliser RoPE avec des max_position_embeddings plus longs.
  • attention_bias (bool, facultatif, par défaut False) — Indique s'il faut utiliser un biais dans les couches de projection des requêtes, des clés, des valeurs et de la sortie lors de l'auto-attention.
  • attention_dropout (Union[int, float], facultatif, valeur par défaut 0.0) — Le taux de dropout appliqué aux probabilités d'attention.
  • head_dim (int, facultatif, par défaut 64) — La dimension des têtes d'attention. Si None, elle est par défaut égale à hidden_size // num_attention_heads
  • encoder_hidden_size (int, facultatif, par défaut 48) — Dimension des représentations cachées.
  • downsampling_ratios (list[int], facultatif, par défaut [2, 2, 4, 4, 5]) — Ratios de sous-échantillonnage dans l'encodeur.
  • semantic_model_config (Union[Dict, Wav2Vec2BertConfig], facultatif) — Une instance de l'objet de configuration du modèle sémantique (Wav2Vec2BertConfig).
  • activation_dropout (float, facultatif, valeur par défaut 0.1) — Le taux de dropout appliqué aux activations à l'intérieur de la couche entièrement connectée.
  • quantization_dim (int, facultatif, valeur par défaut 2048) — Dimension du codebook de quantification vectorielle.
  • quantization_levels (list[int], facultatif, par défaut [4, 4, 4, 4, 4, 4, 4, 4]) — Niveaux pour le codebook de quantification vectorielle.
  • input_sampling_rate (int, facultatif, valeur par défaut 16000) — Taux d'échantillonnage, en hertz (Hz), de la forme d'onde audio en entrée de l'encodeur.
  • output_sampling_rate (int, facultatif, valeur par défaut 24000) — Taux d'échantillonnage, en hertz (Hz), de la forme d'onde audio en sortie du décodeur.

Ceci est la classe de configuration destinée à stocker la configuration d'un NeuCodecModel. Elle est utilisée pour instancier un modèle Neucodec en fonction des arguments spécifiés, définissant ainsi l'architecture du modèle. L'instanciation d'une configuration avec les valeurs par défaut produira une configuration similaire à celle de neuphonic/neucodec

Les objets de configuration héritent de PreTrainedConfig et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de PreTrainedConfig pour plus d’informations.

Exemple :

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

Paramètres

  • feature_size (int, facultatif, valeur par défaut 80) — La dimension des caractéristiques des fonctionnalités extraites.
  • sampling_rate (int, facultatif, valeur par défaut 16000) — La fréquence d'échantillonnage à laquelle les fichiers audio doivent être numérisés, exprimée en hertz (Hz).
  • padding_value (float, facultatif, valeur par défaut 1.0) — La valeur utilisée pour remplir les vecteurs de bourrage du spectrogramme mel.
  • hop_length (int, facultatif, par défaut 320) — Nombre d'échantillons audio encodés par trame. Équivalent au produit des ratios de sous-échantillonnage. Nécessaire pour le bourrage de l'entrée de l'encodeur acoustique.

Construit un extracteur de fonctionnalités NeuCodec, qui calcule les fonctionnalités de la banque de filtres mel pour l’encodeur sémantique et l’audio rembourré pour l’encodeur acoustique.

Cet extracteur de fonctionnalités hérite de SequenceFeatureExtractor, qui contient la plupart des méthodes principales. Les utilisateurs doivent se référer à cette superclasse pour plus d'informations sur ces méthodes.

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

Paramètres

  • audio (np.ndarray, torch.Tensor, list[np.ndarray], list[torch.Tensor]) — Tableau Numpy ou tenseur torch de forme (num_channels, sequence_length). Une liste de tels tableaux ou tenseurs peut également être fournie pour un lot d'entrées.
  • padding (bool, str ou PaddingStrategy, facultatif, défaut : True) — Sélectionne une stratégie pour mettre en place le padding des séquences renvoyées (selon le côté de padding et l'index de padding du modèle) parmi :
    • True ou 'longest' : Ajuster à la séquence la plus longue du lot (ou aucun ajustement si une seule séquence est fournie).
    • 'max_length' : Remplir jusqu'à une longueur maximale spécifiée par l'argument max_length ou jusqu'à la longueur d'entrée maximale acceptable pour le modèle si cet argument n'est pas fourni.
    • False ou 'do_not_pad' (par défaut) : aucun padding (c’est-à-dire, peut produire un lot avec des séquences de longueurs différentes).
  • max_length (int, facultatif) — Longueur maximale de la liste renvoyée et, le cas échéant, longueur du bourrage (voir ci-dessus).
  • truncation (bool) — Active la troncature pour couper les séquences d’entrée plus longues que max_length à max_length.
  • return_tensors (str ou TensorType, facultatif) — Si défini, renvoie des tenseurs au lieu d'une liste d'entiers Python. Les valeurs acceptées sont :
    • 'tf' : Renvoie des objets tf.constant de TensorFlow.
    • 'pt' : Renvoie des objets torch.Tensor de PyTorch.
    • 'np' : Renvoie des objets Numpy np.ndarray.
  • sampling_rate (int, facultatif) — La fréquence d’échantillonnage à laquelle l’entrée audio a été échantillonnée. Il est fortement recommandé de passer sampling_rate lors de l’appel forward afin d’éviter les erreurs silencieuses.
  • device (str, facultatif, par défaut "cpu") — Appareil pour les tenseurs PyTorch lors de l'extraction des caractéristiques de la banque de filtres mel.
  • kwargs (facultatif) — Dictionnaire restant des arguments par mot-clé qui seront transmis au tokenizer ou à l'extracteur de caractéristiques.

NeuCodecModel

classe transformers.NeuCodecModel

< >

( config: NeuCodecConfig )

Paramètres

  • config (NeuCodecConfig) — Classe de configuration du modèle contenant tous les paramètres du modèle. L’initialisation à partir d’un fichier de configuration ne charge pas les poids associés au modèle, uniquement la configuration. Consultez la méthode from_pretrained() pour charger les poids du modèle.

Modèle de codec audio neuronal NeuCodec.

Ce modèle hérite de PreTrainedModel. Consultez la documentation de la classe parente pour les méthodes génériques que la bibliothèque implémente pour tous ses modèles (tels que le téléchargement ou l'enregistrement, le redimensionnement des embeddings d'entrée, la taille des têtes, etc.)

Ce modèle est également une sous-classe de torch.nn.Module de PyTorch. Utilisez-le comme un module PyTorch standard et consultez la documentation de PyTorch pour tout ce qui concerne l'utilisation et le comportement généraux.

décoder

< >

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

Paramètres

  • audio_codes (torch.LongTensor de forme (batch_size, 1, codes_length)) — Indices de codes discrets calculés à l'aide de model.encode.
  • latents (torch.Tensor de forme (batch_size, dimension, time_steps), facultatif) — Représentation continue quantifiée de l'entrée.
  • audio_codes_mask (torch.Tensor de forme (batch_size, codes_length), facultatif) — Masque indiquant les positions valides (non remplies), tel que renvoyé par model.encode. Nécessaire pour un décodage par lots correct d’audios de longueurs variables.

Retourne

NeuCodecDecoderOutput ou tuple(torch.Tensor)

Un NeuCodecDecoderOutput ou un tuple de torch.Tensor (si return_dict=False est passé ou lorsque config.return_dict=False) comprenant divers éléments en fonction de la configuration (None) et des entrées.

  • audio_values (torch.Tensor de forme (batch_size, 1, segment_length), facultatif) — Valeurs de la forme d’onde audio décodée dans le domaine temporel, obtenues en convertissant les codes discrets en signaux audio continus. Cela représente l’audio reconstruit qui peut être lu.

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)

Paramètres

  • input_values (torch.Tensor de forme (batch_size, 1, sequence_length)) — Forme d'onde audio en entrée.
  • input_features (torch.Tensor de forme (batch_size, mel_bins, time_steps)) — Spectrogramme mélo de l'audio d'entrée pour l'encodage sémantique.
  • padding_mask (torch.Tensor de forme (batch_size, 1, sequence_length)) — Masque de bourrage utilisé pour bourrer input_values.
  • input_features_mask (torch.Tensor de forme (batch_size, time_steps), facultatif) — Masque d'attention pour l'entrée spectrogramme de l'encodeur sémantique. 1 pour les trames valides, 0 pour le bourrage.
  • output_latents (bool, facultatif, par défaut False) — Indique s'il faut retourner la représentation latente continue issue du quantificateur.

Retourne

NeuCodecEncoderOutput ou tuple(torch.Tensor)

Un NeuCodecEncoderOutput ou un tuple de torch.Tensor (si return_dict=False est passé ou lorsque config.return_dict=False) comprenant divers éléments en fonction de la configuration (None) et des entrées.

  • audio_codes (torch.LongTensor de forme (batch_size, 1, codes_length), facultatif) — Incrustations de codes discrets calculées à l’aide de model.encode. Elles représentent la forme compressée et quantifiée du signal audio d’entrée, utilisable pour le stockage, la transmission ou la génération.
  • latents (torch.Tensor de forme (batch_size, dimension, time_steps)) — Représentation continue quantifiée de l’embedding de l’entrée.
  • audio_codes_mask (torch.int32 de forme (batch_size, 1, codes_length), facultatif) — padding_mask sous-échantillonné indiquant les codes audio valides dans 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)

Paramètres

  • input_values (torch.Tensor de forme (batch_size, 1, sequence_length)) — Forme d'onde audio en entrée, échantillonnée à config.input_sampling_rate.
  • input_features (torch.Tensor de forme (batch_size, mel_bins, time_steps)) — Spectrogramme mélo de l'audio d'entrée pour l'encodage sémantique.
  • padding_mask (torch.Tensor de forme (batch_size, 1, sequence_length)) — Masque de bourrage utilisé pour bourrer input_values.
  • input_features_mask (torch.Tensor de forme (batch_size, time_steps), facultatif) — Masque d'attention pour l'entrée spectrogramme de l'encodeur sémantique. 1 pour les trames valides, 0 pour le bourrage.
  • output_latents (bool, facultatif, par défaut False) — Indique s'il faut retourner la représentation latente continue issue du quantificateur.

Retourne

NeuCodecOutput ou tuple(torch.Tensor)

Un NeuCodecOutput ou un tuple de torch.Tensor (si return_dict=False est passé ou lorsque config.return_dict=False) comprenant divers éléments en fonction de la configuration (None) et des entrées.

La méthode forward du NeuCodecModel redéfinit la méthode spéciale __call__.

Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance Module plutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement.

  • audio_values (torch.Tensor de forme (batch_size, 1, sequence_length), facultatif) — Valeurs de la forme d’onde audio décodée dans le domaine temporel, obtenues à l’aide de la partie décodeur de NeuCodec. Elles représentent le signal audio reconstruit.
  • audio_codes (torch.LongTensor de forme (batch_size, 1, codes_length), facultatif) — Incrustations de codes discrets calculées à l’aide de model.encode. Il s’agit des représentations quantifiées de l’audio d’entrée, utilisées pour un traitement ou une génération ultérieurs.
  • latents (torch.Tensor de forme (batch_size, dimension, time_steps)) — Représentation continue quantifiée de l’embedding de l’entrée.
  • audio_codes_mask (torch.int32 de forme (batch_size, 1, codes_length), facultatif) — padding_mask sous-échantillonné indiquant les codes audio valides dans audio_codes.

Exemples :

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