# MusicGen

## نظرة عامة

قُدِّم نموذج MusicGen في ورقة [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 هو نموذج Transformer ذاتي التراجع من مرحلة واحدة قادر على توليد عينات موسيقية عالية الجودة مشروطة بوصف نصي أو تلميحات صوتية. تُمرَّر الأوصاف النصية عبر نموذج مشفّر نصي مجمّد للحصول على تسلسل من تمثيلات الحالة المخفية. ثم يُدرَّب MusicGen على التنبؤ برموز صوتية منفصلة، أو *رموز صوتية*، مشروطة بهذه الحالات المخفية. ثم تُفكَّك هذه الرموز الصوتية باستخدام نموذج ضغط صوتي، مثل EnCodec، لاستعادة الموجة الصوتية.

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

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

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

تمت مساهمة هذا النموذج من قِبل [sanchit-gandhi](https://huggingface.co/sanchit-gandhi). يمكن العثور على الكود الأصلي [هنا](https://github.com/facebookresearch/audiocraft). يمكن العثور على نقاط التفتيش المُسبقة التدريب على [Hugging Face Hub](https://huggingface.co/models?sort=downloads&search=facebook%2Fmusicgen-).

## نصائح للاستخدام

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

```bash
python src/transformers/models/musicgen/convert_musicgen_transformers.py \
    --checkpoint small --pytorch_dump_folder /output/path
```

## الإنشاء

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

تُقيَّد عملية التوليد بواسطة التضمينات الموضعية الجيبية (sinusoidal positional embeddings) بإدخالات مدتها 30 ثانية. وهذا يعني أن MusicGen لا يمكنه توليد أكثر من 30 ثانية من الصوت (1503 رموز)، والإدخال الصوتي المُمرَّر عبر التوليد المُوجَّه بالصوت (Audio-Prompted Generation) يساهم في هذا الحد الأقصى؛ فبافتراض إدخال صوتي مدته 20 ثانية، لا يمكن لـ MusicGen توليد أكثر من 10 ثوانٍ إضافية من الصوت.

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

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

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

```python
from transformers import MusicgenForConditionalGeneration

model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-small", device_map="auto")
unconditional_inputs = model.get_unconditional_inputs(num_samples=1)

audio_values = model.generate(**unconditional_inputs, do_sample=True, 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` باستخدام مكتبة طرف ثالث، مثل `scipy`:

```python
import scipy

sampling_rate = model.config.audio_encoder.sampling_rate
scipy.io.wavfile.write("musicgen_out.wav", rate=sampling_rate, data=audio_values[0, 0].numpy())
```

### التوليف الشرطي بالنص

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

```python
from transformers import AutoProcessor, MusicgenForConditionalGeneration

processor = AutoProcessor.from_pretrained("facebook/musicgen-small")
model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-small", 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` (الافتراضي).

### التوليد المُوجَّه بالصوت

يمكن استخدام [MusicgenProcessor](/docs/transformers/main/ar/model_doc/musicgen#transformers.MusicgenProcessor) نفسه لمعالجة مبدئية لمقطع صوتي يُستخدم لاستكمال الصوت. في المثال التالي، نقوم بتحميل ملف صوتي باستخدام مكتبة 🤗 Datasets، والتي يمكن تثبيتها عبر pip باستخدام الأمر أدناه:

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

```python
from datasets import load_dataset

from transformers import AutoProcessor, MusicgenForConditionalGeneration

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

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

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

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

في حالة التوليد الدفعي المُوجَّه بالصوت، يمكن معالجة `audio_values` الناتجة بعد التوليد لإزالة الحشو باستخدام فئة [MusicgenProcessor](/docs/transformers/main/ar/model_doc/musicgen#transformers.MusicgenProcessor):

```python
from datasets import load_dataset

from transformers import AutoProcessor, MusicgenForConditionalGeneration

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

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

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

# post-process to remove padding from the batched audio
audio_values = processor.batch_decode(audio_values, padding_mask=inputs.padding_mask)
```

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

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

```python
from transformers import MusicgenForConditionalGeneration

model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-small", 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. مفكّك MusicGen: نموذج لغوي (LM) يولّد رموز الصوت (أو الأكواد) بشكل ذاتي التراجع (auto-regressive) مشروطًا بتمثيلات الحالة المخفية للمشفّر
3. مُشفِّر/مُفكِّك الصوت: يُستخدم لتشفير موجه صوتي لاستخدامه كرموز موجه، واستعادة الموجة الصوتية من الرموز الصوتية التي يتنبأ بها المُفكِّك

وبالتالي، يمكن استخدام نموذج Musicgen إما كنموذج فك ترميز مستقل، مما يتوافق مع الفئة [MusicgenForCausalLM](/docs/transformers/main/ar/model_doc/musicgen#transformers.MusicgenForCausalLM)، أو كنموذج مركّب يتضمن مُرمّز النص ومُرمّز/فكّ ترميز الصوت، مما يتوافق مع الفئة [MusicgenForConditionalGeneration](/docs/transformers/main/ar/model_doc/musicgen#transformers.MusicgenForConditionalGeneration). إذا كان من الضروري تحميل فك الترميز فقط من نقطة التفتيش المُدرَّبة مسبقًا، فيمكن تحميله عن طريق تحديد الإعداد الصحيح أولاً، أو الوصول إليه من خلال خاصية `.decoder` في النموذج المركّب:

```python
from transformers import AutoConfig, MusicgenForCausalLM, MusicgenForConditionalGeneration

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

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

بما أن نماذج مُشفِّر النص ومُشفِّر/مُفكِّك الصوت مجمّدة أثناء التدريب، يمكن تدريب مُفكِّك MusicGen [MusicgenForCausalLM](/docs/transformers/main/ar/model_doc/musicgen#transformers.MusicgenForCausalLM) بشكل مستقل على مجموعة بيانات من حالات المُشفِّر المخفية وأكواد الصوت. أما عند الاستدلال، فيمكن دمج المُفكِّك المُدرَّب مع مُشفِّر النص المجمّد ومُشفِّر/مُفكِّك الصوت لاستعادة النموذج المركّب [MusicgenForConditionalGeneration](/docs/transformers/main/ar/model_doc/musicgen#transformers.MusicgenForConditionalGeneration).

نصائح:

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

## MusicgenDecoderConfig[[transformers.MusicgenDecoderConfig]]

#### transformers.MusicgenDecoderConfig[[transformers.MusicgenDecoderConfig]]

```python
transformers.MusicgenDecoderConfig(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, cross_attention_hidden_size: int | None = None)
```

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

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

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`) : ما إذا كان يجب إضافة طبقات الانتباه المتقاطع إلى النموذج.

cross_attention_hidden_size (`int`، *اختياري*) : حجم المخفيّ لمخرجات المُشفِّر المُسقَط إلى فضاء المفتاح/القيمة في الانتباه المتقاطع للمُفكِّك. يُستخدم عندما يكون حجم المخفيّ مختلفًا بين المُشفِّر والمُفكِّك.

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

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

## MusicgenConfig[[transformers.MusicgenConfig]]

#### transformers.MusicgenConfig[[transformers.MusicgenConfig]]

```python
transformers.MusicgenConfig(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, initializer_factor: float = 0.02)
```

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

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

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

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

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

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

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

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

مثال:

```python
>>> from transformers import (
...     MusicgenConfig,
...     MusicgenDecoderConfig,
...     T5Config,
...     EncodecConfig,
...     MusicgenForConditionalGeneration,
... )

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

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

>>> # Initializing a MusicgenForConditionalGeneration (with random weights) from the facebook/musicgen-small style configuration
>>> model = MusicgenForConditionalGeneration(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-model")

>>> # loading model and config from pretrained folder
>>> musicgen_config = MusicgenConfig.from_pretrained("musicgen-model")
>>> model = MusicgenForConditionalGeneration.from_pretrained("musicgen-model", config=musicgen_config)
```

## MusicgenProcessor[[transformers.MusicgenProcessor]]

#### transformers.MusicgenProcessor[[transformers.MusicgenProcessor]]

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

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

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

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

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

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

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

#### __call__[[transformers.MusicgenProcessor.__call__]]

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

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

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

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

## MusicgenModel[[transformers.MusicgenModel]]

#### transformers.MusicgenModel[[transformers.MusicgenModel]]

```python
transformers.MusicgenModel(config: MusicgenDecoderConfig)
```

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

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

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

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

يرث هذا النموذج من [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.MusicgenModel.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/modeling_musicgen.py#L564)

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

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)`، *اختياري*) : تسلسل من حالات الإخفاء عند مخرج الطبقة الأخيرة من المُشفِّر. يُستخدم في الانتباه المتقاطع (cross-attention) في المُفكِّك.

encoder_attention_mask (`torch.LongTensor` من الشكل `(batch_size, encoder_sequence_length)`، *اختياري*) : قناع لتجنب تنفيذ الانتباه المتقاطع على فهارس رموز الحشو في مدخلات المُشفِّر input_ids. قيم القناع المختارة من `[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`).

**يعيد:** [BaseModelOutputWithPastAndCrossAttentions](/docs/transformers/main/ar/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPastAndCrossAttentions) أو `tuple(torch.Tensor)`

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

تتجاوز طريقة [MusicgenModel](/docs/transformers/main/ar/model_doc/musicgen#transformers.MusicgenModel) الخاصة بالتقديم (forward) الطريقة الخاصة `__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 على الانتباه، وتُستخدم لحساب المتوسط الموزون في رؤوس الانتباه الذاتي.
- **cross_attentions** (`tuple(torch.Tensor)`, *اختياري*, يُعاد عند تمرير `output_attentions=True` مع `config.add_cross_attention=True` أو عند `config.output_attentions=True`) -- مجموعة مرتبة من `torch.Tensor` (واحدة لكل طبقة) بشكل `(batch_size, num_heads, sequence_length, sequence_length)`.

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

## MusicgenForCausalLM[[transformers.MusicgenForCausalLM]]

#### transformers.MusicgenForCausalLM[[transformers.MusicgenForCausalLM]]

```python
transformers.MusicgenForCausalLM(config: MusicgenDecoderConfig)
```

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

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

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

نموذج MusicGen المُفكِّك مع رأس لنمذجة اللغة في الأعلى.

يرث هذا النموذج من [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.MusicgenForCausalLM.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, 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/modeling_musicgen.py#L656)

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

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)`، *اختياري*) : تسلسل من حالات الإخفاء عند مخرج الطبقة الأخيرة من المُشفِّر. يُستخدم في الانتباه المتقاطع (cross-attention) في المُفكِّك.

encoder_attention_mask (`torch.LongTensor` من الشكل `(batch_size, encoder_sequence_length)`، *اختياري*) : قناع لتجنب تنفيذ الانتباه المتقاطع على فهارس رموز الحشو في مدخلات المُشفِّر input_ids. قيم القناع المختارة من `[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` إلى المتجهات المرتبطة بها، مقارنةً بمصفوفة البحث المضمّنة الداخلية للنموذج.

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

**يعيد:** [CausalLMOutputWithCrossAttentions](/docs/transformers/main/ar/main_classes/output#transformers.modeling_outputs.CausalLMOutputWithCrossAttentions) أو `tuple(torch.Tensor)`

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

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

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

- **loss** (`torch.Tensor` من الشكل `(1,)`، *اختياري*، يُعاد عند توفير `labels`) -- خسارة نمذجة اللغة (لتوقع الرمز التالي).
- **logits** (`torch.Tensor` من الشكل `(batch_size, sequence_length, config.vocab_size)`) -- درجات التنبؤ لرأس نمذجة اللغة (درجات لكل رمز في المفردات قبل SoftMax).
- **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 على الانتباه، وتُستخدم لحساب المتوسط الموزون في رؤوس الانتباه الذاتي.
- **cross_attentions** (`tuple(torch.Tensor)`، *اختياري*، يُعاد عند تمرير `output_attentions=True` أو عند `config.output_attentions=True`) -- مجموعة مرتبة من `torch.Tensor` (واحدة لكل طبقة) من الشكل `(batch_size, num_heads, sequence_length, sequence_length)`.

  أوزان الانتباه المتقاطع بعد 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`) لتسريع فك الترميز التسلسلي.

مثال:

```python
```

## MusicgenForConditionalGeneration[[transformers.MusicgenForConditionalGeneration]]

#### transformers.MusicgenForConditionalGeneration[[transformers.MusicgenForConditionalGeneration]]

```python
transformers.MusicgenForConditionalGeneration(config: transformers.models.musicgen.configuration_musicgen.MusicgenConfig | None = None, text_encoder: transformers.modeling_utils.PreTrainedModel | None = None, audio_encoder: transformers.modeling_utils.PreTrainedModel | None = None, decoder: transformers.models.musicgen.modeling_musicgen.MusicgenForCausalLM | None = None)
```

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

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

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

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

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

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

نموذج MusicGen المركّب الذي يتضمن مشفّرًا للنص ومشفّرًا للصوت ومفكّك Musicgen،

يرث هذا النموذج من [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.MusicgenForConditionalGeneration.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.BoolTensor] = None, input_values: typing.Optional[torch.Tensor] = None, padding_mask: typing.Optional[torch.BoolTensor] = None, decoder_input_ids: typing.Optional[torch.LongTensor] = None, decoder_attention_mask: typing.Optional[torch.BoolTensor] = None, encoder_outputs: tuple[torch.Tensor] | None = None, past_key_values: transformers.cache_utils.Cache | None = 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/modeling_musicgen.py#L1420)

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

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_values (`torch.Tensor` من الشكل `(batch_size, sequence_length)`، *اختياري*) : قيم رقمية عشرية لموجة الصوت الخام المُدخلة. يمكن الحصول على هذه القيم عن طريق تحميل ملف صوتي من نوع `.flac` أو `.wav` في مصفوفة من النوع `list[float]`، أو `numpy.ndarray`، أو `torch.Tensor`، *على سبيل المثال* باستخدام مكتبة torchcodec (`pip install torchcodec`) أو مكتبة soundfile (`pip install soundfile`). لتحضير المصفوفة إلى `input_values`، يجب استخدام [AutoProcessor](/docs/transformers/main/ar/model_doc/auto#transformers.AutoProcessor) لإضافة الحشو (padding) والتحويل إلى متجه (tensor) من النوع `torch.Tensor`. راجع [MusicgenProcessor.__call__()](/docs/transformers/main/ar/model_doc/musicgen#transformers.MusicgenProcessor.__call__) للتفاصيل.

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

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`. وسيتم استخدام القناع السببي أيضًا بشكل افتراضي.

encoder_outputs (`tuple[torch.Tensor]`، *اختياري*) : يتكوّن المصفوفة من (`last_hidden_state`، *اختياري*: `hidden_states`، *اختياري*: `attentions`) `last_hidden_state` من الشكل `(batch_size, sequence_length, hidden_size)`، *اختياري*) هو تسلسل من حالات الخفاء عند مخرج الطبقة الأخيرة من المُشفِّر. يُستخدم في الانتباه المتقاطع (cross-attention) في المُفكِّك.

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` إلى المتجهات المرتبطة بها، مقارنةً بمصفوفة البحث المضمّنة الداخلية للنموذج.

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

**يعيد:** [Seq2SeqLMOutput](/docs/transformers/main/ar/main_classes/output#transformers.modeling_outputs.Seq2SeqLMOutput) أو `tuple(torch.Tensor)`

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

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

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

- **loss** (`torch.Tensor` من الشكل `(1,)`، *اختياري*، يُعاد عند تقديم `labels`) -- خسارة نمذجة اللغة.
- **logits** (`torch.Tensor` من الشكل `(batch_size, sequence_length, config.vocab_size)`) -- درجات التنبؤ لرأس نمذجة اللغة (درجات لكل رمز في المفردات قبل SoftMax).
- **past_key_values** (`EncoderDecoderCache`، *اختياري*، يُعاد عند تمرير `use_cache=True` أو عند `config.use_cache=True`) -- هو كائن من نوع [EncoderDecoderCache](/docs/transformers/main/ar/internal/generation_utils#transformers.EncoderDecoderCache). لمزيد من التفاصيل، راجع [دليل ذاكرة kv](https://huggingface.co/docs/transformers/en/kv_cache).

  تحتوي على حالات مخفية محسوبة مسبقًا (مفاتيح وقيم في كتل الانتباه الذاتي وكتل الانتباه المتقاطع) يمكن استخدامها (انظر مدخل `past_key_values`) لتسريع فك الترميز التسلسلي.
- **decoder_hidden_states** (`tuple(torch.Tensor)`, *اختياري*, يُعاد عند تمرير `output_hidden_states=True` أو عند `config.output_hidden_states=True`) -- مجموعة مرتبة من `torch.Tensor` (واحدة لمخرجات التضمينات، إذا كان النموذج يحتوي على طبقة تضمين، + واحدة لمخرجات كل طبقة) من الشكل `(batch_size, sequence_length, hidden_size)`.

  حالات المخفية (Hidden states) لمفكّك الترميز (decoder) عند مخرج كل طبقة بالإضافة إلى مخرجات التضمين الأولي (initial embedding).
- **decoder_attentions** (`tuple(torch.Tensor)`, *اختياري*, يُعاد عند تمرير `output_attentions=True` أو عند `config.output_attentions=True`) -- مجموعة مرتبة من `torch.Tensor` (واحدة لكل طبقة) من الشكل `(batch_size, num_heads, sequence_length, sequence_length)`.

  أوزان الانتباه في المفكّك، بعد softmax الانتباه، المستخدمة لحساب المتوسط المرجّح في رؤوس الانتباه الذاتي.
- **cross_attentions** (`tuple(torch.Tensor)`، *اختياري*، يُعاد عند تمرير `output_attentions=True` أو عند `config.output_attentions=True`) -- مجموعة مرتبة من `torch.Tensor` (واحدة لكل طبقة) من الشكل `(batch_size, num_heads, sequence_length, sequence_length)`.

  أوزان الانتباه في طبقة الانتباه المتقاطع للمفكّك، بعد softmax للانتباه، وتُستخدم لحساب المتوسط المرجّح في رؤوس الانتباه المتقاطع.
- **encoder_last_hidden_state** (`torch.Tensor` بشكل `(batch_size, sequence_length, hidden_size)`، *اختياري*) -- سلسلة من حالات الإخفاء عند مخرجات الطبقة الأخيرة من المُشفِّر في النموذج.
- **encoder_hidden_states** (`tuple(torch.Tensor)`, *اختياري*, يُعاد عند تمرير `output_hidden_states=True` أو عند `config.output_hidden_states=True`) -- مجموعة مرتبة من `torch.Tensor` (واحدة لمخرجات التضمينات، إذا كان النموذج يحتوي على طبقة تضمين، + واحدة لمخرجات كل طبقة) من الشكل `(batch_size, sequence_length, hidden_size)`.

  حالات المخفية للمشفّر عند مخرج كل طبقة بالإضافة إلى مخرجات التضمين الأولي.
- **encoder_attentions** (`tuple(torch.Tensor)`, *اختياري*, يُعاد عند تمرير `output_attentions=True` أو عند `config.output_attentions=True`) -- مجموعة مرتبة من `torch.Tensor` (واحدة لكل طبقة) من الشكل `(batch_size, num_heads, sequence_length, sequence_length)`.

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

أمثلة:
```python
>>> from transformers import AutoProcessor, MusicgenForConditionalGeneration
>>> import torch

>>> processor = AutoProcessor.from_pretrained("facebook/musicgen-small")
>>> model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-small")

>>> 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, tgt_len, vocab_size)
torch.Size([8, 1, 2048])
```