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.2).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Model ini dipublikasikan di HF papers pada 2025-02-06 dan disumbangkan ke Hugging Face Transformers pada 2026-06-25.

X-Codec2

SDPA

Ikhtisar

Model X-Codec2 diusulkan dalam Llasa: Scaling Train-Time and Inference-Time Compute for Llama-based Speech Synthesis.

X-Codec2 adalah codec audio neural yang dirancang untuk meningkatkan sintesis ucapan dan generasi audio secara umum untuk pipeline large language model (LLM). Codec ini memperluas X-Codec asli dengan menyempurnakan cara informasi semantik dan akustik diintegrasikan serta ditokenisasi, sehingga memungkinkan representasi audio yang efisien dan berfidelitas tinggi.

Tentang arsitekturnya:

  • Tokenisasi Semantik-Akustik Terpadu: X-Codec2 menggabungkan keluaran dari encoder semantik (misalnya, Wav2Vec2-BERT) dan encoder akustik menjadi satu embedding, sehingga menangkap makna tingkat tinggi (misalnya, konten teks, emosi) dan detail audio tingkat rendah (misalnya, timbre).
  • Kuantisasi Skalar Fitur Satu Tahap (FSQ): Berbeda dengan VQ residual multi-lapisan pada sebagian besar pendekatan (misalnya, DAC, EnCodec, X-Codec, Mimi), X-Codec2 menggunakan satu lapisan Feature Scalar Quantization (FSQ) untuk stabilitas dan kompatibilitas dengan LLM kausal, autoregresif.
  • Desain yang Ramah Transformer: Struktur token 1D dari X-Codec2 secara alami selaras dengan pemodelan autoregresif pada LLM seperti LLaMA, sehingga meningkatkan efisiensi pelatihan dan kompatibilitas hilir.

Checkpoint model tersedia di HKUSTAudio/xcodec2-hf.

Model ini disumbangkan oleh Eric Bezzam dan Steven Zheng. Kode pemodelan aslinya dapat ditemukan di sini, sedangkan kode pelatihan mereka ada di sini.

Contoh penggunaan

Berikut adalah contoh singkat tentang cara mengkodekan dan mendekodekan audio menggunakan model ini:

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

Pemrosesan batch

Implementasi ini juga mendukung input berbatch, berbeda dengan rilis aslinya!

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

Percepatan dengan torch.compile

Anda dapat mempercepat inferensi dengan torch.compile. Beberapa panggilan pertama akan lebih lambat karena overhead kompilasi, tetapi panggilan berikutnya akan lebih cepat.

Pada A100, kami mengamati percepatan sekitar 1,35 untuk ukuran batch 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

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

