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

نُشر هذا النموذج في أوراق HF في 24 أكتوبر 2022، وأُضيف إلى مكتبة Hugging Face Transformers في 14 يونيو 2023.

EnCodec

نظرة عامة

قُدِّم نموذج الترميز العصبي EnCodec في High Fidelity Neural Audio Compression بواسطة Alexandre Défossez وJade Copet وGabriel Synnaeve وYossi Adi.

المستخلص من الورقة البحثية هو كالتالي:

نقدّم هنا مشفّرًا صوتيًا (Audio Codec) فائق الدقة يعمل في الوقت الفعلي، ويعتمد على الشبكات العصبية. يتكوّن هذا المشفّر من بنية مشفّرة-مفكّكة (Encoder-Decoder) تعمل على تدفّق البيانات، مع مساحة كامنة مُكمّاة (Quantized Latent Space) يتم تدريبها بطريقة شاملة من البداية إلى النهاية (End-to-End). نبسّط عملية التدريب ونسرّعها باستخدام مُنافس طيفي متعدد المقاييس (Multiscale Spectrogram Adversary) واحد، مما يقلّل من الشوائب بكفاءة ويولّد عينات عالية الجودة. نطرح آلية جديدة لموازنة الدالة الخاسرة (Loss Balancer) لتثبيت عملية التدريب؛ فوزن الدالة الخاسرة يحدد الآن نسبة التدرّج الكلي التي ينبغي أن تمثلها، مما يفصل اختيار هذا المعامل (Hyper-parameter) عن المقياس النموذجي للدالة الخاسرة. أخيرًا، ندرس كيف يمكن استخدام نماذج Transformer خفيفة الوزن لضغط التمثيل الناتج بنسبة تصل إلى 40%، مع الحفاظ على سرعة أعلى من سرعة الوقت الفعلي. نقدّم وصفًا تفصيليًا للخيارات التصميمية الرئيسية للنموذج المقترح، بما في ذلك: هدف التدريب، والتعديلات المعمارية، ودراسة لدوال الخسارة الإدراكية (Perceptual Loss Functions) المختلفة. نعرض تقييمًا ذاتيًا موسّعًا (اختبارات MUSHRA) إلى جانب دراسة استئصالية (Ablation Study) لمجموعة من نطاقات التردد ومجالات الصوت، بما في ذلك الكلام، والكلام في بيئات مليئة بالضجيج والصدى، والموسيقى. يتفوق نهجنا على الطرق المرجعية (Baselines) في جميع الإعدادات المُقيَّمة، مع الأخذ في الاعتبار الصوت أحادي القناة (Monophonic) بمعدل 24 كيلوهرتز والصوت ثنائي القناة (Stereophonic) بمعدل 48 كيلوهرتز.

تمت مساهمة هذا النموذج من قِبل Matthijs وPatrick Von Platen وArthur Zucker. يمكن العثور على الكود الأصلي هنا.

مثال على الاستخدام

فيما يلي مثال سريع على كيفية ترميز وفك ترميز صوت باستخدام هذا النموذج:

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

فئة 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 )

