Transformers documentation
X-Codec
Este modelo se publicó en HF papers el 30 de agosto de 2024 y se contribuyó a Hugging Face Transformers el 15 de agosto de 2025.
X-Codec
Resumen
El modelo X-Codec fue propuesto en Codec Does Matter: Exploring the Semantic Shortcoming of Codec for Audio Language Model por Zhen Ye, Peiwen Sun, Jiahe Lei, Hongzhan Lin, Xu Tan, Zheqi Dai, Qiuqiang Kong, Jianyi Chen, Jiahao Pan, Qifeng Liu, Yike Guo, Wei Xue.
El modelo X-Codec es un códec de audio neuronal que integra información semántica de modelos auto-supervisados (p. ej., HuBERT) junto con la información acústica tradicional. Esto permite:
- Continuación musical: Un mejor modelado de la semántica musical produce continuaciones más coherentes.
- Síntesis de texto a sonido: X-Codec captura la alineación semántica entre los prompts de texto y el audio generado.
- Tokenización de audio consciente del significado: X-Codec se utiliza como tokenizador de audio en el modelo de generación de canciones a partir de letras de YuE.
El resumen del artículo establece lo siguiente:
Los avances recientes en la generación de audio han sido impulsados de manera significativa por las capacidades de los modelos de lenguaje de gran escala (LLM). La investigación existente sobre LLM de audio se ha centrado principalmente en mejorar la arquitectura y la escala de los modelos de lenguaje de audio, así como en el uso de conjuntos de datos más grandes. En general, se utilizan códecs acústicos, como EnCodec, para la tokenización de audio. Sin embargo, estos códecs fueron diseñados originalmente para la compresión de audio, lo que puede dar lugar a un rendimiento subóptimo en el contexto de los LLM de audio. Nuestra investigación tiene como objetivo abordar las deficiencias de los códecs actuales de LLM de audio, en particular sus dificultades para mantener la integridad semántica en el audio generado. Por ejemplo, los métodos existentes, como VALL-E, que condicionan la generación de tokens acústicos en transcripciones de texto, suelen sufrir de inexactitudes en el contenido y tasas de error de palabra (WER) elevadas debido a la interpretación semántica errónea de los tokens acústicos, lo que resulta en la omisión de palabras y errores. Para superar estos problemas, proponemos un enfoque sencillo pero efectivo llamado X-Codec. X-Codec incorpora características semánticas de un codificador semántico preentrenado antes de la etapa de Cuantización Vectorial Residual (RVQ) e introduce una pérdida de reconstrucción semántica después de la RVQ. Al mejorar la capacidad semántica del códec, X-Codec reduce significativamente la WER en las tareas de síntesis de voz y extiende estos beneficios a aplicaciones no vocales, incluida la generación de música y sonido. Nuestros experimentos en tareas de texto a voz, continuación de música y texto a sonido demuestran que la integración de información semántica mejora sustancialmente el rendimiento general de los modelos de lenguaje en la generación de audio.
Tarjetas de modelo:
- xcodec-hubert-librispeech (para audio)
- xcodec-wavlm-mls (para voz)
- xcodec-wavlm-more-data (para el habla)
- xcodec-hubert-general (para audio general)
- xcodec-hubert-general-balanced (para audio general)
Este modelo fue aportado por Manal El Aidouni. El código original se puede encontrar aquí y los puntos de control originales de los cinco modelos diferentes aquí.
Las demostraciones se pueden encontrar en esta página.
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, XcodecModel
dummy_dataset = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
# load model and feature extractor
model_id = "hf-audio/xcodec-hubert-librispeech"
model = XcodecModel.from_pretrained(model_id, device_map="auto")
feature_extractor = AutoFeatureExtractor.from_pretrained(model_id)
# load audio sample
dummy_dataset = dummy_dataset.cast_column("audio", Audio(sampling_rate=feature_extractor.sampling_rate))
audio_sample = dummy_dataset[-1]["audio"]["array"]
inputs = feature_extractor(raw_audio=audio_sample, sampling_rate=feature_extractor.sampling_rate, return_tensors="pt").to(model.device)
# encode and decode
encoder_outputs = model.encode(inputs["input_values"])
decoder_outputs = model.decode(encoder_outputs.audio_codes)
audio_values = decoder_outputs.audio_values
# or the equivalent with a forward pass
audio_values = model(inputs["input_values"]).audio_valuesPara escuchar el audio original y el reconstruido, ejecuta el fragmento de código siguiente y luego abre los archivos generados original.wav y reconstruction.wav en tu reproductor de música para compararlos.
import soundfile as sf
original = audio_sample
reconstruction = audio_values[0].cpu().detach().numpy()
sampling_rate = feature_extractor.sampling_rate
sf.write("original.wav", original, sampling_rate)
sf.write("reconstruction.wav", reconstruction.T, sampling_rate)XcodecConfig
clase transformers.XcodecConfig
< 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 = Nonetarget_bandwidths: list[int | float] | tuple[int | float, ...] = (0.5, 1, 1.5, 2, 4)sample_rate: int = 16000kernel_size: int = 3channel_ratios: list[int] | tuple[int, ...] = (1, 1)strides: list[int] | tuple[int, ...] = (1, 1)block_dilations: list[int] | tuple[int, ...] = (1, 1)unit_kernel_size: int = 3codebook_size: int = 1024codebook_dim: int | None = Noneinitializer_range: float = 0.02acoustic_model_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonesemantic_model_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None )
Parámetros
- target_bandwidths (
List[float], opcional, valor predeterminado[0.5, 1, 1.5, 2, 4]) — El rango de diferentes anchos de banda (en kbps) con los que el modelo puede codificar el audio. - sample_rate (
int, opcional, valor predeterminado16000) — La tasa de muestreo a la que deben digitalizarse los archivos de audio, expresada en hercios (Hz). - kernel_size (
int, opcional, valor predeterminado3) — El tamaño del kernel de convolución. - channel_ratios (
List[float], opcional, valor predeterminado[1, 1]) — Factores de expansión para el número de canales de salida en cada bloque semántico. - strides (
List[int], opcional, valor predeterminado[1, 1]) — Pasos para cada bloque del codificador semántico. - block_dilations (
List[int], opcional, valor predeterminado[1, 1]) — Factores de dilatación para las unidades residuales en los bloques semánticos. - unit_kernel_size (
int, opcional, valor predeterminado 3) — Tamaño del kernel dentro de cada ResidualUnit en los bloques semánticos. - codebook_size (
int, opcional, valor predeterminado1024) — El número de libros de códigos paralelos utilizados por el modelo. - codebook_dim (
int, opcional) — Dimensionalidad de cada vector de incrustación del libro de códigos. - initializer_range (
float, opcional, valor predeterminado0.02) — La desviación estándar del truncated_normal_initializer para inicializar todas las matrices de pesos. - acoustic_model_config (
Union[Dict, DacConfig], opcional) — Una instancia de la configuración del modelo acústico (DAC). - semantic_model_config (
Union[Dict, HubertConfig, WavLMConfig], opcional) — Una instancia del objeto de configuración para el modelo semántico (HuBERT).
Esta es la clase de configuración para almacenar la configuración de un XcodecModel. Se utiliza para instanciar un modelo Xcodec 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 Manel/X-Codec
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 XcodecModel, XcodecConfig
>>> # Initializing configuration
>>> configuration = XcodecConfig()
>>> # Initializing a model (with random weights) from the configuration
>>> model = XcodecModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configXcodecModel
clase transformers.XcodecModel
< source >( config: XcodecConfig )
Parámetros
- config (XcodecConfig) — 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.
El modelo de códec de audio neuronal Xcodec.
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: Tensorreturn_dict: bool | None = None )
Parámetros
- audio_codes (
torch.LongTensorde forma(batch_size, num_quantizers, codes_length)) — Índices de códigos discretos calculados usandomodel.encode. - return_dict (
bool, opcional) — Si se devuelve un ModelOutput
encode
< source >( input_values: Tensorbandwidth: float | None = Nonereturn_dict: bool | None = None )
Parámetros
- input_values (
torch.Tensorde forma(batch_size, channels, num_samples)) — Valores flotantes de la forma de onda de audio de entrada. - bandwidth (
float, opcional) — El ancho de banda objetivo en (kbps) solo admite valores enconfig.target_bandwidths. Por defecto, se establece en el ancho de banda más alto disponible4.0kbps. - return_dict (
bool, opcional) — Indica si se debe devolver un ModelOutput.
forward
< source >( input_values: Tensoraudio_codes: typing.Optional[torch.Tensor] = Nonebandwidth: float | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → XcodecOutput or tuple (audio_codes, audio_values)
Parámetros
- input_values (
torch.Tensorde forma(batch_size, channels, num_samples)) — Los valores flotantes crudos de la forma de onda de audio de entrada. - audio_codes (
torch.LongTensorde forma(batch_size, num_quantizers, codes_length)— Índices de códigos discretos calculados usandomodel.encode. - bandwidth (
float, opcional) — Ancho de banda objetivo en kbps. Debe ser uno deconfig.target_bandwidths. El valor predeterminado es el ancho de banda disponible más alto. - bandwidth (
float, opcional) — Ancho de banda objetivo en kbps. Debe ser uno deconfig.target_bandwidths. El valor predeterminado es el ancho de banda disponible más alto.
Devuelve
XcodecOutput o tupla (audio_codes, audio_values)
audio_codesde forma(batch_size, num_quantizers, codes_length): los códigos discretos cuantizados.audio_valuesde forma(batch_size, channels, num_samples): la forma de onda de audio reconstruida a partir de los códigos.
El método forward de XcodecModel 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.
Ejemplo:
>>> from datasets import load_dataset
>>> from transformers import AutoFeatureExtractor, XcodecModel
>>> model_id = "hf-audio/xcodec-hubert-librispeech"
>>> model = XcodecModel.from_pretrained(model_id)
>>> 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_sample = dataset[0]['audio']['array']
>>> inputs = feature_extractor(raw_audio=audio_sample, return_tensors="pt")
>>> outputs = model(**inputs)
>>> audio_codes = outputs.audio_codes
>>> audio_values = outputs.audio_values