Parameter

  • hidden_size (int, opsional, default 1024) — Dimensi dari representasi tersembunyi.
  • intermediate_size (int, opsional, default 4096) — Dimensi representasi MLP.
  • num_hidden_layers (int, opsional, default 12) — Jumlah lapisan tersembunyi dalam decoder Transformer.
  • num_attention_heads (int, opsional, default 16) — Jumlah attention head untuk setiap lapisan attention di decoder Transformer.
  • num_key_value_heads (int, opsional, default 16) — Ini adalah jumlah key_value heads yang harus digunakan untuk mengimplementasikan Grouped Query Attention. Jika num_key_value_heads=num_attention_heads, model akan menggunakan Multi Head Attention (MHA), jika num_key_value_heads=1 model akan menggunakan Multi Query Attention (MQA), selain itu GQA yang digunakan. Saat mengkonversi checkpoint multi-head menjadi checkpoint GQA, setiap group key dan value head harus dibangun dengan meanpooling semua head asli di dalam grup tersebut. Untuk detail lebih lanjut, lihat paper ini. Jika tidak ditentukan, akan default ke num_attention_heads.
  • hidden_act (str, opsional, defaultnya silu) — Fungsi aktivasi non-linear (fungsi atau string) di decoder. Misalnya, "gelu", "relu", "silu", dan sebagainya.
  • max_position_embeddings (int, opsional, default 4096) — Panjang maksimum urutan yang mungkin digunakan dengan model ini.
  • initializer_range (float, opsional, defaultnya 0.02) — Standar deviasi dari truncated_normal_initializer untuk menginisialisasi semua matriks bobot.
  • rms_norm_eps (float, opsional, defaultnya 1e-06) — Epsilon yang digunakan oleh lapisan normalisasi rms.
  • pad_token_id (int, opsional) — ID token yang digunakan untuk padding dalam kosakata.
  • tie_word_embeddings (bool, opsional, default False) — Apakah akan mengikat bobot embedding sesuai dengan pemetaan tied_weights_keys model.
  • rope_parameters (Union[~modeling_rope_utils.RopeParameters, dict], opsional) — Kamus yang berisi parameter konfigurasi untuk embedding RoPE. Kamus tersebut harus berisi nilai untuk rope_theta dan secara opsional parameter yang digunakan untuk penskalaan jika Anda ingin menggunakan RoPE dengan max_position_embeddings yang lebih panjang.
  • attention_bias (bool, opsional, default False) — Apakah akan menggunakan bias pada lapisan proyeksi query, key, value, dan output selama self-attention.
  • attention_dropout (Union[int, float], opsional, default 0.0) — Rasio dropout untuk probabilitas perhatian.
  • head_dim (int, opsional, default 64) — Dimensi head perhatian. Jika None, nilainya akan default ke hidden_size // num_attention_heads
  • encoder_hidden_size (int, opsional, default 48) — Dimensi dari representasi tersembunyi.
  • downsampling_ratios (list[int], opsional, default [2, 2, 4, 4, 5]) — Rasio untuk downsampling di encoder.
  • semantic_model_config (Union[Dict, Wav2Vec2BertConfig], opsional) — Instans dari objek konfigurasi untuk model semantik (Wav2Vec2BertConfig).
  • sampling_rate (int, opsional, default 16000) — Laju sampling di mana file audio harus didigitalisasi, dinyatakan dalam hertz (Hz).
  • activation_dropout (float, opsional, default 0.1) — Rasio dropout untuk aktivasi di dalam lapisan fully connected.
  • quantization_dim (int, opsional, default 2048) — Dimensi untuk codebook kuantisasi vektor.
  • quantization_levels (list[int], opsional, default [4, 4, 4, 4, 4, 4, 4, 4]) — Level untuk codebook kuantisasi vektor.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari Xcodec2Model. Kelas ini digunakan untuk membuat instans model Xcodec2 berdasarkan argumen yang ditentukan, sehingga mendefinisikan arsitektur model. Membuat instans konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari HKUSTAudio/xcodec2-hf

Objek konfigurasi mewarisi dari PreTrainedConfig dan dapat digunakan untuk mengontrol output model. Baca dokumentasi dari PreTrainedConfig untuk informasi lebih lanjut.

Contoh:

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

kelas transformers.Xcodec2FeatureExtractor

< >

( feature_size = 80sampling_rate = 16000padding_value = 1.0hop_length = 320**kwargs )

Parameter

  • feature_size (int, opsional, default 80) — Dimensi fitur dari fitur yang diekstrak.
  • sampling_rate (int, opsional, default 16000) — Laju sampel di mana file audio harus didigitalisasi, dinyatakan dalam hertz (Hz).
  • padding_value (float, opsional, default 1.0) — Nilai yang digunakan untuk mengisi vektor padding pada spektrogram mel.
  • hop_length (int, opsional, default 320) — Jumlah sampel audio yang dikodekan per frame. Setara dengan hasil perkalian rasio downsampling. Diperlukan untuk padding input encoder akustik.

Membangun feature extractor Xcodec2, yang menghitung fitur mel-filter bank untuk semantic encoder dan audio yang di-pad untuk acoustic encoder.

Feature extractor ini mewarisi dari SequenceFeatureExtractor yang berisi sebagian besar metode utama. Pengguna harus merujuk ke superclass ini untuk informasi lebih lanjut mengenai metode-metode tersebut.

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