المعاملات

  • target_bandwidths (list[float]، اختياري، القيمة الافتراضية [1.5, 3.0, 6.0, 12.0, 24.0]) — نطاق النطاقات الترددية المختلفة التي يمكن للنموذج ترميز الصوت بها.
  • sampling_rate (int, اختياري، القيمة الافتراضية 24000) — معدل أخذ العينات الذي يجب أن تُرقَم به ملفات الصوت، ويُعبَّر عنه بالهرتز (Hz).
  • audio_channels (int، اختياري، القيمة الافتراضية 1) — عدد قنوات الإدخال.
  • normalize (bool، اختياري، القيمة الافتراضية False) — ما إذا كان يجب تطبيع الصوت عند تمريره.
  • chunk_length_s (float, اختياري) — إذا تم تعريفه، تتم معالجة الصوت مسبقاً إلى مقاطع بطول chunk_length_s ثم يتم ترميزها.
  • overlap (float، اختياري) — يحدد التداخل بين كل مقطع. يُستخدم لحساب chunk_stride باستخدام المعادلة التالية: int((1.0 - self.overlap) * self.chunk_length).
  • hidden_size (int، اختياري، القيمة الافتراضية 128) — أبعاد التمثيلات المخفية.
  • num_filters (int، اختياري، القيمة الافتراضية 32) — عدد نوى الالتفاف في طبقة الاستيفاء السفلي الأولى من EncodecConv1d.
  • num_residual_layers (int، اختياري، القيمة الافتراضية 1) — عدد طبقات الباقي.
  • upsampling_ratios (Sequence[int] ، اختياري، القيمة الافتراضية [8, 5, 4, 2]) — نسب حجم النواة والخطوة. يستخدم المُشفِّر نسب تقليل الحجم بدلاً من نسب تكبير الحجم، لذا سيقوم باستخدام النسب بالترتيب المعاكس لتلك المحددة هنا، والتي يجب أن تتطابق مع ترتيب المُفكِّك.
  • norm_type (str، اختياري، القيمة الافتراضية "weight_norm") — طريقة التطبيع. يجب أن تكون ضمن ["weight_norm", "time_group_norm"]
  • kernel_size (int، اختياري، القيمة الافتراضية 7) — حجم النواة للتمرير الأولي.
  • last_kernel_size (int، اختياري، القيمة الافتراضية 7) — حجم النواة لطبقة الالتفاف الأخيرة.
  • residual_kernel_size (int، اختياري، القيمة الافتراضية 3) — حجم النواة للطبقات المتبقية.
  • dilation_growth_rate (int، اختياري، القيمة الافتراضية 2) — مقدار زيادة التمدد (dilation) في كل طبقة.
  • use_causal_conv (bool، اختياري، القيمة الافتراضية True) — ما إذا كان سيتم استخدام التمرير التكاملي السببي بالكامل.
  • pad_mode (str، اختياري، القيمة الافتراضية "reflect") — وضع الحشو للعمليات التلافيفية.
  • compress (int، اختياري، القيمة الافتراضية 2) — تقليل الأبعاد في الفروع المتبقية (من Demucs v3).
  • num_lstm_layers (int، اختياري، القيمة الافتراضية 2) — عدد طبقات LSTM في نهاية المُشفِّر.
  • trim_right_ratio (float، اختياري، القيمة الافتراضية 1.0) — النسبة المستخدمة لقص الجزء الأيمن من الالتفاف المحوّر في إطار الإعداد use_causal_conv = True. إذا كانت تساوي 1.0، فهذا يعني أن كل عملية القص تتم على الجانب الأيمن.
  • codebook_size (int، اختياري، القيمة الافتراضية 1024) — عدد كتيّبات الرموز المتوازية التي يستخدمها النموذج.
  • codebook_dim (int، اختياري) — أبعاد متجه تضمين كل كتاب رموز.
  • use_conv_shortcut (bool، اختياري، القيمة الافتراضية True) — ما إذا كان سيتم استخدام طبقة تلافيفية كاتصال «تخطٍّ» في كتلة EncodecResnetBlock. إذا كانت القيمة False، فسيتم استخدام دالة الهوية، مما يؤدي إلى اتصال متبقّي عام.

هذه فئة الإعدادات المخزنة لإعدادات نموذج EncodecModel. تُستخدم لاستحداث نموذج Encodec وفقاً للحجج المحددة، مع تعريف بنية النموذج. إن استحداث إعدادات باستخدام القيم الافتراضية سيؤدي إلى الحصول على إعدادات مشابهة لتلك الخاصة بـ facebook/encodec_24khz

ترث كائنات التهيئة من PreTrainedConfig ويمكن استخدامها للتحكم في مخرجات النموذج. اقرأ التوثيق الخاص بـ PreTrainedConfig لمزيد من المعلومات.

مثال:

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

فئة transformers.EncodecFeatureExtractor

< >

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

