Transformers documentation
X-Codec2
Este modelo se publicó en HF papers el 2025-02-06 y se contribuyó a Hugging Face Transformers el 2026-06-25.
X-Codec2
Resumen
El modelo X-Codec2 fue propuesto en Llasa: Scaling Train-Time and Inference-Time Compute for Llama-based Speech Synthesis.
X-Codec2 es un códec de audio neuronal diseñado para mejorar la síntesis de voz y la generación de audio general en las tuberías de modelos de lenguaje de gran escala (LLM). Extiende el X-Codec original al refinar cómo se integran y tokenizan la información semántica y acústica, lo que permite una representación de audio eficiente y de alta fidelidad.
Sobre su arquitectura:
- Tokenización semántico-acústica unificada: X-Codec2 fusiona las salidas de un codificador semántico (p. ej., Wav2Vec2-BERT) y un codificador acústico en una única representación, capturando tanto el significado de alto nivel (p. ej., contenido textual, emoción) como los detalles de audio de bajo nivel (p. ej., timbre).
- Cuantización escalar de características de un solo paso (FSQ): A diferencia de la VQ residual de múltiples capas utilizada en la mayoría de los enfoques (p. ej., DAC, EnCodec, X-Codec, Mimi), X-Codec2 utiliza una sola capa de cuantización escalar de características (FSQ) para garantizar estabilidad y compatibilidad con LLMs causales y autoregresivos.
- Diseño compatible con Transformers: La estructura de tokens 1D de X-Codec2 se alinea de forma natural con el modelado autoregresivo en LLMs como LLaMA, lo que mejora la eficiencia del entrenamiento y la compatibilidad con tareas posteriores.
Hay un punto de control del modelo disponible en HKUSTAudio/xcodec2-hf.
Este modelo fue aportado por Eric Bezzam y Steven Zheng. El código de modelado original se puede encontrar aquí, mientras que su código de entrenamiento está 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 = "HKUSTAudio/xcodec2-hf"
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, 293])
audio_values = model.decode(audio_codes).audio_values
print("Audio values shape:", audio_values.shape)
# Audio values shape: torch.Size([1, 1, 93760])
# 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, a diferencia de la versión original
from datasets import Audio, load_dataset
from transformers import AutoFeatureExtractor, AutoModel
batch_size = 2
model_id = "HKUSTAudio/xcodec2-hf"
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, 293])
audio_values = model.decode(audio_codes).audio_values
print("Audio values shape:", audio_values.shape)
# Audio values shape: torch.Size([2, 1, 93760])
# 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.
En una A100, observamos una aceleración de ~1.35 para un tamaño de lote de 4 (script).
import torch
from datasets import Audio, load_dataset
from transformers import AutoFeatureExtractor, AutoModel
batch_size = 4
model_id = "HKUSTAudio/xcodec2-hf"
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)Xcodec2Config
clase transformers.Xcodec2Config
< 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 = Nonesampling_rate: int = 16000activation_dropout: float = 0.1quantization_dim: int = 2048quantization_levels: list[int] | tuple[int, ...] = (4, 4, 4, 4, 4, 4, 4, 4) )
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). - sampling_rate (
int, opcional, valor predeterminado16000) — La tasa de muestreo a la que deben digitalizarse los archivos de audio, expresada en hercios (Hz). - 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.
Esta es la clase de configuración para almacenar la configuración de un Xcodec2Model. Se utiliza para instanciar un modelo Xcodec2 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 HKUSTAudio/xcodec2-hf
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 Xcodec2Config, Xcodec2Model
>>> # Initializing configuration
>>> configuration = Xcodec2Config()
>>> # Initializing a model (with random weights) from the configuration
>>> model = Xcodec2Model(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configXcodec2FeatureExtractor
clase transformers.Xcodec2FeatureExtractor
< 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 Xcodec2, 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.
Xcodec2Model
clase transformers.Xcodec2Model
< source >( config: Xcodec2Config )
Parámetros
- config (Xcodec2Config) — 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 Xcodec2.
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] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Xcodec2DecoderOutput 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.
Devuelve
Xcodec2DecoderOutput o tuple(torch.Tensor)
Un Xcodec2DecoderOutput 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'> ) → Xcodec2EncoderOutput 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
Xcodec2EncoderOutput o tuple(torch.Tensor)
Un Xcodec2EncoderOutput 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'> ) → Xcodec2Output 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
Xcodec2Output o tuple(torch.Tensor)
Un Xcodec2Output 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 Xcodec2Model 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 Xcodec2. 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, Xcodec2Model
>>> dataset = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> audio = dataset["train"]["audio"][0]["array"]
>>> model_id = "HKUSTAudio/xcodec2-hf"
>>> model = Xcodec2Model.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