Hugging Face's logo

Transformers documentation

MusicGen Melody

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 في 2023-06-08 وسُهم به في Hugging Face Transformers في 2024-03-18.

MusicGen Melody

FlashAttention SDPA

نظرة عامة

قُدِّم نموذج MusicGen Melody في Simple and Controllable Music Generation من قِبل Jade Copet وFelix Kreuk وItai Gat وTal Remez وDavid Kant وGabriel Synnaeve وYossi Adi وAlexandre Défossez.

MusicGen Melody هو نموذج Transformer ذاتي التراجع (auto-regressive) من مرحلة واحدة، قادر على توليد عينات موسيقية عالية الجودة مشروطة بوصف نصي أو تلميحات صوتية. تُمرَّر الأوصاف النصية عبر نموذج مُشفِّر للنص مجمّد (frozen) للحصول على تسلسل من تمثيلات الحالة المخفية (hidden-state representations). ثم يُدرَّب MusicGen على التنبؤ برموز صوتية منفصلة، أو رموز صوتية، مشروطة بهذه الحالات المخفية. بعد ذلك، تُفكَّك هذه الرموز الصوتية باستخدام نموذج ضغط صوتي، مثل EnCodec، لاستعادة الموجة الصوتية.

من خلال نمط فعال لتبديل الرموز، لا يتطلب MusicGen تمثيلاً دلاليًا ذاتي الإشراف لروابط النص/الصوت، مما يلغي الحاجة إلى تسلسل عدة نماذج للتنبؤ بمجموعة من كتل الترميز (مثلًا بشكل هرمي أو عبر زيادة العينة). وبدلًا من ذلك، يستطيع توليد جميع كتل الترميز في تمريرة أمامية واحدة.

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

نتناول مهمة توليد الموسيقى الشرطي. نُقدّم MusicGen، وهو نموذج لغوي (LM) واحد يعمل على عدة تدفقات من تمثيل الموسيقى المنفصل المضغوط، أي الرموز. على عكس الأعمال السابقة، يتكوّن MusicGen من نموذج لغوي محوّل (transformer) من مرحلة واحدة مع أنماط تبديل رموز فعّالة، مما يلغي الحاجة إلى تسلسل عدة نماذج، مثل التسلسل الهرمي أو رفع العينة. باتباع هذا النهج، نُظهر كيف يمكن لـ MusicGen توليد عينات عالية الجودة، مع اشتراطها على الوصف النصي أو السمات اللحنية، مما يتيح سيطرة أفضل على المخرجات المولّدة. أجرينا تقييمًا تجريبيًا شاملًا، مع الأخذ في الاعتبار كلًا من الدراسات الآلية والبشرية، مما يُظهر أن النهج المقترح يتفوق على الخطوط الأساسية المُقيَّمة على معيار قياسي لتحويل النص إلى موسيقى. من خلال دراسات الاستئصال، نُسلّط الضوء على أهمية كلٍّ من المكونات التي يتكوّن منها MusicGen.

تمت مساهمة هذا النموذج من قِبل ylacombe. يمكن العثور على الكود الأصلي هنا. يمكن العثور على نقاط التفتيش المُسبقة التدريب على Hugging Face Hub.

الفرق مع MusicGen

هناك فرقان رئيسيان مع MusicGen:

  1. يُستخدم موجه الصوت هنا كإشارة شرطية لعينة الصوت المولّدة، بينما يُستخدم للاستمرار الصوتي في MusicGen.
  2. تُدمج إشارات النص والصوت الشرطية مع حالات المخفية في المُفكِّك بدلاً من استخدامها كإشارة انتباه متقاطع، كما هو الحال في MusicGen.

الإنشاء

يتوافق MusicGen Melody مع وضعَي توليد: التهامي (greedy) والعينة (sampling). عمليًا، يؤدي وضع العينة إلى نتائج أفضل بكثير من التهامي، لذا نشجع على استخدام وضع العينة كلما أمكن. يكون وضع العينة مفعّلًا افتراضيًا، ويمكن تحديده صراحةً عن طريق تعيين do_sample=True في الاستدعاء إلى MusicgenMelodyForConditionalGeneration.generate()، أو عن طريق تجاوز إعدادات التوليد للنموذج (انظر أدناه).

يدعم Transformers كلا من النسخ أحادية القناة (قناة واحدة) والنسخ ثنائية القناة (قناتان) من MusicGen Melody. تولّد النسخ أحادية القناة مجموعة واحدة من كُتُب الرموز (codebooks). أما النسخ ثنائية القناة فتولّد مجموعتين من كُتُب الرموز، واحدة لكل قناة (يسار/يمين)، ويُفكّ تشفير كل مجموعة من كُتُب الرموز بشكل مستقل عبر نموذج ضغط الصوت. ثم تُدمج تدفقات الصوت لكل قناة لإعطاء المخرج النهائي ثنائي القناة.

توليد مشروط بالصوت

يمكن للنموذج توليد عينة صوتية مشروطة بنص وموجّه صوتي من خلال استخدام MusicgenMelodyProcessor لمعالجة المدخلات مسبقًا.

في الأمثلة التالية، نقوم بتحميل ملف صوتي باستخدام مكتبة 🤗 Datasets، والتي يمكن تثبيتها عبر pip باستخدام الأمر أدناه:

pip install --upgrade pip
pip install datasets[audio]

يتم تحميل ملف الصوت الذي سنستخدمه على النحو التالي:

from datasets import load_dataset


dataset = load_dataset("sanchit-gandhi/gtzan", split="train", streaming=True)
sample = next(iter(dataset))["audio"]

يجب أن يكون المقتطف الصوتي خالياً في المثالي من الإشارات منخفضة التردد التي تنتجها عادةً آلات مثل الطبول والباس. يمكن استخدام نموذج Demucs لفصل الأصوات البشرية والإشارات الأخرى عن مكونات الطبول والباس.

إذا كنت ترغب في استخدام Demucs، فأنت بحاجة أولاً إلى اتباع خطوات التثبيت هنا قبل استخدام المقطع التالي:

import torch
from demucs import pretrained
from demucs.apply import apply_model
from demucs.audio import convert_audio


wav = torch.tensor(sample["array"]).to(torch.float32)

demucs = pretrained.get_model('htdemucs')

wav = convert_audio(wav[None], sample["sampling_rate"], demucs.samplerate, demucs.audio_channels)
wav = apply_model(demucs, wav[None])

يمكنك بعد ذلك استخدام المقطع التالي لتوليد الموسيقى:

from transformers import AutoProcessor, MusicgenMelodyForConditionalGeneration


processor = AutoProcessor.from_pretrained("facebook/musicgen-melody")
model = MusicgenMelodyForConditionalGeneration.from_pretrained("facebook/musicgen-melody", device_map="auto")

inputs = processor(
    audio=wav,
    sampling_rate=demucs.samplerate,
    text=["80s blues track with groovy saxophone"],
    padding=True,
    return_tensors="pt",
)
audio_values = model.generate(**inputs, do_sample=True, guidance_scale=3, max_new_tokens=256)

