Hugging Face's logo

Transformers documentation

EnCodec

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

Bu model 2022-10-24 tarihinde HF papers'ta yayımlandı ve 2023-06-14 tarihinde Hugging Face Transformers'a katkıda bulunuldu.

EnCodec

Genel Bakış

EnCodec sinir kodlayıcı modeli, Alexandre Défossez, Jade Copet, Gabriel Synnaeve ve Yossi Adi tarafından High Fidelity Neural Audio Compression makalesinde önerilmiştir.

Makalenin özeti aşağıdaki gibidir:

Yapay sinir ağlarını kullanan, son teknoloji, gerçek zamanlı ve yüksek sadakatli bir ses kodlayıcı (audio codec) sunuyoruz. Bu sistem, uçtan uca (end-to-end) olarak eğitilmiş, kuantize edilmiş gizli uzaya (latent space) sahip bir akış (streaming) kodlayıcı-çözücü (encoder-decoder) mimarisinden oluşmaktadır. Eğitim sürecini basitleştirmek ve hızlandırmak için, artefaktları verimli bir şekilde azaltan ve yüksek kaliteli örnekler üreten tek bir çok ölçekli spektrogram (multiscale spectrogram) rakibi (adversary) kullanıyoruz. Eğitimi stabilize etmek için yeni bir kayıp dengeleyici (loss balancer) mekanizması sunuyoruz: bir kaybın ağırlığı, artık toplam gradyanın temsil etmesi gereken kesriyi tanımlar; bu sayede bu hiper-parametrenin seçimi, kaybın tipik ölçeğinden bağımsız hale gelir. Son olarak, gerçek zamanlıdan daha hızlı kalmak koşuluyla, elde edilen temsilin hafif (lightweight) Transformer modelleri kullanılarak %40'a kadar daha fazla sıkıştırılabileceğini inceliyoruz. Önerilen modelin ana tasarım tercihlerinin ayrıntılı bir açıklamasını sunuyoruz; bunlar arasında eğitim hedefi, mimari değişiklikler ve çeşitli algısal kayıp (perceptual loss) fonksiyonlarının incelenmesi yer almaktadır. Konuşma, gürültülü-yankılı konuşma ve müzik dahil olmak üzere çeşitli bant genişlikleri ve ses alanları için kapsamlı bir öznel değerlendirme (MUSHRA testleri) ve bir ablatif çalışma (ablation study) sunuyoruz. Yaklaşımımız, hem 24 kHz monofonik hem de 48 kHz stereofonik ses için değerlendirilen tüm ayarlarda, taban (baseline) yöntemlere göre üstün performans göstermektedir.

Bu model Matthijs, Patrick Von Platen ve Arthur Zucker tarafından katkıda bulunmuştur. Orijinal kod 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 AutoProcessor, EncodecModel


librispeech_dummy = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")

model = EncodecModel.from_pretrained("facebook/encodec_24khz", device_map="auto")
processor = AutoProcessor.from_pretrained("facebook/encodec_24khz")
librispeech_dummy = librispeech_dummy.cast_column("audio", Audio(sampling_rate=processor.sampling_rate))
audio_sample = librispeech_dummy[-1]["audio"]["array"]
inputs = processor(raw_audio=audio_sample, sampling_rate=processor.sampling_rate, return_tensors="pt").to(model.device)

encoder_outputs = model.encode(inputs["input_values"], inputs["padding_mask"])
# `encoder_outputs.audio_codes` contains discrete codes
audio_values = model.decode(**encoder_outputs, padding_mask=inputs["padding_mask"])[0]
# or the equivalent with a forward pass
audio_values = model(inputs["input_values"], inputs["padding_mask"]).audio_values

EncodecConfig

sınıf transformers.EncodecConfig

< >

( 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 = Nonetarget_bandwidths: list[float] | tuple[float, ...] = (1.5, 3.0, 6.0, 12.0, 24.0)sampling_rate: int = 24000audio_channels: int = 1normalize: bool = Falsechunk_length_s: int | float | None = Noneoverlap: float | None = Nonehidden_size: int = 128num_filters: int = 32num_residual_layers: int = 1upsampling_ratios: list[int] | tuple[int, ...] = (8, 5, 4, 2)norm_type: str = 'weight_norm'kernel_size: int = 7last_kernel_size: int = 7residual_kernel_size: int = 3dilation_growth_rate: int = 2use_causal_conv: bool = Truepad_mode: str = 'reflect'compress: int = 2num_lstm_layers: int = 2trim_right_ratio: float = 1.0codebook_size: int = 1024codebook_dim: int | None = Noneuse_conv_shortcut: bool = True )

