# MusicGen Melody

## نظرة عامة

قُدِّم نموذج MusicGen Melody في [Simple and Controllable Music Generation](https://huggingface.co/papers/2306.05284) من قِبل 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](https://huggingface.co/ylacombe). يمكن العثور على الكود الأصلي [هنا](https://github.com/facebookresearch/audiocraft). يمكن العثور على نقاط التفتيش المُسبقة التدريب على [Hugging Face Hub](https://huggingface.co/models?sort=downloads&search=facebook%2Fmusicgen).

## الفرق مع [MusicGen](./musicgen)

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

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

## الإنشاء

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

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

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

يمكن للنموذج توليد عينة صوتية مشروطة بنص وموجّه صوتي من خلال استخدام [MusicgenMelodyProcessor](/docs/transformers/main/ar/model_doc/musicgen_melody#transformers.MusicgenMelodyProcessor) لمعالجة المدخلات مسبقًا.

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

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

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

```python
from datasets import load_dataset

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

يجب أن يكون المقتطف الصوتي خالياً في المثالي من الإشارات منخفضة التردد التي تنتجها عادةً آلات مثل الطبول والباس. يمكن استخدام نموذج [Demucs](https://github.com/adefossez/demucs/tree/main) لفصل الأصوات البشرية والإشارات الأخرى عن مكونات الطبول والباس.

إذا كنت ترغب في استخدام Demucs، فأنت بحاجة أولاً إلى اتباع خطوات التثبيت [هنا](https://github.com/adefossez/demucs/tree/main?tab=readme-ov-file#for-musicians) قبل استخدام المقطع التالي:

```python
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])
```

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

```python
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، على الرغم من أن جودة التوليد ستُتدهور على الأرجح:

```python
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:

```python
from IPython.display import Audio

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

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