Parameter

  • audio (np.ndarray, torch.Tensor, list[np.ndarray], list[torch.Tensor]) — Array Numpy atau tensor torch dengan bentuk (num_channels, sequence_length). Daftar array atau tensor seperti itu juga dapat disediakan untuk batch input.
  • padding (bool, str atau PaddingStrategy, opsional, defaultnya True) — Pilih strategi untuk melakukan padding pada urutan yang dikembalikan (sesuai sisi padding dan indeks padding model) di antara:
    • True atau 'longest': Pad hingga urutan terpanjang dalam batch (atau tanpa padding jika hanya satu urutan yang diberikan).
    • 'max_length': Pad hingga panjang maksimum yang ditentukan dengan argumen max_length atau hingga panjang input maksimum yang dapat diterima oleh model jika argumen tersebut tidak diberikan.
    • False atau 'do_not_pad' (default): Tidak ada padding (yaitu, dapat menghasilkan batch dengan urutan yang panjangnya berbeda).
  • max_length (int, opsional) — Panjang maksimum dari daftar yang dikembalikan dan secara opsional panjang padding (lihat di atas).
  • truncation (bool) — Mengaktifkan pemotongan untuk memotong urutan input yang lebih panjang dari max_length menjadi max_length.
  • return_tensors (str atau TensorType, opsional) — Jika diset, akan mengembalikan tensor alih-alih daftar integer Python. Nilai yang dapat diterima adalah:
    • 'tf': Mengembalikan objek TensorFlow tf.constant.
    • 'pt': Mengembalikan objek PyTorch torch.Tensor.
    • 'np': Mengembalikan objek Numpy np.ndarray.
  • sampling_rate (int, opsional) — Laju sampel di mana input audio disampelkan. Sangat disarankan untuk meneruskan sampling_rate pada panggilan forward untuk mencegah kesalahan yang tidak terdeteksi.
  • device (str, opsional, default "cpu") — Perangkat untuk tensor PyTorch selama ekstraksi fitur mel-filter bank.
  • kwargs (opsional) — Kamus sisa argumen kata kunci yang akan diteruskan ke tokenizer atau feature extractor.

Xcodec2Model

kelas transformers.Xcodec2Model

< >

( config: Xcodec2Config )

Parameter

  • config (Xcodec2Config) — Kelas konfigurasi model dengan semua parameter model. Inisialisasi dengan file konfigurasi tidak memuat bobot yang terkait dengan model, hanya konfigurasinya. Lihat metode from_pretrained() untuk memuat bobot model.

Model codec audio neural Xcodec2.

Model ini mewarisi dari PreTrainedModel. Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan oleh pustaka untuk semua model (seperti mengunduh atau menyimpan, mengubah ukuran embedding input, memangkas kepala, dll.)

Model ini juga merupakan subclass dari torch.nn.Module PyTorch. Gunakan sebagai PyTorch Module biasa dan merujuk ke dokumentasi PyTorch untuk semua hal yang berkaitan dengan penggunaan dan perilaku umum.

decode

< >

( audio_codes: typing.Optional[torch.Tensor] = Nonelatents: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Xcodec2DecoderOutput or tuple(torch.Tensor)

Parameter

  • audio_codes (torch.LongTensor dengan bentuk (batch_size, 1, codes_length)) — Indeks kode diskrit yang dihitung menggunakan model.encode.
  • latents (torch.Tensor dengan bentuk (batch_size, dimension, time_steps), opsional) — Representasi kontinu terkuantisasi dari input.

Mengembalikan

Xcodec2DecoderOutput atau tuple(torch.Tensor)

Sebuah Xcodec2DecoderOutput atau tuple dari torch.Tensor (jika return_dict=False diteruskan atau ketika config.return_dict=False) yang terdiri dari berbagai elemen tergantung pada konfigurasi (None) dan input.

  • audio_values (torch.Tensor dengan bentuk (batch_size, 1, segment_length), opsional) — Nilai waveform audio yang didekodekan dalam domain waktu, diperoleh dengan mengonversi kode diskrit kembali menjadi sinyal audio kontinu. Ini merepresentasikan audio yang direkonstruksi dan dapat diputar kembali.

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)