Parametreler

  • target_bandwidths (list[float], isteğe bağlı, varsayılan [1.5, 3.0, 6.0, 12.0, 24.0]) — Modelin ses kodlayabileceği farklı bant genişlikleri aralığı.
  • sampling_rate (int, isteğe bağlı, varsayılan 24000) — Ses dosyalarının dijitalleştirileceği örnekleme hızı, hertz (Hz) cinsinden ifade edilir.
  • audio_channels (int, isteğe bağlı, varsayılan 1) — Giriş kanal sayısı.
  • normalize (bool, isteğe bağlı, varsayılan False) — Ses geçirildiğinde normalize edilecek mi?
  • chunk_length_s (float, isteğe bağlı) — Tanımlıysa ses, chunk_length_s uzunluğunda parçalara bölünerek ön işlenir ve ardından kodlanır.
  • overlap (float, isteğe bağlı) — Her parça arasındaki örtüşmeyi tanımlar. chunk_stride değerini hesaplamak için aşağıdaki formül kullanılır: int((1.0 - self.overlap) * self.chunk_length).
  • hidden_size (int, isteğe bağlı, varsayılan 128) — Gizli temsillerin boyutu.
  • num_filters (int, isteğe bağlı, varsayılan 32) — İlk EncodecConv1d alt örnekleme katmanındaki konvolüsyon çekirdeklerinin sayısı.
  • num_residual_layers (int, isteğe bağlı, varsayılan 1) — Kalıntı katman sayısı.
  • upsampling_ratios (Sequence[int] , isteğe bağlı, varsayılan [8, 5, 4, 2]) — Çekirdek boyutu ve adım oranları. Kodlayıcı, örnekleme artırma oranları yerine örnekleme azaltma oranlarını kullandığından, burada belirtilen oranların ters sırasını kullanır ve bu sıralama çözücü sırasıyla eşleşmelidir.
  • norm_type (str, isteğe bağlı, varsayılan "weight_norm") — Normalizasyon yöntemi. ["weight_norm", "time_group_norm"] içinde olmalıdır.
  • kernel_size (int, isteğe bağlı, varsayılan 7) — İlk konvolüsyon için çekirdek boyutu.
  • last_kernel_size (int, isteğe bağlı, varsayılan 7) — Son konvolüsyon katmanının çekirdek boyutu.
  • residual_kernel_size (int, isteğe bağlı, varsayılan 3) — Residual katmanlar için çekirdek boyutu.
  • dilation_growth_rate (int, isteğe bağlı, varsayılan 2) — Her katmanda dilasyonun ne kadar artırılacağını belirtir.
  • use_causal_conv (bool, isteğe bağlı, varsayılan True) — Tamamen nedensel konvolüsyonun kullanılıp kullanılmayacağı.
  • pad_mode (str, isteğe bağlı, varsayılan "reflect") — Kovülasyonlar için dolgu modu.
  • compress (int, isteğe bağlı, varsayılan 2) — Demucs v3'ten gelen, artımsal dallardaki azaltılmış boyut.
  • num_lstm_layers (int, isteğe bağlı, varsayılan 2) — Kodlayıcının sonunda bulunan LSTM katmanlarının sayısı.
  • trim_right_ratio (float, isteğe bağlı, varsayılan 1.0) — use_causal_conv = True yapılandırmasında, transpoze konvolüsyonun sağ tarafında kırpma için kullanılan oran. 1.0'a eşitse, tüm kırpmanın sağ tarafta yapıldığı anlamına gelir.
  • codebook_size (int, isteğe bağlı, varsayılan 1024) — Modelin kullandığı paralel kod kitaplarının sayısı.
  • codebook_dim (int, isteğe bağlı) — Her codebook gömme vektörünün boyutu.
  • use_conv_shortcut (bool, isteğe bağlı, varsayılan True) — EncodecResnetBlock bloğunda ‘skip’ bağlantısı olarak bir konvolüsyon katmanı kullanılıp kullanılmayacağını belirtir. False ise, jenerik bir artımsal bağlantı sağlayan bir kimlik fonksiyonu kullanılır.

