Transformers documentation

NeuCodec

Transformers

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

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

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

NeuCodec

Ikhtisar

Model NeuCodec diusulkan dalam Finite Scalar Quantization Enables Redundant and Transmission-Robust Neural Audio Compression at Low Bit-rates.

NeuCodec adalah codec audio neural yang dikembangkan dari XCodec2. Codec ini memanfaatkan fitur-fitur berikut:

Kuantisasi Skalar Terhingga (Finite Scalar Quantization/FSQ) yang menghasilkan satu buku kode, menjadikannya ideal untuk pemodelan hilir dengan Model Bahasa Berbicara.
Dilatih dengan data CC sehingga tidak ada batasan data Non-Commercial.
Pada 50 token/detik dan 16 bit per token, laju bit keseluruhan adalah 0,8 kbps.
Codec menerima input 16kHz dan menghasilkan 24kHz menggunakan upsampling decoder.
Skema encoding FSQ memungkinkan ketahanan terhadap kesalahan pada level bit yang cocok untuk saluran yang tidak andal dan berisik.

Kode pemodelan asli dapat ditemukan 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 = "neuphonic/neucodec"
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, 292])
audio_values = model.decode(audio_codes).audio_values
print("Audio values shape:", audio_values.shape)

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

from datasets import Audio, load_dataset
from transformers import AutoFeatureExtractor, AutoModel

batch_size = 2
model_id = "neuphonic/neucodec"
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, 292])
audio_values = model.decode(audio_codes).audio_values
print("Audio values shape:", audio_values.shape)

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

import torch
from datasets import Audio, load_dataset
from transformers import AutoFeatureExtractor, AutoModel

batch_size = 4
model_id = "neuphonic/neucodec"
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)

NeuCodecConfig

kelas transformers.NeuCodecConfig

< 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 = 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 = Noneactivation_dropout: float = 0.1quantization_dim: int = 2048quantization_levels: list[int] | tuple[int, ...] = (4, 4, 4, 4, 4, 4, 4, 4)input_sampling_rate: int = 16000output_sampling_rate: int = 24000 )

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).
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.
input_sampling_rate (int, opsional, default 16000) — Laju sampling, dalam hertz (Hz), dari gelombang audio input encoder.
output_sampling_rate (int, opsional, default 24000) — Laju sampling, dalam hertz (Hz), dari gelombang audio keluaran decoder.

Ini adalah kelas konfigurasi untuk menyimpan konfigurasi dari NeuCodecModel. Kelas ini digunakan untuk membuat model Neucodec berdasarkan argumen yang ditentukan, yang mendefinisikan arsitektur model. Membuat konfigurasi dengan nilai bawaan akan menghasilkan konfigurasi yang serupa dengan konfigurasi dari neuphonic/neucodec

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

Contoh:

>>> from transformers import NeuCodecConfig, NeuCodecModel

>>> # Initializing configuration
>>> configuration = NeuCodecConfig()

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

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

NeuCodecFeatureExtractor

kelas transformers.NeuCodecFeatureExtractor

< source >

( 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 ekstraktor fitur NeuCodec, yang menghitung fitur bank filter mel untuk encoder semantik dan audio yang di-pad untuk encoder akustik.

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

< source >

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

NeuCodecModel

kelas transformers.NeuCodecModel

< source >

( config: NeuCodecConfig )

Parameter

config (NeuCodecConfig) — 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 NeuCodec.

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

< source >

( audio_codes: typing.Optional[torch.Tensor] = Nonelatents: typing.Optional[torch.Tensor] = Noneaudio_codes_mask: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → NeuCodecDecoderOutput 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.
audio_codes_mask (torch.Tensor dengan bentuk (batch_size, codes_length), opsional) — Mask yang menandai posisi valid (non-padding), sebagaimana dikembalikan oleh model.encode. Diperlukan untuk decoding batched yang benar dari audio dengan panjang bervariasi.

Mengembalikan

NeuCodecDecoderOutput atau tuple(torch.Tensor)

NeuCodecDecoderOutput 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

< source >

( 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'> ) → NeuCodecEncoderOutput 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

NeuCodecEncoderOutput atau tuple(torch.Tensor)

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

< source >

Parameter

input_values (torch.Tensor dengan bentuk (batch_size, 1, sequence_length)) — Gelombang audio input, disampel pada config.input_sampling_rate.
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

NeuCodecOutput atau tuple(torch.Tensor)

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

Metode forward dari NeuCodecModel 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 didekodekan dalam domain waktu, diperoleh menggunakan bagian decoder dari NeuCodec. Nilai-nilai ini merepresentasikan sinyal audio yang 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, NeuCodecModel

>>> dataset = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> audio = dataset["train"]["audio"][0]["array"]

>>> model_id = "neuphonic/neucodec"
>>> model = NeuCodecModel.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  # sampled at 24kHz

Update on GitHub

←Nemotron ASR Streaming Parakeet→