Hugging Face's logo

Transformers documentation

X-Codec2

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

Ce modèle a été publié dans les papiers HF le 2025-02-06 et contribué à Hugging Face Transformers le 2026-06-25.

X-Codec2

SDPA

Aperçu

Le modèle X-Codec2 a été proposé dans Llasa: Scaling Train-Time and Inference-Time Compute for Llama-based Speech Synthesis.

X-Codec2 est un codec audio neuronal conçu pour améliorer la synthèse vocale et la génération audio générale dans les pipelines de grands modèles de langage (LLM). Il étend le X-Codec d'origine en affinant la manière dont les informations sémantiques et acoustiques sont intégrées et tokenisées, permettant ainsi une représentation audio efficace et de haute fidélité.

Concernant son architecture :

  • Tokenisation sémantique-acoustique unifiée : X-Codec2 fusionne les sorties d'un encodeur sémantique (par ex. Wav2Vec2-BERT) et d'un encodeur acoustique en un unique embedding, capturant à la fois le sens de haut niveau (par ex. contenu textuel, émotion) et les détails audio de bas niveau (par ex. timbre).
  • Quantification scalaire de caractéristiques en une seule étape (FSQ) : Contrairement à la VQ résiduelle multicouche utilisée dans la plupart des approches (par exemple, DAC, EnCodec, X-Codec, Mimi), X-Codec2 utilise une seule couche de quantification scalaire de caractéristiques (FSQ) pour assurer la stabilité et la compatibilité avec les LLM causaux et autorégressifs.
  • Conception adaptée aux Transformers : la structure de jetons 1D de X-Codec2 s'aligne naturellement sur la modélisation autorégressive des LLM comme LLaMA, ce qui améliore l'efficacité de l'entraînement et la compatibilité en aval.

Un point de contrôle du modèle est disponible sur HKUSTAudio/xcodec2-hf.

Ce modèle a été contribué par Eric Bezzam et Steven Zheng. Le code de modélisation original peut être trouvé ici, tandis que leur code d'entraînement est 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 = "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_values

Traitement par lots

Cette prise en charge également les entrées par lot, contrairement à la version initiale !

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_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.

Sur une A100, nous avons observé une accélération d'environ 1,35 pour une taille de lot 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

classe transformers.Xcodec2Config

< >

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

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).
  • sampling_rate (int, facultatif, par défaut 16000) — La fréquence d'échantillonnage à laquelle les fichiers audio doivent être numérisés, exprimée en hertz (Hz).
  • 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.

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

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 Xcodec2Config, Xcodec2Model

>>> # Initializing configuration
>>> configuration = Xcodec2Config()

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

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

Xcodec2FeatureExtractor

classe transformers.Xcodec2FeatureExtractor

< >

( 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 caractéristiques Xcodec2, qui calcule les caractéristiques 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.

Xcodec2Model

classe transformers.Xcodec2Model

< >

( config: Xcodec2Config )

Paramètres

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

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] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Xcodec2DecoderOutput 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.

Retourne

Xcodec2DecoderOutput ou tuple(torch.Tensor)

Un Xcodec2DecoderOutput 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'> ) → Xcodec2EncoderOutput 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

Xcodec2EncoderOutput ou tuple(torch.Tensor)

Un Xcodec2EncoderOutput 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'> ) → Xcodec2Output 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

Xcodec2Output ou tuple(torch.Tensor)

Un Xcodec2Output 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 de Xcodec2Model 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 Xcodec2. 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, 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
Update on GitHub

←X-Codec XLS-R→