Bu, bir EncodecModel yapılandırmasını depolamak için kullanılan yapılandırma sınıfıdır. Belirtilen argümanlara göre bir Encodec modelini örneklemek ve model mimarisini tanımlamak için kullanılır. Varsayılan değerlerle bir yapılandırma örneklendiğinde, facebook/encodec_24khz ile benzer bir yapılandırma elde edilir.

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 EncodecModel, EncodecConfig

>>> # Initializing a "facebook/encodec_24khz" style configuration
>>> configuration = EncodecConfig()

>>> # Initializing a model (with random weights) from the "facebook/encodec_24khz" style configuration
>>> model = EncodecModel(configuration)

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

EncodecFeatureExtractor

sınıf transformers.EncodecFeatureExtractor

< >

( feature_size: int = 1sampling_rate: int = 24000padding_value: float = 0.0chunk_length_s: float | None = Noneoverlap: float | None = None**kwargs )

Parametreler

  • feature_size (int, isteğe bağlı, varsayılan 1) — Çıkarılan özelliklerin boyutu. Mono için 1, stereo için 2 kullanın.
  • sampling_rate (int, isteğe bağlı, varsayılan 24000) — Ses dalgasının dijitalleştirilmesi gereken örnekleme hızı, hertz (Hz) cinsinden ifade edilir.
  • padding_value (float, isteğe bağlı, varsayılan 0.0) — Doldurma değerlerini doldurmak için kullanılan değer.
  • chunk_length_s (float, isteğe bağlı) — Tanımlıysa ses, chunk_length_s uzunluğunda parçalara bölünerek ön işlenir ve ardından kodlanır.
  • overlap (float, isteğe bağlı) — Her parça arasındaki örtüşmeyi tanımlar. chunk_stride değerini hesaplamak için aşağıdaki formül kullanılır: int((1.0 - self.overlap) * self.chunk_length).

Bir EnCodec özellik çıkarıcı oluşturur.

Bu özellik çıkarıcı, ana yöntemlerin çoğunu içeren SequenceFeatureExtractor sınıfından devralır. Kullanıcıların bu yöntemler hakkında daha fazla bilgi için bu üst sınıfa başvurması gerekir.

Varsayılanlarla bir özellik çıkarıcı örneklenirse, facebook/encodec_24khz mimarisine benzer bir yapılandırma elde edilir.

__call__

< >

( raw_audio: numpy.ndarray | list[float] | list[numpy.ndarray] | list[list[float]]padding: bool | str | transformers.utils.generic.PaddingStrategy | None = Nonetruncation: bool | None = Falsemax_length: int | None = Nonereturn_tensors: str | transformers.utils.generic.TensorType | None = Nonesampling_rate: int | None = None )

Parametreler

  • raw_audio (np.ndarray, list[float], list[np.ndarray], list[list[float]]) — İşlenecek dizi veya dizi partisi. Her dizi, bir numpy dizisi, bir float değerleri listesi, bir numpy dizileri listesi veya float değerleri listeleri listesi olabilir. Mono ses için (feature_size = 1) numpy dizisinin şekli (num_samples,) olmalı, stereo ses için (feature_size = 2) ise (2, num_samples) olmalıdır.
  • padding (bool, str veya PaddingStrategy, isteğe bağlı, varsayılan olarak True) — Dönen dizilere dolgu uygulanacak stratejiyi seçin (modelin dolgu yönüne ve dolgu indeksine göre):
    • True veya '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_length argümanı ile belirtilen maksimum uzunluğa veya bu argüman sağlanmadıysa modelin kabul edebileceği maksimum giriş uzunluğuna kadar doldurur.
    • False veya 'do_not_pad' (varsayılan): Dolgu yok (yani, farklı uzunluklarda diziler içeren bir parti çıktı olarak üretilebilir).
  • truncation (bool, isteğe bağlı, varsayılan False) — max_length'den uzun giriş dizilerini max_length değerine kısaltmak için kesme işlemini etkinleştirir.
  • 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.
  • return_tensors (str veya TensorType, isteğe bağlı) — Belirlenirse, Python tamsayı listesi yerine tensörler döndürülür. Kabul edilen değerler şunlardır:
    • 'pt': PyTorch torch.Tensor nesnelerini döndürür.
    • 'np': Numpy np.ndarray nesnelerini döndürür.
  • sampling_rate (int, isteğe bağlı) — audio girdisinin örneklenmiş olduğu örneklem hızı. Sessiz hataları önlemek için ileri çağrıda sampling_rate değerini geçmek şiddetle önerilir.