يمكنك أيضًا تمرير إشارة الصوت مباشرةً دون استخدام Demucs، على الرغم من أن جودة التوليد ستُتدهور على الأرجح:

from transformers import AutoProcessor, MusicgenMelodyForConditionalGeneration


processor = AutoProcessor.from_pretrained("facebook/musicgen-melody")
model = MusicgenMelodyForConditionalGeneration.from_pretrained("facebook/musicgen-melody", device_map="auto")

inputs = processor(
    audio=sample["array"],
    sampling_rate=sample["sampling_rate"],
    text=["80s blues track with groovy saxophone"],
    padding=True,
    return_tensors="pt",
)
audio_values = model.generate(**inputs, do_sample=True, guidance_scale=3, max_new_tokens=256)

المخرجات الصوتية هي متغير Torch ثلاثي الأبعاد من الشكل (batch_size, num_channels, sequence_length). للاستماع إلى العينات الصوتية المولّدة، يمكنك إما تشغيلها في دفتر ملاحظات ipynb:

from IPython.display import Audio


sampling_rate = model.config.audio_encoder.sampling_rate
Audio(audio_values[0].numpy(), rate=sampling_rate)

أو احفظها كملف .wav باستخدام مكتبة طرف ثالث، مثل soundfile:

import soundfile as sf


sampling_rate = model.config.audio_encoder.sampling_rate
sf.write("musicgen_out.wav", audio_values[0].T.numpy(), sampling_rate)

التوليف الشرطي النصي فقط

يمكن استخدام MusicgenMelodyProcessor نفسه لمعالجة موجه نصي فقط مسبقًا.

from transformers import AutoProcessor, MusicgenMelodyForConditionalGeneration


processor = AutoProcessor.from_pretrained("facebook/musicgen-melody")
model = MusicgenMelodyForConditionalGeneration.from_pretrained("facebook/musicgen-melody", device_map="auto")

inputs = processor(
    text=["80s pop track with bassy drums and synth", "90s rock song with loud guitars and heavy drums"],
    padding=True,
    return_tensors="pt",
)
audio_values = model.generate(**inputs, do_sample=True, guidance_scale=3, max_new_tokens=256)

يُستخدم guidance_scale في التوجيه الحر من المُصنِّف (CFG)، حيث يحدد الوزن بين القيم الاحتمالية الشرطية (التي تُتنبأ بها من أوامر النص) والقيم الاحتمالية غير الشرطية (التي تُتنبأ بها من أمر غير شرطي أو 'فارغ'). كلما ارتفع مقياس التوجيه، شجّع ذلك النموذج على توليد عينات أكثر ارتباطًا بأمر الإدخال، وعادةً على حساب جودة صوتية أدنى. يتم تفعيل CFG عن طريق تعيين guidance_scale > 1. للحصول على أفضل النتائج، استخدم guidance_scale=3 (الافتراضي).

يمكنك أيضًا توليد الدفعات:


from transformers import AutoProcessor, MusicgenMelodyForConditionalGeneration


processor = AutoProcessor.from_pretrained("facebook/musicgen-melody")
model = MusicgenMelodyForConditionalGeneration.from_pretrained("facebook/musicgen-melody", device_map="auto")

