Hugging Face's logo

Transformers documentation

X-Codec2

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Este modelo foi publicado no HF papers em 2025-02-06 e contribuído para o Hugging Face Transformers em 2026-06-25.

X-Codec2

SDPA

Visão geral

O modelo X-Codec2 foi proposto em Llasa: Scaling Train-Time and Inference-Time Compute for Llama-based Speech Synthesis.

X-Codec2 é um codec de áudio neural projetado para melhorar a síntese de fala e a geração geral de áudio em pipelines de large language model (LLM). Ele estende o X-Codec original, refinando a forma como as informações semânticas e acústicas são integradas e tokenizadas, permitindo uma representação de áudio eficiente e de alta fidelidade.

Sobre sua arquitetura:

  • Tokenização semântico-acústica unificada: o X-Codec2 funde as saídas de um codificador semântico (por exemplo, Wav2Vec2-BERT) e de um codificador acústico em um único embedding, capturando tanto o significado de alto nível (por exemplo, conteúdo textual, emoção) quanto os detalhes de áudio de baixo nível (por exemplo, timbre).
  • Quantização Escalar de Recursos de Estágio Único (FSQ): Diferentemente do VQ residual de múltiplas camadas usado na maioria das abordagens (por exemplo, DAC, EnCodec, X-Codec, Mimi), o X-Codec2 utiliza uma única camada de Quantização Escalar de Recursos (FSQ) para garantir estabilidade e compatibilidade com LLMs causais e autoregressivos.
  • Design amigável a Transformers: A estrutura de tokens 1D do X-Codec2 se alinha naturalmente com a modelagem autoregressiva em LLMs como LLaMA, melhorando a eficiência do treinamento e a compatibilidade em tarefas downstream.

Um checkpoint do modelo está disponível em HKUSTAudio/xcodec2-hf.

Este modelo foi contribuído por Eric Bezzam e Steven Zheng. O código de modelagem original pode ser encontrado aqui, enquanto o código de treinamento está aqui.

Exemplo de uso

Aqui está um exemplo rápido de como codificar e decodificar um áudio usando 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_values

Processamento em lote

Esta implementação também suporta entrada em lote, ao contrário da versão 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_values

Aceleração com torch.compile

Você pode acelerar a inferência com torch.compile. As primeiras chamadas serão mais lentas devido ao overhead de compilação, mas as chamadas subsequentes serão mais rápidas.

Em uma A100, observamos uma aceleração de ~1,35 para um tamanho 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

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

Parâmetros

  • hidden_size (int, opcional, padrão 1024) — Dimensão das representações ocultas.
  • intermediate_size (int, opcional, padrão 4096) — Dimensão das representações do MLP.
  • num_hidden_layers (int, opcional, padrão 12) — Número de camadas ocultas no decodificador do Transformer.
  • num_attention_heads (int, opcional, padrão 16) — Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer.
  • num_key_value_heads (int, opcional, padrão 16) — Este é o número de cabeças de key_value que devem ser usadas para implementar Grouped Query Attention. Se num_key_value_heads=num_attention_heads, o modelo usará Multi Head Attention (MHA); se num_key_value_heads=1, o modelo usará Multi Query Attention (MQA); caso contrário, será usado GQA. Ao converter um checkpoint multi-head para um checkpoint GQA, cada grupo de cabeças de key e value deve ser construído por meio do meanpooling de todas as cabeças originais dentro desse grupo. Para mais detalhes, consulte este artigo. Se não for especificado, o valor padrão será num_attention_heads.
  • hidden_act (str, opcional, padrão silu) — A função de ativação não linear (função ou string) no decodificador. Por exemplo, "gelu", "relu", "silu", etc.
  • max_position_embeddings (int, opcional, padrão 4096) — O comprimento máximo de sequência com o qual este modelo pode ser utilizado.
  • initializer_range (float, opcional, padrão 0.02) — O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.
  • rms_norm_eps (float, opcional, padrão 1e-06) — O epsilon usado pelas camadas de normalização rms.
  • pad_token_id (int, opcional) — ID do token usado para preenchimento no vocabulário.
  • tie_word_embeddings (bool, opcional, padrão False) — Se deve vincular as embeddings de pesos de acordo com o mapeamento tied_weights_keys do modelo.
  • rope_parameters (Union[~modeling_rope_utils.RopeParameters, dict], opcional) — Dicionário contendo os parâmetros de configuração para os embeddings RoPE. O dicionário deve conter um valor para rope_theta e, opcionalmente, parâmetros usados para escalonamento, caso você queira usar RoPE com max_position_embeddings maiores.
  • attention_bias (bool, opcional, padrão False) — Indica se deve ser usado um viés nas camadas de projeção de query, key, value e output durante a autoatenção.
  • attention_dropout (Union[int, float], opcional, padrão 0.0) — A taxa de dropout para as probabilidades de atenção.
  • head_dim (int, opcional, padrão 64) — A dimensão da cabeça de atenção. Se for None, o valor padrão será hidden_size // num_attention_heads
  • encoder_hidden_size (int, opcional, padrão 48) — Dimensão das representações ocultas.
  • downsampling_ratios (list[int], opcional, padrão [2, 2, 4, 4, 5]) — Razões para redução de amostragem no codificador.
  • semantic_model_config (Union[Dict, Wav2Vec2BertConfig], opcional) — Uma instância do objeto de configuração para o modelo semântico (Wav2Vec2BertConfig).
  • sampling_rate (int, opcional, padrão 16000) — A taxa de amostragem na qual os arquivos de áudio devem ser digitalizados, expressa em hertz (Hz).
  • activation_dropout (float, opcional, padrão 0.1) — A taxa de dropout para as ativações dentro da camada totalmente conectada.
  • quantization_dim (int, opcional, padrão 2048) — Dimensão do codebook de quantização vetorial.
  • quantization_levels (list[int], opcional, padrão [4, 4, 4, 4, 4, 4, 4, 4]) — Níveis para o codebook de quantização vetorial.