Bir veya birden fazla diziyi model için özelliklendirmek ve hazırlamak için ana yöntem.

EncodecModel

sınıf transformers.EncodecModel

< >

( config: EncodecConfig )

Parametreler

  • config (EncodecConfig) — 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.

EnCodec sinirsel ses kodek 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

< >

( audio_codes: LongTensoraudio_scales: Tensorpadding_mask: typing.Optional[torch.Tensor] = Nonereturn_dict: bool | None = Nonelast_frame_pad_length: int | None = 0 )

Parametreler

  • audio_codes (torch.LongTensor, şekli (nb_frames, batch_size, nb_quantizers, frame_len), isteğe bağlı) — model.encode kullanılarak hesaplanan ayrık kod gömümleri.
  • audio_scales (uzunluğu nb_frames olan, (batch_size, 1) biçiminde torch.Tensor içeren bir liste, opsiyonel) — Her audio_codes girdisi için ölçekleme çarpanı.
  • padding_mask (torch.Tensor, şekli (channels, sequence_length)) — input_values için dolgu yapmakta kullanılan dolgu maskesi.
  • return_dict (bool, isteğe bağlı) — Düz bir tuple yerine ModelOutput döndürülecek mi?
  • last_frame_pad_length (int, isteğe bağlı) — Son karedeki dolgu uzunluğunu temsil eden ve çözümleme sırasında kaldırılan tamsayı.

Verilen kareleri bir çıkış ses dalgası biçiminde çözer.

Çıktının girdiden biraz daha büyük olabileceğini unutmayın. Bu durumda, sonundaki fazladan adımlar kesilebilir.

encode

< >

( input_values: Tensorpadding_mask: typing.Optional[torch.Tensor] = Nonebandwidth: float | None = Nonereturn_dict: bool | None = None ) → EncodecEncoderOutput dict or a tuple containing

Parametreler

  • input_values (torch.Tensor, şekli (batch_size, channels, sequence_length)) — Giriş ses dalgasının ondalık sayı değerleri.
  • padding_mask (torch.Tensor, şekli (batch_size, channels, sequence_length)) — input_values için dolgu yapmakta kullanılan dolgu maskesi.
  • bandwidth (float, isteğe bağlı) — Hedef bant genişliği. config.target_bandwidths içindeki değerlerden biri olmalıdır. None ise, mümkün olan en küçük bant genişliği kullanılır. bandwidth, değerinin binde biri olarak temsil edilir; örneğin 6kbps bant genişliği, bandwidth == 6.0 olarak temsil edilir.

Dönüş değeri

EncodecEncoderOutput dict veya bir tuple içeren

  • audio_codes (torch.LongTensor, şekli (nb_frames, batch_size, nb_quantizers, frame_len), isteğe bağlı),
  • audio_scales (uzunluğu nb_frames olan, (batch_size, 1) biçiminde torch.Tensor içeren bir liste, isteğe bağlı),
  • last_frame_pad_length (int, isteğe bağlı).

Girdi ses dalgacığını (nb_frames, batch_size, nb_quantizers, frame_len) biçiminde ayrık kodlara dönüştürür.

  • nb_frames=1, self.config.chunk_length=None ise (kodlayıcı tüm ses üzerinde uygulandığı için), 24 kHz modelinde durum budur. Aksi halde nb_frames=ceil(input_length/self.config.chunk_stride) olur, bu da 48 kHz modelinin durumudur.
  • frame_len, her çerçevenin uzunluğudur ve self.config.chunk_length=None ise (örneğin 24 kHz model için) ceil(input_length/self.config.hop_length)'e eşittir. Aksi halde, self.config.chunk_length tanımlıysa frame_len=self.config.chunk_length/self.config.hop_length olur; örneğin frame_len=150 olan 48 kHz model durumu.

forward

< >

