diffusers/v0.43.0/ar/api/pipelines/ace_step.md

ACE-Step 1.5

تم تقديم ACE-Step 1.5 في ACE-Step 1.5: Pushing the Boundaries of Open-Source Music Generation من قبل فريق ACE-Step (ACE Studio و StepFun). وهو نموذج موسيقي أساسي مفتوح المصدر يولّد موسيقى ستيريو بجودة تجارية مع كلمات من أوامر نصية.

يولّد ACE-Step 1.5 صوتًا ستيريو بطول متغير عند 48 كيلوهرتز (من 10 ثوانٍ إلى 10 دقائق) من أوامر نصية وكلمات أغنية اختيارية. يجمع النظام الكامل بين مخطط نموذج لغوي ومولّد Diffusion Transformer (DiT)؛ وتغلّف هذه المسار النصف الخاص بـ DiT في ذلك المكدس، وتتكون من ثلاثة مكونات: AutoencoderOobleck VAE يضغط الموجات الصوتية إلى كامنات ستيريو عند 25 هرتز، ومشفّر نصي مبني على Qwen3 لتكييف الأوامر وكلمات الأغنية، وAceStepTransformer1DModel DiT يعمل في فضاء الكامن الخاص بـ VAE باستخدام مطابقة التدفق.

يدعم النموذج أكثر من 50 لغة للكلمات — بما في ذلك الإنجليزية والصينية واليابانية والكورية والفرنسية والألمانية والإسبانية والإيطالية والبرتغالية والروسية — ويعمل على وحدات معالجة الرسومات المخصصة للمستهلكين (أقل من 4 غيغابايت من ذاكرة الفيديو عند النقل).

تمت مساهمة خط المعالجة هذا من قبل فريق ACE-Step. يمكن العثور على قاعدة الكود الأصلية في ace-step/ACE-Step-1.5.

الأنواع

توفر ACE-Step 1.5 ثلاثة نقاط تحقق (checkpoints) لنموذج DiT تشترك في نفس بنية المحوّل (transformer) لكنها تختلف في سلوك التوجيه (guidance)؛ حيث يقوم خط المعالجة (pipeline) تلقائيًا باكتشاف نقاط التحقق من نوع turbo من إعدادات المحوّل المحمّل، ويتجاهل توجيه CFG لتلك الأوزان المُقطّرة للتوجيه (guidance-distilled weights).

النوع	CFG	الخطوات الافتراضية	القيمة الافتراضية لـ guidance_scale	الافتراضي shift	مستودع HF
turbo (مُقطّر التوجيه)	إيقاف	8	تم تجاهلها	3.0	ACE-Step/acestep-v15-xl-turbo-diffusers
base	on	8	7.0	3.0	ACE-Step/acestep-v15-base
sft	on	8	7.0	3.0	ACE-Step/acestep-v15-sft

تستخدم النموذج الأساسي ونموذج SFT المتعلم null_condition_emb للتوجيه الحر من التصنيف (APG، وليس CFG العادي). غالباً ما يقوم المستخدمون بتجاوز num_inference_steps إلى 30–60 في النموذج الأساسي/SFT للحصول على جودة أعلى.

نصائح

عند إنشاء موجه، ضع في اعتبارك:

• تعمل مدخلات الأوامر الوصفية بشكل أفضل؛ استخدم الصفات لوصف أسلوب الموسيقى والآلات والمزاج والإيقاع.
• يجب أن يصف الأمر الخصائص الموسيقية العامة (مثل "أغنية بوب مرحة مع جيتار كهربائي وطبول").
• يجب أن تكون الكلمات منظمة بوسوم مثل [verse]، [chorus]، [bridge]، وما إلى ذلك.

أثناء الاستدلال:

• num_inference_steps وguidance_scale وshift تعتمد افتراضيًا على القيم المعروضة أعلاه. بالنسبة لنقاط التفتيش turbo، يتم تجاهل guidance_scale > 1.0 مع تحذير لأن التوجيه مُدمج في الأوزان.
• يتحكم معامل audio_duration في مدة الموسيقى المولّدة بالثواني.
• يجب أن يتطابق معامل vocal_language مع لغة الكلمات.
• pipe.sample_rate وpipe.latents_per_second مستمدّان من إعدادات VAE (48000 هرتز و25 إطارًا في الثانية للنقاط الفحصية المنشورة).
• لمهام الصوت إلى الصوت، مرّر src_audio وreference_audio كمصفوفات ستيريو مُسبقة المعالجة عند pipe.sample_rate.
• flash وflash_hub يستخدمان دعم النافذة المنزلقة الأصلية في FlashAttention للانتباه الذاتي في ACE-Step ويتوقعان دفعات نصية غير مملوءة. إذا احتوت الدفعة على تملئة، فاستخدم flash_varlen أو flash_varlen_hub بدلاً من ذلك. الاستدلال على موجه واحد مع padding="longest" يكون غير مملوء عادةً.

import torch
import soundfile as sf
from diffusers import AceStepPipeline

pipe = AceStepPipeline.from_pretrained("ACE-Step/acestep-v15-xl-turbo-diffusers", dtype=torch.bfloat16)
pipe = pipe.to("cuda")  # or "mps", "xpu", "cpu"

audio = pipe(
    prompt="A beautiful piano piece with soft melodies and gentle rhythm",
    lyrics="[verse]\nSoft notes in the morning light\nDancing through the air so bright\n[chorus]\nMusic fills the air tonight\nEvery note feels just right",
    audio_duration=30.0,
).audios

sf.write("output.wav", audio[0].T.cpu().float().numpy(), pipe.sample_rate)

AceStepPipeline[[diffusers.AceStepPipeline]]

diffusers.AceStepPipeline[[diffusers.AceStepPipeline]]

diffusers.AceStepPipeline(vae: AutoencoderOobleck, text_encoder: PreTrainedModel, tokenizer: TokenizersBackend, transformer: AceStepTransformer1DModel, condition_encoder: AceStepConditionEncoder, scheduler: FlowMatchEulerDiscreteScheduler, audio_tokenizer: typing.Optional[diffusers.pipelines.ace_step.modeling_ace_step.AceStepAudioTokenizer] = None, audio_token_detokenizer: typing.Optional[diffusers.pipelines.ace_step.modeling_ace_step.AceStepAudioTokenDetokenizer] = None)

المصدر

المعاملات:

vae (AutoencoderOobleck) : نموذج الترميز التحويلي التبايني (VAE) لتشفير وفك تشفير موجات الصوت إلى تمثيلات كامنة ومنها.

text_encoder (AutoModel) : نموذج ترميز النصوص (مثل Qwen3-Embedding-0.6B) لتشفير أوامر النص والكلمات.

tokenizer (AutoTokenizer) : مُجزِّئ (Tokenizer) لمُشفِّر النص.

transformer (AceStepTransformer1DModel) : نموذج Diffusion Transformer (DiT) لإزالة الضوضاء من البيانات الكامنة للصوت.

condition_encoder (AceStepConditionEncoder) : مُشفِّر شروط يجمع بين تمثيلات النص والكلمات والأصوات للاستخدام في الانتباه المتقاطع.

scheduler (FlowMatchEulerDiscreteScheduler) : مجدول أويلر لمطابقة التدفق. يغذي ACE-Step خطوات الزمن الخاصة بـ DiT ضمن [0, 1]، لذا يتم ضبط المجدول مع num_train_timesteps=1 وshift=1.0 — حيث يقوم خط الأنابيب بحساب جدول سيجما المُزاح / المُسرَّع الخاص به بنفسه ويمرره عبر set_timesteps(sigmas=...).

خط أنابيب لتوليد الموسيقى من النص باستخدام ACE-Step 1.5.

يرث هذا النموذج من DiffusionPipeline. راجع توثيق الفئة الأصلية لمعرفة الطرق العامة المُنفَّذة لجميع خطوط الأنابيب (التنزيل، الحفظ، التشغيل على جهاز معين، إلخ).

تستخدم خط المعالجة مطابقة التدفق مع جدول خطوات زمنية مخصص لعملية الانتشار. يستخدم متغير النموذج turbo 8 خطوات استدلال افتراضيًا.

أنواع المهام المدعومة:

• "text2music": توليد الموسيقى من أوامر نصية وكلمات الأغاني.
• "cover": توليد الصوت من الصوت المصدر / الرموز الدلالية مع نقل طبقة الصوت من الصوت المرجعي.
• "repaint": إعادة توليد جزء من الصوت الموجود مع الحفاظ على الباقي.
• "extract": استخراج مسار صوتي محدد (مثل الغناء أو الطبول) من الصوت.
• "lego": توليد مسار محدد بناءً على السياق الصوتي.
• "complete": إكمال صوت الإدخال بمقاطع إضافية.

call[[diffusers.AceStepPipeline.call]]

__call__(prompt: typing.Union[str, typing.List[str]] = None, lyrics: typing.Union[str, typing.List[str]] = '', audio_duration: float = 60.0, vocal_language: typing.Union[str, typing.List[str]] = 'en', num_inference_steps: int = 8, guidance_scale: float = 7.0, shift: float = 3.0, generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, output_type: typing.Optional[str] = 'pt', return_dict: bool = True, callback: typing.Optional[typing.Callable[[int, int, torch.Tensor], NoneType]] = None, callback_steps: typing.Optional[int] = 1, callback_on_step_end: typing.Optional[typing.Callable[..., dict]] = None, callback_on_step_end_tensor_inputs: typing.List[str] = ('latents',), instruction: typing.Optional[str] = None, max_text_length: int = 256, max_lyric_length: int = 2048, bpm: typing.Optional[int] = None, keyscale: typing.Optional[str] = None, timesignature: typing.Optional[str] = None, task_type: str = 'text2music', track_name: typing.Optional[str] = None, complete_track_classes: typing.Optional[typing.List[str]] = None, src_audio: typing.Optional[torch.Tensor] = None, reference_audio: typing.Optional[torch.Tensor] = None, audio_codes: typing.Union[str, typing.List[str], NoneType] = None, repainting_start: typing.Optional[float] = None, repainting_end: typing.Optional[float] = None, audio_cover_strength: float = 1.0, cfg_interval_start: float = 0.0, cfg_interval_end: float = 1.0, timesteps: typing.Optional[typing.List[float]] = None, attention_kwargs: typing.Optional[dict] = None)

المصدر

المعاملات:

prompt (str أو List[str]، اختياري) : الأمر أو الأوامر الموجِّهة لتوليد الموسيقى. يصف النمط، والنوع، والآلات، وما إلى ذلك.

lyrics (str أو List[str]، اختياري، القيمة الافتراضية "") : نص كلمات الأغنية. يدعم الكلمات المنظمة بوسوم مثل [verse]، [chorus]، وما إلى ذلك.

audio_duration (float، اختياري، القيمة الافتراضية 60.0) : مدة الصوت المولّد بالثواني.

vocal_language (str أو List[str]، اختياري، الافتراضي "en") : رمز اللغة الخاص بالكلمات (مثل "en"، "zh"، "ja").

num_inference_steps (int، اختياري، القيمة الافتراضية 8) : عدد خطوات إزالة الضوضاء. تم تصميم نموذج turbo لـ 8 خطوات.

guidance_scale (float، اختياري، القيمة الافتراضية 7.0) : مقياس التوجيه للتوجيه الحر من التصنيف. تعطّل القيمة 1.0 خاصية CFG.

shift (float، اختياري، القيمة الافتراضية 3.0) : معامل الإزاحة لجدول خطوات الزمن (1.0 أو 2.0 أو 3.0).

generator (torch.Generator أو List[torch.Generator]، اختياري) : مولّد لجعل التوليد حتميًا.

latents (torch.Tensor، اختياري) : ضوضاء كامنات مُولّدة مسبقًا على شكل (batch_size, latent_length, acoustic_dim).

output_type (str، اختياري، القيمة الافتراضية "pt") : صيغة الإخراج. "pt" لمصفوفة PyTorch، "np" لمصفوفة NumPy، "latent" للقيم الكامنة الخام.

return_dict (bool، اختياري، القيمة الافتراضية True) : ما إذا كان يجب إرجاع AudioPipelineOutput أو مجرد tuple.

callback (Callable، اختياري) : دالة تُستدعى كل callback_steps خطوات مع (step, timestep, latents).

