Transformers documentation
NeuCodec
Bu model, 2025-09-11 tarihinde HF papers'ta yayımlandı ve 2026-09-02 tarihinde Hugging Face Transformers'a katkıda bulunuldu.
NeuCodec
Genel Bakış
NeuCodec modeli, Finite Scalar Quantization Enables Redundant and Transmission-Robust Neural Audio Compression at Low Bit-rates makalesinde önerilmiştir.
NeuCodec, XCodec2'yi genişleten sinirsel bir ses kodlayıcısıdır. Aşağıdaki özelliklerden yararlanır:
- Sonlu Skaler Kuantizasyon (FSQ) kuantizasyonu tek bir kod kitabı ile sonuçlanır ve bu da onu Ses Dil Modelleri ile aşağı akış modellemesi için ideal kılar.
- Non-Commercial veri kısıtlamalarının bulunmaması sağlanacak şekilde CC verileriyle eğitildi.
- 50 token/sn ve token başına 16 bit ile toplam bit hızı 0.8kbps'tir.
- Kodlayıcı, 16kHz giriş alır ve örnekleme artırma çözücü kullanarak 24kHz çıktı üretir.
- FSQ kodlama şeması, güvenilir olmayan ve gürültülü kanallara uygun, bit düzeyinde hata direnci sağlar.
Orijinal model kodu burada bulunabilir.
Kullanım örneği
Bu modelle bir ses dosyasını kodlama ve çözmeye dair hızlı bir örnek:
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_valuesToplu işleme
Bu uygulama ayrıca toplu (batched) girdiyi de destekler!
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_valuestorch.compile ile hızlandırma
torch.compile ile çıkarımı hızlandırabilirsiniz. Derleme maliyeti nedeniyle ilk birkaç çağrı daha yavaş olacaktır, ancak sonraki çağrılar daha hızlı olacaktır.
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
sınıf 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 )
Parametreler
- hidden_size (
int, isteğe bağlı, varsayılan1024) — Gizli temsillerin boyutu. - intermediate_size (
int, isteğe bağlı, varsayılan4096) — MLP temsillerinin boyutu. - num_hidden_layers (
int, isteğe bağlı, varsayılan12) — Transformer çözücüdeki gizli katman sayısı. - num_attention_heads (
int, isteğe bağlı, varsayılan16) — Transformer decoder'ındaki her dikkat katmanı için dikkat başı sayısı. - num_key_value_heads (
int, isteğe bağlı, varsayılan16) — Bu, Grouped Query Attention uygulamasında kullanılacak key_value başlarının sayısıdır.num_key_value_heads=num_attention_headsise model Multi Head Attention (MHA) kullanır,num_key_value_heads=1ise model Multi Query Attention (MQA) kullanır, aksi halde GQA kullanılır. Çok başlı bir checkpoint'i GQA checkpoint'ine dönüştürürken, her grup key ve value başı, o gruptaki tüm orijinal başların ortalama havuzlanması (meanpooling) ile oluşturulmalıdır. Daha fazla ayrıntı için bu makaleye göz atın. Belirtilmezse, varsayılan olaraknum_attention_headskullanılır. - hidden_act (
str, isteğe bağlı, varsayılansilu) — Çözücüdeki doğrusal olmayan aktivasyon fonksiyonu (fonksiyon veya dize). Örneğin,"gelu","relu","silu"vb. - max_position_embeddings (
int, isteğe bağlı, varsayılan4096) — Bu modelin kullanılabileceği en uzun dizi uzunluğu. - initializer_range (
float, isteğe bağlı, varsayılan0.02) — Tüm ağırlık matrislerini başlatmak için kullanılan truncated_normal_initializer'ın standart sapması. - rms_norm_eps (
float, isteğe bağlı, varsayılan1e-06) — rms normalizasyon katmanları tarafından kullanılan epsilon. - pad_token_id (
int, isteğe bağlı) — Sözlükte dolgu için kullanılan token kimliği. - tie_word_embeddings (
bool, isteğe bağlı, varsayılanFalse) — Modelintied_weights_keyseşlemesine göre ağırlık gömme bağlamalarının yapılıp yapılmayacağı. - rope_parameters (
Union[~modeling_rope_utils.RopeParameters, dict], isteğe bağlı) — RoPE gömme yapılandırma parametrelerini içeren sözlük. Sözlük,rope_thetaiçin bir değer ve daha uzunmax_position_embeddingsile RoPE kullanmak istiyorsanız ölçekleme için kullanılan isteğe bağlı parametreleri içermelidir. - attention_bias (
bool, isteğe bağlı, varsayılanFalse) — Öz-dikkat sırasında sorgu, anahtar, değer ve çıktı projeksiyon katmanlarında önyargı (bias) kullanılıp kullanılmayacağı. - attention_dropout (
Union[int, float], isteğe bağlı, varsayılan0.0) — Dikkat olasılıkları için dropout oranı. - head_dim (
int, isteğe bağlı, varsayılan64) — Dikkat başlığı boyutu. None ise, varsayılan olarak hidden_size // num_attention_heads değerini alır. - encoder_hidden_size (
int, isteğe bağlı, varsayılan48) — Gizli temsillerin boyutu. - downsampling_ratios (
list[int], isteğe bağlı, varsayılan[2, 2, 4, 4, 5]) — Kodlayıcıda indirgeme (downsampling) oranları. - semantic_model_config (
Union[Dict, Wav2Vec2BertConfig], isteğe bağlı) — Semantik (Wav2Vec2BertConfig) modelinin yapılandırma nesnesinin bir örneği. - activation_dropout (
float, isteğe bağlı, varsayılan0.1) — Tamamen bağlı katmandaki aktivasyonlar için dropout oranı. - quantization_dim (
int, isteğe bağlı, varsayılan 2048) — Vektör kuantizasyonu kod kitabı için boyut. - quantization_levels (
list[int], isteğe bağlı, varsayılan[4, 4, 4, 4, 4, 4, 4, 4]) — Vektör kuantizasyonu kod kitabı için seviyeler. - input_sampling_rate (
int, isteğe bağlı, varsayılan 16000) — Kodlayıcının girdi ses dalgasının örnekleme hızı, hertz (Hz) cinsinden. - output_sampling_rate (
int, isteğe bağlı, varsayılan 24000) — Çözücünün çıkış ses dalgasının örnekleme hızı, hertz (Hz) cinsinden.
Bu, bir NeuCodecModel yapılandırmasını depolamak için kullanılan yapılandırma sınıfıdır. Belirtilen argümanlara göre bir Neucodec modelini örneklemek ve model mimarisini tanımlamak için kullanılır. Varsayılan değerlerle bir yapılandırma örneği oluşturmak, neuphonic/neucodec ile benzer bir yapılandırmaya yol açar.
Yapılandırma nesneleri PreTrainedConfig sınıfından devralır ve model çıktılarını kontrol etmek için kullanılabilir. Daha fazla bilgi için PreTrainedConfig belgesini okuyun.
Örnek:
>>> 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.configNeuCodecFeatureExtractor
sınıf transformers.NeuCodecFeatureExtractor
< source >( feature_size = 80sampling_rate = 16000padding_value = 1.0hop_length = 320**kwargs )
Parametreler
- feature_size (
int, isteğe bağlı, varsayılan 80) — Çıkarılan özelliklerin boyutu. - sampling_rate (
int, isteğe bağlı, varsayılan 16000) — Ses dosyalarının dijitalleştirileceği örneklem hızı, hertz (Hz) cinsinden ifade edilir. - padding_value (
float, isteğe bağlı, varsayılan 1.0) — Mel spektrogramu için dolgu vektörlerini doldurmak için kullanılan değer. - hop_length (
int, isteğe bağlı, varsayılan 320) — Çerçeve başına kodlanan ses örneklerinin sayısı. Alt örnekleme oranlarının çarpımına eşdeğerdir. Akustik kodlayıcı girdi dolgusu için gereklidir.
NeuCodec özellik çıkarıcısı oluşturur; bu çıkarıcı, anlamsal kodlayıcı için mel-filtre bankası özelliklerini ve akustik kodlayıcı için dolgulu sesi hesaplar.
Bu özellik çıkarıcı, ana yöntemlerin çoğunu içeren SequenceFeatureExtractor sınıfından devralır. Kullanıcıların bu yöntemlerle ilgili daha fazla bilgi için bu üst sınıfa başvurması gerekir.
__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 )
Parametreler
- audio (
np.ndarray,torch.Tensor,list[np.ndarray],list[torch.Tensor]) — Şekli (num_channels, sequence_length) olan bir Numpy dizisi veya torch tensörü. Bir girdi grubu için bu tür dizilerin veya tensörlerin bir listesi de sağlanabilir. - padding (
bool,strveya PaddingStrategy, isteğe bağlı, varsayılan olarakTrue) — Dönen dizilere dolgu uygulanacak stratejiyi seçin (modelin dolgu yönüne ve dolgu indeksine göre):Trueveya'longest': Toplu işlemdeki en uzun dizinin uzunluğuna kadar dolgu yapılır (yalnızca tek bir dizi sağlandıysa dolgu yapılmaz).'max_length':max_lengthargümanı ile belirtilen maksimum uzunluğa veya bu argüman sağlanmadıysa modelin kabul edebileceği maksimum giriş uzunluğuna kadar doldurur.Falseveya'do_not_pad'(varsayılan): Dolgu yok (yani, farklı uzunluklarda diziler içeren bir parti çıktı olarak üretilebilir).
- max_length (
int, isteğe bağlı) — Döndürülen listenin ve isteğe bağlı dolgu uzunluğunun (bkz. yukarı) maksimum uzunluğu. - truncation (
bool) — max_length'den uzun olan girdi dizilerini max_length değerine kısaltmak için kesme işlemini etkinleştirir. - return_tensors (
strveya TensorType, isteğe bağlı) — Belirlenirse, Python tamsayı listesi yerine tensörler döndürülür. Kabul edilen değerler şunlardır:'tf': TensorFlowtf.constantnesnelerini döndürür.'pt': PyTorchtorch.Tensornesnelerini döndürür.'np': Numpynp.ndarraynesnelerini döndürür.
- sampling_rate (
int, isteğe bağlı) —audiogirdisinin örneklenmiş olduğu örnek hızı. Sessiz hataları önlemek içinsampling_ratedeğerini forward çağrısında geçmeniz şiddetle önerilir. - device (
str, isteğe bağlı, varsayılan"cpu") — Mel filtre bankası özellik çıkarımı sırasında PyTorch tensörleri için cihaz. - kwargs (isteğe bağlı) — Tokenizöre veya özellik çıkarıcıya iletilecek kalan anahtar-argüman sözlüğü.
NeuCodecModel
sınıf transformers.NeuCodecModel
< source >( config: NeuCodecConfig )
Parametreler
- config (NeuCodecConfig) — Modelin tüm parametrelerini içeren model yapılandırma sınıfı. Bir yapılandırma dosyasıyla başlatmak, modelle ilişkili ağırlıkları yüklemez, yalnızca yapılandırmayı yükler. Model ağırlıklarını yüklemek için from_pretrained() yöntemine bakın.
NeuCodec sinirsel ses kodlayıcı modeli.
Bu model PreTrainedModel sınıfından devralır. Kütüphanenin tüm modelleri için uyguladığı genel yöntemler (indirme veya kaydetme, giriş gömme boyutlarını yeniden boyutlandırma, başları budama vb.) için üst sınıf belgelendirmesine bakın.
Bu model aynı zamanda bir PyTorch torch.nn.Module alt sınıfıdır. Bunu standart bir PyTorch Module olarak kullanın ve genel kullanım ve davranışla ilgili tüm konular için PyTorch dokümantasyonuna başvurun.
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)
Parametreler
- audio_codes (
torch.LongTensor, şekli(batch_size, 1, codes_length)) —model.encodekullanılarak hesaplanan ayrık kod dizinleri. - latents (
torch.Tensor, şekli(batch_size, dimension, time_steps), opsiyonel) — Girdinin kuantize edilmiş sürekli temsili. - audio_codes_mask (
torch.Tensor, şekli(batch_size, codes_length), isteğe bağlı) —model.encodetarafından döndürülen, geçerli (doldurma olmayan) konumları işaretleyen maske. Değişken uzunluklu seslerin doğru toplu çözülmesi için gereklidir.
Dönüş değeri
NeuCodecDecoderOutput veya tuple(torch.Tensor)
NeuCodecDecoderOutput veya bir torch.Tensor demeti (eğer return_dict=False geçirildiyse veya config.return_dict=False ise), yapılandırmaya (None) ve girdilere bağlı olarak çeşitli öğelerden oluşur.
- audio_values (
torch.Tensor, şekli(batch_size, 1, segment_length), isteğe bağlı) — Süreklilik kodlarının sürekli ses sinyallerine geri dönüştürülmesiyle elde edilen, zaman alanında çözümlenmiş ses dalgası değerleri. Bu, oynatılabilen yeniden oluşturulmuş sesi temsil eder.
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)
Parametreler
- input_values (
torch.Tensor, şekli(batch_size, 1, sequence_length)) — Girdi ses dalgası. - input_features (
torch.Tensor, şekli(batch_size, mel_bins, time_steps)) — Anlamsal kodlama için girdi ses mel spektrogramu. - padding_mask (
torch.Tensor, şekli(batch_size, 1, sequence_length)) —input_valuesiçin dolgu yapmakta kullanılan dolgu maskesi. - input_features_mask (
torch.Tensor, şekli(batch_size, time_steps), isteğe bağlı) — Anlamsal kodlayıcıya giren spektrogram girdisi için dikkat maskesi. Geçerli kareler için1, dolgu için0. - output_latents (
bool, isteğe bağlı, varsayılanFalse) — Kuantizörden sürekli latent temsilin döndürülüp döndürülmeyeceğini belirtir.
Dönüş değeri
NeuCodecEncoderOutput veya tuple(torch.Tensor)
NeuCodecEncoderOutput veya bir torch.Tensor demeti (eğer return_dict=False geçirildiyse veya config.return_dict=False ise), yapılandırmaya (None) ve girdilere bağlı olarak çeşitli öğelerden oluşur.
- audio_codes (
torch.LongTensor, şekli(batch_size, 1, codes_length), isteğe bağlı) —model.encodekullanılarak hesaplanan ayrık kod gömüleri. Bunlar, depolama, iletim veya üretim için kullanılabilen, girdi ses sinyalının sıkıştırılmış ve kuantize edilmiş formunu temsil eder. - latents (
torch.Tensor, şekli(batch_size, dimension, time_steps)) — Girdinin gömme (embedding) değerlerinin kuantize edilmiş sürekli temsili. - audio_codes_mask (
torch.int32, şekli(batch_size, 1, codes_length), opsiyonel) —audio_codesiçindeki geçerli ses kodlarını belirtmek için indirgenmişpadding_mask.
forward
< 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'> ) → NeuCodecOutput or tuple(torch.Tensor)
Parametreler
- input_values (
torch.Tensor, şekli(batch_size, 1, sequence_length)) —config.input_sampling_rateörnekleme hızında örneklenmiş giriş ses dalgası. - input_features (
torch.Tensor, şekli(batch_size, mel_bins, time_steps)) — Anlamsal kodlama için girdi ses mel spektrogramu. - padding_mask (
torch.Tensor, şekli(batch_size, 1, sequence_length)) —input_valuesiçin dolgu yapmakta kullanılan dolgu maskesi. - input_features_mask (
torch.Tensor, şekli(batch_size, time_steps), isteğe bağlı) — Anlamsal kodlayıcıya giren spektrogram girdisi için dikkat maskesi. Geçerli kareler için1, dolgu için0. - output_latents (
bool, isteğe bağlı, varsayılanFalse) — Kuantizörden sürekli latent temsilin döndürülüp döndürülmeyeceğini belirtir.
Dönüş değeri
NeuCodecOutput veya tuple(torch.Tensor)
NeuCodecOutput veya
torch.Tensor bir demeti (eğer return_dict=False geçirildiyse veya config.return_dict=False ise), yapılandırmaya (None) ve girdilere bağlı olarak çeşitli öğelerden oluşur.
NeuCodecModel forward metodu, __call__ özel metodunu geçersiz kılar.
İleri geçiş tarifi bu fonksiyon içinde tanımlanmalı olsa da, sonrasında bunun yerine
Moduleörneğini çağırmak gerekir; çünkü önceki, ön ve son işleme adımlarını çalıştırmaktan sorumluyken ikincisi bunları sessizce yok sayar.
- audio_values (
torch.Tensor, şekli(batch_size, 1, sequence_length), isteğe bağlı) — NeuCodec'in decoder kısmı kullanılarak zaman alanında elde edilen, çözümlenmiş ses dalgası değerleri. Bunlar yeniden oluşturulan ses sinyalini temsil eder. - audio_codes (
torch.LongTensor, şekli(batch_size, 1, codes_length), opsiyonel) —model.encodekullanılarak hesaplanan ayrık kod gömme değerleri. Bunlar, ileri işleme veya üretim için kullanılan girdi sesinin kuantize edilmiş temsilleridir. - latents (
torch.Tensor, şekli(batch_size, dimension, time_steps)) — Girdinin gömme (embedding) değerlerinin kuantize edilmiş sürekli temsili. - audio_codes_mask (
torch.int32, şekli(batch_size, 1, codes_length), opsiyonel) —audio_codesiçindeki geçerli ses kodlarını belirtmek için indirgenmişpadding_mask.
Örnekler:
>>> 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