Diffusers documentation
Stable Audio 3
Stable Audio 3
نموذج Stable Audio 3 (SA3) هو نموذج لتحويل النص إلى صوت من Stability AI يولّد صوتًا ستيريو عالي الجودة بمعدل 44.1 kHz. يستخدم DiT من نوع rectified-flow مشروطًا بإشارتين:
- النص — يُرمَّز بواسطة مُرمِّز T5Gemma ثابت ويُحقن عبر الانتباه المتقاطع.
- المدة — قيمة عشرية (بالثواني) تُضمَّن بواسطة StableAudio3DurationEmbedder وتُستخدم كمتجه تكييف عام لتطبيع الطبقات التكيفية.
يتم فك ترميز الصوت بواسطة مُرمِّز الترميز التلقائي SAME (المُرمِّز الموسيقي المُحاذاة دلاليًا)، AutoencoderSAME.
تستخدم كلا نقطتي التفتيش FlowMatchEulerDiscreteScheduler مع جدول سيجما موحّد على مقياس log-SNR، ولا يختلفان إلا في stochastic_sampling وعدد الخطوات الافتراضي:
| نقطة التفتيش | diffusion_objective | stochastic_sampling | num_inference_steps |
|---|---|---|---|
stable-audio-3-medium-base | rectified_flow | False (أويلر الحتمي) | 100 (غير مُقطَّرة) |
stable-audio-3-medium (مُقطَّر) | rf_denoiser | True (إعادة الضوضاء بنظام التنس الطاولة) | 8 (مُقطَّر على 8 خطوات) |
يتم تضمين إعدادات المجدول الصحيحة في كل نقطة تحقق محوّلة، لذا فإن num_inference_steps يتخذ القيمة الصحيحة افتراضيًا عندما تتركه غير مضبوط. مرّره فقط لتجاوز القيمة الافتراضية.
قاعدة الكود الأصلية: Stability-AI/stable-audio-3.
تحويل نقاط التفتيش الأصلية
نقاط التفتيش الخاصة بـ Stability AI غير منشورة بتنسيق diffusers، لذا قم بتحويلها محليًا. يقوم السكربت بتنزيل model_config.json الخاص بنقطة التفتيش واختيار المجدول من diffusion_objective الخاص بها:
python scripts/convert_stable_audio_3_to_diffusers.py \ --checkpoint_path stabilityai/stable-audio-3-medium-base \ --text_encoder_repo google/t5gemma-b-b-ul2 \ --output_dir /tmp/sa3-diffusers-euler \ --dtype float32
stable-audio-3-medium-baseمستودع مقيّد. نفّذhf auth loginبحساب لديه صلاحية الوصول قبل التحويل، وإلا سيفشل التنزيل برمز 401.
مثال على الاستخدام
حمّل نقطة التحويل المحوّلة من مجلد الإخراج المحلي الخاص بها (ثبّت soundfile باستخدام pip install soundfile):
import torch
import soundfile as sf
from diffusers import StableAudio3Pipeline
pipe = StableAudio3Pipeline.from_pretrained("/tmp/sa3-diffusers-euler", torch_dtype=torch.float32)
pipe = pipe.to("cuda") # or "mps", "xpu", "cpu"
generator = torch.Generator("cuda").manual_seed(0)
audio = pipe(
"A gentle piano melody with soft strings in a concert hall",
duration=10.0, # seconds; latent length is computed automatically
generator=generator,
).audios
sf.write("sa3_output.wav", audio[0].T.cpu().float().numpy(), samplerate=44100)يُسجَّل خط الأنابيب أيضًا مع AutoPipelineForText2Audio، والذي يحلّ نقطة التفتيش تلقائيًا إلى StableAudio3Pipeline:
from diffusers import AutoPipelineForText2Audio
pipe = AutoPipelineForText2Audio.from_pretrained("/tmp/sa3-diffusers-euler", torch_dtype=torch.float32)تستخدم الأمثلة مسارًا محليًا لأن
stabilityai/stable-audio-3-mediumوstable-audio-3-medium-baseلم تُنشر بعد بصيغة diffusers (فإن التحميل عبر معرف المستودع يعيد خطأ 404). بمجرد النشر، يعمل معرف المستودع بدلاً من المسار المحلي.
نصائح
- استخدم
torch.float32على المعالج المركزي (CPU) أو وحدة معالجة الإشارات (MPS) (Apple Silicon) — فاستخدامtorch.float16على MPS ينتج ضوضاء. - النموذج المُصغَّر (
stable-audio-3-medium) هو مُصغَّر خصوميًا — حيث تكون التوجيهات مدمجة في الأوزان. اتركguidance_scale=1.0(القيمة الافتراضية) ولا تمررnegative_promptلذلك نقطة الفحص؛ فكلاهما يؤدي وظيفة مفيدة فقط لنقطة الفحص غير المُصغَّرةstable-audio-3-medium-base. silence_padding_duration(الافتراضي0.0) يضيف مساحة صامتة في نهاية تسلسل الكمون. اتركه عند0.0ما لم يكن النموذج مدرَّبًا على إخفاء تلك الحشوة — وإلا فإن الإطارات الإضافية تستنزف طاقة الإخراج ويصبح الناتج هادئًا.- اضبط
num_waveforms_per_prompt > 1لتوليد مقاطع متعددة لكل موجه.
StableAudio3Pipeline
فئة diffusers.StableAudio3Pipeline
< source >( vae: AutoencoderSAMEtext_encoder: T5GemmaEncoderModeltokenizer: GemmaTokenizerduration_embedder: StableAudio3DurationEmbeddertransformer: StableAudio3DiTModelscheduler: FlowMatchEulerDiscreteScheduler )
المعاملات
- vae ([AutoencoderSAME]) — شيفر-فكّ شبيه (autoencoder) من نوع SAME يُستخدم لتشفير وفكّ تشفير الكامنات الصوتية.
- text_encoder ([~transformers.T5GemmaEncoderModel]) —
مُشفِّر نص T5Gemma مجمّد (
google/t5gemma-b-b-ul2). - tokenizer ([~transformers.GemmaTokenizerFast]) — مُقسِّم (Tokenizer) لمُشفِّر النص.
- duration_embedder ([StableAudio3DurationEmbedder]) —
يُحوّل
durationبالثواني إلى متجه تكييف عام لـ AdaLN في كل كتلة DiT. - transformer ([StableAudio3DiTModel]) — نموذج DiT للتنبؤ بالسرعة في التدفق المُصحَّح.
- scheduler ([FlowMatchEulerDiscreteScheduler]) — المجدول لحلقة إزالة الضوضاء التكرارية. يستخدم نقطة التفتيش الإنتاجية (المُقطَّرة) SA3 Medium stochastic_sampling=True لخطوات ping-pong عشوائية عددها 8 بالضبط؛ بينما تستخدم نقطة التفتيش الأساسية غير المُقطَّرة stochastic_sampling=False لحوالي 100 خطوة Euler حتمية.
خط أنابيب لتوليد الصوت من النص باستخدام Stable Audio 3.
يستخدم SA3 نموذج DiT مُقطّر لتدفق مُصحح مع أخذ عينات بنظام ping-pong. لا حاجة إلى التوجيه بدون مُصنّف (guidance_scale / negative_prompt) للنقطة الفاحصة المُقطّرة (اترك guidance_scale=1.0، وهو الافتراضي)، لكنه ذو معنى للنقطة الفاحصة غير المُقطّرة stable-audio-3-medium-base.
يرث هذا النموذج من [DiffusionPipeline]. راجع توثيق الفئة الأصلية لمعرفة الطرق العامة المُنفَّذة لجميع خطوط الأنابيب.
__call__
< source >( prompt: typing.Union[str, typing.List[str], NoneType] = Noneduration: float = 10.0num_inference_steps: typing.Optional[int] = Nonelogsnr_min: float = -6.2logsnr_max: float = 2.0silence_padding_duration: float = 0.0guidance_scale: float = 1.0negative_prompt: typing.Union[str, typing.List[str], NoneType] = Nonenum_waveforms_per_prompt: int = 1generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_encoder_attention_mask: typing.Optional[torch.LongTensor] = Nonereturn_dict: bool = Truecallback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], dict]] = Nonecallback_on_step_end_tensor_inputs: typing.List[str] = ['latents']output_type: str = 'pt' ) → [~pipelines.AudioPipelineOutput] or tuple
المعاملات
- prompt (str أو list[str]، اختياري) —
نص أو نصوص الأوامر. مرّر
prompt_embedsبدلاً من ذلك لتخطي الترميز الشيفري والتشفير. - duration (float، القيمة الافتراضية 10.0) — المدة المطلوبة للمخرجات بالثواني.
- num_inference_steps (int، اختياري) —
عدد خطوات إزالة الضوضاء. عند تعيين
None(الافتراضي)، يتم اختيار عدد الخطوات من إعداد stochastic_sampling في المجدول: 8 عند True (نقطة الحفظ المُقطّرة بنمط ping-pong) و100 عند False (نقطة الحفظ الأساسية غير المُقطّرة). مرّر قيمة صريحة للتجاوز. - logsnr_min (float، القيمة الافتراضية -6.2) — أدنى قيمة لـ log-SNR في جدول الضجيج — يتوافق مع بداية الجدول ذات الضجيج العالي.
- logsnr_max (float، القيمة الافتراضية 2.0) — القيمة القصوى لـ log-SNR في جدول الضوضاء — يتوافق مع الطرف منخفض الضوضاء من الجدول.
- silence_padding_duration (float، القيمة الافتراضية 0.0) — ثوانٍ إضافية من السياق الكامن (latent) يتم توليدها تتجاوز المحتوى المستهدف، مما يمنح النموذج مساحة كافية عند الحدود؛ يتم تقليم المخرجات مرة أخرى إلى duration. القيمة الافتراضية هي 0.0 (معطّل). قم بزيادة القيمة فقط إذا تم تدريب/تقطير النموذج (distilled) لإخفاء هذا الحشو — وإلا فإن الإطارات الإضافية ستستنزف طاقة المخرجات.
- guidance_scale (float، القيمة الافتراضية 1.0) —
مقياس التوجيه الحر من المصنّف. تعطيل التوجيه عند
1.0(وهي القيمة الافتراضية، والقيمة الوحيدة المعقولة لنقطة الفحص المُقطّرة SA3 Medium، حيث يكون CFG مدمجًا في الأوزان). القيم> 1.0ذات معنى لنقطة الفحص غير المُقطّرةstable-audio-3-medium-base؛ فالقيم الأعلى تتبع الموجّه عن قرب أكبر على حساب التنوع. - negative_prompt (str أو list[str]، اختياري) —
موجّه أو موجّهات تصف ما يجب تجنّبه عند
guidance_scale > 1.0. الافتراضي هو نص فارغ (غير مشروط) عندguidance_scale > 1.0إذا لم يُقدَّم هذا ولا negative_prompt_embeds. يُتجاهل عندguidance_scale <= 1.0. - num_waveforms_per_prompt (int، القيمة الافتراضية 1) — عدد الموجات الصوتية التي سيتم توليدها لكل موجه.
- generator (torch.Generator أو list[torch.Generator]، اختياري) — للتوليد الحتمي وإعادة الضوضاء القابلة للتكرار في حلقة ping-pong.
- latents (torch.Tensor، اختياري) —
كائنات latents ابتدائية مُولّدة مسبقًا. إذا كانت
Noneيتم أخذ عينة من كائن Gaussian جديد. - prompt_embeds (torch.Tensor، اختياري) —
تضمينات نصية محسوبة مسبقًا
(batch, seq_len, 768). - encoder_attention_mask (torch.LongTensor، اختياري) — قناع منطقي للتضمينات المحسوبة مسبقًا.
- negative_prompt_embeds (torch.Tensor، اختياري) — تضمينات نصية سالبة محسوبة مسبقًا، كبديل عن negative_prompt.
- negative_encoder_attention_mask (torch.LongTensor، اختياري) — قناع منطقي للتضمينات السلبية المحسوبة مسبقًا.
- return_dict (bool، القيمة الافتراضية True) — إرجاع AudioPipelineOutput أو tuple عادي.
- callback_on_step_end (Callable، اختياري) — يُستدعى في نهاية كل خطوة إزالة ضوضاء مع (self, step_idx, timestep, callback_kwargs)، حيث يتضمن callback_kwargs المصفوفات المدرجة في callback_on_step_end_tensor_inputs. يجب أن يعيد قاموسًا يحتوي على المصفوفات (المعدّلة اختياريًا) لاستخدامها في بقية الحلقة.
- callback_on_step_end_tensor_inputs (list[str]، القيمة الافتراضية [“latents”]) — المصفوفات التي تُمرَّر إلى callback_on_step_end. يجب أن تكون مجموعة فرعية من self._callback_tensor_inputs.
- output_type (str، الافتراضي
"pt") —"pt"لمصفوفة PyTorch، أو"np"لمصفوفة NumPy، أو"latent"لتخطي فك الترميز وإرجاع القيم الكامنة الخام.
يعيد
[~pipelines.AudioPipelineOutput] أو tuple
.audios هو متجه / مصفوفة بأبعاد (batch * num_waveforms_per_prompt, audio_channels, samples).
توليد صوت من نص.
أمثلة:
>>> import torch
>>> import soundfile as sf
>>> from diffusers import StableAudio3Pipeline
>>> pipe = StableAudio3Pipeline.from_pretrained("stabilityai/stable-audio-3-medium", torch_dtype=torch.float16)
>>> pipe = pipe.to("cuda")
>>> generator = torch.Generator("cuda").manual_seed(0)
>>> audio = pipe(
... "A gentle piano melody with soft strings in a concert hall",
... duration=10.0,
... generator=generator,
... ).audios
>>> sf.write("output.wav", audio[0].T.cpu().float().numpy(), samplerate=pipe.vae.config.sampling_rate)encode_duration
< source >( duration: floatdevice: devicenum_waveforms_per_prompt: intbatch_size: int )
Embed قيمة المدة في متجه الشروط العام.
encode_prompt
< source >( prompt: typing.Union[str, typing.List[str], NoneType]device: devicenum_waveforms_per_prompt: intprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = None )
المعاملات
- prompt — نص موجه أو قائمة من الموجهات. يتم تجاهله عند توفير
prompt_embeds. - device — الجهاز المستهدف.
- num_waveforms_per_prompt — عدد موجات الإخراج التي سيتم توليدها لكل موجه؛ حيث يتم تكرار متجهات الشرط (conditioning tensors) وفقاً لذلك.
- prompt_embeds — تمثيلات نصية محسوبة مسبقًا
(batch, seq_len, hidden_size). - encoder_attention_mask — قناع منطقي
(batch, seq_len)للتضمينات المحسوبة مسبقًا؛1= رمز حقيقي،0= حشو.
ترميز موجهات النص إلى متجهات شروط الانتباه المتقاطع.
prepare_cross_attention
< source >( prompt_embeds: Tensorencoder_attention_mask: Tensorglobal_hidden_states: Tensor )
قم ببناء سياق الانتباه المتقاطع (cross-attention context) عن طريق إضافة تضمين المدة (duration embedding) كرمز إضافي.
يوجّه SA3 مُشكّل seconds_total إلى كلا المدخل العام (AdaLN) وسياق الانتباه المتقاطع (cross_attention_cond_ids = ["prompt", "seconds_total"]). يتم دمج تضمين المدة بعد رموز النص، ويُمدَّد قناع الانتباه بإدخال صالح واحد.
StableAudio3InpaintPipeline
فئة diffusers.StableAudio3InpaintPipeline
< source >( vae: AutoencoderSAMEtext_encoder: T5GemmaEncoderModeltokenizer: GemmaTokenizerduration_embedder: StableAudio3DurationEmbeddertransformer: StableAudio3DiTModelscheduler: FlowMatchEulerDiscreteScheduler )
المعاملات
- vae ([AutoencoderSAME]) — شيفر-فكّ شبيه (autoencoder) من نوع SAME يُستخدم لتشفير وفكّ تشفير الكامنات الصوتية.
- text_encoder ([~transformers.T5GemmaEncoderModel]) —
مُشفِّر نص T5Gemma مجمّد (
google/t5gemma-b-b-ul2). - tokenizer ([~transformers.GemmaTokenizerFast]) — مُقسِّم (Tokenizer) لمُشفِّر النص.
- duration_embedder ([StableAudio3DurationEmbedder]) —
يُحوّل
durationبالثواني إلى متجه تكييف عام لـ AdaLN في كل كتلة DiT. - transformer ([StableAudio3DiTModel]) — نموذج DiT للتنبؤ بالسرعة في التدفق المُصحَّح.
- scheduler ([FlowMatchEulerDiscreteScheduler]) — المجدول لحلقة إزالة الضوضاء التكرارية. يستخدم نقطة التفتيش الإنتاجية (المُقطَّرة) SA3 Medium stochastic_sampling=True لخطوات ping-pong عشوائية عددها 8 بالضبط؛ بينما تستخدم نقطة التفتيش الأساسية غير المُقطَّرة stochastic_sampling=False لحوالي 100 خطوة Euler حتمية.
خط أنابيب معالجة الصوت (Inpainting) لنموذج Stable Audio 3.
Shares its text-to-audio logic with [StableAudio3Pipeline] (kept in sync via # Copied from). When audio and mask are provided, encodes the reference audio with the frozen SAME encoder and injects masked_latent ∥ mask as local-additive conditioning into each DiT block via the transformer’s local_add_cond pathway
(to_local_embed).
توقيع الاستدعاء الموسّع (انظر __call__):
audio (torch.Tensor من الشكل (batch, channels, samples)):
موجة الصوت المرجعية عند vae.config.sampling_rate هرتز.
mask (torch.Tensor من الشكل (batch, 1, latent_length)):
قناع ثنائي لكل إطار في الفضاء الكامن. 1 = الحفاظ على الصوت الأصلي؛ 0 = المنطقة التي سيتم استكمالها.
__call__
< source >( prompt: typing.Union[str, typing.List[str], NoneType] = Noneduration: float = 10.0audio: typing.Optional[torch.Tensor] = Nonemask: typing.Optional[torch.Tensor] = Nonemask_start_seconds: typing.Union[float, typing.List[float], NoneType] = Nonemask_end_seconds: typing.Union[float, typing.List[float], NoneType] = Nonenum_inference_steps: typing.Optional[int] = Nonelogsnr_min: float = -6.2logsnr_max: float = 2.0silence_padding_duration: float = 0.0num_waveforms_per_prompt: int = 1generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = Nonereturn_dict: bool = Truecallback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], dict]] = Nonecallback_on_step_end_tensor_inputs: typing.List[str] = ['latents']output_type: str = 'pt' )
المعاملات
- prompt (str أو list[str]، اختياري) — نص أو نصوص الأوامر.
- duration (float، القيمة الافتراضية 10.0) — مدة الإخراج بالثواني. يجب أن تتطابق مع الصوت المرجعي.
- audio (torch.Tensor، اختياري) —
موجة مرجعية
(batch, channels, samples)بمعدلvae.config.sampling_rateهرتز. مطلوب لملء النواقص (inpainting). - mask (torch.Tensor, optional) —
قناع في فضاء الكمون لكل إطار
(batch, 1, L)حيث 0 = منطقة إعادة الرسم، و1 = الحفظ. يجب تقديمmaskأوmask_start_seconds/mask_end_seconds. - mask_start_seconds (float أو list[float]، اختياري) — وقت(أوقات) بداية منطقة inpaint بالثواني.
- mask_end_seconds (float أو list[float]، اختياري) —
وقت(أوقات) نهاية منطقة inpaint (يجب أن يقترن مع
mask_start_seconds). - num_inference_steps (int، اختياري) —
عدد خطوات إزالة الضوضاء. عند تعيين
None(الافتراضي)، يتم اختيار عدد الخطوات من إعداد stochastic_sampling الخاص بمجدول التنفيذ، بما يتوافق مع [StableAudio3Pipeline]. - logsnr_min (float، القيمة الافتراضية -6.2) — أدنى قيمة لـ log-SNR في جدول الضجيج — يتوافق مع بداية الجدول ذات الضجيج العالي.
- logsnr_max (float، القيمة الافتراضية 2.0) — القيمة القصوى لـ log-SNR في جدول الضوضاء — يتوافق مع الطرف منخفض الضوضاء من الجدول.
- silence_padding_duration (float، القيمة الافتراضية 0.0) — مساحة إضافية في الكامن بعد المحتوى المستهدف.
- num_waveforms_per_prompt (int، القيمة الافتراضية 1) — عدد الموجات لكل موجه.
- generator — مولّد الأرقام العشوائية (RNG) لضمان قابلية التكرار.
- latents — ضوضاء بداية مُولّدة مسبقًا (
None→ عيّنة جديدة). - prompt_embeds — تمثيلات نصية محسوبة مسبقًا.
- encoder_attention_mask — قناع للتضمينات المحسوبة مسبقًا.
- return_dict (bool، القيمة الافتراضية True) — إرجاع AudioPipelineOutput أو tuple.
- callback_on_step_end (Callable، اختياري) — يُستدعى في نهاية كل خطوة إزالة ضوضاء مع (self, step_idx, timestep, callback_kwargs). يجب أن يعيد قاموسًا يحتوي على المصفوفات (المعدّلة اختياريًا) لاستخدامها في بقية الحلقة.
- callback_on_step_end_tensor_inputs (list[str]، القيمة الافتراضية [“latents”]) — المصفوفات التي تُمرَّر إلى callback_on_step_end. يجب أن تكون مجموعة فرعية من self._callback_tensor_inputs.
- output_type (str، الافتراضي
"pt") —"pt"/"np"/"latent".
إنشاء صوت مُعالَج مشروط على موجه نصي ومرجع.
أمثلة:
>>> import torch
>>> import soundfile as sf
>>> import torchaudio
>>> from diffusers import StableAudio3InpaintPipeline
>>> pipe = StableAudio3InpaintPipeline.from_pretrained(
... "stabilityai/stable-audio-3-medium", torch_dtype=torch.float16
... )
>>> pipe = pipe.to("cuda")
>>> audio, sr = torchaudio.load("reference.wav")
>>> audio = torchaudio.functional.resample(audio, sr, pipe.vae.config.sampling_rate).unsqueeze(0).to("cuda")
>>> generator = torch.Generator("cuda").manual_seed(0)
>>> audio = pipe(
... "A gentle piano melody with soft strings in a concert hall",
... duration=10.0,
... audio=audio,
... mask_start_seconds=4.0,
... mask_end_seconds=6.0,
... generator=generator,
... ).audios
>>> sf.write("output.wav", audio[0].T.cpu().float().numpy(), samplerate=pipe.vae.config.sampling_rate)encode_duration
< source >( duration: floatdevice: devicenum_waveforms_per_prompt: intbatch_size: int )
Embed قيمة المدة في متجه الشروط العام.
encode_prompt
< source >( prompt: typing.Union[str, typing.List[str], NoneType]device: devicenum_waveforms_per_prompt: intprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = None )
المعاملات
- prompt — نص موجه أو قائمة من الموجهات. يتم تجاهله عند توفير
prompt_embeds. - device — الجهاز المستهدف.
- num_waveforms_per_prompt — عدد موجات الإخراج التي سيتم توليدها لكل موجه؛ حيث يتم تكرار متجهات الشرط (conditioning tensors) وفقاً لذلك.
- prompt_embeds — تمثيلات نصية محسوبة مسبقًا
(batch, seq_len, hidden_size). - encoder_attention_mask — قناع منطقي
(batch, seq_len)للتضمينات المحسوبة مسبقًا؛1= رمز حقيقي،0= حشو.
ترميز موجهات النص إلى متجهات شروط الانتباه المتقاطع.
prepare_cross_attention
< source >( prompt_embeds: Tensorencoder_attention_mask: Tensorglobal_hidden_states: Tensor )
قم ببناء سياق الانتباه المتقاطع (cross-attention context) عن طريق إضافة تضمين المدة (duration embedding) كرمز إضافي.
يوجّه SA3 مُشكّل seconds_total إلى كلا المدخل العام (AdaLN) وسياق الانتباه المتقاطع (cross_attention_cond_ids = ["prompt", "seconds_total"]). يتم دمج تضمين المدة بعد رموز النص، ويُمدَّد قناع الانتباه بإدخال صالح واحد.
StableAudio3AudioToAudioPipeline
يولّد نسخة متغيّرة من مقطع صوتي مرجعي: يتم إضافة ضوضاء إلى المرجع بأكمله بمستوى init_noise_level ثم إزالة الضوضاء منه، على عكس StableAudio3InpaintPipeline الذي يستخدم تكييفًا محليًا إضافيًا لكل إطار يحافظ على إطارات محددة بدقة.
فئة diffusers.StableAudio3AudioToAudioPipeline
< source >( vae: AutoencoderSAMEtext_encoder: T5GemmaEncoderModeltokenizer: GemmaTokenizerduration_embedder: StableAudio3DurationEmbeddertransformer: StableAudio3DiTModelscheduler: FlowMatchEulerDiscreteScheduler )
المعاملات
- vae ([AutoencoderSAME]) — شيفر-فكّ شبيه (autoencoder) من نوع SAME يُستخدم لتشفير وفكّ تشفير الكامنات الصوتية.
- text_encoder ([~transformers.T5GemmaEncoderModel]) —
مُشفِّر نص T5Gemma مجمّد (
google/t5gemma-b-b-ul2). - tokenizer ([~transformers.GemmaTokenizerFast]) — مُقسِّم (Tokenizer) لمُشفِّر النص.
- duration_embedder ([StableAudio3DurationEmbedder]) —
يُحوّل
durationبالثواني إلى متجه تكييف عام لـ AdaLN في كل كتلة DiT. - transformer ([StableAudio3DiTModel]) — نموذج DiT للتنبؤ بالسرعة في التدفق المُصحَّح.
- scheduler ([FlowMatchEulerDiscreteScheduler]) — المجدول لحلقة إزالة الضوضاء التكرارية. يستخدم نقطة التفتيش الإنتاجية (المُقطَّرة) SA3 Medium stochastic_sampling=True لخطوات ping-pong عشوائية عددها 8 بالضبط؛ بينما تستخدم نقطة التفتيش الأساسية غير المُقطَّرة stochastic_sampling=False لحوالي 100 خطوة Euler حتمية.
خط أنابيب لتوليد تنويعات صوتية من صوت إلى صوت لنموذج Stable Audio 3.
تشارك منطق النص إلى الصوت مع [StableAudio3Pipeline] (يُحافظ على مزامنتها عبر # Copied from). تشفّر الصوت المرجعي باستخدام مشفّر SAME المثبّت، وتخلطه مع ضوضاء جديدة وفقاً لـinit_noise_level، ثم تُزيل الضوضاء من هناك — الإشارة بأكملها تخضع لإضافة الضوضاء وإزالتها على مستوى عام، على عكس [StableAudio3InpaintPipeline] التي تستخدم تكييفاً إضافياً محلياً لكل إطار.
توقيع الاستدعاء الموسّع (انظر __call__):
audio (torch.Tensor من الشكل (batch, channels, samples)):
موجة الصوت المرجعية عند vae.config.sampling_rate هرتز.
init_noise_level (float):
كمية الضوضاء التي تُخلط مع الإشارة المرجعية قبل إزالة الضوضاء. 1.0 = ضوضاء كاملة (ما يعادل
النص إلى الصوت)؛ والقيم الأقل تحافظ على المزيد من الإشارة المرجعية.
__call__
< source >( prompt: typing.Union[str, typing.List[str], NoneType] = Noneduration: float = 10.0audio: typing.Optional[torch.Tensor] = Noneinit_noise_level: float = 1.0num_inference_steps: typing.Optional[int] = Nonelogsnr_min: float = -6.2logsnr_max: float = 2.0silence_padding_duration: float = 0.0num_waveforms_per_prompt: int = 1generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = Nonereturn_dict: bool = Truecallback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], dict]] = Nonecallback_on_step_end_tensor_inputs: typing.List[str] = ['latents']output_type: str = 'pt' )
المعاملات
- prompt (str أو list[str]، اختياري) — نص أو نصوص الأوامر.
- duration (float، القيمة الافتراضية 10.0) — مدة الإخراج بالثواني. يجب أن تتطابق مع الصوت المرجعي.
- audio (torch.Tensor، اختياري) —
موجة مرجعية
(batch, channels, samples)بمعدلvae.config.sampling_rateهرتز. مطلوب. - init_noise_level (float، القيمة الافتراضية 1.0) —
مستوى الضوضاء (ضمن
(0, 1]) الذي يُخلَط مع المرجع قبل إزالة الضوضاء:x_start = (1 - init_noise_level) * reference_latents + init_noise_level * noise. يؤدي تحديد1.0إلى التخلّي عن المرجع كاملًا (ما يعادل [StableAudio3Pipeline])؛ بينما تحافظ القيم الأدنى على نسبة متزايدة من بنية المرجع مع الاستمرار في تنفيذ العدد الكامل من الخطوات. - num_inference_steps (int، اختياري) —
عدد خطوات إزالة الضوضاء. عند تعيين
None(الافتراضي)، يتم اختيار عدد الخطوات من إعداد stochastic_sampling الخاص بمجدول التنفيذ، بما يتوافق مع [StableAudio3Pipeline]. - logsnr_min (float، القيمة الافتراضية -6.2) — أدنى قيمة لـ log-SNR في جدول الضجيج — يتوافق مع بداية الجدول ذات الضجيج العالي.
- logsnr_max (float، القيمة الافتراضية 2.0) — القيمة القصوى لـ log-SNR في جدول الضوضاء — يتوافق مع الطرف منخفض الضوضاء من الجدول.
- silence_padding_duration (float، القيمة الافتراضية 0.0) — مساحة إضافية في الكامن بعد المحتوى المستهدف.
- num_waveforms_per_prompt (int، القيمة الافتراضية 1) — عدد الموجات لكل موجه.
- generator — مولّد الأرقام العشوائية (RNG) لضمان قابلية التكرار.
- latents — ضوضاء بداية مُولّدة مسبقًا (
None→ عيّنة جديدة). - prompt_embeds — تمثيلات نصية محسوبة مسبقًا.
- encoder_attention_mask — قناع للتضمينات المحسوبة مسبقًا.
- return_dict (bool، القيمة الافتراضية True) — إرجاع AudioPipelineOutput أو tuple.
- callback_on_step_end (Callable، اختياري) — يُستدعى في نهاية كل خطوة إزالة ضوضاء مع (self, step_idx, timestep, callback_kwargs). يجب أن يعيد قاموسًا يحتوي على المصفوفات (المعدّلة اختياريًا) لاستخدامها في بقية الحلقة.
- callback_on_step_end_tensor_inputs (list[str]، القيمة الافتراضية [“latents”]) — المصفوفات التي تُمرَّر إلى callback_on_step_end. يجب أن تكون مجموعة فرعية من self._callback_tensor_inputs.
- output_type (str، الافتراضي
"pt") —"pt"/"np"/"latent".
أنشئ تنويعًا صوتيًا مشروطًا على موجه نصي وموجة مرجعية.
أمثلة:
>>> import torch
>>> import soundfile as sf
>>> import torchaudio
>>> from diffusers import StableAudio3AudioToAudioPipeline
>>> pipe = StableAudio3AudioToAudioPipeline.from_pretrained(
... "stabilityai/stable-audio-3-medium", torch_dtype=torch.float16
... )
>>> pipe = pipe.to("cuda")
>>> audio, sr = torchaudio.load("reference.wav")
>>> audio = torchaudio.functional.resample(audio, sr, pipe.vae.config.sampling_rate).unsqueeze(0).to("cuda")
>>> generator = torch.Generator("cuda").manual_seed(0)
>>> audio = pipe(
... "A gentle piano melody with soft strings in a concert hall",
... duration=10.0,
... audio=audio,
... init_noise_level=0.6,
... generator=generator,
... ).audios
>>> sf.write("output.wav", audio[0].T.cpu().float().numpy(), samplerate=pipe.vae.config.sampling_rate)encode_duration
< source >( duration: floatdevice: devicenum_waveforms_per_prompt: intbatch_size: int )
Embed قيمة المدة في متجه الشروط العام.
encode_prompt
< source >( prompt: typing.Union[str, typing.List[str], NoneType]device: devicenum_waveforms_per_prompt: intprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = None )
المعاملات
- prompt — نص موجه أو قائمة من الموجهات. يتم تجاهله عند توفير
prompt_embeds. - device — الجهاز المستهدف.
- num_waveforms_per_prompt — عدد موجات الإخراج التي سيتم توليدها لكل موجه؛ حيث يتم تكرار متجهات الشرط (conditioning tensors) وفقاً لذلك.
- prompt_embeds — تمثيلات نصية محسوبة مسبقًا
(batch, seq_len, hidden_size). - encoder_attention_mask — قناع منطقي
(batch, seq_len)للتضمينات المحسوبة مسبقًا؛1= رمز حقيقي،0= حشو.
ترميز موجهات النص إلى متجهات شروط الانتباه المتقاطع.
prepare_cross_attention
< source >( prompt_embeds: Tensorencoder_attention_mask: Tensorglobal_hidden_states: Tensor )
قم ببناء سياق الانتباه المتقاطع (cross-attention context) عن طريق إضافة تضمين المدة (duration embedding) كرمز إضافي.
يوجّه SA3 مُشكّل seconds_total إلى كلا المدخل العام (AdaLN) وسياق الانتباه المتقاطع (cross_attention_cond_ids = ["prompt", "seconds_total"]). يتم دمج تضمين المدة بعد رموز النص، ويُمدَّد قناع الانتباه بإدخال صالح واحد.
StableAudio3DurationEmbedder
فئة diffusers.StableAudio3DurationEmbedder
< source >( output_dim: int = 768fourier_dim: int = 256min_val: float = 0.0max_val: float = 384.0min_freq: float = 0.5max_freq: float = 10000.0 )
المعاملات
- output_dim (int، القيمة الافتراضية 768) —
بعد التضمين الناتج. يجب أن يتطابق مع
global_cond_dimالخاص بـ DiT. - fourier_dim (int، القيمة الافتراضية 256) — أبعاد ميزات فورييه الداخلية (يجب أن تكون زوجية).
- min_val (float، القيمة الافتراضية 0.0) — القيمة الدنيا للمدة المستخدمة في تحديد حدود التطبيع.
- max_val (float، القيمة الافتراضية 384.0) —
القيمة القصوى للمدة المستخدمة في تحديد حدود التطبيع. تُثبَّت القيم التي تتجاوز هذا الحد. يمثل 384 ثانية الحد الأعلى للإنتاج لنموذج SA3 Medium الخاص بمشروط
seconds_total. - min_freq (float، القيمة الافتراضية 0.5) — الحد الأدنى للتردد في الأساس الأسي لدالة فورييه.
- max_freq (float، القيمة الافتراضية 10000.0) — التردد الأقصى للأسس الأربعة (Fourier) الأسية.
يُضمّن قيمة المدة (بالثواني) في متجه شروط عام لنموذج Stable Audio 3 DiT (يُستخدم كمدخل global_hidden_states لـ AdaLN).
ينسخ NumberConditioner(fourier_features_type="expo") من التنفيذ المرجعي لـ SA3.
forward
< source >( seconds: Tensor )