callback_steps (int، اختياري، القيمة الافتراضية 1) : تكرار دالة الاستدعاء.

callback_on_step_end (Callable، اختياري) : دالة تُستدعى في نهاية كل خطوة إزالة ضوضاء أثناء الاستدلال. تُستدعى الدالة مع الحُجج التالية: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). سيتضمن callback_kwargs قائمة بجميع المصفوفات كما حددتها callback_on_step_end_tensor_inputs.

callback_on_step_end_tensor_inputs (List، اختياري) : قائمة مدخلات المصفوفات (tensors) لدالة callback_on_step_end. سيتم تمرير المصفوفات المحددة في القائمة كحجة callback_kwargs. لن تتمكن من تضمين سوى المتغيرات المدرجة في خاصية ._callback_tensor_inputs لفئة خط الأنابيب (pipeline) الخاص بك.

instruction (str، اختياري) : نص تعليمات مخصص لمهمة التوليد. إذا لم يُقدَّم، يتم توليده تلقائيًا بناءً على task_type.

max_text_length (int، اختياري، القيمة الافتراضية 256) : الحد الأقصى لطول الرموز لتشفير موجه النص.

max_lyric_length (int، اختياري، القيمة الافتراضية 2048) : الحد الأقصى لطول الرموز لتشفير الكلمات.

bpm (int، اختياري) : BPM (عدد النقرات في الدقيقة) لبيانات الموسيقى الوصفية. إذا كانت None، فإن النموذج يقدّرها.

keyscale (str, اختياري) : المفتاح الموسيقي (مثل "C major"، "A minor"). إذا كان None، فإن النموذج يقدّره.

timesignature (str، اختياري) : توقيعة الزمن (مثلًا "4" لـ 4/4، "3" لـ 3/4). إذا كانت None، فإن النموذج يقدّرها.

task_type (str، اختياري، الافتراضي "text2music") : نوع مهمة التوليد. أحد "text2music"، "cover"، "repaint"، "extract"، "lego"، "complete".

track_name (str, اختياري) : اسم المسار لمهام "extract" أو "lego" (مثلًا "vocals"، "drums").

complete_track_classes (List[str]، اختياري) : فئات التتبع للمهمة "complete".

src_audio (torch.Tensor، اختياري) : متجه الصوت المصدر ذو الشكل [channels, samples] عند تردد 48kHz لمهام تحويل الصوت إلى صوت (repaint, lego, cover, extract, complete). يتم ترميز الصوت عبر VAE لإنتاج كامنات المصدر.

reference_audio (torch.Tensor, اختياري) : مرجع صوتي على شكل [channels, samples] بمعدل 48 هرتز لتكييف النبرة. يُستخدم لاستخراج خصائص النبرة من أجل نقل الأسلوب.

audio_codes (str أو List[str]، اختياري) : نصوص رموز الدلالات الصوتية (مثل "<|audio_code_123|><|audio_code_456|>..."). عند تقديمها، يتم التبديل تلقائيًا إلى وضع "cover" وتقوم وحدات ACE-Step المسجلة لتجزئة الصوت وفك تجزئته بتحويل رموز 5 هرتز إلى شروط صوتية بتردد 25 هرتز.

repainting_start (float, اختياري) : وقت البدء بالثواني لمنطقة إعادة الرسم (لمهام "repaint" و"lego").

repainting_end (float, اختياري) : وقت النهاية بالثواني لمنطقة إعادة الرسم. استخدم -1 أو None حتى النهاية.

audio_cover_strength (float، اختياري، القيمة الافتراضية 1.0) : قوة دمج تغطية الصوت (من 0.0 إلى 1.0). عندما تكون القيمة < 1.0، يتم دمج المخرجات المشروطة بالتغطية والمخرجات المشروطة بالنص فقط. تنتج القيم المنخفضة تأثيرًا أكبر لنقل الأسلوب.

cfg_interval_start (float، اختياري، القيمة الافتراضية 0.0) : نسبة البداية (0.0-1.0) لنطاق خطوة الزمن التي يُطبَّق فيها CFG.

