Transformers documentation
Music Flamingo
نُشر هذا النموذج في أوراق HF في 13 نوفمبر 2025، وسُهم به في Hugging Face Transformers في 30 مارس 2026.
Music Flamingo
نظرة عامة
Music Flamingo هو نموذج صوتي-لغوي كبير مفتوح بالكامل، مصمم لفهم الموسيقى والاستدلال عليها بشكل قوي. يقوم هذا النموذج على بنية Audio Flamingo 3 من خلال تضمين Rotary Time Embeddings (RoTE)، والتي تُدخل معلومات الموقع الزمني لتمكين النموذج من التعامل مع تسلسلات صوتية تصل مدتها إلى 20 دقيقة (1200 ثانية).
نقطة التفتيش للنموذج متاحة في: nvidia/music-flamingo-2601-hf
أبرز النقاط:
- مشفر صوتي موحّد يغطي الكلام والأصوات والموسيقى.
- تضمينات الدوران الزمني (RoTE) لتحسين النمذجة الزمنية، مما يتيح دعم حتى 20 دقيقة من الصوت.
- دعم موسّع للصوت الطويل عبر التقطيع النافذ ومحاذاة ما بعد التجميع (حتى 20 دقيقة كحد أقصى). يعالج النموذج الصوت في نوافذ مدتها 30 ثانية مع حد صارم يبلغ 40 نافذة (20 دقيقة إجمالاً). سيتم اقتطاع أي صوت يتجاوز 20 دقيقة.
- رموز حدود صوتية خاصة (
<|sound_bos|>و<|sound_eos|>) لتحسين نمذجة تسلسلات الصوت. - دمج حتمي يحافظ على طول التسلسل من خلال استبدال رموز المحلّلات الصوتية بتضمينات صوتية.
تمت مساهمة هذا النموذج من قِبل Lasha Koroshinadze وEric Bezzam.
ورقة
Music Flamingo: توسيع فهم الموسيقى في نماذج اللغة الصوتية
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/
الاستخدام
وضع التعليم الصوتي
يدعم النموذج تعليمات صوتية-نصية، بما في ذلك التفاعلات متعددة الأدوار، حيث تتم معالجتها جميعاً على شكل دفعات.
➡️ صوت + تعليمات نصية
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)➡️ متعدد الأدوار:
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)➡️ الاستدلال المُجمَّع!
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)➡️ التدريب:
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|>) لتحديد تسلسلات الصوت. لا يُدخل الدمج أي تغيير في طول التسلسل.
محاذاة على مستوى المعالج
- يتم تقسيم كل موجة خام إلى نوافذ بطول ثابت بناءً على
chunk_length(بالثواني) وsampling_rate(هرتز) الخاص بمستخرج الميزات. - للقسم الزمني (نافذة) لكل، يحسب المعالج عدد إطارات ما بعد التجميع
post_pool_lenالتي سيُخرجها المُشفِّر (بما يتوافق مع جدول التحوّل/التجميع). - يوسّع المعالج رمز موضع الصوت حسب إجمالي عدد الإطارات بعد التجميع عبر جميع النوافذ.
- يستبدل النموذج لاحقًا مواضع الرموز تلك بتضمينات الصوت المُساقطة المقابلة.
الصوت الطويل والتقسيم إلى نوافذ
مهم: الحد الأقصى لطول الصوت هو 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
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Noneaudio_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonetext_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneaudio_token_id: int = 151669projector_hidden_act: str = 'gelu'projector_bias: bool = Trueaudio_bos_token_id: int = 151670audio_eos_token_id: int = 151671audio_frame_step: float = 0.01rope_parameters: dict | None = None )
المعاملات
- 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، ومعاملات اختيارية تُستخدم للتصحيح (scaling) في حال رغبتَ في استخدام RoPE معmax_position_embeddingsأطول.
هذه فئة الإعدادات المخزنة لإعدادات نموذج MusicFlamingoModel. تُستخدم لاستحداث نموذج Musicflamingo وفقًا للحجج المحددة، مع تعريف بنية النموذج. إن استحداث إعدادات باستخدام القيم الافتراضية سيؤدي إلى إعدادات مشابهة لتلك الخاصة بـ nvidia/music-flamingo-2601-hf
ترث كائنات التهيئة من PreTrainedConfig ويمكن استخدامها للتحكم في مخرجات النموذج. اقرأ التوثيق الخاص بـ PreTrainedConfig لمزيد من المعلومات.
مثال:
>>> 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.configMusicFlamingoProcessor
فئة transformers.MusicFlamingoProcessor
< source >( feature_extractortokenizerchat_template = Noneaudio_token = '<sound>'audio_bos_token = '<|sound_bos|>'audio_eos_token = '<|sound_eos|>'max_audio_len = 1200 )
المعاملات
- 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 جميع وظائف feature_extractor_class وtokenizer_class. راجع ~feature_extractor_class و~tokenizer_class لمزيد من المعلومات.
MusicFlamingoModel
فئة transformers.MusicFlamingoModel
< source >( config: MusicFlamingoConfig )
المعاملات
- config (MusicFlamingoConfig) — فئة إعدادات النموذج التي تحتوي على جميع معاملات النموذج. لا يؤدي التهيئة باستخدام ملف الإعداد إلى تحميل الأوزان المرتبطة بالنموذج، بل الإعدادات فقط. راجع طريقة from_pretrained() لتحميل أوزان النموذج.
نموذج MusicFlamingo (مشفّر Whisper المُحسَّن، مُسقط متعدد الوسائط، نموذج لغة Qwen2)، دون رأس نمذجة اللغة.
يرث هذا النموذج من PreTrainedModel. راجع توثيق الفئة الأصلية لمعرفة الطرق العامة التي تنفذها المكتبة لجميع نماذجها (مثل التحميل أو الحفظ، وتغيير حجم تضمينات الإدخال، وقص الرؤوس، وما إلى ذلك).
هذا النموذج هو أيضًا فئة فرعية من torch.nn.Module في PyTorch. استخدمه كوحدة PyTorch عادية، وارجع إلى توثيق PyTorch لكل ما يتعلق بالاستخدام العام والسلوك.
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Noneinput_features: typing.Optional[torch.Tensor] = Noneinput_features_mask: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.Tensor] = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → MusicFlamingoModelOutputWithPast or tuple(torch.Tensor)
المعاملات
- input_ids (
torch.LongTensorبشكل(batch_size, sequence_length), اختياري) — مؤشرات رموز تسلسل الإدخال في قاموس الكلمات. سيتم تجاهل الحشو افتراضيًا.يمكن الحصول على الفهارس باستخدام AutoTokenizer. راجع PreTrainedTokenizer.encode() و PreTrainedTokenizer.call() للتفاصيل.
- input_features (
torch.Tensorمن الشكل(batch_size, sequence_length, feature_dim)، اختياري) — المصفوفات المقابلة لميزات الصوت المدخلة. يمكن الحصول على ميزات الصوت باستخدامfeature_extractor_class. راجعfeature_extractor_class.__call__للتفاصيل (يستخدم MusicFlamingoProcessorfeature_extractor_classلمعالجة الملفات الصوتية). - input_features_mask (
torch.Tensorمن الشكل(batch_size, feature_sequence_length)) — قناع لتجنب تنفيذ الانتباه على فهارس الحشو. - attention_mask (
torch.Tensorبشكل(batch_size, sequence_length), اختياري) — قناع لتجنب تنفيذ الانتباه على فهارس رموز الحشو. القيم المختارة للقناع هي[0, 1]:- 1 للرموز التي لم تُقنَّع،
- 0 للرموز التي تم إخفاؤها.
- position_ids (
torch.LongTensorبشكل(batch_size, sequence_length), اختياري) — مؤشرات مواضع رموز كل تسلسل إدخال في تضمينات المواضع. يتم اختيارها ضمن النطاق[0, config.n_positions - 1]. - past_key_values (
~cache_utils.Cache, اختياري) — حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي وكتل الانتباه المتقاطع) يمكن استخدامها لتسريع فك الترميز التسلسلي. يتكون هذا عادةً منpast_key_valuesالذي يعيده النموذج في مرحلة سابقة من فك الترميز، عندماuse_cache=Trueأوconfig.use_cache=True.يُسمح فقط بمرجع Cache كمدخل، راجع دليل ذاكرة kv لدينا. إذا لم يتم تمرير
past_key_values، فسيتم تهيئة DynamicCache افتراضياً.سيُخرج النموذج نفس صيغة الكاش التي تُمرَّر كمدخل.
عند استخدام
past_key_values، يُتوقَّع من المستخدم إدخالinput_idsغير المعالجة فقط (تلك التي لم تُقدَّم حالات مفاتيحها وقيمها السابقة إلى هذا النموذج) بأبعاد(batch_size, unprocessed_length)بدلاً من جميعinput_idsبأبعاد(batch_size, sequence_length). - inputs_embeds (
torch.Tensorمن الشكل(batch_size, sequence_length, hidden_size)، اختياري) — اختياريًا، بدلاً من تمريرinput_ids، يمكنك اختيار تمرير تمثيل مضمّن مباشرة. وهذا مفيد إذا كنت ترغب في الحصول على مزيد من التحكم في كيفية تحويل فهارسinput_idsإلى المتجهات المرتبطة بها، مقارنةً بمصفوفة البحث المضمّنة الداخلية للنموذج. - use_cache (
bool، اختياري) — إذا تم تعيينه إلىTrue، تُعاد حالات المفاتيح والقيمpast_key_valuesويمكن استخدامها لتسريع فك الترميز (انظرpast_key_values).
يعيد
MusicFlamingoModelOutputWithPast أو tuple(torch.Tensor)
MusicFlamingoModelOutputWithPast أو مجموعة مرتبة من
torch.Tensor (إذا تم تمرير return_dict=False أو عندما يكون config.return_dict=False) وتتضمن عناصر مختلفة
تعتمد على الإعداد (MusicFlamingoConfig) والمدخلات.
تتجاوز طريقة MusicFlamingoModel الخاصة بالتقديم (forward) الطريقة الخاصة __call__.
على الرغم من أنه يجب تعريف وصفة المرور الأمامي داخل هذه الدالة، إلا أنه ينبغي استدعاء كائن
Moduleبدلاً من هذه الدالة، لأن الكائن يتولى تنفيذ خطوات المعالجة المسبقة والمعالجة اللاحقة، بينما تتجاهل الدالة هذه الخطوات بصمت.
- audio_hidden_states (
torch.Tensor، اختياري) — حالات مخفية صوتية مُسقطَة.
MusicFlamingoForConditionalGeneration
فئة transformers.MusicFlamingoForConditionalGeneration
< source >( config: MusicFlamingoConfig )
المعاملات
- config (MusicFlamingoConfig) — فئة إعدادات النموذج التي تحتوي على جميع معاملات النموذج. لا يؤدي التهيئة باستخدام ملف الإعداد إلى تحميل الأوزان المرتبطة بالنموذج، بل الإعدادات فقط. راجع طريقة from_pretrained() لتحميل أوزان النموذج.
نموذج MusicFlamingo الذي يتكون من مشفّر Whisper مُعاد تدريبه، وتضمين زمني دوّاري، ومشروع متعدد الوسائط، ونموذج لغوي Qwen2.
يرث هذا النموذج من PreTrainedModel. راجع توثيق الفئة الأصلية لمعرفة الطرق العامة التي تنفذها المكتبة لجميع نماذجها (مثل التحميل أو الحفظ، وتغيير حجم تضمينات الإدخال، وقص الرؤوس، وما إلى ذلك).
هذا النموذج هو أيضًا فئة فرعية من torch.nn.Module في PyTorch. استخدمه كوحدة PyTorch عادية، وارجع إلى توثيق PyTorch لكل ما يتعلق بالاستخدام العام والسلوك.
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Noneinput_features: typing.Optional[torch.Tensor] = Noneinput_features_mask: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.Tensor] = Nonelabels: typing.Optional[torch.LongTensor] = Noneuse_cache: bool | None = Nonelogits_to_keep: typing.Union[int, torch.Tensor] = 0**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → MusicFlamingoCausalLMOutputWithPast or tuple(torch.Tensor)
المعاملات
- input_ids (
torch.LongTensorبشكل(batch_size, sequence_length), اختياري) — مؤشرات رموز تسلسل الإدخال في قاموس الكلمات. سيتم تجاهل الحشو افتراضيًا.يمكن الحصول على الفهارس باستخدام AutoTokenizer. راجع PreTrainedTokenizer.encode() و PreTrainedTokenizer.call() للتفاصيل.
- input_features (
torch.Tensorمن الشكل(batch_size, sequence_length, feature_dim)، اختياري) — المصفوفات المقابلة لميزات الصوت المدخلة. يمكن الحصول على ميزات الصوت باستخدامfeature_extractor_class. راجعfeature_extractor_class.__call__للتفاصيل (يستخدم MusicFlamingoProcessorfeature_extractor_classلمعالجة الملفات الصوتية). - input_features_mask (
torch.Tensorمن الشكل(batch_size, feature_sequence_length)) — قناع لتجنب تنفيذ الانتباه على فهارس الحشو. - attention_mask (
torch.Tensorبشكل(batch_size, sequence_length), اختياري) — قناع لتجنب تنفيذ الانتباه على فهارس رموز الحشو. القيم المختارة للقناع هي[0, 1]:- 1 للرموز التي لم تُقنَّع،
- 0 للرموز التي تم إخفاؤها.
- position_ids (
torch.LongTensorبشكل(batch_size, sequence_length), اختياري) — مؤشرات مواضع رموز كل تسلسل إدخال في تضمينات المواضع. يتم اختيارها ضمن النطاق[0, config.n_positions - 1]. - past_key_values (
~cache_utils.Cache, اختياري) — حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي وكتل الانتباه المتقاطع) يمكن استخدامها لتسريع فك الترميز التسلسلي. يتكون هذا عادةً منpast_key_valuesالذي يعيده النموذج في مرحلة سابقة من فك الترميز، عندماuse_cache=Trueأوconfig.use_cache=True.يُسمح فقط بمرجع Cache كمدخل، راجع دليل ذاكرة kv لدينا. إذا لم يتم تمرير
past_key_values، فسيتم تهيئة DynamicCache افتراضياً.سيُخرج النموذج نفس صيغة الكاش التي تُمرَّر كمدخل.
عند استخدام
past_key_values، يُتوقَّع من المستخدم إدخالinput_idsغير المعالجة فقط (تلك التي لم تُقدَّم حالات مفاتيحها وقيمها السابقة إلى هذا النموذج) بأبعاد(batch_size, unprocessed_length)بدلاً من جميعinput_idsبأبعاد(batch_size, sequence_length). - inputs_embeds (
torch.Tensorمن الشكل(batch_size, sequence_length, hidden_size)، اختياري) — اختياريًا، بدلاً من تمريرinput_ids، يمكنك اختيار تمرير تمثيل مضمّن مباشرة. وهذا مفيد إذا كنت ترغب في الحصول على مزيد من التحكم في كيفية تحويل فهارسinput_idsإلى المتجهات المرتبطة بها، مقارنةً بمصفوفة البحث المضمّنة الداخلية للنموذج. - 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، يتم حساب logits لجميعinput_ids(حالة خاصة). لا يُحتاج إلى logits إلا للرمز الأخير في عملية التوليد، ويمكن أن يوفر حسابها لذلك الرمز وحده ذاكرة كبيرة، وهو أمر مهم بشكل ملحوظ للتسلسلات الطويلة أو حجم المفردات الكبير. إذا كانtorch.Tensor، يجب أن يكون بعدًا واحدًا (1D) ويتوافق مع الفهارس التي يجب الاحتفاظ بها في بُعد طول التسلسل. يكون هذا مفيدًا عند استخدام تنسيق المصفوفات المعبأة (packed tensor format) (بعد واحد لكل من الدفعة وطول التسلسل).
يعيد
MusicFlamingoCausalLMOutputWithPast أو tuple(torch.Tensor)
MusicFlamingoCausalLMOutputWithPast أو مجموعة مرتبة من
torch.Tensor (إذا تم تمرير return_dict=False أو عندما يكون config.return_dict=False) وتتضمن عناصر مختلفة
تعتمد على الإعداد (MusicFlamingoConfig) والمدخلات.
تتجاوز طريقة MusicFlamingoForConditionalGeneration الخاصة بالتقديم (forward) الطريقة الخاصة __call__.
على الرغم من أنه يجب تعريف وصفة المرور الأمامي داخل هذه الدالة، إلا أنه ينبغي استدعاء كائن
Moduleبدلاً من هذه الدالة، لأن الكائن يتولى تنفيذ خطوات المعالجة المسبقة والمعالجة اللاحقة، بينما تتجاهل الدالة هذه الخطوات بصمت.
loss (
torch.Tensorof shape(1,), اختياري, يُعاد عند توفيرlabels) — خسارة نمذجة اللغة (لتوقع الرمز التالي).logits (
torch.Tensorمن الشكل(batch_size, sequence_length, config.vocab_size)) — درجات التنبؤ لرأس نمذجة اللغة.past_key_values (
Cache، اختياري، يُعاد عند تمريرuse_cache=Trueأو عند تعيينconfig.use_cache=True) — إنه كائن من نوع Cache.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 على الانتباه، وتُستخدم لحساب المتوسط الموزون في رؤوس الانتباه الذاتي.
audio_hidden_states (
torch.Tensor، اختياري) — حالات المخفية لمشفّر الصوت بعد الإسقاط.