( input_values: Tensorpadding_mask: typing.Optional[torch.BoolTensor] = Nonebandwidth: float | None = Noneaudio_codes: typing.Optional[torch.LongTensor] = Noneaudio_scales: typing.Optional[torch.Tensor] = Nonereturn_dict: bool | None = Nonelast_frame_pad_length: int | None = 0 ) → EncodecOutput or tuple(torch.Tensor)

Parametreler

  • input_values (torch.Tensor, şekli (batch_size, channels, sequence_length), isteğe bağlı) — Ham ses girdisi, Float'a dönüştürülür ve config.chunk_stride adım uzunluğu ile self.chunk_length uzunluğundaki parçalar kullanılarak kodlanabilmesi için uygun uzunluğa dolgu yapılır.
  • padding_mask (torch.BoolTensor şeklinde (batch_size, channels, sequence_length), isteğe bağlı) — Padding token indekslerinde ölçekleme faktörlerinin hesaplanmasını önlemek için maske (bu indekslerde conv hesaplamasından kaçınılabilir mi+). Mask değerleri [0, 1]:
    • 1, maskelenmemiş jetonlar için,
    • maskelenmiş jetonlar için 0.

    padding_mask, girdi kırpılmış veya dolgu yapılmamış olmadıkça her zaman iletilmelidir. Bunun nedeni, tensörleri etkili bir şekilde işleyebilmek için girdi sesinin input_length % stride = step koşulunu sağlayacak şekilde, step = chunk_length-stride olacak biçimde doldurulması gerektiğidir. Bu, tüm parçacıkların aynı şekle sahip olmasını garanti eder.

  • bandwidth (float, isteğe bağlı) — Hedef bant genişliği. config.target_bandwidths içindeki değerlerden biri olmalıdır. None ise en küçük olası bant genişliği kullanılır. bandwidth, değerinin binde biri olarak temsil edilir; örneğin 6kbps bant genişliği bandwidth == 6.0 olarak temsil edilir.
  • audio_codes (torch.LongTensor, şekli (nb_frames, batch_size, nb_quantizers, frame_len), isteğe bağlı) — model.encode kullanılarak hesaplanan ayrık kod gömümleri.
  • audio_scales (list, uzunluğu nb_frames, öğeleri (batch_size, 1) biçiminde torch.Tensor, isteğe bağlı) — Her audio_codes girdisi için ölçekleme çarpanı.
  • return_dict (bool, isteğe bağlı) — Çıktıların sözlük olarak döndürülüp döndürülmeyeceğini belirtir.
  • last_frame_pad_length (int, isteğe bağlı) — Varsa, son karedeki dolgu uzunluğu. Kodlanmış karelerin bir tensör olarak çıkarılabilmesini sağlamak için kullanılır. Kodlanmış karelerden dolguların kaldırılmasını sağlamak için bu değer, çözümleme sırasında geçirilmelidir.

Dönüş değeri

EncodecOutput veya tuple(torch.Tensor)

EncodecOutput veya bir torch.Tensor demeti (eğer return_dict=False geçirildiyse veya config.return_dict=False ise), yapılandırmaya (EncodecConfig) ve girdilere bağlı olarak çeşitli öğelerden oluşur.

EncodecModel 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_codes (torch.LongTensor, şekli (nb_frames, batch_size, nb_quantizers, frame_len), opsiyonel) — model.encode kullanılarak hesaplanan ayrık kod gömme değerleri.
  • audio_values (torch.Tensor, şekli (batch_size, segment_length), isteğe bağlı) — Encodec'in decoder kısmı kullanılarak elde edilen çözümlenmiş ses değerleri.

Örnekler:

>>> from datasets import load_dataset
>>> from transformers import AutoProcessor, EncodecModel

>>> dataset = load_dataset("hf-internal-testing/ashraq-esc50-1-dog-example")
>>> audio_sample = dataset["train"]["audio"][0]["array"]

>>> model_id = "facebook/encodec_24khz"
>>> model = EncodecModel.from_pretrained(model_id)
>>> processor = AutoProcessor.from_pretrained(model_id)

>>> inputs = processor(raw_audio=audio_sample, return_tensors="pt")

>>> outputs = model(**inputs)
>>> audio_codes = outputs.audio_codes
>>> audio_values = outputs.audio_values
Update on GitHub

←Dia FastSpeech2Conformer→