Esta é a classe de configuração para armazenar a configuração de um Xcodec2Model. Ela é usada para instanciar um modelo Xcodec2 de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do HKUSTAudio/xcodec2-hf

Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.

Exemplo:

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

Parâmetros

  • feature_size (int, opcional, padrão 80) — A dimensão dos recursos das características extraídas.
  • sampling_rate (int, opcional, padrão 16000) — A taxa de amostragem na qual os arquivos de áudio devem ser digitalizados, expressa em hertz (Hz).
  • padding_value (float, opcional, padrão 1.0) — O valor usado para preencher os vetores de padding do espectrograma mel.
  • hop_length (int, opcional, padrão 320) — Número de amostras de áudio codificadas por quadro. Equivale ao produto das taxas de redução de amostragem. Necessário para o preenchimento da entrada do codificador acústico.

Constrói um extrator de recursos Xcodec2, que calcula recursos de banco de filtros mel para o codificador semântico e áudio com preenchimento para o codificador acústico.

Este extrator de características herda de SequenceFeatureExtractor, que contém a maioria dos métodos principais. Os usuários devem consultar essa superclasse para obter mais informações sobre esses métodos.

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

Parâmetros

  • audio (np.ndarray, torch.Tensor, list[np.ndarray], list[torch.Tensor]) — Array NumPy ou tensor torch com forma (num_channels, sequence_length). Também é possível fornecer uma lista desses arrays ou tensors para um lote de entradas.
  • padding (bool, str ou PaddingStrategy, opcional, padrão é True) — Selecione uma estratégia para aplicar padding às sequências retornadas (de acordo com o lado de padding e o índice de padding do modelo) entre:
    • True ou 'longest': Preenche até a sequência mais longa do lote (ou não aplica preenchimento se apenas uma sequência for fornecida).
    • 'max_length': Preenche até o comprimento máximo especificado com o argumento max_length ou até o comprimento máximo aceitável de entrada para o modelo, caso esse argumento não seja fornecido.
    • False ou 'do_not_pad' (padrão): Sem padding (ou seja, pode gerar um lote com sequências de comprimentos diferentes).
  • max_length (int, opcional) — Comprimento máximo da lista retornada e, opcionalmente, o comprimento do padding (veja acima).
  • truncation (bool) — Ativa a truncagem para cortar sequências de entrada com comprimento maior que max_length para max_length.
  • return_tensors (str ou TensorType, opcional) — Se definido, retornará tensors em vez de uma lista de inteiros do Python. Os valores aceitos são:
    • 'tf': Retorna objetos tf.constant do TensorFlow.
    • 'pt': Retorna objetos torch.Tensor do PyTorch.
    • 'np': Retorna objetos np.ndarray do Numpy.
  • sampling_rate (int, opcional) — A taxa de amostragem na qual a entrada de audio foi amostrada. É fortemente recomendável passar sampling_rate na chamada de forward para evitar erros silenciosos.
  • device (str, opcional, padrão "cpu") — Dispositivo para tensores do PyTorch durante a extração de recursos do banco de filtros mel.
  • kwargs (opcional) — Dicionário restante de argumentos por palavra-chave que será passado para o tokenizer ou o extrator de recursos.

Xcodec2Model

classe transformers.Xcodec2Model