cfg_interval_end (float، اختياري، القيمة الافتراضية 1.0) : النسبة النهائية (0.0-1.0) لنطاق خطوة الزمن التي يُطبَّق فيها CFG.

timesteps (List[float]، اختياري) : جدول خطوات زمنية مخصص. إذا تم تقديمه، يتجاوز num_inference_steps وshift.

attention_kwargs (dict، اختياري) : قاموس kwargs يُمرَّر إلى AttentionProcessor. يُستخدم لتمرير مقياس LoRA عبر {"scale": float}.

يعيد: AudioPipelineOutput أو tuple

إذا كان return_dict هو True، يُعاد AudioPipelineOutput، وإلا يُعاد tuple يحتوي على الصوت المولّد.

دالة الاستدعاء call لخط الأنابيب pipeline لتوليد الموسيقى.

أمثلة:

>>> import torch
>>> import soundfile as sf
>>> from diffusers import AceStepPipeline

>>> pipe = AceStepPipeline.from_pretrained(
...     "ACE-Step/acestep-v15-xl-turbo-diffusers", torch_dtype=torch.bfloat16
... )
>>> pipe = pipe.to("cuda")

>>> # Text-to-music generation with metadata
>>> audio = pipe(
...     prompt="A beautiful piano piece with soft melodies",
...     lyrics="[verse]\nSoft notes in the morning light\n[chorus]\nMusic fills the air tonight",
...     audio_duration=30.0,
...     num_inference_steps=8,
...     bpm=120,
...     keyscale="C major",
...     timesignature="4",
... ).audios

>>> # Save the generated audio
>>> sf.write("output.wav", audio[0, 0].cpu().numpy(), 48000)

>>> # Repaint task: regenerate a section of existing stereo 48kHz audio
>>> src_audio, sr = sf.read("input.wav")
>>> src_audio = torch.from_numpy(src_audio).float().T
>>> audio = pipe(
...     prompt="Epic rock guitar solo",
...     lyrics="",
...     task_type="repaint",
...     src_audio=src_audio,
...     repainting_start=10.0,
...     repainting_end=20.0,
... ).audios

>>> # Cover task with reference audio for timbre transfer
>>> ref_audio, sr = sf.read("reference.wav")
>>> ref_audio = torch.from_numpy(ref_audio).float().T
>>> audio = pipe(
...     prompt="Pop song with bright vocals",
...     lyrics="[verse]\nHello world",
...     task_type="cover",
...     reference_audio=ref_audio,
...     audio_cover_strength=0.8,
... ).audios

check_inputs[[diffusers.AceStepPipeline.check_inputs]]

check_inputs(prompt: typing.Union[str, typing.List[str]], lyrics: typing.Union[str, typing.List[str]], task_type: str, num_inference_steps: int, guidance_scale: float, shift: float, audio_cover_strength: float, cfg_interval_start: float, cfg_interval_end: float, repainting_start: typing.Optional[float], repainting_end: typing.Optional[float])

المصدر

تحقّق من الحجج الموجهة للمستخدم قبل بدء تخصيص مصفوفات الضوضاء.

encode_prompt[[diffusers.AceStepPipeline.encode_prompt]]

encode_prompt(prompt: typing.Union[str, typing.List[str]], lyrics: typing.Union[str, typing.List[str]], device: device, vocal_language: typing.Union[str, typing.List[str]] = 'en', audio_duration: float = 60.0, instruction: typing.Optional[str] = None, bpm: typing.Optional[int] = None, keyscale: typing.Optional[str] = None, timesignature: typing.Optional[str] = None, max_text_length: int = 256, max_lyric_length: int = 2048)

المصدر

المعاملات:

prompt (str أو List[str]) : وصف نصي (أو أوصاف نصية) للموسيقى.

lyrics (str أو List[str]) : نصوص الأغنية.

device (torch.device) : جهاز المصفوفات.

vocal_language (str أو List[str]، اختياري، الافتراضي "en") : رموز اللغة للأغاني.

audio_duration (float، اختياري، القيمة الافتراضية 60.0) : مدة الصوت بالثواني.

instruction (str، اختياري) : نص التعليمات للتوليد.

bpm (int، اختياري) : BPM (عدد النقرات في الدقيقة) لبيانات الوصف.

