Diffusers documentation
MiniMax Music 3
MiniMax Music 3
MiniMax Music 3 هو نموذج لتوليد الموسيقى ينتج أغاني كاملة تصل مدتها إلى خمس دقائق انطلاقًا من كلمات الأغنية ووصف موسيقي، مع أصوات غنائية معبّرة وهيكل موسيقي ممتد.
النموذج هو هجين من مرحلة توليد ذاتية التراجع ومرحلة انتشار: نموذج لغة عالمي مبني على Qwen3 بحجم 8B يتنبأ برمز صوتي دلالي واحد لكل إطار، بينما يملأ مُفكك عمق صغير سبعة كتل رموز RVQ متبقية، وتُشكّل حالاتهما المخفية المدمجة شرطًا لمحوّل مطابقة تدفق بحجم 2.4B ينتج كامنات Flow-VAE في مقاطع متداخلة. يُحوّل مُفكك بنمط DAC هذه الكامنات إلى صوت ستيريو بتردد 44.1 kHz.
الاستخدام
يتوفر MiniMax Music 3 على شكل خط أنابيب معياري.
import soundfile as sf
import torch
from diffusers import ModularPipeline
pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-Music3")
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda") # or "mps", "xpu", "cpu"
lyrics = """[verse]
Morning light filtering through the pine
Every quiet street is yours and mine
[chorus]
Softly the world begins to breathe"""
prompt = (
"Genre: acoustic pop. BPM: 96. Key: C major. Warm and intimate, building gently into the chorus. "
"Vocals: soft female lead, close and breathy, light stacked harmonies in the chorus. "
"Arrangement: fingerpicked guitar and soft piano; brushed drums and upright bass enter in the chorus."
)
audio = pipe(
prompt=prompt,
lyrics=lyrics,
audio_duration=60.0,
generator=torch.Generator("cuda").manual_seed(7),
output="audios",
)[0]
sf.write("minimax_music3.wav", audio.T, pipe.sampling_rate)تقليل استهلاك الذاكرة
راجع دليل تقليل استخدام الذاكرة لمزيد من التفاصيل حول تقنيات توفير الذاكرة المختلفة.
يتطلب خط الأنابيب الكامل حوالي 23 غيغابايت من ذاكرة الفيديو (VRAM) في وضع bfloat16. مع التفريغ التلقائي إلى وحدة المعالجة المركزية (CPU)، يتم تشغيل عملية التوليد في حوالي 22 غيغابايت من ذاكرة الفيديو المتاحة، بالإضافة إلى ذلك، فإن التفريغ الجماعي لنموذج اللغة يتسع في 8 غيغابايت.
import torch
from diffusers import ComponentsManager, ModularPipeline
from diffusers.hooks.group_offloading import apply_group_offloading
manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda") # or "mps", "xpu", "cpu"
pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-Music3", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)
# Only needed below ~22 GB of free VRAM — slower, but fits in 8 GB.
apply_group_offloading(
pipe.language_model, onload_device=torch.device("cuda"), offload_type="leaf_level", use_stream=True
)نصائح
- يجب أن تكون وسوم الهيكل مثل
[intro]و[verse]و[pre-chorus]و[chorus]و[bridge]و[instrumental]و[solo]و[outro]كلٌّ منها في سطر مستقل داخلlyrics. يتم تجاهل النص الموجود في نفس السطر مع وسم البداية بموجب عقد إدخال النموذج. - يتحكم وصف الموسيقى في الغناء: صف جنس الصوت ونبرته بوضوح (مثلًا “صوت أنثوي دافئ”) وإلا قد ينحرف النموذج نحو موسيقى بدون غناء. للتحكم الدقيق، قسّم الوصف إلى بيانات وصفية عامة (النوع الموسيقي، الإيقاس، المفتاح، التقدم العاطفي)، وتفاصيل الغناء، والترتيب.
audio_durationهو حد أقصى — فقد ينهي نموذج اللغة الأغنية مبكرًا باستخدام رمز إيقاف. تولّد المرحلة التلقائية التوليدية 25 إطارًا لكل ثانية من الصوت، وهي المهيمنة على وقت التشغيل.- مقياس التوجيه الحر من التصنيف في مرحلة مطابقة التدفق هو إعداد موجّه (القيمة المرجعية للاستدلال هي
1.7): استبدله بـ
pipe.update_components(guider=ClassifierFreeGuidance(guidance_scale=...)). - يعيد خط الأنابيب المخرجات الأصلية بجودة 44.1 kHz وصوت ستيريو من مُصنِّع الصوت. يعيد خادم المرجع أيضًا أخذ العينات بمعدل 32 kHz؛ طبّق إعادة أخذ عينات خاصة بك إذا كنت بحاجة إلى ذلك المعدل بالتحديد.
MiniMaxMusic3ModularPipeline
فئة diffusers.MiniMaxMusic3ModularPipeline
< source >( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )
خط أنابيب ModularPipeline لتوليد الموسيقى المشروطة بالكلمات والتعليقات باستخدام MiniMax Music 3.
MiniMaxMusic3Blocks
خط أنابيب معياري لتوليد الموسيقى المشروطة بالكلمات والأوصاف باستخدام MiniMax Music 3. يولّد نموذج اللغة التلقائي Qwen3 رموزًا دلالية وحالاتًا خفية لكل إطار من الكلمات ووصف الموسيقى؛ ثم يحوّل محوّل مطابقة التدفق (flow-matching transformer) الحالات الخفية إلى كامنات Flow-VAE على شكل مقاطع متتالية؛ وأخيرًا يفكّك مُصوِّغ (vocoder) بنمط DAC هذه الكامنات إلى موجة صوتية مجسّمة بمعدل عينة 44.1 kHz.
المكوّنات:
مُقسّم الرموز (Qwen2Tokenizer) نموذج اللغة (Qwen3ForCausalLM) rvq_depth_decoder
(MiniMaxMusic3RVQDepthDecoder) condition_encoder (MiniMaxMusic3ConditionEncoder) transformer
(MiniMaxMusic3Transformer1DModel) scheduler (FlowMatchEulerDiscreteScheduler) guider
(ClassifierFreeGuidance) vocoder (MiniMaxMusic3Vocoder)
المدخلات:
prompt (str):
وصف الموسيقى (النوع، المزاج، الغناء، الآلات الموسيقية، التوزيع).
lyrics (str):
الكلمات التي سيتم غناؤها. يجب أن تكون وسوم الهيكل مثل [verse] أو [chorus] كلٌّ منها في سطر مستقل؛ فأي نص يقع في نفس السطر مع وسم في البداية يُستبعد بموجب عقد المدخلات الخاص بالنقطة المرجعية.
audio_duration (float, اختياري, القيمة الافتراضية 60.0):
الحد الأقصى لطول الصوت المولّد بالثواني. قد يتوقف نموذج اللغة قبل ذلك. يُقيَّد بـ 9000 إطار (ست دقائق).
generator (Generator, اختياري):
مولّد Torch لتوليد حتمي.
num_inference_steps (int, اختياري, القيمة الافتراضية 30):
عدد خطوات Euler المطابقة للتدفق لكل شريحة.
output_type (str, اختياري, القيمة الافتراضية np):
صيغة الإخراج: ‘np’ أو ‘pt’.
المخرجات:
audios (Tensor | ndarray):
الموجة الصوتية المجوّفة (Stereo) المولّدة ذات الشكل (batch, channels, samples) ضمن المدى [-1, 1].
MiniMaxMusic3ConditionEncoder
فئة diffusers.MiniMaxMusic3ConditionEncoder
< source >( condition_hidden_dim: int = 4096num_condition_layers: int = 8out_dim: int = 2048input_sampling_rate: int = 24000input_hop_length: int = 960output_sampling_rate: int = 44100output_hop_length: int = 512 )
يُرجع حالات الإخفاء لكل إطار من مرحلة التوليد الذاتي التتابعي إلى خط الزمن الكامن الخاص بـ Flow-VAE.
تحمل كل إطار مُولَّد num_condition_layers من حالات المخفية بحجم condition_hidden_dim (واحدة من نموذج اللغة وواحدة لكل خطوة في دفتر الرموز المتبقي). يتم مزجها بأوزان softmax المتعلمة، ثم إسقاطها، وإعادة أخذ عينات منها من معدل إطارات نموذج اللغة إلى معدل إطارات الكامنة باستخدام الاستيفاء بأقرب جارٍ.
forward
< source >( hidden_states: Tensor ) → torch.Tensor of shape (batch, latent_length, out_dim)
المعاملات
- hidden_states (
torch.Tensorمن الشكل(batch, frames, num_condition_layers * condition_hidden_dim)) — حالات مخفية مجمعة لكل إطار من المرحلة التوليدية الذاتية.
يعيد
torch.Tensor من الشكل (batch, latent_length, out_dim)
سلسلة الشروط المتماثلة مع الفضاء الكامن.
MiniMaxMusic3RVQDepthDecoder
فئة diffusers.MiniMaxMusic3RVQDepthDecoder
< source >( hidden_size: int = 4096num_layers: int = 4num_attention_heads: int = 16intermediate_size: int = 6144audio_vocab_size: int = 1024num_codebooks: int = 8max_position_embeddings: int = 16 )
النموذج اللغوي المحلي لـ MiniMax Music 3. داخل كل إطار صوتي، يتنبأ بشكل ذاتي التراجع بالكتب الرمزية السبعة المتبقية RVQ (c1..c7) من حالة النموذج اللغوي العالمي المخفية والرمز الدلالي للإطار، ويعرض الحالات المخفية لكل خطوة التي تشترط محول مطابقة التدفق.
كما أنها تمتلك جدول التضمين (embedding table) لدفاترم الشيفرة المتبقية (residual codebooks)، والذي تستخدمه خط المعالجة لتضمين الإطارات الكاملة من أجل حلقة تغذية راجعة لنموذج اللغة العام.
forward
< source >( inputs_embeds: Tensor ) → torch.Tensor of shape (batch, steps, hidden_size)
المعاملات
- inputs_embeds (
torch.Tensorمن الشكل(batch, steps, hidden_size)) — تضمينات تسلسل العمق المُسقطّة: حالة الإخفاء العالمية متبوعةً بالتضمينات المُرمّزة التي تمّ أخذها حتى الآن، حيث يمرّ كلٌّ منها عبرprojection.
يعيد
torch.Tensor من الشكل (batch, steps, hidden_size)
حالات مخفية مُطبَّعة؛ حيث تُغذّي الخطوة الأخيرة رأس كتاب الرموز التالي.
MiniMaxMusic3Vocoder
فئة diffusers.MiniMaxMusic3Vocoder
< source >( latent_channels: int = 128decoder_input_dim: int = 1024decoder_hidden_dim: int = 1536upsampling_ratios: tuple = (8, 8, 4, 2)sampling_rate: int = 44100 )
مفكّك الموجات الصوتية Flow-VAE في MiniMax Music 3 (مفكّك بنمط DAC). يقوم بفكّ ترميز الكمّيات الكامنة المطابقة للتدفق (flow-matched latents) ذات الشكل (batch, latent_channels, length) إلى موجات صوتية مجسّمة (stereo) بمعدل أخذ عينات sampling_rate؛ حيث يتم فكّ ترميز قناتي الصوت كتيّارين مطويّين (folded) بحجم latent_channels // 2.
forward
< source >( latents: Tensor ) → torch.Tensor of shape (batch, 2, samples)