< >

( config: Xcodec2Config )

Parâmetros

  • config (Xcodec2Config) — Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método from_pretrained() para carregar os pesos do modelo.

Modelo de codec de áudio neural Xcodec2.

Este modelo herda de PreTrainedModel. Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.)

Este modelo também é uma subclasse de torch.nn.Module do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso geral e ao comportamento.

decode

< >

( 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.LongTensor de forma (batch_size, 1, codes_length)) — Índices de códigos discretos calculados usando model.encode.
  • latents (torch.Tensor de forma (batch_size, dimension, time_steps), opcional) — Representação contínua quantizada da entrada.

Retorna

Xcodec2DecoderOutput ou tuple(torch.Tensor)

Um Xcodec2DecoderOutput ou uma tupla de torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários elementos, dependendo da configuração (None) e das entradas.

  • audio_values (torch.Tensor de forma (batch_size, 1, segment_length), opcional) — Valores da forma de onda de áudio decodificada no domínio do tempo, obtidos convertendo os códigos discretos de volta em sinais de áudio contínuos. Isso representa o áudio reconstruído que pode ser reproduzido.

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)

Parâmetros

  • input_values (torch.Tensor de forma (batch_size, 1, sequence_length)) — Forma de onda de áudio de entrada.
  • input_features (torch.Tensor de forma (batch_size, mel_bins, time_steps)) — Espectrograma mel de áudio de entrada para codificação semântica.
  • padding_mask (torch.Tensor de forma (batch_size, 1, sequence_length)) — Máscara de preenchimento usada para preencher input_values.
  • input_features_mask (torch.Tensor de forma (batch_size, time_steps), opcional) — Máscara de atenção para a entrada do espectrograma no codificador semântico. 1 para quadros válidos, 0 para preenchimento.
  • output_latents (bool, opcional, padrão False) — Se deve retornar a representação latente contínua do quantizador.

Retorna

Xcodec2EncoderOutput ou tuple(torch.Tensor)

Um Xcodec2EncoderOutput ou uma tupla de torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários elementos, dependendo da configuração (None) e das entradas.

  • audio_codes (torch.LongTensor de forma (batch_size, 1, codes_length), opcional) — Embebidings de códigos discretos calculados usando model.encode. Esses representam a forma comprimida e quantizada do sinal de áudio de entrada que pode ser usada para armazenamento, transmissão ou geração.
  • latents (torch.Tensor de forma (batch_size, dimension, time_steps)) — Representação contínua quantizada do embedding de entrada.
  • audio_codes_mask (torch.int32 de forma (batch_size, 1, codes_length), opcional) — padding_mask reduzido para indicar os códigos de áudio válidos em 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)

Parâmetros

  • input_values (torch.Tensor de forma (batch_size, 1, sequence_length)) — Forma de onda de áudio de entrada.
  • input_features (torch.Tensor de forma (batch_size, mel_bins, time_steps)) — Espectrograma mel de áudio de entrada para codificação semântica.
  • padding_mask (torch.Tensor de forma (batch_size, 1, sequence_length)) — Máscara de preenchimento usada para preencher input_values.
  • input_features_mask (torch.Tensor de forma (batch_size, time_steps), opcional) — Máscara de atenção para a entrada do espectrograma no codificador semântico. 1 para quadros válidos, 0 para preenchimento.
  • output_latents (bool, opcional, padrão False) — Se deve retornar a representação latente contínua do quantizador.

Retorna

Xcodec2Output ou tuple(torch.Tensor)

Um Xcodec2Output ou uma tupla de torch.Tensor (se return_dict=False for passado ou quando config.return_dict=False) contendo vários elementos, dependendo da configuração (None) e das entradas.

O método forward do Xcodec2Model substitui o método especial __call__.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de Module em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

  • audio_values (torch.Tensor de forma (batch_size, 1, sequence_length), opcional) — Valores da forma de onda de áudio decodificada no domínio do tempo, obtidos usando a parte decodificadora do Xcodec2. Esses valores representam o sinal de áudio reconstruído.
  • audio_codes (torch.LongTensor de forma (batch_size, 1, codes_length), opcional) — Embebidings de códigos discretos calculados usando model.encode. Estas são as representações quantizadas do áudio de entrada usadas para processamento ou geração adicionais.
  • latents (torch.Tensor de forma (batch_size, dimension, time_steps)) — Representação contínua quantizada do embedding de entrada.
  • audio_codes_mask (torch.int32 de forma (batch_size, 1, codes_length), opcional) — padding_mask reduzido para indicar os códigos de áudio válidos em audio_codes.

Exemplos:

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