المعاملات

  • feature_size (int، اختياري، القيمة الافتراضية 1) — أبعاد الميزة للميزات المستخرجة. استخدم 1 للمono و2 لـ stereo.
  • sampling_rate (int, اختياري، القيمة الافتراضية 24000) — معدل أخذ العينات الذي يجب أن تُرقَم به الموجة الصوتية، معبّرًا عنه بالهرتز (Hz).
  • padding_value (float، اختياري، القيمة الافتراضية 0.0) — القيمة المستخدمة لملء قيم الحشو.
  • chunk_length_s (float, اختياري) — إذا تم تعريفه، تتم معالجة الصوت مسبقاً إلى مقاطع بطول chunk_length_s ثم يتم ترميزها.
  • overlap (float، اختياري) — يحدد التداخل بين كل مقطع. يُستخدم لحساب chunk_stride باستخدام المعادلة التالية: int((1.0 - self.overlap) * self.chunk_length).

ينشئ مستخرج ميزات EnCodec.

يرث مستخرج الميزات هذا من SequenceFeatureExtractor الذي يحتوي على معظم الطرق الرئيسية. ينبغي للمستخدمين الرجوع إلى هذه الفئة الأصلية لمزيد من المعلومات حول تلك الطرق.

إنشاء مستخرج ميزات باستخدام القيم الافتراضية سيؤدي إلى تكوين مشابه لتكوين بنية facebook/encodec_24khz.

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

المعاملات

  • raw_audio (np.ndarray، list[float]، list[np.ndarray]، list[list[float]]) — التسلسل أو الدفعة من التسلسلات المراد معالجتها. يمكن أن يكون كل تسلسل مصفوفة numpy، أو قائمة من قيم float، أو قائمة من مصفوفات numpy، أو قائمة من قوائم قيم float. يجب أن تكون المصفوفة numpy من الشكل (num_samples,) للصوت أحادي القناة (feature_size = 1)، أو (2, num_samples) للصوت ثنائي القناة (feature_size = 2).
  • padding (bool, str أو PaddingStrategy, اختياري, الافتراضي هو True) — اختر استراتيجية لحشو التسلسلات المُعادَة (وفقًا لجانب الحشو وفهرس الحشو الخاص بالنموذج) من بين الخيارات التالية:
    • True أو 'longest': يتم ملء التسلسلات حتى أطول تسلسل في الدفعة (أو لا يتم أي ملء إذا تم تقديم تسلسل واحد فقط).
    • 'max_length': يتم ملء النص حتى الطول الأقصى المحدد عبر الحجة max_length أو حتى الطول الأقصى المقبول لإدخال النموذج إذا لم تُقدَّم تلك الحجة.
    • False أو 'do_not_pad' (الافتراضي): لا يوجد حشو (أي، يمكن إخراج دفعة تحتوي على تسلسلات بطول مختلف).
  • truncation (bool، اختياري، القيمة الافتراضية False) — يفعّل القصّ لقطع تسلسلات الإدخال الأطول من max_length إلى max_length.
  • max_length (int، اختياري) — الحد الأقصى لطول القائمة المُعادَة وطول الحشو بشكل اختياري (انظر أعلاه).
  • return_tensors (str أو TensorType, اختياري) — إذا تم تعيينه، فسيُعاد تينسورات بدلاً من قائمة من الأعداد الصحيحة في Python. القيم المقبولة هي:
    • 'pt': إرجاع كائنات torch.Tensor من PyTorch.
    • 'np': إرجاع كائنات np.ndarray من نوع Numpy.
  • sampling_rate (int, اختياري) — معدل أخذ العينات الذي تم به أخذ عينات مدخل audio. يُوصى بشدة بتمرير sampling_rate عند استدعاء الأمامي لمنع الأخطاء الصامتة.

الطريقة الرئيسية لتحويل السلسلة أو السلاسل إلى ميزات وتجهيزها للنموذج.

EncodecModel

فئة transformers.EncodecModel

< >

( config: EncodecConfig )

المعاملات

  • config (EncodecConfig) — فئة إعدادات النموذج التي تحتوي على جميع معاملات النموذج. لا يؤدي التهيئة باستخدام ملف الإعداد إلى تحميل الأوزان المرتبطة بالنموذج، بل الإعدادات فقط. راجع طريقة from_pretrained() لتحميل أوزان النموذج.