Parameter

  • input_values (torch.Tensor dengan bentuk (batch_size, 1, sequence_length)) — Gelombang audio masukan.
  • input_features (torch.Tensor dengan bentuk (batch_size, mel_bins, time_steps)) — Spektrogram mel audio input untuk pengkodean semantik.
  • padding_mask (torch.Tensor dengan bentuk (batch_size, 1, sequence_length)) — Mask padding yang digunakan untuk mengisi input_values.
  • input_features_mask (torch.Tensor dengan bentuk (batch_size, time_steps), opsional) — Mask attention untuk input spektrogram ke encoder semantik. 1 untuk frame valid, 0 untuk padding.
  • output_latents (bool, opsional, default False) — Apakah akan mengembalikan representasi laten kontinu dari kuantizer.

Mengembalikan

Xcodec2EncoderOutput atau tuple(torch.Tensor)

Sebuah Xcodec2EncoderOutput atau tuple dari torch.Tensor (jika return_dict=False dilewatkan atau ketika config.return_dict=False) yang terdiri dari berbagai elemen tergantung pada konfigurasi (None) dan input.

  • audio_codes (torch.LongTensor dengan bentuk (batch_size, 1, codes_length), opsional) — Embedding kode diskrit yang dihitung menggunakan model.encode. Kode-kode ini merepresentasikan bentuk terkompresi dan terkuantisasi dari sinyal audio masukan, yang dapat digunakan untuk penyimpanan, transmisi, atau generasi.
  • latents (torch.Tensor dengan bentuk (batch_size, dimension, time_steps)) — Representasi kontinu terkuantisasi dari embedding input.
  • audio_codes_mask (torch.int32 dengan bentuk (batch_size, 1, codes_length), opsional) — padding_mask yang telah di-downsample untuk menunjukkan kode audio yang valid dalam 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)

Parameter

  • input_values (torch.Tensor dengan bentuk (batch_size, 1, sequence_length)) — Gelombang audio masukan.
  • input_features (torch.Tensor dengan bentuk (batch_size, mel_bins, time_steps)) — Spektrogram mel audio input untuk pengkodean semantik.
  • padding_mask (torch.Tensor dengan bentuk (batch_size, 1, sequence_length)) — Mask padding yang digunakan untuk mengisi input_values.
  • input_features_mask (torch.Tensor dengan bentuk (batch_size, time_steps), opsional) — Mask attention untuk input spektrogram ke encoder semantik. 1 untuk frame valid, 0 untuk padding.
  • output_latents (bool, opsional, default False) — Apakah akan mengembalikan representasi laten kontinu dari kuantizer.

Mengembalikan

Xcodec2Output atau tuple(torch.Tensor)

Xcodec2Output atau tuple dari torch.Tensor (jika return_dict=False dilewatkan atau ketika config.return_dict=False) yang terdiri dari berbagai elemen tergantung pada konfigurasi (None) dan input.

Metode forward dari Xcodec2Model menimpa metode khusus __call__.

Meskipun resep untuk forward pass perlu didefinisikan di dalam fungsi ini, sebaiknya panggil instance Module setelahnya alih-alih fungsi ini, karena yang pertama menangani langkah-langkah pra-pemrosesan dan pasca-pemrosesan, sedangkan yang kedua mengabaikannya secara diam-diam.

  • audio_values (torch.Tensor dengan bentuk (batch_size, 1, sequence_length), opsional) — Nilai waveform audio yang telah didekodekan dalam domain waktu, diperoleh menggunakan bagian decoder dari Xcodec2. Nilai-nilai ini merepresentasikan sinyal audio yang telah direkonstruksi.
  • audio_codes (torch.LongTensor dengan bentuk (batch_size, 1, codes_length), opsional) — Embedding kode diskrit yang dihitung menggunakan model.encode. Ini adalah representasi kuantisasi dari audio input yang digunakan untuk pemrosesan atau generasi lebih lanjut.
  • latents (torch.Tensor dengan bentuk (batch_size, dimension, time_steps)) — Representasi kontinu terkuantisasi dari embedding input.
  • audio_codes_mask (torch.int32 dengan bentuk (batch_size, 1, codes_length), opsional) — padding_mask yang telah di-downsample untuk menunjukkan kode audio yang valid dalam audio_codes.

Contoh:

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