Transformers documentation
NeuCodec
Este modelo se publicó en HF papers el 2025-09-11 y se contribuyó a Hugging Face Transformers el 2026-09-02.
NeuCodec
Resumen
El modelo NeuCodec se propuso en Finite Scalar Quantization Enables Redundant and Transmission-Robust Neural Audio Compression at Low Bit-rates.
NeuCodec es un códec de audio neuronal que extiende XCodec2. Aprovecha las siguientes características:
- La cuantización escalar finita (FSQ) da como resultado un único libro de códigos, lo que la hace ideal para el modelado posterior con modelos de lenguaje de voz.
- Entrenado con datos de CC de modo que no hay restricciones de datos no comerciales.
- A 50 tokens/seg y 16 bits por token, la tasa de bits total es de 0.8kbps.
- El códec recibe una entrada de 16 kHz y produce una salida de 24 kHz mediante un decodificador de remuestreo ascendente.
- El esquema de codificación FSQ permite una resistencia a errores a nivel de bits adecuada para canales poco fiables y ruidosos.
El código de modelado original se puede encontrar aquí.
Ejemplo de uso
Aquí hay un ejemplo rápido de cómo codificar y decodificar un audio con 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_valuesProcesamiento por lotes
¡Esta implementación también admite entradas por lotes!
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_valuesAceleración con torch.compile
Puede acelerar la inferencia con torch.compile. Las primeras llamadas serán más lentas debido a la sobrecarga de compilación, pero las llamadas posteriores serán más 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
clase transformers.NeuCodecConfig
< 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 = 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, valor predeterminado1024) — Dimensión de las representaciones ocultas. - intermediate_size (
int, opcional, valor predeterminado4096) — Dimensión de las representaciones del MLP. - num_hidden_layers (
int, opcional, valor predeterminado12) — Número de capas ocultas en el decodificador del Transformer. - num_attention_heads (
int, opcional, valor predeterminado16) — Número de cabezas de atención para cada capa de atención en el decodificador Transformer. - num_key_value_heads (
int, opcional, valor predeterminado16) — Este es el número de cabezas key_value que se deben utilizar para implementar Grouped Query Attention. Sinum_key_value_heads=num_attention_heads, el modelo utilizará Multi Head Attention (MHA); sinum_key_value_heads=1, el modelo utilizará Multi Query Attention (MQA); en caso contrario, se utilizará GQA. Al convertir un checkpoint multi-head en un checkpoint GQA, cada cabeza de clave y valor del grupo debe construirse mediante el promediado (meanpooling) de todas las cabezas originales dentro de ese grupo. Para más detalles, consulta este artículo. Si no se especifica, el valor predeterminado seránum_attention_heads. - hidden_act (
str, opcional, valor predeterminadosilu) — La función de activación no lineal (función o cadena) en el decodificador. Por ejemplo,"gelu","relu","silu", etc. - max_position_embeddings (
int, opcional, valor predeterminado4096) — La longitud máxima de secuencia con la que se podría utilizar este modelo. - initializer_range (
float, opcional, valor predeterminado0.02) — La desviación estándar del truncated_normal_initializer para inicializar todas las matrices de pesos. - rms_norm_eps (
float, opcional, valor predeterminado1e-06) — El epsilon utilizado por las capas de normalización rms. - pad_token_id (
int, opcional) — Id del token utilizado para el relleno en el vocabulario. - tie_word_embeddings (
bool, opcional, valor predeterminadoFalse) — Si se deben vincular las matrices de pesos de embeddings según el mapeotied_weights_keysdel modelo. - rope_parameters (
Union[~modeling_rope_utils.RopeParameters, dict], opcional) — Diccionario que contiene los parámetros de configuración para las incrustaciones RoPE. El diccionario debe contener un valor pararope_thetay, opcionalmente, parámetros utilizados para el escalado en caso de que desee usar RoPE conmax_position_embeddingsmás largos. - attention_bias (
bool, opcional, valor predeterminadoFalse) — Si se debe usar un sesgo en las capas de proyección de consulta, clave, valor y salida durante la autoatención. - attention_dropout (
Union[int, float], opcional, valor predeterminado0.0) — La proporción de dropout para las probabilidades de atención. - head_dim (
int, opcional, valor predeterminado64) — La dimensión de la cabeza de atención. Si es None, se establecerá en hidden_size // num_attention_heads - encoder_hidden_size (
int, opcional, valor predeterminado48) — Dimensión de las representaciones ocultas. - downsampling_ratios (
list[int], opcional, valor predeterminado[2, 2, 4, 4, 5]) — Proporciones para el muestreo descendente en el codificador. - semantic_model_config (
Union[Dict, Wav2Vec2BertConfig], opcional) — Una instancia del objeto de configuración para el modelo semántico (Wav2Vec2BertConfig). - activation_dropout (
float, opcional, valor predeterminado0.1) — La proporción de dropout para las activaciones dentro de la capa totalmente conectada. - quantization_dim (
int, opcional, valor predeterminado 2048) — Dimensión del libro de códigos de cuantización vectorial. - quantization_levels (
list[int], opcional, por defecto[4, 4, 4, 4, 4, 4, 4, 4]) — Niveles para el libro de códigos de cuantización vectorial. - input_sampling_rate (
int, opcional, valor predeterminado 16000) — Tasa de muestreo, en hercios (Hz), de la forma de onda de audio de entrada del codificador. - output_sampling_rate (
int, opcional, valor predeterminado 24000) — Frecuencia de muestreo, en hercios (Hz), de la forma de onda de audio de salida del decodificador.
Esta es la clase de configuración para almacenar la configuración de un NeuCodecModel. Se utiliza para instanciar un modelo Neucodec según los argumentos especificados, definiendo la arquitectura del modelo. Instanciar una configuración con los valores predeterminados producirá una configuración similar a la de neuphonic/neucodec
Los objetos de configuración heredan de PreTrainedConfig y se pueden usar para controlar las salidas del modelo. Lea la documentación de PreTrainedConfig para obtener más información.
Ejemplo:
>>> 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.configNeuCodecFeatureExtractor
clase transformers.NeuCodecFeatureExtractor
< source >( feature_size = 80sampling_rate = 16000padding_value = 1.0hop_length = 320**kwargs )
Parámetros
- feature_size (
int, opcional, valor predeterminado 80) — La dimensión de las características de las características extraídas. - sampling_rate (
int, opcional, valor predeterminado 16000) — La tasa de muestreo a la que deben digitalizarse los archivos de audio, expresada en hercios (Hz). - padding_value (
float, opcional, valor predeterminado 1.0) — El valor que se utiliza para rellenar los vectores de relleno del espectrograma mel. - hop_length (
int, opcional, valor predeterminado 320) — Número de muestras de audio codificadas por cuadro. Equivalente al producto de las proporciones de reducción de muestreo. Necesario para el relleno de la entrada del codificador acústico.
Construye un extractor de características de NeuCodec, que calcula las características del banco de filtros mel para el codificador semántico y el audio relleno para el codificador acústico.
Este extractor de características hereda de SequenceFeatureExtractor, que contiene la mayoría de los métodos principales. Los usuarios deben consultar esta superclase para obtener más información sobre dichos métodos.
__call__
< source >( 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]) — Matriz de Numpy o tensor de torch con forma (num_channels, sequence_length). También se puede proporcionar una lista de dichas matrices o tensors para un lote de entradas. - padding (
bool,stro PaddingStrategy, opcional, por defectoTrue) — Seleccione una estrategia para rellenar las secuencias devueltas (según el lado de relleno y el índice de relleno del modelo) entre:Trueo'longest': Rellena hasta la secuencia más larga del lote (o no aplica relleno si solo se proporciona una secuencia).'max_length': Rellena hasta una longitud máxima especificada con el argumentomax_lengtho hasta la longitud de entrada máxima aceptable para el modelo si no se proporciona dicho argumento.Falseo'do_not_pad'(predeterminado): Sin relleno (es decir, puede generar un lote con secuencias de diferentes longitudes).
- max_length (
int, opcional) — Longitud máxima de la lista devuelta y, opcionalmente, longitud de relleno (véase arriba). - truncation (
bool) — Activa la truncación para recortar las secuencias de entrada más largas que max_length a max_length. - return_tensors (
stro TensorType, opcional) — Si se establece, devolverá tensores en lugar de una lista de enteros de Python. Los valores aceptables son:'tf': Devuelve objetostf.constantde TensorFlow.'pt': Devuelve objetostorch.Tensorde PyTorch.'np': Devuelve objetos Numpynp.ndarray.
- sampling_rate (
int, opcional) — La tasa de muestreo a la que se muestreó la entrada deaudio. Se recomienda encarecidamente pasarsampling_rateen la llamada de forward para evitar errores silenciosos. - device (
str, opcional, valor predeterminado"cpu") — Dispositivo para los tensores de PyTorch durante la extracción de características del banco de filtros mel. - kwargs (opcional) — Diccionario restante de argumentos por nombre que se pasará al tokenizador o al extractor de características.
NeuCodecModel
clase transformers.NeuCodecModel
< source >( config: NeuCodecConfig )
Parámetros
- config (NeuCodecConfig) — Clase de configuración del modelo con todos los parámetros del modelo. Inicializar con un archivo de configuración no carga los pesos asociados con el modelo, solo la configuración. Consulte el método from_pretrained() para cargar los pesos del modelo.
Modelo de códec de audio neuronal NeuCodec.
Este modelo hereda de PreTrainedModel. Consulta la documentación de la clase superior para los métodos genéricos que la biblioteca implementa para todos sus modelos (como la descarga o el guardado, el redimensionamiento de las incrustaciones de entrada, la poda de cabezas, etc.).
Este modelo también es una subclase de torch.nn.Module de PyTorch. Úsalo como un módulo de PyTorch regular y consulta la documentación de PyTorch para todo lo relacionado con el uso y el comportamiento generales.
decode
< source >( 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.LongTensorde forma(batch_size, 1, codes_length)) — Índices de códigos discretos calculados usandomodel.encode. - latents (
torch.Tensorde forma(batch_size, dimension, time_steps), opcional) — Representación continua cuantizada de la entrada. - audio_codes_mask (
torch.Tensorde forma(batch_size, codes_length), opcional) — Máscara que marca las posiciones válidas (sin relleno), tal como la devuelvemodel.encode. Necesaria para la decodificación por lotes correcta de audio de longitud variable.
Devuelve
NeuCodecDecoderOutput o tuple(torch.Tensor)
Un NeuCodecDecoderOutput o una tupla de
torch.Tensor (si se pasa return_dict=False o cuando config.return_dict=False) que comprende varios
elementos según la configuración (None) y las entradas.
- audio_values (
torch.Tensorde forma(batch_size, 1, segment_length), opcional) — Valores de la forma de onda de audio decodificada en el dominio del tiempo, obtenidos al convertir los códigos discretos de vuelta en señales de audio continuas. Esto representa el audio reconstruido que se puede reproducir.
encode
< source >( 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.Tensorde forma(batch_size, 1, sequence_length)) — Forma de onda de audio de entrada. - input_features (
torch.Tensorde forma(batch_size, mel_bins, time_steps)) — Espectrograma mel de audio de entrada para la codificación semántica. - padding_mask (
torch.Tensorde forma(batch_size, 1, sequence_length)) — Máscara de relleno utilizada para rellenarinput_values. - input_features_mask (
torch.Tensorde forma(batch_size, time_steps), opcional) — Máscara de atención para la entrada de espectrograma al codificador semántico.1para los fotogramas válidos,0para el relleno. - output_latents (
bool, opcional, valor predeterminadoFalse) — Si se debe devolver la representación latente continua del cuantizador.
Devuelve
NeuCodecEncoderOutput o tuple(torch.Tensor)
Un NeuCodecEncoderOutput o una tupla de
torch.Tensor (si se pasa return_dict=False o cuando config.return_dict=False) que comprende varios
elementos según la configuración (None) y las entradas.
- audio_codes (
torch.LongTensorde forma(batch_size, 1, codes_length), opcional) — Incrustaciones de códigos discretos calculadas mediantemodel.encode. Estas representan la forma comprimida y cuantizada de la señal de audio de entrada, que puede utilizarse para almacenamiento, transmisión o generación. - latents (
torch.Tensorde forma(batch_size, dimension, time_steps)) — Representación continua cuantizada del embedding de la entrada. - audio_codes_mask (
torch.int32de forma(batch_size, 1, codes_length), opcional) —padding_masksubmuestreado para indicar los códigos de audio válidos enaudio_codes.
forward
< source >( 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.Tensorde forma(batch_size, 1, sequence_length)) — Forma de onda de audio de entrada, muestreada aconfig.input_sampling_rate. - input_features (
torch.Tensorde forma(batch_size, mel_bins, time_steps)) — Espectrograma mel de audio de entrada para la codificación semántica. - padding_mask (
torch.Tensorde forma(batch_size, 1, sequence_length)) — Máscara de relleno utilizada para rellenarinput_values. - input_features_mask (
torch.Tensorde forma(batch_size, time_steps), opcional) — Máscara de atención para la entrada de espectrograma al codificador semántico.1para los fotogramas válidos,0para el relleno. - output_latents (
bool, opcional, valor predeterminadoFalse) — Si se debe devolver la representación latente continua del cuantizador.
Devuelve
NeuCodecOutput o tuple(torch.Tensor)
Un NeuCodecOutput o una tupla de
torch.Tensor (si se pasa return_dict=False o cuando config.return_dict=False) que comprende varios
elementos según la configuración (None) y las entradas.
El método forward de NeuCodecModel reemplaza el método especial __call__.
Aunque la receta para la pasada hacia adelante debe definirse dentro de esta función, se debe llamar a la instancia de
Moduledespués en lugar de a esta, ya que la primera se encarga de ejecutar los pasos de pre y postprocesamiento, mientras que la segunda los ignora silenciosamente.
- audio_values (
torch.Tensorde forma(batch_size, 1, sequence_length), opcional) — Valores de la forma de onda de audio decodificados en el dominio del tiempo, obtenidos mediante la parte decodificadora de NeuCodec. Estos representan la señal de audio reconstruida. - audio_codes (
torch.LongTensorde forma(batch_size, 1, codes_length), opcional) — Incrustaciones de códigos discretos calculadas mediantemodel.encode. Estas son las representaciones cuantizadas del audio de entrada utilizadas para un procesamiento o generación posteriores. - latents (
torch.Tensorde forma(batch_size, dimension, time_steps)) — Representación continua cuantizada del embedding de la entrada. - audio_codes_mask (
torch.int32de forma(batch_size, 1, codes_length), opcional) —padding_masksubmuestreado para indicar los códigos de audio válidos enaudio_codes.
Ejemplos:
>>> 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