نموذج EnCodec، وهو مشفّر صوتي عصبي.

يرث هذا النموذج من PreTrainedModel. راجع توثيق الفئة الأصلية لمعرفة الطرق العامة التي تنفذها المكتبة لجميع نماذجها (مثل التحميل أو الحفظ، وتغيير حجم تضمينات الإدخال، وقص الرؤوس، وما إلى ذلك).

هذا النموذج هو أيضًا فئة فرعية من torch.nn.Module في PyTorch. استخدمه كوحدة PyTorch عادية، وارجع إلى توثيق PyTorch لكل ما يتعلق بالاستخدام العام والسلوك.

decode

< >

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

المعاملات

  • audio_codes (torch.LongTensor من الشكل (nb_frames, batch_size, nb_quantizers, frame_len)، اختياري) — تضمينات رموز منفصلة محسوبة باستخدام model.encode.
  • audio_scales (قائمة بطول nb_frames من torch.Tensor بشكل (batch_size, 1)، اختياري) — معامل التوسيع لكل مدخل audio_codes.
  • padding_mask (torch.Tensor من الشكل (channels, sequence_length)) — قناع الحشو المستخدم لحشو input_values.
  • return_dict (bool، اختياري) — ما إذا كان يجب إرجاع ModelOutput بدلاً من tuple عادي.
  • last_frame_pad_length (int, اختياري) — عدد صحيح يمثل طول الحشو في الإطار الأخير، والذي يُزال أثناء فك الترميز.

يفكك الإطارات المعطاة إلى موجة صوتية ناتجة.

لاحظ أن المخرجات قد تكون أكبر قليلاً من المدخلات. في هذه الحالة، يمكن قص أي خطوات زائدة في النهاية.

encode

< >

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

المعاملات

  • input_values (torch.Tensor من الشكل (batch_size, channels, sequence_length)) — قيمات عشرية لموجة الصوت المدخلة.
  • padding_mask (torch.Tensor من الشكل (batch_size, channels, sequence_length)) — قناع الحشو المستخدم لحشو input_values.
  • bandwidth (float، اختياري) — النطاق الترددي المستهدف. يجب أن يكون أحد قيم config.target_bandwidths. إذا كانت None، يتم استخدام أصغر نطاق ترددي ممكن. يُعبَّر عن bandwidth كألف من قيمته الفعلية، على سبيل المثال، يُعبَّر عن نطاق ترددي قدره 6kbps على أنه bandwidth == 6.0

يعيد

EncodecEncoderOutput قاموس أو مجموعة مرتبة تحتوي

  • audio_codes (torch.LongTensor من الشكل (nb_frames, batch_size, nb_quantizers, frame_len)، اختياري)،
  • audio_scales (قائمة بطول nb_frames من torch.Tensor بشكل (batch_size, 1)، اختياري)،
  • last_frame_pad_length (int، اختياري).

يقوم بتشفير موجة الصوت المدخلة إلى رموز منفصلة ذات الشكل (nb_frames, batch_size, nb_quantizers, frame_len).

  • nb_frames=1 إذا كان self.config.chunk_length=None (لأن المُشفِّر يُطبَّق على الصوت الكامل)، وهو ما ينطبق على نموذج 24kHz. وإلا، يكون nb_frames=ceil(input_length/self.config.chunk_stride)، وهو ما ينطبق على نموذج 48kHz.
  • frame_len هو طول كل إطار، وهو يساوي ceil(input_length/self.config.hop_length) إذا كان self.config.chunk_length=None (على سبيل المثال، بالنسبة لنموذج 24kHz). وإلا، إذا كان self.config.chunk_length معرّفًا، فإن frame_len=self.config.chunk_length/self.config.hop_length، على سبيل المثال، الحالة الخاصة بنموذج 48kHz حيث frame_len=150.

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)