keyscale (str، اختياري) : المفتاح الموسيقي (مثل "C major").

timesignature (str، اختياري) : توقيعة الزمن (مثل "4" لـ 4/4).

max_text_length (int، اختياري، القيمة الافتراضية 256) : الحد الأقصى لطول الرموز (tokens) للموجّهات النصية.

max_lyric_length (int، اختياري، القيمة الافتراضية 2048) : الحد الأقصى لطول الرموز للأغاني.

يعيد:

مجموعة (Tuple) من (text_hidden_states, text_attention_mask, lyric_hidden_states, lyric_attention_mask).

ترميز موجهات النص والكلمات إلى تمثيلات متجهة.

تُرمَّز موجهات النص عبر نموذج مُرمِّز النص الكامل لإنتاج حالات خفية سياقية. أما كلمات الأغاني فتُمرَّر فقط عبر طبقة التضمين في مُرمِّز النص (استعلام الرموز)، لأن مُرمِّز الكلمات في مُرمِّز الشروط يتولى الترميز السياقي.

prepare_latents[[diffusers.AceStepPipeline.prepare_latents]]

prepare_latents(batch_size: int, audio_duration: float, dtype: dtype, device: device, generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None)

المصدر

المعاملات:

batch_size (int) : عدد العينات التي سيتم توليدها.

audio_duration (float) : مدة الصوت بالثواني.

dtype (torch.dtype) : نوع البيانات للكائنات الكامنة.

device (torch.device) : الجهاز الخاص بالمتغيرات الكامنة.

generator (torch.Generator أو List[torch.Generator]، اختياري) : مولّد(ات) الأرقام العشوائية.

latents (torch.Tensor، اختياري) : كامنات مُولّدة مسبقًا.

يعيد:

متغيرات ضوضاء ذات شكل (batch_size, latent_length, acoustic_dim).

جهّز كامنات الضوضاء الأولية لعملية مطابقة التدفق.

prepare_reference_audio_latents[[diffusers.AceStepPipeline.prepare_reference_audio_latents]]

prepare_reference_audio_latents(reference_audio: Tensor, batch_size: int, device: device, dtype: dtype)

المصدر

المعاملات:

reference_audio (torch.Tensor) : متجه صوت مرجعي على شكل [channels, samples] بمعدل عينة self.sample_rate.

batch_size (int) : حجم الدفعة.

device (torch.device) : الجهاز المستهدف.

dtype (torch.dtype) : نوع البيانات المستهدف.

يعيد:

مجموعة (Tuple) من (refer_audio_acoustic, refer_audio_order_mask).

معالجة الصوت المرجعي إلى كامنات صوتية لمشفّر النبرة.

يتم تكرار الصوت المرجعي/قصّه ليصبح 30 ثانية (3 مقاطع من 10 ثوانٍ لكلٍّ من البداية والوسط والنهاية)، ثم يُرمَّز عبر VAE، وبعد ذلك يُحوَّل لمُرمِّز النبرة.

prepare_src_latents[[diffusers.AceStepPipeline.prepare_src_latents]]

prepare_src_latents(device: device, dtype: dtype, batch_size: int = 1, src_audio: typing.Optional[torch.Tensor] = None, audio_codes: typing.Union[str, typing.List[str], NoneType] = None, latent_length: typing.Optional[int] = None, task_type: str = 'text2music')

المصدر

المعاملات:

src_audio (torch.Tensor، اختياري) : مُتجه الصوت المصدر ذو الشكل [channels, samples] عند self.sample_rate.

audio_codes (str أو List[str]، اختياري) : نصوص رموز الدلالات الصوتية.

latent_length (int, اختياري) : الطول الكامن المستهدف عند عدم تقديم صوت مصدر أو رموز صوت.

device (torch.device) : الجهاز المستهدف.

dtype (torch.dtype) : نوع البيانات المستهدف.

batch_size (int) : حجم الدفعة.

task_type (str) : نوع المهمة الحالي.

يعيد:

مجموعة مرتبة من (src_latents, latent_length) حيث يكون شكل src_latents هو [batch, T, D].

جهّز الكمونيات المصدرية لمهام النص إلى الموسيقى والصوت إلى الصوت.