# take the first quarter of the audio sample
sample_1 = sample["array"][: len(sample["array"]) // 4]

# take the first half of the audio sample
sample_2 = sample["array"][: len(sample["array"]) // 2]

inputs = processor(
    audio=[sample_1, sample_2],
    sampling_rate=sample["sampling_rate"],
    text=["80s blues track with groovy saxophone", "90s rock song with loud guitars and heavy drums"],
    padding=True,
    return_tensors="pt",
)
audio_values = model.generate(**inputs, do_sample=True, guidance_scale=3, max_new_tokens=256)

التوليد غير المشروط

يمكن الحصول على المدخلات للتوليد غير الشرطي (أو “الفارغ”) من خلال الطريقة MusicgenMelodyProcessor.get_unconditional_inputs():

from transformers import MusicgenMelodyForConditionalGeneration, MusicgenMelodyProcessor


model = MusicgenMelodyForConditionalGeneration.from_pretrained("facebook/musicgen-melody", device_map="auto")
unconditional_inputs = MusicgenMelodyProcessor.from_pretrained("facebook/musicgen-melody").get_unconditional_inputs(num_samples=1)

audio_values = model.generate(**unconditional_inputs, do_sample=True, max_new_tokens=256)

إعدادات التوليد

يمكن العثور على المعلمات الافتراضية التي تتحكم في عملية التوليد، مثل أخذ العينات، ومقياس التوجيه، وعدد الرموز المولّدة، في إعدادات التوليد الخاصة بالنموذج، ويمكن تحديثها حسب الرغبة:

from transformers import MusicgenMelodyForConditionalGeneration


model = MusicgenMelodyForConditionalGeneration.from_pretrained("facebook/musicgen-melody", device_map="auto")

# inspect the default generation config
model.generation_config

# increase the guidance scale to 4.0
model.generation_config.guidance_scale = 4.0

# decrease the max length to 256 tokens
model.generation_config.max_length = 256

لاحظ أن أي معاملات تُمرَّر إلى طريقة generate ستُغني عن تلك الموجودة في إعدادات التوليد، لذا فإن تعيين do_sample=False في الاستدعاء الخاص بـ generate سيغني عن تعيين model.generation_config.do_sample في إعدادات التوليد.

هيكل النموذج

يمكن تفكيك نموذج MusicGen إلى ثلاث مراحل متميزة:

  1. مُشفِّر النص: يُحوِّل مدخلات النص إلى تسلسل من تمثيلات الحالات المخفية. تستخدم نماذج MusicGen المُدرَّبة مسبقًا مُشفِّر نص مجمَّدًا من T5 أو Flan-T5.
  2. فكّ الترميز اللوني لموسيقجين: نموذج لغوي (LM) يولّد رموز الصوت (أو الأكواد) بشكل تلقائي متتابع مشروطًا بتمثيلات الحالة المخفية للمشفّر
  3. مفكّك الصوت: يُستخدم لاستعادة موجة الصوت من رموز الصوت التي يتنبأ بها المفكّك.

وبالتالي، يمكن استخدام نموذج Musicgen إما كنموذج فك ترميز مستقل، مما يتوافق مع الفئة MusicgenMelodyForCausalLM، أو كنموذج مركّب يتضمن مُرمّز النص ومُرمّز الصوت، مما يتوافق مع الفئة MusicgenMelodyForConditionalGeneration. إذا كان من الضروري تحميل فك الترميز فقط من نقطة الفحص المُدرَّبة مسبقًا، فيمكن تحميله عن طريق تحديد الإعداد الصحيح أولاً، أو الوصول إليه من خلال خاصية .decoder في النموذج المركّب:

from transformers import AutoConfig, MusicgenMelodyForCausalLM, MusicgenMelodyForConditionalGeneration


# Option 1: get decoder config and pass to `.from_pretrained`
decoder_config = AutoConfig.from_pretrained("facebook/musicgen-melody").decoder
decoder = MusicgenMelodyForCausalLM.from_pretrained("facebook/musicgen-melody", **decoder_config.to_dict(), device_map="auto")

# Option 2: load the entire composite model, but only return the decoder
decoder = MusicgenMelodyForConditionalGeneration.from_pretrained("facebook/musicgen-melody", device_map="auto").decoder

بما أن نموذجَي مُشفِّر النص ومُشفِّر الصوت مجمّدان أثناء التدريب، يمكن تدريب مُفكِّك MusicGen MusicgenMelodyForCausalLM بشكل مستقل على مجموعة بيانات من حالات المُشفِّر المخفية وأكواد الصوت. أما عند الاستدلال، فيمكن دمج المُفكِّك المُدرَّب مع مُشفِّر النص ومُشفِّر الصوت المجمّدين لاستعادة النموذج المركّب MusicgenMelodyForConditionalGeneration.

تحويل نقاط التفتيش

  • بعد تنزيل نقاط التفتيش الأصلية من هنا، يمكنك تحويلها باستخدام سكربت التحويل المتاح في src/transformers/models/musicgen_melody/convert_musicgen_melody_transformers.py عبر الأمر التالي:
python src/transformers/models/musicgen_melody/convert_musicgen_melody_transformers.py \
    --checkpoint="facebook/musicgen-melody" --pytorch_dump_folder /output/path

نصائح:

  • يتم تدريب MusicGen على نقطة الفحص (checkpoint) بمعدل عينة 32kHz من Encodec. يجب عليك التأكد من استخدام إصدار متوافق من نموذج Encodec.
  • تميل وضعية العينة إلى تقديم نتائج أفضل من وضعية الطمع - يمكنك التبديل إلى العينة باستخدام المتغير do_sample في الاستدعاء إلى MusicgenMelodyForConditionalGeneration.generate()

MusicgenMelodyDecoderConfig

فئة transformers.MusicgenMelodyDecoderConfig

< >

( 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 = Nonevocab_size: int = 2048max_position_embeddings: int = 2048num_hidden_layers: int = 24ffn_dim: int = 4096num_attention_heads: int = 16layerdrop: float | int = 0.0use_cache: bool = Trueactivation_function: str = 'gelu'hidden_size: int = 1024dropout: float | int = 0.1attention_dropout: float | int = 0.0activation_dropout: float | int = 0.0initializer_factor: float = 0.02scale_embedding: bool = Falsenum_codebooks: int = 4audio_channels: int = 1pad_token_id: int | None = 2048bos_token_id: int | None = 2048eos_token_id: int | list[int] | None = Nonetie_word_embeddings: bool = Falseis_decoder: bool = Falseadd_cross_attention: bool = False )

المعاملات

  • vocab_size (int، اختياري، القيمة الافتراضية 2048) — حجم مفردات النموذج. يحدد عدد الرموز المختلفة التي يمكن تمثيلها بواسطة input_ids.
  • max_position_embeddings (int، اختياري، القيمة الافتراضية 2048) — أقصى طول تسلسل قد يُستخدم معه هذا النموذج.
  • num_hidden_layers (int، اختياري، القيمة الافتراضية 24) — عدد الطبقات المخفية في مُفكِّك Transformer.
  • ffn_dim (int، اختياري، القيمة الافتراضية 4096) — بعد تمثيلات MLP.
  • num_attention_heads (int، اختياري، القيمة الافتراضية 16) — عدد رؤوس الانتباه لكل طبقة انتباه في مُفكِّك Transformer.
  • layerdrop (Union[float, int]، اختياري، القيمة الافتراضية 0.0) — احتمالية LayerDrop. راجع [ورقة LayerDrop](انظر https://huggingface.co/papers/1909.11556) لمزيد من التفاصيل.
  • use_cache (bool، اختياري، القيمة الافتراضية True) — ما إذا كان يجب على النموذج إرجاع قيم المفاتيح/القيم الأخيرة للانتباه (لا تستخدمها جميع النماذج). لا ينطبق إلا إذا كان config.is_decoder=True أو إذا كان النموذج نموذجًا توليديًا يعتمد على المُفكِّك فقط.
  • activation_function (str، اختياري، القيمة الافتراضية gelu) — دالة التنشيط غير الخطية (دالة أو نص) في المُفكِّك. على سبيل المثال، "gelu"، "relu"، "silu"، وغيرها.
  • hidden_size (int، اختياري، القيمة الافتراضية 1024) — أبعاد التمثيلات المخفية.
  • dropout (Union[float, int]، اختياري، القيمة الافتراضية 0.1) — النسبة لجميع طبقات dropout.
  • attention_dropout (Union[float, int]، اختياري، القيمة الافتراضية 0.0) — نسبة إسقاط (dropout) لاحتمالات الانتباه.
  • activation_dropout (Union[float, int]، اختياري، القيمة الافتراضية 0.0) — نسبة dropout للتفعيلات داخل الطبقة المتصلة بالكامل.
  • initializer_factor (float, اختياري، القيمة الافتراضية 0.02) — عامل يُستخدم لتجميع جميع مصفوفات الأوزان (يجب إبقاؤه عند القيمة 1، ويُستخدم داخليًا لاختبارات التهيئة).
  • scale_embedding (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم توسيع التضمينات (embeddings) من خلال القسمة على sqrt(d_model).
  • num_codebooks (int، اختياري، القيمة الافتراضية 4) — عدد كتيّبات الرموز المتوازية التي يستخدمها النموذج.
  • audio_channels (int، اختياري، القيمة الافتراضية 1) — عدد قنوات الصوت التي يستخدمها النموذج (إما أحادية أو ستيريو). تولّد نماذج الستيريو تدفقًا صوتيًا منفصلًا لكل من قناتي الإخراج اليسرى واليمنى. أما النماذج الأحادية فتولّد تدفقًا صوتيًا واحدًا للإخراج.
  • pad_token_id (int، اختياري، القيمة الافتراضية 2048) — معرّف الرمز المستخدم للتعبئة في المفردات.
  • bos_token_id (int، اختياري، القيمة الافتراضية 2048) — معرّف الرمز المستخدم لبدء البث في المفردات.
  • eos_token_id (Union[int, list[int]], اختياري) — معرّف الرمز المستخدم لنهاية التدفق في المفردات.
  • tie_word_embeddings (bool، اختياري، القيمة الافتراضية False) — ما إذا كان سيتم ربط ترميزات الأوزان وفقاً لخريطة tied_weights_keys الخاصة بالنموذج.
  • is_decoder (bool، اختياري، القيمة الافتراضية False) — ما إذا كان النموذج يُستخدم كمفكّك (decoder) أم لا. إذا كانت القيمة False، يُستخدم النموذج كمُرمِّز (encoder).
  • add_cross_attention (bool، اختياري، القيمة الافتراضية False) — ما إذا كان يجب إضافة طبقات الانتباه المتقاطع إلى النموذج.

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

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

MusicgenMelodyProcessor

فئة transformers.MusicgenMelodyProcessor

< >

( feature_extractortokenizer )

المعاملات

  • feature_extractor (MusicgenMelodyFeatureExtractor) — مستخرج الميزات هو مدخل مطلوب.
  • tokenizer (T5Tokenizer) — مُجزِّئ النصّ مدخل إلزامي.

ينشئ MusicgenMelodyProcessor الذي يجمع مستخرج الميزات ومجزئ الرموز في معالج واحد.

يوفر MusicgenMelodyProcessor جميع وظائف MusicgenMelodyFeatureExtractor وT5Tokenizer. راجع ~MusicgenMelodyFeatureExtractor و~T5Tokenizer لمزيد من المعلومات.

__call__

< >

( *args**kwargs )

المعاملات

  • return_tensors (str أو TensorType, اختياري) — إذا تم تعيينه، فسيُعاد تينسورات من إطار عمل محدد. القيم المقبولة هي:
    • 'pt': إرجاع كائنات torch.Tensor من PyTorch.
    • 'np': إرجاع كائنات np.ndarray من NumPy.

get_unconditional_inputs

< >

( num_samples = 1return_tensors = 'pt' )

المعاملات

  • num_samples (int, اختياري) — عدد عينات الصوت التي سيتم توليدها بشكل غير مشروط.

دالة مساعدة للحصول على مدخلات فارغة (null) للتوليد غير الشرطي، مما يتيح استخدام النموذج دون الحاجة إلى مستخرج الميزات أو المرمّز.

مثال:

>>> from transformers import MusicgenMelodyForConditionalGeneration, MusicgenMelodyProcessor

>>> model = MusicgenMelodyForConditionalGeneration.from_pretrained("facebook/musicgen-melody")

>>> # get the unconditional (or 'null') inputs for the model
>>> processor = MusicgenMelodyProcessor.from_pretrained("facebook/musicgen-melody")
>>> unconditional_inputs = processor.get_unconditional_inputs(num_samples=1)

>>> audio_samples = model.generate(**unconditional_inputs, max_new_tokens=256)

MusicgenMelodyFeatureExtractor

فئة transformers.MusicgenMelodyFeatureExtractor

< >

( feature_size = 12sampling_rate = 32000hop_length = 4096chunk_length = 30n_fft = 16384num_chroma = 12padding_value = 0.0return_attention_mask = Falsestem_indices = [3, 2]**kwargs )

المعاملات

  • feature_size (int، اختياري، القيمة الافتراضية 12) — بعد الميزة للميزات المستخرجة.
  • sampling_rate (int، اختياري، القيمة الافتراضية 32000) — معدل أخذ العينات الذي يجب أن تُرقَم به ملفات الصوت، معبّرًا عنه بالهرتز (Hz).
  • hop_length (int، اختياري، القيمة الافتراضية 4096) — طول النوافذ المتداخلة المستخدمة في تحويل فورييه الزمني القصير (STFT) للحصول على معاملات ترددات ميل.
  • chunk_length (int، اختياري، القيمة الافتراضية 30) — الحد الأقصى لعدد المقاطع المكوّنة من sampling_rate عينة، المستخدمة لقصّ تسلسلات الصوت الأطول أو ملء تسلسلات الصوت الأقصر.
  • n_fft (int، اختياري، القيمة الافتراضية 16384) — حجم تحويل فورييه.
  • num_chroma (int، اختياري، القيمة الافتراضية 12) — عدد حاويات الكروما (chroma bins) المستخدمة.
  • padding_value (float، اختياري، القيمة الافتراضية 0.0) — قيمة الحشو المستخدمة لحشو الصوت.
  • return_attention_mask (bool, اختياري, الافتراضي هو False) — ما إذا كان يجب إرجاع قناع الانتباه. يمكن تجاوز هذا الإعداد عند استدعاء مستخرج الميزات. ما هي أقنعة الانتباه؟ بالنسبة لنماذج Whisper، يجب دائمًا تمرير attention_mask للاستدلال الدُفعي، لتجنب الأخطاء الدقيقة.

    ما هي أقنعة الانتباه؟

    فيما يتعلق بنماذج Whisper، يجب دائمًا تمرير attention_mask عند الاستدلال الدُفعي (batched inference) لتجنب الأخطاء الدقيقة.

  • stem_indices (list[int]، اختياري، القيمة الافتراضية [3, 2]) — قنوات الجذع التي يجب استخراجها إذا تم تمرير مخرجات demucs.

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

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

تستخرج هذه الفئة ميزات الكروما من الصوت المعالج بواسطة Demucs أو مباشرة من موجة الصوت الخام.

MusicgenMelodyConfig

فئة transformers.MusicgenMelodyConfig

< >

( 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 = Nonetext_encoder: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneaudio_encoder: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonedecoder: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonenum_chroma: int = 12chroma_length: int = 235initializer_factor: float = 0.02 )

المعاملات

  • text_encoder (Union[dict, PretrainedConfig]) — مثال على كائن التهيئة الذي يحدد إعدادات مُشفِّر النص.
  • audio_encoder (Union[dict, PretrainedConfig]) — مثال على كائن التهيئة الذي يحدد إعدادات مُشفِّر الصوت.
  • decoder (Union[dict, PretrainedConfig]) — مثال على كائن التهيئة الذي يحدد إعدادات المُفكِّك.
  • num_chroma (int، اختياري، القيمة الافتراضية 12) — عدد حاويات الكروما (chroma bins) المستخدمة.
  • chroma_length (int، اختياري، القيمة الافتراضية 235) — أقصى مدة لـ chroma إذا تم استخدام الصوت لتكييف النموذج. يتوافق مع أقصى مدة تم استخدامها أثناء التدريب.
  • initializer_factor (float, اختياري، القيمة الافتراضية 0.02) — عامل يُستخدم لتجميع جميع مصفوفات الأوزان (يجب إبقاؤه عند القيمة 1، ويُستخدم داخليًا لاختبارات التهيئة).

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

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

مثال:

>>> from transformers import (
...     MusicgenMelodyConfig,
...     MusicgenMelodyDecoderConfig,
...     T5Config,
...     EncodecConfig,
...     MusicgenMelodyForConditionalGeneration,
... )

>>> # Initializing text encoder, audio encoder, and decoder model configurations
>>> text_encoder_config = T5Config()
>>> audio_encoder_config = EncodecConfig()
>>> decoder_config = MusicgenMelodyDecoderConfig()

>>> configuration = MusicgenMelodyConfig(
...     text_encoder=text_encoder_config, audio_encoder=audio_encoder_config, decoder=decoder_config
... )

>>> # Initializing a MusicgenMelodyForConditionalGeneration (with random weights) from the facebook/musicgen-melody style configuration
>>> model = MusicgenMelodyForConditionalGeneration(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
>>> config_text_encoder = model.config.text_encoder
>>> config_audio_encoder = model.config.audio_encoder
>>> config_decoder = model.config.decoder

>>> # Saving the model, including its configuration
>>> model.save_pretrained("musicgen_melody-model")

>>> # loading model and config from pretrained folder
>>> musicgen_melody_config = MusicgenMelodyConfig.from_pretrained("musicgen_melody-model")
>>> model = MusicgenMelodyForConditionalGeneration.from_pretrained("musicgen_melody-model", config=musicgen_melody_config)

MusicgenMelodyModel

فئة transformers.MusicgenMelodyModel

< >

( config: MusicgenMelodyDecoderConfig )

المعاملات

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

نموذج Musicgen Melody الأساسي الذي يُخرج حالات مخفية خام دون أي رأس محدد في الأعلى.

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

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

forward

< >

( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneencoder_hidden_states: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.Tensor] = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPast or tuple(torch.Tensor)

المعاملات

  • input_ids (torch.LongTensor بشكل (batch_size * num_codebooks, sequence_length)) — فهارس رموز تسلسل الإدخال في قاموس الكلمات، المقابلة لتسلسل رموز الصوت. يمكن الحصول على الفهارس عن طريق ترميز موجه صوتي باستخدام نموذج ترميز الصوت للتنبؤ برموز الصوت، كما هو الحال مع EncodecModel. راجع EncodecModel.encode() للحصول على التفاصيل. ما هي معرّفات الإدخال؟ ستتم تحويل input_ids تلقائيًا من الشكل (batch_size * num_codebooks, target_sequence_length) إلى (batch_size, num_codebooks, target_sequence_length) في مسار التقدّم. إذا حصلت على رموز الصوت من نموذج ترميز الصوت، مثل EncodecModel، فتأكد من أن عدد الإطارات يساوي 1، وأنك تعيد تشكيل رموز الصوت من (frames, batch_size, num_codebooks, target_sequence_length) إلى (batch_size * num_codebooks, target_sequence_length) قبل تمريرها كـ input_ids.

    يمكن الحصول على الفهارس عن طريق ترميز موجه صوتي باستخدام نموذج مشفّر صوتي للتنبؤ بأكواد صوتية، كما هو الحال مع EncodecModel. راجع EncodecModel.encode() للتفاصيل.

    ما هي معرّفات الإدخال؟

    سيتم تحويل input_ids تلقائيًا من الشكل (batch_size * num_codebooks, target_sequence_length) إلى (batch_size, num_codebooks, target_sequence_length) في مسار الأمامي. إذا كنت تحصل على رموز صوتية من نموذج ترميز صوتي، مثل EncodecModel، فتأكد من أن عدد الإطارات يساوي 1، وأنك تعيد تشكيل الرموز الصوتية من (frames, batch_size, num_codebooks, target_sequence_length) إلى (batch_size * num_codebooks, target_sequence_length) قبل تمريرها كـ input_ids.

  • attention_mask (torch.Tensor بشكل (batch_size, sequence_length), اختياري) — قناع لتجنب تنفيذ الانتباه على فهارس رموز الحشو. القيم المختارة للقناع هي [0, 1]:
    • 1 للرموز التي لم تُقنَّع،
    • 0 للرموز التي تم إخفاؤها.

    ما هي أقنعة الانتباه؟

  • encoder_hidden_states (torch.Tensor من الشكل (batch_size, encoder_sequence_length, hidden_size)، اختياري) — تسلسل من حالات الخفاء (hidden-states) يمثل دمج مخرج مُشفِّر النص مع مخرج مُشفِّر الصوت المُعالج. يُستخدم كإشارة شرطية، وبالتالي سيتم دمجه مع decoder_input_ids المُسقَطة.
  • encoder_attention_mask (torch.LongTensor بشكل (batch_size, encoder_sequence_length), اختياري) — قناع لتجنب تنفيذ الانتباه على الحالات المخفية الشرطية. قيم القناع المختارة في [0, 1]:
    • 1 للرموز التي لم تُقنَّع،
    • 0 للرموز التي تم إخفاؤها.

    ما هي أقنعة الانتباه؟

  • past_key_values (~cache_utils.Cache, اختياري) — حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي وكتل الانتباه المتقاطع) يمكن استخدامها لتسريع فك الترميز التسلسلي. يتكون هذا عادةً من past_key_values الذي يعيده النموذج في مرحلة سابقة من فك الترميز، عندما use_cache=True أو config.use_cache=True.

    يُسمح فقط بمرجع Cache كمدخل، راجع دليل ذاكرة kv لدينا. إذا لم يتم تمرير past_key_values، فسيتم تهيئة DynamicCache افتراضياً.

    سيُخرج النموذج نفس صيغة الكاش التي تُمرَّر كمدخل.

    عند استخدام past_key_values، يُتوقَّع من المستخدم إدخال input_ids غير المعالجة فقط (تلك التي لم تُقدَّم حالات مفاتيحها وقيمها السابقة إلى هذا النموذج) بأبعاد (batch_size, unprocessed_length) بدلاً من جميع input_ids بأبعاد (batch_size, sequence_length).

  • inputs_embeds (torch.Tensor من الشكل (batch_size, sequence_length, hidden_size)، اختياري) — اختياريًا، بدلاً من تمرير input_ids، يمكنك اختيار تمرير تمثيل مضمّن مباشرة. وهذا مفيد إذا كنت ترغب في الحصول على مزيد من التحكم في كيفية تحويل فهارس input_ids إلى المتجهات المرتبطة بها، مقارنةً بمصفوفة البحث المضمّنة الداخلية للنموذج.
  • use_cache (bool، اختياري) — إذا تم تعيينه إلى True، تُعاد حالات المفاتيح والقيم past_key_values ويمكن استخدامها لتسريع فك الترميز (انظر past_key_values).

يعيد

BaseModelOutputWithPast أو tuple(torch.Tensor)

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

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

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

  • last_hidden_state (torch.Tensor من الشكل (batch_size, sequence_length, hidden_size)) — تسلسل حالات مخفية عند مخرج الطبقة الأخيرة من النموذج.

    إذا تم استخدام past_key_values، فإن الحالة المخفية الأخيرة فقط من التسلسلات ذات الشكل (batch_size, 1, hidden_size) هي التي تُخرج.

  • past_key_values (Cache، اختياري، يُعاد عند تمرير use_cache=True أو عند تعيين config.use_cache=True) — إنه كائن من نوع Cache. لمزيد من التفاصيل، راجع دليل ذاكرة kv.

    تحتوي على حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي، وفي كتل الانتباه المتقاطع اختياريًا إذا كان config.is_encoder_decoder=True) يمكن استخدامها (انظر مدخل past_key_values) لتسريع فك الترميز التسلسلي.

  • hidden_states (tuple(torch.Tensor)، اختياري، يُعاد عند تمرير output_hidden_states=True أو عند تعيين config.output_hidden_states=True) — مجموعة من torch.Tensor (واحدة لإخراج الطبقات المضمنة، إذا كان النموذج يحتوي على طبقة تضمين، + واحدة لإخراج كل طبقة) من الشكل (batch_size, sequence_length, hidden_size).

    حالات النموذج المخفية عند مخرج كل طبقة بالإضافة إلى مخرجات التضمين الأولي الاختيارية.

  • attentions (tuple(torch.Tensor)، اختياري، يُعاد عند تمرير output_attentions=True أو عند تعيين config.output_attentions=True) — مجموعة من torch.Tensor (واحدة لكل طبقة) بأبعاد (batch_size, num_heads, sequence_length, sequence_length).

    أوزان الانتباه بعد تطبيق دالة softmax على الانتباه، وتُستخدم لحساب المتوسط الموزون في رؤوس الانتباه الذاتي.

MusicgenMelodyForCausalLM

فئة transformers.MusicgenMelodyForCausalLM

< >

( config: MusicgenMelodyDecoderConfig )

المعاملات

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

نموذج فك ترميز Musicgen Melody مع رأس لنمذجة اللغة في الأعلى.

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

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

forward

< >

( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneencoder_hidden_states: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.Tensor] = Noneuse_cache: bool | None = Nonelabels: typing.Optional[torch.LongTensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → MusicgenMelodyOutputWithPast or tuple(torch.Tensor)

المعاملات

  • input_ids (torch.LongTensor بشكل (batch_size * num_codebooks, sequence_length)) — فهارس رموز تسلسل الإدخال في قاموس الكلمات، المقابلة لتسلسل رموز الصوت. يمكن الحصول على الفهارس عن طريق ترميز موجه صوتي باستخدام نموذج ترميز الصوت للتنبؤ برموز الصوت، كما هو الحال مع EncodecModel. راجع EncodecModel.encode() للحصول على التفاصيل. ما هي معرّفات الإدخال؟ ستتم تحويل input_ids تلقائيًا من الشكل (batch_size * num_codebooks, target_sequence_length) إلى (batch_size, num_codebooks, target_sequence_length) في مسار التقدّم. إذا حصلت على رموز الصوت من نموذج ترميز الصوت، مثل EncodecModel، فتأكد من أن عدد الإطارات يساوي 1، وأنك تعيد تشكيل رموز الصوت من (frames, batch_size, num_codebooks, target_sequence_length) إلى (batch_size * num_codebooks, target_sequence_length) قبل تمريرها كـ input_ids.

    يمكن الحصول على الفهارس عن طريق ترميز موجه صوتي باستخدام نموذج مشفّر صوتي للتنبؤ بأكواد صوتية، كما هو الحال مع EncodecModel. راجع EncodecModel.encode() للتفاصيل.

    ما هي معرّفات الإدخال؟

    سيتم تحويل input_ids تلقائيًا من الشكل (batch_size * num_codebooks, target_sequence_length) إلى (batch_size, num_codebooks, target_sequence_length) في مسار الأمامي. إذا كنت تحصل على رموز صوتية من نموذج ترميز صوتي، مثل EncodecModel، فتأكد من أن عدد الإطارات يساوي 1، وأنك تعيد تشكيل الرموز الصوتية من (frames, batch_size, num_codebooks, target_sequence_length) إلى (batch_size * num_codebooks, target_sequence_length) قبل تمريرها كـ input_ids.

  • attention_mask (torch.Tensor بشكل (batch_size, sequence_length), اختياري) — قناع لتجنب تنفيذ الانتباه على فهارس رموز الحشو. القيم المختارة للقناع هي [0, 1]:
    • 1 للرموز التي لم تُقنَّع،
    • 0 للرموز التي تم إخفاؤها.

    ما هي أقنعة الانتباه؟

  • encoder_hidden_states (torch.Tensor من الشكل (batch_size, encoder_sequence_length, hidden_size)، اختياري) — تسلسل من حالات الخفاء (hidden-states) يمثل دمج مخرج مُشفِّر النص مع مخرج مُشفِّر الصوت المُعالج. يُستخدم كإشارة شرطية، وبالتالي سيتم دمجه مع decoder_input_ids المُسقَطة.
  • encoder_attention_mask (torch.LongTensor بشكل (batch_size, encoder_sequence_length), اختياري) — قناع لتجنب تنفيذ الانتباه على الحالات المخفية الشرطية. قيم القناع المختارة في [0, 1]:
    • 1 للرموز التي لم تُقنَّع،
    • 0 للرموز التي تم إخفاؤها.

    ما هي أقنعة الانتباه؟

  • past_key_values (~cache_utils.Cache, اختياري) — حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي وكتل الانتباه المتقاطع) يمكن استخدامها لتسريع فك الترميز التسلسلي. يتكون هذا عادةً من past_key_values الذي يعيده النموذج في مرحلة سابقة من فك الترميز، عندما use_cache=True أو config.use_cache=True.

    يُسمح فقط بمرجع Cache كمدخل، راجع دليل ذاكرة kv لدينا. إذا لم يتم تمرير past_key_values، فسيتم تهيئة DynamicCache افتراضياً.

    سيُخرج النموذج نفس صيغة الكاش التي تُمرَّر كمدخل.

    عند استخدام past_key_values، يُتوقَّع من المستخدم إدخال input_ids غير المعالجة فقط (تلك التي لم تُقدَّم حالات مفاتيحها وقيمها السابقة إلى هذا النموذج) بأبعاد (batch_size, unprocessed_length) بدلاً من جميع input_ids بأبعاد (batch_size, sequence_length).

  • inputs_embeds (torch.Tensor من الشكل (batch_size, sequence_length, hidden_size)، اختياري) — اختياريًا، بدلاً من تمرير input_ids، يمكنك اختيار تمرير تمثيل مضمّن مباشرة. وهذا مفيد إذا كنت ترغب في الحصول على مزيد من التحكم في كيفية تحويل فهارس input_ids إلى المتجهات المرتبطة بها، مقارنةً بمصفوفة البحث المضمّنة الداخلية للنموذج.
  • use_cache (bool، اختياري) — إذا تم تعيينه إلى True، تُعاد حالات المفاتيح والقيم past_key_values ويمكن استخدامها لتسريع فك الترميز (انظر past_key_values).
  • labels (torch.LongTensor من الشكل (batch_size, sequence_length, num_codebooks)، اختياري) — التسميات لنمذجة اللغة. لاحظ أن التسميات تُزاح داخل النموذج، أي يمكنك تعيين labels = input_ids يتم اختيار الفهارس من [-100, 0, ..., config.vocab_size] جميع التسميات المعينة إلى -100 تُتجاهل (تُقنَّع)، ولا يُحسب الخسارة إلا للتسميات الموجودة في [0, ..., config.vocab_size]

يعيد

MusicgenMelodyOutputWithPast أو tuple(torch.Tensor)

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

تتجاوز طريقة MusicgenMelodyForCausalLM الخاصة بالتقديم (forward) الطريقة الخاصة __call__.

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

  • loss (torch.Tensor of shape (1,), اختياري, يُعاد عند توفير labels) — خسارة نمذجة اللغة (لتوقع الرمز التالي).

  • logits (torch.Tensor من الشكل (batch_size, sequence_length, config.vocab_size)) — درجات التنبؤ لرأس نمذجة اللغة (درجات لكل رمز في المفردات قبل SoftMax).

  • past_key_values (Cache، اختياري، يُعاد عند تمرير use_cache=True أو عند تعيين config.use_cache=True) — إنه كائن من نوع Cache. لمزيد من التفاصيل، راجع دليل ذاكرة kv.

    تحتوي على حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي) يمكن استخدامها (انظر مدخل past_key_values) لتسريع فك الترميز التسلسلي.

  • hidden_states (tuple[torch.Tensor]، اختياري، يُعاد عند تمرير output_hidden_states=True أو عند تعيين config.output_hidden_states=True) — مجموعة من torch.Tensor (واحدة لإخراج الطبقات المضمنة، إذا كان النموذج يحتوي على طبقة تضمين، + واحدة لإخراج كل طبقة) من الشكل (batch_size, sequence_length, hidden_size).

    حالات النموذج المخفية عند مخرج كل طبقة بالإضافة إلى مخرجات التضمين الأولي الاختيارية.

  • attentions (tuple[torch.Tensor]، اختياري، يُعاد عند تمرير output_attentions=True أو عند تعيين config.output_attentions=True) — مجموعة من torch.Tensor (واحدة لكل طبقة) بأبعاد (batch_size, num_heads, sequence_length, sequence_length).

    أوزان الانتباه بعد تطبيق دالة softmax على الانتباه، وتُستخدم لحساب المتوسط الموزون في رؤوس الانتباه الذاتي.

  • encoder_hidden_states (torch.Tensor من الشكل (batch_size, encoder_sequence_length, hidden_size)، اختياري) — تسلسل من حالات المخفية الشرطية يمثل دمج مخرج مشفّر النص المُسقط مع مخرج مشفّر الصوت المُسقط. يُستخدم كإشارة شرطية.

مثال:

MusicgenMelodyForConditionalGeneration

فئة transformers.MusicgenMelodyForConditionalGeneration

< >

( config: MusicgenMelodyConfig = Nonetext_encoder: transformers.modeling_utils.PreTrainedModel | None = Noneaudio_encoder: transformers.modeling_utils.PreTrainedModel | None = Nonedecoder: transformers.models.musicgen_melody.modeling_musicgen_melody.MusicgenMelodyForCausalLM | None = None )

المعاملات

  • config (MusicgenMelodyConfig، اختياري) — فئة إعدادات النموذج التي تحتوي على جميع معاملات النموذج. لا يؤدي التهيئة باستخدام ملف الإعداد إلى تحميل الأوزان المرتبطة بالنموذج، بل الإعدادات فقط. راجع طريقة from_pretrained() لتحميل أوزان النموذج.
  • text_encoder (PreTrainedModel، اختياري) — نموذج ترميز النص الذي يرمز النص إلى حالات خفية للتكييف.
  • audio_encoder (PreTrainedModel، اختياري) — نموذج مُشفِّر الصوت الذي يُشفِّر الصوت إلى حالات خفية للتكييف.
  • decoder (MusicgenMelodyForCausalLM, اختياري) — نموذج المُفكِّك الذي يولّد رموز الصوت بناءً على إشارات التكييف.

نموذج Musicgen Melody لتوليد الرموز المشروط على أنماط أخرى (مثل توليد النص من صورة ونص).

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

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

forward

< >

( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.BoolTensor] = Noneinput_features: typing.Optional[torch.Tensor] = Nonedecoder_input_ids: typing.Optional[torch.LongTensor] = Nonedecoder_attention_mask: typing.Optional[torch.BoolTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneencoder_hidden_states: typing.Optional[torch.Tensor] = Noneinputs_embeds: typing.Optional[torch.Tensor] = Nonedecoder_inputs_embeds: typing.Optional[torch.Tensor] = Nonelabels: typing.Optional[torch.LongTensor] = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → MusicgenMelodyOutputWithPast or tuple(torch.Tensor)

المعاملات

  • input_ids (torch.LongTensor بشكل (batch_size, sequence_length), اختياري) — مؤشرات رموز تسلسل الإدخال في قاموس الكلمات. سيتم تجاهل الحشو افتراضيًا.

    يمكن الحصول على الفهارس باستخدام AutoTokenizer. راجع PreTrainedTokenizer.encode() و PreTrainedTokenizer.call() للتفاصيل.

    ما هي معرّفات الإدخال؟

  • attention_mask (torch.BoolTensor من الشكل (batch_size, sequence_length), اختياري) — قناع لتجنب تنفيذ الانتباه على فهارس رموز الحشو. قيم القناع المختارة من [0, 1]:
    • 1 للرموز التي لم تُقنَّع،
    • 0 للرموز التي تم إخفاؤها.

    ما هي أقنعة الانتباه؟

  • input_features (torch.Tensor من الشكل (batch_size, sequence_length, feature_dim)، اختياري) — المصفوفات المقابلة لميزات الصوت المدخلة. يمكن الحصول على ميزات الصوت باستخدام MusicgenMelodyFeatureExtractor. راجع MusicgenMelodyFeatureExtractor.__call__() للتفاصيل (MusicgenMelodyProcessor يستخدم MusicgenMelodyFeatureExtractor لمعالجة الملفات الصوتية).
  • decoder_input_ids (torch.LongTensor بشكل (batch_size * num_codebooks, target_sequence_length), اختياري) — مفاتيح رموز تسلسل مدخلات المُفكِّك في قاموس الرموز، المقابلة لتسلسل رموز الصوت. يمكن الحصول على المفاتيح من خلال ترميز موجه صوتي باستخدام نموذج مُرمِّز صوتي للتنبؤ برموز الصوت، كما هو الحال مع EncodecModel. راجع EncodecModel.encode() للحصول على التفاصيل. ما هي معرّفات مدخلات المُفكِّك؟ ستتمّ تحويل decoder_input_ids تلقائيًا من الشكل (batch_size * num_codebooks, target_sequence_length) إلى (batch_size, num_codebooks, target_sequence_length) في مسار التقدّم. إذا حصلت على رموز صوت من نموذج ترميز صوتي، مثل EncodecModel، فتأكد من أن عدد الإطارات يساوي 1، وأنك تعيد تشكيل رموز الصوت من (frames, batch_size, num_codebooks, target_sequence_length) إلى (batch_size * num_codebooks, target_sequence_length) قبل تمريرها كـ decoder_input_ids.

    يمكن الحصول على الفهارس عن طريق ترميز موجه صوتي باستخدام نموذج مشفّر صوتي للتنبؤ بأكواد صوتية، كما هو الحال مع EncodecModel. راجع EncodecModel.encode() للتفاصيل.

    ما هي معرّفات مدخلات المُفكِّك؟

    سيتم تحويل decoder_input_ids تلقائيًا من الشكل (batch_size * num_codebooks, target_sequence_length) إلى (batch_size, num_codebooks, target_sequence_length) في مسار الأمامي. إذا كنت تحصل على رموز صوتية من نموذج ترميز صوتي، مثل EncodecModel، فتأكد من أن عدد الإطارات يساوي 1، وأنك تعيد تشكيل الرموز الصوتية من (frames, batch_size, num_codebooks, target_sequence_length) إلى (batch_size * num_codebooks, target_sequence_length) قبل تمريرها كـ decoder_input_ids.

  • decoder_attention_mask (torch.LongTensor من الشكل (batch_size, target_sequence_length)، اختياري) — السلوك الافتراضي: توليد متجه يتجاهل رموز الحشو في decoder_input_ids. كما سيتم استخدام قناع سببي (Causal mask) افتراضيًا.
  • past_key_values (~cache_utils.Cache, اختياري) — حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي وكتل الانتباه المتقاطع) يمكن استخدامها لتسريع فك الترميز التسلسلي. يتكون هذا عادةً من past_key_values الذي يعيده النموذج في مرحلة سابقة من فك الترميز، عندما use_cache=True أو config.use_cache=True.

    يُسمح فقط بمرجع Cache كمدخل، راجع دليل ذاكرة kv لدينا. إذا لم يتم تمرير past_key_values، فسيتم تهيئة DynamicCache افتراضياً.

    سيُخرج النموذج نفس صيغة الكاش التي تُمرَّر كمدخل.

    عند استخدام past_key_values، يُتوقَّع من المستخدم إدخال input_ids غير المعالجة فقط (تلك التي لم تُقدَّم حالات مفاتيحها وقيمها السابقة إلى هذا النموذج) بأبعاد (batch_size, unprocessed_length) بدلاً من جميع input_ids بأبعاد (batch_size, sequence_length).

  • encoder_hidden_states (torch.Tensor من الشكل (batch_size, encoder_sequence_length, hidden_size)، اختياري) — تسلسل من حالات المخفية الشرطية يمثل دمج مخرج مشفّر النص المُسقط مع مخرج مشفّر الصوت المُسقط. يُستخدم كإشارة شرطية، وبالتالي سيتم دمجه مع decoder_input_ids المُسقطة.
  • inputs_embeds (torch.Tensor من الشكل (batch_size, sequence_length, hidden_size)، اختياري) — اختياريًا، بدلاً من تمرير input_ids، يمكنك اختيار تمرير تمثيل مضمّن مباشرة. وهذا مفيد إذا كنت ترغب في الحصول على مزيد من التحكم في كيفية تحويل فهارس input_ids إلى المتجهات المرتبطة بها، مقارنةً بمصفوفة البحث المضمّنة الداخلية للنموذج.
  • decoder_inputs_embeds (torch.Tensor من الشكل (batch_size, target_sequence_length, hidden_size), اختياري) — اختياريًا، بدلاً من تمرير decoder_input_ids يمكنك اختيار تمرير تمثيل مضمّن مباشرة. إذا past_key_values مستخدم، فاختياريًا يكفي إدخال آخر decoder_inputs_embeds فقط (انظر past_key_values). هذا مفيد إذا كنت تريد مزيدًا من التحكم في كيفية تحويل decoder_input_ids فهارس إلى المتجهات المرتبطة بها مقارنةً بمصفوفة البحث التضمينية الداخلية للنموذج.

    إذا لم يتم تعيين كلٍّ من decoder_input_ids وdecoder_inputs_embeds، فإن decoder_inputs_embeds يأخذ قيمة inputs_embeds.

  • labels (torch.LongTensor من الشكل (batch_size, sequence_length, num_codebooks)، اختياري) — التسميات لنمذجة اللغة. لاحظ أن التسميات تُزاح داخل النموذج، أي يمكنك تعيين labels = input_ids يتم اختيار الفهارس من [-100, 0, ..., config.vocab_size] جميع التسميات المعينة إلى -100 تُتجاهل (تُقنَّع)، ولا يُحسب الخسارة إلا للتسميات الموجودة في [0, ..., config.vocab_size]
  • use_cache (bool، اختياري) — إذا تم تعيينه إلى True، تُعاد حالات المفاتيح والقيم past_key_values ويمكن استخدامها لتسريع فك الترميز (انظر past_key_values).

يعيد

MusicgenMelodyOutputWithPast أو tuple(torch.Tensor)

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

تتجاوز طريقة MusicgenMelodyForConditionalGeneration الخاصة بالتقديم (forward) الطريقة الخاصة __call__.

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

  • loss (torch.Tensor of shape (1,), اختياري, يُعاد عند توفير labels) — خسارة نمذجة اللغة (لتوقع الرمز التالي).

  • logits (torch.Tensor من الشكل (batch_size, sequence_length, config.vocab_size)) — درجات التنبؤ لرأس نمذجة اللغة (درجات لكل رمز في المفردات قبل SoftMax).

  • past_key_values (Cache، اختياري، يُعاد عند تمرير use_cache=True أو عند تعيين config.use_cache=True) — إنه كائن من نوع Cache. لمزيد من التفاصيل، راجع دليل ذاكرة kv.

    تحتوي على حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي) يمكن استخدامها (انظر مدخل past_key_values) لتسريع فك الترميز التسلسلي.

  • hidden_states (tuple[torch.Tensor]، اختياري، يُعاد عند تمرير output_hidden_states=True أو عند تعيين config.output_hidden_states=True) — مجموعة من torch.Tensor (واحدة لإخراج الطبقات المضمنة، إذا كان النموذج يحتوي على طبقة تضمين، + واحدة لإخراج كل طبقة) من الشكل (batch_size, sequence_length, hidden_size).

    حالات النموذج المخفية عند مخرج كل طبقة بالإضافة إلى مخرجات التضمين الأولي الاختيارية.

  • attentions (tuple[torch.Tensor]، اختياري، يُعاد عند تمرير output_attentions=True أو عند تعيين config.output_attentions=True) — مجموعة من torch.Tensor (واحدة لكل طبقة) بأبعاد (batch_size, num_heads, sequence_length, sequence_length).

    أوزان الانتباه بعد تطبيق دالة softmax على الانتباه، وتُستخدم لحساب المتوسط الموزون في رؤوس الانتباه الذاتي.

  • encoder_hidden_states (torch.Tensor من الشكل (batch_size, encoder_sequence_length, hidden_size)، اختياري) — تسلسل من حالات المخفية الشرطية يمثل دمج مخرج مشفّر النص المُسقط مع مخرج مشفّر الصوت المُسقط. يُستخدم كإشارة شرطية.

أمثلة:

>>> from transformers import AutoProcessor, MusicgenMelodyForConditionalGeneration
>>> import torch

>>> processor = AutoProcessor.from_pretrained("facebook/musicgen-melody")
>>> model = MusicgenMelodyForConditionalGeneration.from_pretrained("facebook/musicgen-melody")

>>> inputs = processor(
...     text=["80s pop track with bassy drums and synth", "90s rock song with loud guitars and heavy drums"],
...     padding=True,
...     return_tensors="pt",
... )

>>> pad_token_id = model.generation_config.pad_token_id
>>> decoder_input_ids = (
...     torch.ones((inputs.input_ids.shape[0] * model.decoder.num_codebooks, 1), dtype=torch.long)
...     * pad_token_id
... )

>>> logits = model(**inputs, decoder_input_ids=decoder_input_ids).logits
>>> logits.shape  # (bsz * num_codebooks, encoder_len + tgt_len, vocab_size)
torch.Size([8, 249, 2048])
Update on GitHub

←MusicGen Nemotron 3 Diarization→