المعاملات

  • input_values (torch.Tensor من الشكل (batch_size, channels, sequence_length)، اختياري) — مدخلات صوت خام تم تحويلها إلى Float وتم ملؤها بالطول المناسب لتُرمَّز باستخدام مقاطع من الطول self.chunk_length وخطوة config.chunk_stride.
  • padding_mask (torch.BoolTensor بشكل (batch_size, channels, sequence_length), اختياري) — قناع لتجنب حساب معاملات التوسيع على فهارس رموز الحشو (هل يمكننا تجنب حساب الالتفاف عليها؟). قيم القناع المختارة من [0, 1]: 1 للرموز غير المقنّعة، و0 للرموز المقنّعة. يجب دائمًا تمرير padding_mask، ما لم يكن المدخلات مقطوعة أو غير محشوّة. وذلك لأن المعالجة الفعّالة للتensors تتطلب حشو الصوت المدخل بحيث يكون input_length % stride = step حيث step = chunk_length-stride. وهذا يضمن أن جميع المقاطع لها نفس الشكل [0, 1]:
    • 1 للرموز التي لم تُقنَّع،
    • 0 للرموز التي تم إخفاؤها.

    يجب دائمًا تمرير padding_mask، ما لم يكن المدخلات مقصوصة أو غير مُسدَّدة. والسبب في ذلك هو أنه من أجل معالجة المصفوفات (tensors) بفعالية، يجب سدّ مسافات الصوت المدخل بحيث يكون input_length % stride = step حيث step = chunk_length-stride. وهذا يضمن أن تكون جميع المقاطع (chunks) بنفس الشكل

  • bandwidth (float, اختياري) — النطاق الترددي المستهدف. يجب أن يكون أحد قيم config.target_bandwidths. إذا كانت None، يتم استخدام أصغر نطاق ترددي ممكن. يُعبَّر عن bandwidth بالألف من قيمته الفعلية، على سبيل المثال، يُعبَّر عن نطاق ترددي قدره 6kbps على أنه bandwidth == 6.0
  • audio_codes (torch.LongTensor من الشكل (nb_frames, batch_size, nb_quantizers, frame_len)، اختياري) — تضمينات رموز منفصلة محسوبة باستخدام model.encode.
  • audio_scales (list بطول nb_frames من torch.Tensor بشكل (batch_size, 1)، اختياري) — معامل التوسيع لكل مدخل من audio_codes.
  • return_dict (bool، اختياري) — ما إذا كان يجب إرجاع المخرجات على شكل قاموس.
  • last_frame_pad_length (int, اختياري) — طول الحشو في الإطار الأخير، إن وُجد. يُستخدم هذا لضمان إمكانية إخراج الإطارات المُرمّزة كمُتجه (Tensor). يجب تمرير هذه القيمة أثناء فك الترميز لضمان إزالة الحشو من الإطارات المُرمّزة.

يعيد

EncodecOutput أو tuple(torch.Tensor)

EncodecOutput أو مجموعة (tuple) من torch.Tensor (إذا تم تمرير return_dict=False أو عندما يكون config.return_dict=False) وتتضمن عناصر مختلفة تعتمد على الإعداد (EncodecConfig) والمدخلات.

تتجاوز طريقة EncodecModel الخاصة بالتقدم الأمامي الطريقة الخاصة __call__.

على الرغم من أنه يجب تعريف وصفة المرور الأمامي داخل هذه الدالة، إلا أنه ينبغي استدعاء كائن Module بدلاً من هذه الدالة، لأن الكائن يتولى تنفيذ خطوات المعالجة المسبقة والمعالجة اللاحقة، بينما تتجاهل الدالة هذه الخطوات بصمت.

  • audio_codes (torch.LongTensor من الشكل (nb_frames, batch_size, nb_quantizers, frame_len)، اختياري) — تضمينات رموز منفصلة محسوبة باستخدام model.encode.
  • audio_values (torch.Tensor من الشكل (batch_size, segment_length)، اختياري) — قيم الصوت المُفكّكة، المُستخرجة باستخدام جزء فك الترميز في Encodec.

أمثلة:

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