Diffusers documentation
SanaWMLTX2RefinerTransformer3DModel
SanaWMLTX2RefinerTransformer3DModel
نموذج DiT التوليفي الذاتي السببي المقسّم إلى أجزاء، المستخدم كمرحلة ثانية في SanaWMPipeline، ويعمل بواسطة SanaWMLTX2Refiner.
هو مطابق معماريًا إلى LTX2VideoTransformer3DModel — نفس حُجج الإعداد، ونفس الوحدات الفرعية، ونفس أسماء المعاملات — لذا يُحمَّل نقطة التفتيش LTX-2 المُصدَّرة فيه دون أي تغيير. يختلف مسار الأمامي:
- يتم تشغيل تدفق الفيديو فقط (تُتخطى فروع الانتباه المتقاطع للصوت والصوت/الفيديو)،
- تعمل آلية الانتباه الذاتي (self-attention) مقابل ذاكرة KV منقّبة ذات نافذة منزلقة صريحة (
SanaWMRefinerKVCache) تحتفظ بمغسّات الانتباه (attention sinks) بالإضافة إلى السجل المُحسَّن الأخير، مما يجعل الحساب لكل كتلة محدوداً، ويتناسب إجمالي تكلفة التحسين خطياً مع طول الفيديو، - يُوفّر المُستدعي RoPE للفيديو، مما يتيح لكل نافذة توليدية ذاتية الاستمرارية الاحتفاظ بالمؤشر المطلق لكل إطار في الفيديو المصدر (انظر SanaWMLTX2RefinerTransformer3DModel.build_rotary_emb_for_absolute_positions()).
يمكن تحميل النموذج باستخدام:
import torch
from diffusers import SanaWMLTX2RefinerTransformer3DModel
transformer = SanaWMLTX2RefinerTransformer3DModel.from_pretrained(
"Efficient-Large-Model/SANA-WM_bidirectional-diffusers",
subfolder="refiner/transformer",
torch_dtype=torch.bfloat16,
)SanaWMLTX2RefinerTransformer3DModel
فئة diffusers.SanaWMLTX2RefinerTransformer3DModel
< source >( in_channels: int = 128out_channels: int | None = 128patch_size: int = 1patch_size_t: int = 1num_attention_heads: int = 32attention_head_dim: int = 128cross_attention_dim: int = 4096vae_scale_factors: tuple = (8, 32, 32)pos_embed_max_pos: int = 20base_height: int = 2048base_width: int = 2048gated_attn: bool = Falsecross_attn_mod: bool = Falseaudio_in_channels: int = 128audio_out_channels: int | None = 128audio_patch_size: int = 1audio_patch_size_t: int = 1audio_num_attention_heads: int = 32audio_attention_head_dim: int = 64audio_cross_attention_dim: int = 2048audio_scale_factor: int = 4audio_pos_embed_max_pos: int = 20audio_sampling_rate: int = 16000audio_hop_length: int = 160audio_gated_attn: bool = Falseaudio_cross_attn_mod: bool = Falsenum_layers: int = 48activation_fn: str = 'gelu-approximate'qk_norm: str = 'rms_norm_across_heads'norm_elementwise_affine: bool = Falsenorm_eps: float = 1e-06caption_channels: int = 3840attention_bias: bool = Trueattention_out_bias: bool = Truerope_theta: float = 10000.0rope_double_precision: bool = Truecausal_offset: int = 1timestep_scale_multiplier: int = 1000cross_attn_timestep_scale_multiplier: int = 1000rope_type: str = 'interleaved'use_prompt_embeddings = Trueperturbed_attn: bool = Falseff_bias: bool = Trueaudio_ff_bias: bool = Trueuse_prompt_adaln_single: bool = Trueuse_keyframes_abs_pos_embedding: bool = False )
المعاملات
- in_channels (
int)، القيمة الافتراضية128) — عدد القنوات في المدخلات. - out_channels (
int، القيمة الافتراضية128) — عدد القنوات في المخرجات. - patch_size (
int، القيمة الافتراضية1) — حجم البقع المكانية المستخدمة في طبقة تضمين البقع. - patch_size_t (
int، القيمة الافتراضية1) — حجم البقع الزمنية (temporal patches) المستخدمة في طبقة تضمين البقع (patch embedding). - num_attention_heads (
int، القيمة الافتراضية32) — عدد الرؤوس المستخدمة في الانتباه متعدد الرؤوس. - attention_head_dim (
int، القيمة الافتراضية128) — عدد القنوات في كل رأس. - cross_attention_dim (
int، القيمة الافتراضية4096) — عدد القنوات لرؤوس الانتباه المتقاطع. - num_layers (
int، القيمة الافتراضية48) — عدد طبقات كتل Transformer المستخدمة. - activation_fn (
str، القيمة الافتراضية"gelu-approximate") — دالة التنشيط المستخدمة في الشبكة العصبية الأمامية. - qk_norm (
str، القيمة الافتراضية"rms_norm_across_heads") — طبقة التطبيع المستخدمة. - rope_type (
str، القيمة الافتراضية"interleaved") — نوع تطبيق RoPE الذي سيتم استخدامه ("interleaved"أو"split").
محوّل التكراري السببي المقسّم (chunk-causal autoregressive refiner transformer) المستخدم كمرحلة 2 في SANA-WM.
متطابق معمارياً مع LTX2VideoTransformer3DModel — نفس حُجج الإعداد، ونفس الوحدات الفرعية، ونفس أسماء المعاملات — لذا يُحمَّل نقطة التفتيش LTX-2 المُصدَّرة فيه دون أي تغيير. ما يختلف هو مسار الأمامي:
- يتم تشغيل تدفق الفيديو فقط (تُتخطى فروع الانتباه المتقاطع للصوت والصوت/الفيديو)،
- تعمل آلية الانتباه الذاتي (self-attention) مقابل ذاكرة KV منقّبة ذات نافذة منزلقة صريحة (
SanaWMRefinerKVCache) تحتفظ بمغسّات الانتباه (attention sinks) بالإضافة إلى السجل المُحسَّن الأخير، مما يجعل تكلفة التحسين محدودة لكل كتلة توليدية تسلسلية (AR block) وتتدرج خطياً مع طول الفيديو، - يُوفّر المُستدعي RoPE للفيديو، مما يتيح لكل نافذة AR الاحتفاظ بالمؤشر المطلق لكل إطار في الفيديو المصدر (انظر build_rotary_emb_for_absolute_positions()).
تعكس الحُجج المتبقية حُجج LTX2VideoTransformer3DModel بشكلٍ مطابقٍ واحدًا لواحد. تُحفظ حُجج وحدة الصوت والوحدات الفرعية الخاصة بها بشكلٍ خالصٍ فقط حتى يتمكّن أوزان الصوت في نقطة الفحص من المرور ذهابًا وإيابًا؛ فهي غير مستخدمة في تمريرة المُحسّن الأمامية.
build_rotary_emb_for_absolute_positions
< source >( batch_size: intframe_positions: listheight: intwidth: intdevice: devicefps: float ) → tuple[torch.Tensor, torch.Tensor]
المعاملات
- batch_size (
int) — حجم الدفعة (Batch size) لبث الإحداثيات إليه. - frame_positions (
list[int]) — فهارس إطارات الكامنة المطلقة التي تغطيها هذه النافذة. - height (
int), width (int) — الدقة المكانية الكامنة. - device (
torch.device) — الجهاز الذي تُبنى عليه الإحداثيات. - fps (
float) — معدل إطارات الفيديو، وهو ما يحدد توسيع RoPE الزمني في LTX-2.
يعيد
tuple[torch.Tensor, torch.Tensor]
زوج (cos, sin) الخاص بـ RoPE.
أنشئ RoPE للفيديو لقائمة صريحة من فهارس الإطارات الكامنة المطلقة.
SanaWMLTX2AudioVideoRotaryPosEmbed.prepare_video_coords يفترض استخدام torch.arange(num_frames) متتابع، وهو ما يناسب الاستدلال ثنائي الاتجاه. أما مُحسّن AR النافذة المنزلقة فيحتاج بدلاً من ذلك إلى الحفاظ على الفهرس المطلق لكل إطار في الفيديو المصدر، حتى يلتقط RoPE الطور الزمني الصحيح عبر نافذة [sink + recent + active].
forward
< source >( hidden_states: Tensorencoder_hidden_states: Tensortimestep: Tensorvideo_rotary_emb: tupleencoder_attention_mask: typing.Optional[torch.Tensor] = Nonekv_cache: diffusers.models.transformers.transformer_sana_wm_refiner.SanaWMRefinerKVCache | None = Nonekv_cache_mode: str | None = Noneattention_kwargs: dict | None = Nonereturn_dict: bool = True ) → Transformer2DModelOutput or tuple
المعاملات
- hidden_states (
torch.Tensor) — كائنات فيديو مُجزّأة (patchified) للكتلة النشطة، على شكل(batch_size, num_video_tokens, in_channels). - encoder_hidden_states (
torch.Tensor) — تضمينات نصية بأبعاد(batch_size, text_seq_len, caption_channels). - timestep (
torch.Tensor) — خطوة زمنية من الشكل(batch_size, num_video_tokens)، وقد تم توسيعها مسبقًا بواسطةself.config.timestep_scale_multiplier. - video_rotary_emb (
tuple[torch.Tensor, torch.Tensor]) — RoPE الخاص بـ(cos, sin)لمواضع الإطار المطلقة للكتلة النشطة، كما تُرجعه build_rotary_emb_for_absolute_positions(). - encoder_attention_mask (
torch.Tensor، اختياري) — قناع انتباه نصي مضاعف بالشكل(batch_size, text_seq_len). - kv_cache (
SanaWMRefinerKVCache، اختياري) — ذاكرة مؤقتة KV بنافذة منزلقة تحتفظ بمصارف الانتباه لكل طبقة والتاريخ المُحسَّن الأخير، بالإضافة إلىsink_peRoPE المشترك. مطلوب دائمًا عند تعيينkv_cache_mode. - kv_cache_mode (
str, اختياري) — أحد ما يلي:"inject": الانتباه إلى[sink + history + current]K/V (خطوات إزالة الضوضاء)."capture_pre_rope": بدون بادئة؛ سجّل K/V قبل تطبيق RoPE لهذا التمرير الأمامي في ذاكرة التخزين المؤقت (يُستخدم مرة واحدة لبذر غرق الانتباه من الكمونيات الخام للمرحلة الأولى)."inject_and_capture_post_rope": انتبه إلى[sink + history + current]من K/V وسجّل K/V بعد تطبيق RoPE لهذا الكتلة في الكاش بحيث يمكن إضافتها إلى السجل.
عندما تكون
None، يعمل الكتلة على انتباه ذاتي كامل عادي على الرموز الحالية فقط. - attention_kwargs (
dict، اختياري) — معاملات اختيارية تُمرَّر إلى معالجة مقياس LoRA. - return_dict (
bool، اختياري، القيمة الافتراضيةTrue) — ما إذا كان يجب إرجاع Transformer2DModelOutput بدلاً من tuple عادي.
يعيد
Transformer2DModelOutput أو tuple
السرعة المتوقعة للكتلة النشطة، ذات الشكل (batch_size, num_video_tokens, out_channels).
مرور أمامي يعتمد على الفيديو فقط عبر كتلة AR واحدة.
SanaWMRefinerKVCache
فئة diffusers.models.transformers.transformer_sana_wm_refiner.SanaWMRefinerKVCache
< source >( num_layers: int )
حاوية تحتوي على [SanaWMRefinerKVLayerCache] واحد لكل كتلة محول، بالإضافة إلى RoPE المشترك للغرق.
يُنفّذ هذا العقد rf_shifted_sink لذاكرة KV الذي تم تدريب مُحسّن المرحلة الثانية من SANA-WM باستخدامه. التحسين سببي على مستوى الكتل: يتم إزالة الضوضاء عن block_size من الإطارات الكامنة في كل مرة، مع الانتباه إلى نافذة محدودة من [مص الانتباه + التاريخ الأخير + الكتلة النشطة] من K/V.
sink_pe: زوج (cos, sin) الخاص بـ RoPE للإطارات الممتصة، يُعاد بناؤه في كل نافذة AR عند الإزاحة المنزلقةsink_rope_offsetبحيث تكون الإطارات الممتصة مباشرةً قبل ذاكرة العمل المحدودة. يتم مشاركتها عبر الطبقات لأن RoPE لا تعتمد على الطبقة.
SanaWMRefinerKVLayerCache
فئة diffusers.models.transformers.transformer_sana_wm_refiner.SanaWMRefinerKVLayerCache
< source >( )
ذاكرة KV لكل طبقة لمُحسّن AR السببي المقسّم في المرحلة الثانية من SANA-WM.
يحتفظ بالنصفين من بادئة نافذة الانزلاق التي يستهدفها الانتباه الذاتي للمُحسِّن، بالإضافة إلى خانة لقراءة K/V التي التقطها التقدّم الأخير. جميع الموترات على شكل (batch_size, num_tokens, inner_dim) (أي قبل فكّ التسطيح لكل رأس)، بما يتوافق مع التخطيط الذي يدمجه الانتباه الذاتي للمُحسِّن.
sink_k_pre/sink_v: pre-RoPE K/V للإطارات الخاصة بأطر حوض الانتباه (attention-sink)، تم التقاطها مرة واحدة من الكامنات الخام للمرحلة الأولى. يتم تخزينها قبل تطبيق RoPE بحيث يمكن لكل نافذة AR إعادة تطبيق RoPE عند إزاحة الحوض الخاصة بها (SanaWMRefinerKVCache.sink_pe).history_k/history_v: ما بعد RoPE K/V للإطارات الأخيرة المُحسَّنة بالفعل، وجاهزة للدمج كما هي.captured_k_pre/captured_v_preوcaptured_k_post/captured_v_post: فتحات قراءة تُكتب بواسطة أوضاع الالتقاطkv_cache_mode.
استخرج K/V بعد RoPE الذي التقطه آخر تمرير أمامي.
استخرج K/V قبل RoPE الذي التقطه التقدّم الأخير.
أعدّ K/V لتاريخ حديث بعد تطبيق RoPE، أو None إذا كان فارغاً.
أعد ك/في (K/V) الخاص بمصارف ما قبل RoPE، أو None إذا لم يتم التقاطه (أو كان فارغاً).
احفظ K/V الناتج بعد RoPE من التمرير الأمامي الحالي.
احفظ K/V قبل تطبيق RoPE الناتج عن التمرير الأمامي الحالي.
خزّن K/V لتاريخ حديث بعد تطبيق RoPE.
حفظ K/V الخاص بالـ sink قبل تطبيق RoPE.
Transformer2DModelOutput
فئة diffusers.models.modeling_outputs.Transformer2DModelOutput
< source >( sample: torch.Tensor )
المعاملات
- sample (
torch.Tensorمن الشكل(batch_size, num_channels, height, width)أو(batch size, num_vector_embeds - 1, num_latent_pixels)إذا كان Transformer2DModel منفصلاً) — مخرجات الحالات المخفية المشروطة على مدخلencoder_hidden_states. إذا كان منفصلاً، يعيد توزيعات الاحتمال للبكسلات الكامنة غير الملوثة.
مخرجات Transformer2DModel.