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

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→