```python
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](/docs/transformers/main/ar/model_doc/musicgen_melody#transformers.MusicgenMelodyProcessor) نفسه لمعالجة موجه نصي فقط مسبقًا.

```python
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` (الافتراضي).

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

```python

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()](/docs/transformers/main/ar/model_doc/musicgen_melody#transformers.MusicgenMelodyProcessor.get_unconditional_inputs):

```python
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)
```

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

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

```python
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](/docs/transformers/main/ar/model_doc/musicgen_melody#transformers.MusicgenMelodyForCausalLM)، أو كنموذج مركّب يتضمن مُرمّز النص ومُرمّز الصوت، مما يتوافق مع الفئة [MusicgenMelodyForConditionalGeneration](/docs/transformers/main/ar/model_doc/musicgen_melody#transformers.MusicgenMelodyForConditionalGeneration). إذا كان من الضروري تحميل فك الترميز فقط من نقطة الفحص المُدرَّبة مسبقًا، فيمكن تحميله عن طريق تحديد الإعداد الصحيح أولاً، أو الوصول إليه من خلال خاصية `.decoder` في النموذج المركّب:

```python
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](/docs/transformers/main/ar/model_doc/musicgen_melody#transformers.MusicgenMelodyForCausalLM) بشكل مستقل على مجموعة بيانات من حالات المُشفِّر المخفية وأكواد الصوت. أما عند الاستدلال، فيمكن دمج المُفكِّك المُدرَّب مع مُشفِّر النص ومُشفِّر الصوت المجمّدين لاستعادة النموذج المركّب [MusicgenMelodyForConditionalGeneration](/docs/transformers/main/ar/model_doc/musicgen_melody#transformers.MusicgenMelodyForConditionalGeneration).

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

- بعد تنزيل نقاط التفتيش الأصلية من [هنا](https://github.com/facebookresearch/audiocraft/blob/main/docs/MUSICGEN.md#importing--exporting-models)، يمكنك تحويلها باستخدام **سكربت التحويل** المتاح في `src/transformers/models/musicgen_melody/convert_musicgen_melody_transformers.py` عبر الأمر التالي:

```bash
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.MusicgenMelodyDecoderConfig[[transformers.MusicgenMelodyDecoderConfig]]

```python
transformers.MusicgenMelodyDecoderConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, vocab_size: int = 2048, max_position_embeddings: int = 2048, num_hidden_layers: int = 24, ffn_dim: int = 4096, num_attention_heads: int = 16, layerdrop: float | int = 0.0, use_cache: bool = True, activation_function: str = 'gelu', hidden_size: int = 1024, dropout: float | int = 0.1, attention_dropout: float | int = 0.0, activation_dropout: float | int = 0.0, initializer_factor: float = 0.02, scale_embedding: bool = False, num_codebooks: int = 4, audio_channels: int = 1, pad_token_id: int | None = 2048, bos_token_id: int | None = 2048, eos_token_id: int | list[int] | None = None, tie_word_embeddings: bool = False, is_decoder: bool = False, add_cross_attention: bool = False)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/musicgen_melody/configuration_musicgen_melody.py#L28)

**المعاملات:**

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](see 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`) : ما إذا كان النموذج يُستخدم كمُفكِّك أم لا. إذا كان `False`، يُستخدم النموذج كمُشفِّر.

add_cross_attention (`bool`, *اختياري*, الافتراضي هو `False`) : ما إذا كان يجب إضافة طبقات الانتباه المتقاطع إلى النموذج.

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

ترث كائنات الإعداد من [PreTrainedConfig](/docs/transformers/main/ar/main_classes/configuration#transformers.PreTrainedConfig) ويمكن استخدامها للتحكم في مخرجات النموذج. اقرأ التوثيق الخاص بـ [PreTrainedConfig](/docs/transformers/main/ar/main_classes/configuration#transformers.PreTrainedConfig) لمزيد من المعلومات.

## MusicgenMelodyProcessor[[transformers.MusicgenMelodyProcessor]]

#### transformers.MusicgenMelodyProcessor[[transformers.MusicgenMelodyProcessor]]

```python
transformers.MusicgenMelodyProcessor(feature_extractor, tokenizer)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/musicgen_melody/processing_musicgen_melody.py#L29)

**المعاملات:**

feature_extractor (`MusicgenMelodyFeatureExtractor`) : مُستخرج الميزات هو مدخل مطلوب.

tokenizer (`T5Tokenizer`) : مُجزِّئ النص (tokenizer) هو مدخل مطلوب.

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

يوفر [MusicgenMelodyProcessor](/docs/transformers/main/ar/model_doc/musicgen_melody#transformers.MusicgenMelodyProcessor) جميع وظائف [MusicgenMelodyFeatureExtractor](/docs/transformers/main/ar/model_doc/musicgen_melody#transformers.MusicgenMelodyFeatureExtractor) و[T5Tokenizer](/docs/transformers/main/ar/model_doc/t5#transformers.T5Tokenizer). راجع [~MusicgenMelodyFeatureExtractor](/docs/transformers/main/ar/model_doc/musicgen_melody#transformers.MusicgenMelodyFeatureExtractor) و[~T5Tokenizer](/docs/transformers/main/ar/model_doc/t5#transformers.T5Tokenizer) لمزيد من المعلومات.

#### __call__[[transformers.MusicgenMelodyProcessor.__call__]]

```python
__call__(*args, **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/musicgen_melody/processing_musicgen_melody.py#L37)

**المعاملات:**

return_tensors (`str` أو [TensorType](/docs/transformers/main/ar/internal/file_utils#transformers.TensorType)، *اختياري*) : إذا تم تعيينه، فسيُرجع تينسورات من إطار عمل محدد. القيم المقبولة هي:  - `'pt'`: يُرجع كائنات `torch.Tensor` من PyTorch. - `'np'`: يُرجع كائنات `np.ndarray` من NumPy.

#### get_unconditional_inputs[[transformers.MusicgenMelodyProcessor.get_unconditional_inputs]]

```python
get_unconditional_inputs(num_samples = 1, return_tensors = 'pt')
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/musicgen_melody/processing_musicgen_melody.py#L90)

**المعاملات:**

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

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

مثال:
```python
>>> 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]]

#### transformers.MusicgenMelodyFeatureExtractor[[transformers.MusicgenMelodyFeatureExtractor]]

```python
transformers.MusicgenMelodyFeatureExtractor(feature_size = 12, sampling_rate = 32000, hop_length = 4096, chunk_length = 30, n_fft = 16384, num_chroma = 12, padding_value = 0.0, return_attention_mask = False, stem_indices = [3, 2], **kwargs)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/musicgen_melody/feature_extraction_musicgen_melody.py#L40)

**المعاملات:**

feature_size (`int`، *اختياري*، القيمة الافتراضية 12) : بُعد الميزة للميزات المستخرجة.

sampling_rate (`int`, *اختياري*, القيمة الافتراضية 32000) : معدل أخذ العينات الذي يجب أن تُرقَم به ملفات الصوت، ويُعبَّر عنه بالهرتز (Hz).

hop_length (`int`، *اختياري*، القيمة الافتراضية 4096) : طول النوافذ المتداخلة لخوارزمية STFT المستخدمة للحصول على معاملات ترددات Mel.

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`) : ما إذا كان يجب إرجاع قناع الانتباه. يمكن تجاوز هذه القيمة عند استدعاء مستخرج الميزات.  [ما هي أقنعة الانتباه؟](../glossary#attention-mask)    بالنسبة لنماذج Whisper، يجب دائمًا تمرير `attention_mask` عند الاستدلال على دفعات، لتجنب الأخطاء الدقيقة.

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

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

يرث مستخرج الميزات هذا من [SequenceFeatureExtractor](/docs/transformers/main/ar/main_classes/feature_extractor#transformers.SequenceFeatureExtractor) الذي يحتوي على معظم الطرق الرئيسية. ينبغي للمستخدمين الرجوع إلى هذه الفئة الأصلية لمزيد من المعلومات حول تلك الطرق.

تستخرج هذه الفئة ميزات الكروما من الصوت المعالج بواسطة [Demucs](https://github.com/adefossez/demucs/tree/main) أو مباشرة من موجة الصوت الخام.

## MusicgenMelodyConfig[[transformers.MusicgenMelodyConfig]]

#### transformers.MusicgenMelodyConfig[[transformers.MusicgenMelodyConfig]]

```python
transformers.MusicgenMelodyConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, text_encoder: dict | transformers.configuration_utils.PreTrainedConfig | None = None, audio_encoder: dict | transformers.configuration_utils.PreTrainedConfig | None = None, decoder: dict | transformers.configuration_utils.PreTrainedConfig | None = None, num_chroma: int = 12, chroma_length: int = 235, initializer_factor: float = 0.02)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/musicgen_melody/configuration_musicgen_melody.py#L86)

**المعاملات:**

text_encoder (`Union[dict, `PretrainedConfig`]`) : نسخة من كائن الإعداد الذي يحدد إعدادات مُشفِّر النص.

audio_encoder (`Union[dict, `PretrainedConfig`]`) : نسخة من كائن الإعداد الذي يعرّف إعدادات مُشفِّر الصوت.

decoder (`Union[dict, `PretrainedConfig`]`) : نسخة من كائن التهيئة الذي يعرّف إعدادات المُفكِّك (decoder).

num_chroma (`int`، *اختياري*، القيمة الافتراضية 12) : عدد دلاء الكروما (chroma bins) المستخدمة.

chroma_length (`int`، *اختياري*، القيمة الافتراضية 235) : أقصى مدة للكروما إذا تم استخدام الصوت لتكييف النموذج. يتوافق مع أقصى مدة تم استخدامها أثناء التدريب.

initializer_factor (`float`، *اختياري*، القيمة الافتراضية `0.02`) : معامل لتجميع جميع مصفوفات الأوزان (يجب إبقاؤه عند 1، ويُستخدم داخليًا لاختبارات التهيئة).

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

ترث كائنات الإعداد من [PreTrainedConfig](/docs/transformers/main/ar/main_classes/configuration#transformers.PreTrainedConfig) ويمكن استخدامها للتحكم في مخرجات النموذج. اقرأ التوثيق الخاص بـ [PreTrainedConfig](/docs/transformers/main/ar/main_classes/configuration#transformers.PreTrainedConfig) لمزيد من المعلومات.

مثال:

```python
>>> 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]]

#### transformers.MusicgenMelodyModel[[transformers.MusicgenMelodyModel]]

```python
transformers.MusicgenMelodyModel(config: MusicgenMelodyDecoderConfig)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/musicgen_melody/modeling_musicgen_melody.py#L539)

**المعاملات:**

config ([MusicgenMelodyDecoderConfig](/docs/transformers/main/ar/model_doc/musicgen_melody#transformers.MusicgenMelodyDecoderConfig)) : فئة إعدادات النموذج التي تحتوي على جميع معاملات النموذج. عند التهيئة باستخدام ملف إعدادات، لا يتم تحميل الأوزان المرتبطة بالنموذج، بل الإعدادات فقط. راجع طريقة [from_pretrained()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.from_pretrained) لتحميل أوزان النموذج.

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

يرث هذا النموذج من [PreTrainedModel](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel). راجع توثيق الفئة الأصلية لمعرفة الطرق العامة التي تنفذها المكتبة لجميع نماذجها (مثل التنزيل أو الحفظ، وتغيير حجم تضمينات الإدخال، وقص الرؤوس، وما إلى ذلك).

هذا النموذج هو أيضاً فئة فرعية من [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) في PyTorch. استخدمه كوحدة PyTorch عادية، وارجع إلى توثيق PyTorch لكل ما يتعلق بالاستخدام العام والسلوك.

#### forward[[transformers.MusicgenMelodyModel.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, encoder_hidden_states: typing.Optional[torch.Tensor] = None, encoder_attention_mask: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/musicgen_melody/modeling_musicgen_melody.py#L552)

**المعاملات:**

input_ids (`torch.LongTensor` من الشكل `(batch_size * num_codebooks, sequence_length)`) : فهارس رموز تسلسل الإدخال في قاموس الكلمات، المقابلة لتسلسل رموز الصوت. يمكن الحصول على الفهارس عن طريق ترميز موجه صوتي باستخدام نموذج ترميز الصوت للتنبؤ برموز الصوت، كما هو الحال مع [EncodecModel](/docs/transformers/main/ar/model_doc/encodec#transformers.EncodecModel). راجع [EncodecModel.encode()](/docs/transformers/main/ar/model_doc/encodec#transformers.EncodecModel.encode) للتفاصيل. [ما هي معرّفات الإدخال؟](../glossary#input-ids)    سيتم تحويل `input_ids` تلقائيًا من الشكل `(batch_size * num_codebooks, target_sequence_length)` إلى `(batch_size, num_codebooks, target_sequence_length)` في مسار التقدّم. إذا حصلت على رموز الصوت من نموذج ترميز الصوت، مثل [EncodecModel](/docs/transformers/main/ar/model_doc/encodec#transformers.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 للرموز التي **مقنّعة**.  [ما هي أقنعة الانتباه؟](../glossary#attention-mask)

encoder_hidden_states (`torch.Tensor` من الشكل `(batch_size, encoder_sequence_length, hidden_size)`، *اختياري*) : تسلسل من حالات الخفاء يمثل دمج مخرج مُشفِّر النص مع مخرج مُشفِّر الصوت المُعالَج. يُستخدم كإشارة شرطية، وبالتالي سيتم دمجه مع `decoder_input_ids` المُسقَط.

encoder_attention_mask (`torch.LongTensor` من الشكل `(batch_size, encoder_sequence_length)`، *اختياري*) : قناع لتجنب تنفيذ الانتباه على الحالات المخفية الشرطية. قيم القناع المختارة في `[0, 1]`: - 1 للرموز التي **ليست مقنّعة**، - 0 للرموز التي **مقنّعة**. [ما هي أقنعة الانتباه؟](../glossary#attention-mask)

past_key_values (`~cache_utils.Cache`، *اختياري*) : حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي وكتل الانتباه المتقاطع) يمكن استخدامها لتسريع فك الترميز التسلسلي. يتكوّن هذا عادةً من `past_key_values` التي يعيدها النموذج في مرحلة سابقة من فك الترميز، عندما يكون `use_cache=True` أو `config.use_cache=True`. يُسمح فقط بتمرير كائن [Cache](/docs/transformers/main/ar/internal/generation_utils#transformers.Cache) كمدخل، راجع [دليل ذاكرة kv](https://huggingface.co/docs/transformers/en/kv_cache). إذا لم يتم تمرير `past_key_values`، فسيتم تهيئة [DynamicCache](/docs/transformers/main/ar/internal/generation_utils#transformers.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](/docs/transformers/main/ar/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPast) أو `tuple(torch.Tensor)`

[BaseModelOutputWithPast](/docs/transformers/main/ar/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPast) أو مجموعة من `torch.Tensor` (إذا تم تمرير `return_dict=False` أو عندما يكون `config.return_dict=False`) وتتضمن عناصر مختلفة اعتماداً على الإعداد (`None`) والمدخلات.

تتجاوز طريقة [MusicgenMelodyModel](/docs/transformers/main/ar/model_doc/musicgen_melody#transformers.MusicgenMelodyModel) الأمامية الطريقة الخاصة `__call__`.

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

- **last_hidden_state** (`torch.Tensor` من الشكل `(batch_size, sequence_length, hidden_size)`) -- تسلسل من حالات الإخفاء (hidden-states) عند مخرج الطبقة الأخيرة من النموذج.

  إذا تم استخدام `past_key_values`، فإن الحالة المخفية الأخيرة فقط من التسلسلات ذات الشكل `(batch_size, 1, hidden_size)` هي التي تُخرج.
- **past_key_values** (`Cache`، *اختياري*، يُعاد عند تمرير `use_cache=True` أو عند تعيين `config.use_cache=True`) -- هو كائن من نوع [Cache](/docs/transformers/main/ar/internal/generation_utils#transformers.Cache). لمزيد من التفاصيل، راجع [دليل ذاكرة kv](https://huggingface.co/docs/transformers/en/kv_cache).

  تحتوي على حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي، وفي كتل الانتباه المتقاطع اختياريًا إذا كان `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]]

#### transformers.MusicgenMelodyForCausalLM[[transformers.MusicgenMelodyForCausalLM]]

```python
transformers.MusicgenMelodyForCausalLM(config: MusicgenMelodyDecoderConfig)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/musicgen_melody/modeling_musicgen_melody.py#L623)

**المعاملات:**

config ([MusicgenMelodyDecoderConfig](/docs/transformers/main/ar/model_doc/musicgen_melody#transformers.MusicgenMelodyDecoderConfig)) : فئة إعدادات النموذج التي تحتوي على جميع معاملات النموذج. عند التهيئة باستخدام ملف إعدادات، لا يتم تحميل الأوزان المرتبطة بالنموذج، بل الإعدادات فقط. راجع طريقة [from_pretrained()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.from_pretrained) لتحميل أوزان النموذج.

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

يرث هذا النموذج من [PreTrainedModel](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel). راجع توثيق الفئة الأصلية لمعرفة الطرق العامة التي تنفذها المكتبة لجميع نماذجها (مثل التنزيل أو الحفظ، وتغيير حجم تضمينات الإدخال، وقص الرؤوس، وما إلى ذلك).

هذا النموذج هو أيضاً فئة فرعية من [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) في PyTorch. استخدمه كوحدة PyTorch عادية، وارجع إلى توثيق PyTorch لكل ما يتعلق بالاستخدام العام والسلوك.

#### forward[[transformers.MusicgenMelodyForCausalLM.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, encoder_hidden_states: typing.Optional[torch.Tensor] = None, encoder_attention_mask: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, use_cache: bool | None = None, labels: typing.Optional[torch.LongTensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/musicgen_melody/modeling_musicgen_melody.py#L651)

**المعاملات:**

input_ids (`torch.LongTensor` من الشكل `(batch_size * num_codebooks, sequence_length)`) : فهارس رموز تسلسل الإدخال في قاموس الكلمات، المقابلة لتسلسل رموز الصوت. يمكن الحصول على الفهارس عن طريق ترميز موجه صوتي باستخدام نموذج ترميز الصوت للتنبؤ برموز الصوت، كما هو الحال مع [EncodecModel](/docs/transformers/main/ar/model_doc/encodec#transformers.EncodecModel). راجع [EncodecModel.encode()](/docs/transformers/main/ar/model_doc/encodec#transformers.EncodecModel.encode) للتفاصيل. [ما هي معرّفات الإدخال؟](../glossary#input-ids)    سيتم تحويل `input_ids` تلقائيًا من الشكل `(batch_size * num_codebooks, target_sequence_length)` إلى `(batch_size, num_codebooks, target_sequence_length)` في مسار التقدّم. إذا حصلت على رموز الصوت من نموذج ترميز الصوت، مثل [EncodecModel](/docs/transformers/main/ar/model_doc/encodec#transformers.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 للرموز التي **مقنّعة**.  [ما هي أقنعة الانتباه؟](../glossary#attention-mask)

encoder_hidden_states (`torch.Tensor` من الشكل `(batch_size, encoder_sequence_length, hidden_size)`، *اختياري*) : تسلسل من حالات الخفاء يمثل دمج مخرج مُشفِّر النص مع مخرج مُشفِّر الصوت المُعالَج. يُستخدم كإشارة شرطية، وبالتالي سيتم دمجه مع `decoder_input_ids` المُسقَط.

encoder_attention_mask (`torch.LongTensor` من الشكل `(batch_size, encoder_sequence_length)`، *اختياري*) : قناع لتجنب تنفيذ الانتباه على الحالات المخفية الشرطية. قيم القناع المختارة في `[0, 1]`: - 1 للرموز التي **ليست مقنّعة**، - 0 للرموز التي **مقنّعة**. [ما هي أقنعة الانتباه؟](../glossary#attention-mask)

past_key_values (`~cache_utils.Cache`، *اختياري*) : حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي وكتل الانتباه المتقاطع) يمكن استخدامها لتسريع فك الترميز التسلسلي. يتكوّن هذا عادةً من `past_key_values` التي يعيدها النموذج في مرحلة سابقة من فك الترميز، عندما يكون `use_cache=True` أو `config.use_cache=True`. يُسمح فقط بتمرير كائن [Cache](/docs/transformers/main/ar/internal/generation_utils#transformers.Cache) كمدخل، راجع [دليل ذاكرة kv](https://huggingface.co/docs/transformers/en/kv_cache). إذا لم يتم تمرير `past_key_values`، فسيتم تهيئة [DynamicCache](/docs/transformers/main/ar/internal/generation_utils#transformers.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](/docs/transformers/main/ar/model_doc/musicgen_melody#transformers.MusicgenMelodyConfig)) والمدخلات.

تتجاوز طريقة [MusicgenMelodyForCausalLM](/docs/transformers/main/ar/model_doc/musicgen_melody#transformers.MusicgenMelodyForCausalLM) الخاصة بالتقديم (forward) الطريقة الخاصة `__call__`.

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

- **loss** (`torch.Tensor` من الشكل `(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](/docs/transformers/main/ar/internal/generation_utils#transformers.Cache). لمزيد من التفاصيل، راجع [دليل ذاكرة kv](https://huggingface.co/docs/transformers/en/kv_cache).

  تحتوي على حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي) يمكن استخدامها (انظر مدخل `past_key_values`) لتسريع فك الترميز التسلسلي.
- **hidden_states** (`tuple[torch.Tensor]`، *اختياري*، يُعاد عند تمرير `output_hidden_states=True` أو عند تعيين `config.output_hidden_states=True`) -- مجموعة (Tuple) من `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)`، *اختياري*) -- تسلسل من حالات المخفية الشرطية يمثل دمج مخرج مشفّر النص المُسقط مع مخرج مشفّر الصوت المُسقط. يُستخدم كإشارة شرطية.

مثال:

```python
```

## MusicgenMelodyForConditionalGeneration[[transformers.MusicgenMelodyForConditionalGeneration]]

#### transformers.MusicgenMelodyForConditionalGeneration[[transformers.MusicgenMelodyForConditionalGeneration]]

```python
transformers.MusicgenMelodyForConditionalGeneration(config: MusicgenMelodyConfig = None, text_encoder: transformers.modeling_utils.PreTrainedModel | None = None, audio_encoder: transformers.modeling_utils.PreTrainedModel | None = None, decoder: transformers.models.musicgen_melody.modeling_musicgen_melody.MusicgenMelodyForCausalLM | None = None)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/musicgen_melody/modeling_musicgen_melody.py#L1091)

**المعاملات:**

config ([MusicgenMelodyConfig](/docs/transformers/main/ar/model_doc/musicgen_melody#transformers.MusicgenMelodyConfig)، *اختياري*) : فئة إعدادات النموذج التي تحتوي على جميع معاملات النموذج. لا يؤدي التهيئة باستخدام ملف الإعداد إلى تحميل الأوزان المرتبطة بالنموذج، بل الإعدادات فقط. راجع طريقة [from_pretrained()](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel.from_pretrained) لتحميل أوزان النموذج.

text_encoder (`PreTrainedModel`، *اختياري*) : نموذج مُشفِّر النص الذي يُشفِّر النص إلى حالات خفية للتكييف.

audio_encoder (`PreTrainedModel`، *اختياري*) : نموذج مُشفِّر الصوت الذي يُشفِّر الصوت إلى حالات خفية للتكييف.

decoder (`MusicgenMelodyForCausalLM`، *اختياري*) : نموذج المُفكِّك الذي يولّد رموز الصوت بناءً على إشارات التكييف.

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

يرث هذا النموذج من [PreTrainedModel](/docs/transformers/main/ar/main_classes/model#transformers.PreTrainedModel). راجع توثيق الفئة الأصلية لمعرفة الطرق العامة التي تنفذها المكتبة لجميع نماذجها (مثل التنزيل أو الحفظ، وتغيير حجم تضمينات الإدخال، وقص الرؤوس، وما إلى ذلك).

هذا النموذج هو أيضاً فئة فرعية من [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) في PyTorch. استخدمه كوحدة PyTorch عادية، وارجع إلى توثيق PyTorch لكل ما يتعلق بالاستخدام العام والسلوك.

#### forward[[transformers.MusicgenMelodyForConditionalGeneration.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.BoolTensor] = None, input_features: typing.Optional[torch.Tensor] = None, decoder_input_ids: typing.Optional[torch.LongTensor] = None, decoder_attention_mask: typing.Optional[torch.BoolTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, encoder_hidden_states: typing.Optional[torch.Tensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, decoder_inputs_embeds: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.LongTensor] = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[المصدر](https://github.com/huggingface/transformers/blob/main/src/transformers/models/musicgen_melody/modeling_musicgen_melody.py#L1388)

**المعاملات:**

input_ids (`torch.LongTensor` من الشكل `(batch_size, sequence_length)`، *اختياري*) : فهارس رموز تسلسل الإدخال في قاموس الكلمات. سيتم تجاهل الحشو افتراضيًا. يمكن الحصول على الفهارس باستخدام [AutoTokenizer](/docs/transformers/main/ar/model_doc/auto#transformers.AutoTokenizer). راجع [PreTrainedTokenizer.encode()](/docs/transformers/main/ar/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) و [PreTrainedTokenizer.__call__()](/docs/transformers/main/ar/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) للتفاصيل. [ما هي معرّفات الإدخال؟](../glossary#input-ids)

attention_mask (`torch.BoolTensor` من الشكل `(batch_size, sequence_length)`، *اختياري*) : قناع لتجنب تنفيذ الانتباه على فهارس رموز الحشو. قيم القناع المختارة في `[0, 1]`: - 1 للرموز التي **ليست مقنّعة**، - 0 للرموز التي **مقنّعة**. [ما هي أقنعة الانتباه؟](../glossary#attention-mask)

input_features (`torch.Tensor` من الشكل `(batch_size, sequence_length, feature_dim)`، *اختياري*) : المصفوفات المقابلة لميزات الصوت المدخلة. يمكن الحصول على ميزات الصوت باستخدام [MusicgenMelodyFeatureExtractor](/docs/transformers/main/ar/model_doc/musicgen_melody#transformers.MusicgenMelodyFeatureExtractor). راجع `MusicgenMelodyFeatureExtractor.__call__()` للتفاصيل (يستخدم [MusicgenMelodyProcessor](/docs/transformers/main/ar/model_doc/musicgen_melody#transformers.MusicgenMelodyProcessor) [MusicgenMelodyFeatureExtractor](/docs/transformers/main/ar/model_doc/musicgen_melody#transformers.MusicgenMelodyFeatureExtractor) لمعالجة الأصوات).

decoder_input_ids (`torch.LongTensor` من الشكل `(batch_size * num_codebooks, target_sequence_length)`، *اختياري*) : فهارس رموز تسلسل مدخلات المُفكِّك في قاموس الكلمات، المقابلة لتسلسل رموز الصوت. يمكن الحصول على الفهارس عن طريق ترميز موجه صوتي باستخدام نموذج مُرمِّز صوتي للتنبؤ برموز الصوت، كما هو الحال مع [EncodecModel](/docs/transformers/main/ar/model_doc/encodec#transformers.EncodecModel). راجع [EncodecModel.encode()](/docs/transformers/main/ar/model_doc/encodec#transformers.EncodecModel.encode) للتفاصيل. [ما هي معرفات مدخلات المُفكِّك؟](../glossary#decoder-input-ids)    سيتم تحويل `decoder_input_ids` تلقائيًا من الشكل `(batch_size * num_codebooks, target_sequence_length)` إلى `(batch_size, num_codebooks, target_sequence_length)` في مسار الأمامي. إذا حصلت على رموز صوت من نموذج ترميز صوتي، مثل [EncodecModel](/docs/transformers/main/ar/model_doc/encodec#transformers.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`. وسيتم استخدام القناع السببي أيضًا بشكل افتراضي.

past_key_values (`~cache_utils.Cache`، *اختياري*) : حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي وكتل الانتباه المتقاطع) يمكن استخدامها لتسريع فك الترميز التسلسلي. يتكوّن هذا عادةً من `past_key_values` التي يعيدها النموذج في مرحلة سابقة من فك الترميز، عندما يكون `use_cache=True` أو `config.use_cache=True`. يُسمح فقط بتمرير كائن [Cache](/docs/transformers/main/ar/internal/generation_utils#transformers.Cache) كمدخل، راجع [دليل ذاكرة kv](https://huggingface.co/docs/transformers/en/kv_cache). إذا لم يتم تمرير `past_key_values`، فسيتم تهيئة [DynamicCache](/docs/transformers/main/ar/internal/generation_utils#transformers.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](/docs/transformers/main/ar/model_doc/musicgen_melody#transformers.MusicgenMelodyConfig)) والمدخلات.

تتجاوز طريقة [MusicgenMelodyForConditionalGeneration](/docs/transformers/main/ar/model_doc/musicgen_melody#transformers.MusicgenMelodyForConditionalGeneration) الخاصة بالتقديم (forward) الطريقة الخاصة `__call__`.

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

- **loss** (`torch.Tensor` من الشكل `(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](/docs/transformers/main/ar/internal/generation_utils#transformers.Cache). لمزيد من التفاصيل، راجع [دليل ذاكرة kv](https://huggingface.co/docs/transformers/en/kv_cache).

  تحتوي على حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي) يمكن استخدامها (انظر مدخل `past_key_values`) لتسريع فك الترميز التسلسلي.
- **hidden_states** (`tuple[torch.Tensor]`، *اختياري*، يُعاد عند تمرير `output_hidden_states=True` أو عند تعيين `config.output_hidden_states=True`) -- مجموعة (Tuple) من `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)`، *اختياري*) -- تسلسل من حالات المخفية الشرطية يمثل دمج مخرج مشفّر النص المُسقط مع مخرج مشفّر الصوت المُسقط. يُستخدم كإشارة شرطية.

أمثلة:
```python
>>> 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])
```