# Music Flamingo

## نظرة عامة

Music Flamingo هو نموذج صوتي-لغوي كبير مفتوح بالكامل، مصمم لفهم الموسيقى والاستدلال عليها بشكل قوي. يقوم هذا النموذج على بنية [Audio Flamingo 3](./audioflamingo3) من خلال تضمين **Rotary Time Embeddings (RoTE)**، والتي تُدخل معلومات الموقع الزمني لتمكين النموذج من التعامل مع تسلسلات صوتية تصل مدتها إلى 20 دقيقة (1200 ثانية).

نقطة التفتيش للنموذج متاحة في: [nvidia/music-flamingo-2601-hf](https://huggingface.co/nvidia/music-flamingo-2601-hf)

أبرز النقاط:

- مشفر صوتي موحّد يغطي الكلام والأصوات والموسيقى.
- **تضمينات الدوران الزمني (RoTE)** لتحسين النمذجة الزمنية، مما يتيح دعم **حتى 20 دقيقة من الصوت**.
- **دعم موسّع للصوت الطويل عبر التقطيع النافذ ومحاذاة ما بعد التجميع (حتى 20 دقيقة كحد أقصى).** يعالج النموذج الصوت في نوافذ مدتها 30 ثانية مع حد صارم يبلغ 40 نافذة (20 دقيقة إجمالاً). سيتم اقتطاع أي صوت يتجاوز 20 دقيقة.
- رموز حدود صوتية خاصة (`<|sound_bos|>` و`<|sound_eos|>`) لتحسين نمذجة تسلسلات الصوت.
- دمج حتمي يحافظ على طول التسلسل من خلال استبدال رموز المحلّلات الصوتية بتضمينات صوتية.

تمت مساهمة هذا النموذج من قِبل [Lasha Koroshinadze](https://huggingface.co/lashahub) و[Eric Bezzam](https://huggingface.co/bezzam).

### ورقة

[Music Flamingo: توسيع فهم الموسيقى في نماذج اللغة الصوتية](https://huggingface.co/papers/2511.10289) S. Ghosh, A. Goel, L. Koroshinadze, S. Lee, Z. Kong, J. F. Santos, R. Duraiswami, D. Manocha, W. Ping, M. Shoeybi, B. Catanzaro NVIDIA وجامعة ماريلاند المشروع: https://research.nvidia.com/labs/adlr/MF/

## الاستخدام

### وضع التعليم الصوتي

يدعم النموذج تعليمات صوتية-نصية، بما في ذلك التفاعلات متعددة الأدوار، حيث تتم معالجتها جميعاً على شكل دفعات.

➡️ صوت + تعليمات نصية

```python
from transformers import AutoProcessor, MusicFlamingoForConditionalGeneration

model_id = "nvidia/music-flamingo-2601-hf"
processor = AutoProcessor.from_pretrained(model_id)
model = MusicFlamingoForConditionalGeneration.from_pretrained(model_id, device_map="auto")

conversation = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "Describe this track in full detail - tell me the genre, tempo, and key, then dive into the instruments, production style, and overall mood it creates."},
            {"type": "audio", "path": "https://huggingface.co/datasets/nvidia/AudioSkills/resolve/main/assets/song_1.mp3"},
        ],
    }
]

inputs = processor.apply_chat_template(
    conversation,
    tokenize=True,
    add_generation_prompt=True,
    return_dict=True,
).to(model.device)
inputs["input_features"] = inputs["input_features"].to(model.dtype)

outputs = model.generate(**inputs, max_new_tokens=500)

decoded_outputs = processor.batch_decode(outputs[:, inputs.input_ids.shape[1]:], skip_special_tokens=True)
print(decoded_outputs)
```

➡️ متعدد الأدوار:

```python
from transformers import AutoProcessor, MusicFlamingoForConditionalGeneration

model_id = "nvidia/music-flamingo-2601-hf"
processor = AutoProcessor.from_pretrained(model_id)
model = MusicFlamingoForConditionalGeneration.from_pretrained(model_id, device_map="auto")

conversation = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "Write a rich caption that blends the technical details (genre, BPM, key, chords, mix) with how the song feels emotionally and dynamically as it unfolds.",
            },
            {"type": "audio", "path": "https://huggingface.co/datasets/nvidia/AudioSkills/resolve/main/assets/song_1.mp3"},
        ],
    },
    {
        "role": "assistant",
        "content": [{"type": "text", "text": "This energetic Eurodance anthem at 150 BPM in E major combines bright synth arpeggios with a punchy four-on-the-floor beat..."}],
    },
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "What instruments stand out the most?"},
        ],
    },
]

inputs = processor.apply_chat_template(
    conversation,
    tokenize=True,
    add_generation_prompt=True,
    return_dict=True,
).to(model.device)
inputs["input_features"] = inputs["input_features"].to(model.dtype)

outputs = model.generate(**inputs, max_new_tokens=500)

decoded_outputs = processor.batch_decode(outputs[:, inputs.input_ids.shape[1]:], skip_special_tokens=True)
print(decoded_outputs)
```

➡️ الاستدلال المُجمَّع!

```python
from transformers import AutoProcessor, MusicFlamingoForConditionalGeneration

model_id = "nvidia/music-flamingo-2601-hf"
processor = AutoProcessor.from_pretrained(model_id)
model = MusicFlamingoForConditionalGeneration.from_pretrained(model_id, device_map="auto")

conversations = [
    [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Describe this track in full detail - tell me the genre, tempo, and key, then dive into the instruments, production style, and overall mood it creates."},
                {
                    "type": "audio",
                    "path": "https://huggingface.co/datasets/nvidia/AudioSkills/resolve/main/assets/song_1.mp3",
                },
            ],
        }
    ],
    [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Generate a structured lyric sheet from the input music.",
                },
                {"type": "audio", "path": "https://huggingface.co/datasets/nvidia/AudioSkills/resolve/main/assets/song_2.mp3"},
            ],
        }
    ],
]

inputs = processor.apply_chat_template(
    conversations,
    tokenize=True,
    add_generation_prompt=True,
    return_dict=True,
).to(model.device)
inputs["input_features"] = inputs["input_features"].to(model.dtype)

outputs = model.generate(**inputs, max_new_tokens=500)

decoded_outputs = processor.batch_decode(outputs[:, inputs.input_ids.shape[1]:], skip_special_tokens=True)
print(decoded_outputs)
```

➡️ التدريب:

```python
from transformers import AutoProcessor, MusicFlamingoForConditionalGeneration

model_id = "nvidia/music-flamingo-2601-hf"
processor = AutoProcessor.from_pretrained(model_id)
model = MusicFlamingoForConditionalGeneration.from_pretrained(model_id, device_map="auto")
model.train()

conversation = [
    [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Break the track down like a critic - list its tempo, key, and chordal motion, then explain the textures, dynamics, and emotional impact of the performance."},
                {"type": "audio", "path": "https://huggingface.co/datasets/nvidia/AudioSkills/resolve/main/assets/song_1.mp3"},
            ],
        },
        {
            "role": "assistant",
            "content": [{"type": "text", "text": "This Eurodance track operates at 150 BPM in E major, with harmonic movement centering on the I-vi-IV-V family. The production features layered synth arpeggios, a four-on-the-floor kick pattern, and a mezzo-soprano lead vocal with bright timbre. Dynamically, the track builds through verses into an anthemic chorus with full synth orchestration and backing vocals, creating an uplifting, euphoric atmosphere characteristic of late 2000s dance-pop."}],
        }
    ],
    [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Describe this song from both a technical and artistic lens: mention tempo, harmony, and instrumentation, but also mood, lyrical themes, and structure.",
                },
                {"type": "audio", "path": "https://huggingface.co/datasets/nvidia/AudioSkills/resolve/main/assets/song_2.mp3"},
            ],
        },
        {
            "role": "assistant",
            "content": [{"type": "text", "text": "This electronic pop track combines upbeat production with playful lyrical themes centered around late-night pizza cravings. The structure follows a verse-chorus format with recurring melodic motifs and rhythmic patterns that emphasize the celebratory, lighthearted mood of the piece."}],
        }

    ]
]

inputs = processor.apply_chat_template(
    conversation,
    tokenize=True,
    add_generation_prompt=True,
    return_dict=True,
    processor_kwargs={"output_labels": True},
).to(model.device)
inputs["input_features"] = inputs["input_features"].to(model.dtype)

loss = model(**inputs).loss
loss.backward()
```

## كيف يعمل النموذج

### البنية

* **مُشفِّر الصوت** مستخرج ميزات ومُشفِّر بنمط Whisper → متوسط مجمّع عبر الزمن (خطوة 2) → LayerNorm. ينتج حالات مخفية لكل إطار بمعدل ما بعد التجميع.

* **تضمينات الدوران الزمني (RoTE)** تُطبَّق على مخرجات المُشفِّر لحقن معلومات الموقع الزمني، مما يتيح للنموذج التعامل مع تسلسلات صوتية تصل إلى 20 دقيقة (1200 ثانية). يستخدم RoTE تضمينات دوران محورية ثنائية الأبعاد لأبعاد الدفعة والزمن مع تعديل زوايا قائم على الزمن.

* **MusicFlamingoMultiModalProjector** شبكة عصبية متعددة الطبقات صغيرة الحجم تُحوّل ميزات المُشفِّر إلى حجم المخفي لنموذج اللغة.

* **MusicFlamingoForConditionalGeneration** نموذج لغة سببي يقبل تضمينات نصية حيث يُستبدل كل خانة رمز بديل للصوت، في مكانه، بتضمين إطار صوتي. يستخدم رموز حدود خاصة (`<|sound_bos|>` و`<|sound_eos|>`) لتحديد تسلسلات الصوت. لا يُدخل الدمج أي تغيير في طول التسلسل.

### محاذاة على مستوى المعالج

1. يتم تقسيم كل موجة خام إلى نوافذ بطول ثابت بناءً على `chunk_length` (بالثواني) و`sampling_rate` (هرتز) الخاص بمستخرج الميزات.
2. للقسم الزمني (نافذة) لكل، يحسب المعالج عدد إطارات ما بعد التجميع `post_pool_len` التي سيُخرجها المُشفِّر (بما يتوافق مع جدول التحوّل/التجميع).
3. يوسّع المعالج رمز موضع الصوت حسب إجمالي عدد الإطارات بعد التجميع عبر جميع النوافذ.
4. يستبدل النموذج لاحقًا مواضع الرموز تلك بتضمينات الصوت المُساقطة المقابلة.

## الصوت الطويل والتقسيم إلى نوافذ

**مهم: الحد الأقصى لطول الصوت هو 20 دقيقة.** سيتم اقتطاع أي صوت أطول من ذلك.

* يعالج الإعداد الافتراضي نوافذ مدتها 30 ثانية بمعدل عينة 16 كيلو هرتز بصيغة أحادية.
* **يفرض المعالج حدًا أقصى صارمًا قدره 40 نافذة لكل عينة، مما يؤدي إلى حد أقصى قدره 20 دقيقة من الصوت (40 نافذة × 30 ثانية).**
* توفر تضمينات الوقت الدوارة (RoTE) معلومات الموضع للتسلسلات التي تصل مدتها إلى 20 دقيقة (1200 ثانية).
* لكل نافذة:

  * `mel_len` هو طول الميِل المُكمّل.
  * تقلّل مجموعة التحويلات الزمنية من الوقت لأن `conv_output_len = (mel_len - 1) // 2 + 1`.
  * إطارات ما بعد التجميع لكل نافذة: `post_pool_len = (conv_output_len - 2) // 2 + 1`.
  * يتم توسيع رمز الوكيل الصوتي إلى مجموع `post_pool_len` عبر جميع النوافذ.

## MusicFlamingoConfig[[transformers.MusicFlamingoConfig]]

#### transformers.MusicFlamingoConfig[[transformers.MusicFlamingoConfig]]

```python
transformers.MusicFlamingoConfig(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, audio_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, text_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, audio_token_id: int = 151669, projector_hidden_act: str = 'gelu', projector_bias: bool = True, audio_bos_token_id: int = 151670, audio_eos_token_id: int = 151671, audio_frame_step: float = 0.01, rope_parameters: dict | None = None)
```

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

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

audio_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`، *اختياري*) : كائن الإعداد أو قاموس العمود الفقري الصوتي.

text_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`، *اختياري*) : كائن الإعداد أو قاموس العمود الفقري النصي.

audio_token_id (`int`، *اختياري*، القيمة الافتراضية `151669`) : فهرس رمز الصوت المستخدم كعلامة مؤقتة للصوت المُدخل.

projector_hidden_act (`str`، *اختياري*، القيمة الافتراضية هي `gelu`) : دالة التنشيط المستخدمة في المُشغِّل متعدد الوسائط.

projector_bias (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان سيتم استخدام الانحياز في المُسقط متعدد الوسائط.

audio_bos_token_id (`int`، *اختياري*، القيمة الافتراضية 151670) : فهرس رمز بداية الصوت المستخدم لتحديد بداية مقاطع الصوت.

audio_eos_token_id (`int`، *اختياري*، القيمة الافتراضية 151671) : فهرس رمز نهاية الصوت المستخدم لتحديد نهاية مقاطع الصوت.

audio_frame_step (`float`، *اختياري*، القيمة الافتراضية 0.01) : المدة بالثواني لإطار مدخل واحد من نوع mel (تم التدريب باستخدام hop_length 160 وsampling_rate 16000).

rope_parameters (`dict`, *اختياري*) : قاموس يحتوي على معاملات التهيئة لتضمينات RoPE. يجب أن يحتوي القاموس على قيمة لـ `rope_theta`، ومعاملات اختيارية تُستخدم للتصعيد في حال رغبتك في استخدام RoPE مع `max_position_embeddings` أطول.

هذه فئة الإعدادات المخزنة لإعدادات نموذج MusicFlamingoModel. تُستخدم لاستحداث نموذج Musicflamingo وفقًا للحجج المحددة، مع تعريف بنية النموذج. إن استحداث إعدادات باستخدام القيم الافتراضية سيؤدي إلى إعدادات مشابهة لتلك الخاصة بـ [nvidia/music-flamingo-2601-hf](https://huggingface.co/nvidia/music-flamingo-2601-hf)

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

مثال:

```python
>>> from transformers import MusicFlamingoForConditionalGeneration, MusicFlamingoConfig, AudioFlamingo3EncoderConfig, Qwen2Config

>>> # Initializing an MusicFlamingoEncoder config
>>> audio_config = AudioFlamingo3EncoderConfig()

>>> # Initializing a Qwen2 config
>>> text_config = Qwen2Config()

>>> # Initializing an MusicFlamingo configuration
>>> configuration = MusicFlamingoConfig(audio_config, text_config)

>>> # Initializing a model from the musicflamingo style configuration
>>> model = MusicFlamingoForConditionalGeneration(configuration)

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

## MusicFlamingoProcessor[[transformers.MusicFlamingoProcessor]]

#### transformers.MusicFlamingoProcessor[[transformers.MusicFlamingoProcessor]]

```python
transformers.MusicFlamingoProcessor(feature_extractor, tokenizer, chat_template = None, audio_token = '<sound>', audio_bos_token = '<|sound_bos|>', audio_eos_token = '<|sound_eos|>', max_audio_len = 1200)
```

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

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

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

tokenizer (`tokenizer_class`) : مُجزِّئ النص (tokenizer) هو مدخل إلزامي.

chat_template (`str`) : قالب Jinja لتحويل قوائم الرسائل في المحادثة إلى نص قابل للتحويم.

audio_token (`Optional[str]`، *اختياري*، القيمة الافتراضية `"<sound>"`) : الرمز الخاص المستخدم لتمثيل مدخلات الصوت في قالب المحادثة.

audio_bos_token (`Optional[str]`، *اختياري*، القيمة الافتراضية `"<|sound_bos|>"`) : الرمز الخاص المستخدم لتمثيل بداية الصوت.

audio_eos_token (`Optional[str]`، *اختياري*، القيمة الافتراضية `"<|sound_eos|>"`) : الرمز الخاص المستخدم لتمثيل نهاية الصوت.

max_audio_len (`int`، *اختياري*، القيمة الافتراضية 1200) : الحد الأقصى لطول تسلسلات الصوت بالثواني. سيتم اقتطاع أي صوت أطول من هذا الحد.

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

يوفر [MusicFlamingoProcessor](/docs/transformers/main/ar/model_doc/musicflamingo#transformers.MusicFlamingoProcessor) جميع وظائف `feature_extractor_class` و`tokenizer_class`. راجع `~feature_extractor_class` و`~tokenizer_class` لمزيد من المعلومات.

## MusicFlamingoModel[[transformers.MusicFlamingoModel]]

#### transformers.MusicFlamingoModel[[transformers.MusicFlamingoModel]]

```python
transformers.MusicFlamingoModel(config: MusicFlamingoConfig)
```

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

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

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

نموذج MusicFlamingo (مشفّر Whisper المُحسَّن، مُسقط متعدد الوسائط، نموذج لغة Qwen2)، دون رأس نمذجة اللغة.

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

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, input_features: typing.Optional[torch.Tensor] = None, input_features_mask: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: 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/musicflamingo/modeling_musicflamingo.py#L277)

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

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)

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

input_features_mask (`torch.Tensor` من الشكل `(batch_size, feature_sequence_length)`) : قناع لتجنب تنفيذ الانتباه على فهارس الحشو.

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

position_ids (`torch.LongTensor` من الشكل `(batch_size, sequence_length)`، *اختياري*) : فهارس مواضع رموز كل تسلسل إدخال في تضمينات المواضع. يتم اختيارها من النطاق `[0, config.n_positions - 1]`.  [ما هي معرّفات المواضع؟](../glossary#position-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)`.

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

use_cache (`bool`، *اختياري*) : إذا تم ضبطه على `True`، تُعاد حالات المفاتيح والقيم `past_key_values` ويمكن استخدامها لتسريع فك الترميز (انظر `past_key_values`).

**يعيد:** `MusicFlamingoModelOutputWithPast` أو `tuple(torch.Tensor)`

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

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

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

- **audio_hidden_states** (`torch.Tensor`، *اختياري*) -- حالات مخفية صوتية مُسقطَة.

## MusicFlamingoForConditionalGeneration[[transformers.MusicFlamingoForConditionalGeneration]]

#### transformers.MusicFlamingoForConditionalGeneration[[transformers.MusicFlamingoForConditionalGeneration]]

```python
transformers.MusicFlamingoForConditionalGeneration(config: MusicFlamingoConfig)
```

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

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

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

نموذج MusicFlamingo الذي يتكون من مشفّر Whisper مُعاد تدريبه، وتضمين زمني دوّاري، ومشروع متعدد الوسائط، ونموذج لغوي Qwen2.

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

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, input_features: typing.Optional[torch.Tensor] = None, input_features_mask: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: 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, logits_to_keep: typing.Union[int, torch.Tensor] = 0, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

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

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

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)

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

input_features_mask (`torch.Tensor` من الشكل `(batch_size, feature_sequence_length)`) : قناع لتجنب تنفيذ الانتباه على فهارس الحشو.

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

position_ids (`torch.LongTensor` من الشكل `(batch_size, sequence_length)`، *اختياري*) : فهارس مواضع رموز كل تسلسل إدخال في تضمينات المواضع. يتم اختيارها من النطاق `[0, config.n_positions - 1]`.  [ما هي معرّفات المواضع؟](../glossary#position-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)`.

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

labels (`torch.LongTensor` من الشكل `(batch_size, sequence_length)`، *اختياري*) : تسميات لحساب خسارة نمذجة اللغة المقنّعة.

use_cache (`bool`، *اختياري*) : إذا تم ضبطه على `True`، تُعاد حالات المفاتيح والقيم `past_key_values` ويمكن استخدامها لتسريع فك الترميز (انظر `past_key_values`).

logits_to_keep (`Union[int, torch.Tensor]`، *اختياري*، القيمة الافتراضية `0`) : إذا كان `int`، يتم حساب القيم اللوجستية (logits) لآخر `logits_to_keep` رموز. إذا كانت `0`، يتم حساب القيم اللوجستية لجميع `input_ids` (حالة خاصة). لا تكون قيم اللوجستيات للرمز الأخير فقط ضرورية للتوليد، ويمكن أن يوفر حسابها لذلك الرمز وحده ذاكرة، وهو ما يصبح ذا أهمية كبيرة للترتيبات الطويلة أو لحجم المفردات الكبير. إذا كان `torch.Tensor`، يجب أن يكون بعدًا واحدًا (1D) ويتوافق مع الفهارس التي يجب الاحتفاظ بها في بُعد طول الترتيب. وهذا مفيد عند استخدام تنسيق المصفوفات المعبأة (packed tensor format) (بعد واحد لكل من الدفعة وطول الترتيب).

**يعيد:** `MusicFlamingoCausalLMOutputWithPast` أو `tuple(torch.Tensor)`

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

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

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

- **loss** (`torch.Tensor` من الشكل `(1,)`، *اختياري*، يُعاد عند توفير `labels`) -- خسارة نمذجة اللغة (لتوقع الرمز التالي).
- **logits** (`torch.Tensor` من الشكل `(batch_size, sequence_length, config.vocab_size)`) -- درجات التنبؤ لرأس نمذجة اللغة.
- **past_key_values** (`Cache`، *اختياري*، يُعاد عند تمرير `use_cache=True` أو عند تعيين `config.use_cache=True`) -- هو كائن من نوع [Cache](/docs/transformers/main/ar/internal/generation_utils#transformers.Cache).
- **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 على الانتباه، وتُستخدم لحساب المتوسط الموزون في رؤوس الانتباه الذاتي.
- **audio_hidden_states** (`torch.Tensor`، *اختياري*) -- حالات المخفية لمشفّر الصوت بعد الإسقاط.

مثال:

```python
>>> from transformers import MusicFlamingoForConditionalGeneration, AutoProcessor

>>> model_id = "nvidia/audio-flamingo-3-hf"
>>> processor = AutoProcessor.from_pretrained(model_id)
>>> model = MusicFlamingoForConditionalGeneration.from_pretrained(model_id, device_map="auto")
```