diffusers/main/ar/api/models/ltx2_video_transformer3d.md

LTX2VideoTransformer3DModel

أُدخل نموذج Diffusion Transformer للبيانات ثلاثية الأبعاد من LTX بواسطة Lightricks.

يمكن تحميل النموذج باستخدام مقتطف الشيفرة التالي.

from diffusers import LTX2VideoTransformer3DModel

transformer = LTX2VideoTransformer3DModel.from_pretrained("Lightricks/LTX-2", subfolder="transformer", dtype=torch.bfloat16).to("cuda")  # or "mps", "xpu", "cpu"

LTX2VideoTransformer3DModel[[diffusers.LTX2VideoTransformer3DModel]]

diffusers.LTX2VideoTransformer3DModel[[diffusers.LTX2VideoTransformer3DModel]]

diffusers.LTX2VideoTransformer3DModel(in_channels: int = 128, out_channels: int | None = 128, patch_size: int = 1, patch_size_t: int = 1, num_attention_heads: int = 32, attention_head_dim: int = 128, cross_attention_dim: int = 4096, vae_scale_factors: tuple[int, int, int] = (8, 32, 32), pos_embed_max_pos: int = 20, base_height: int = 2048, base_width: int = 2048, gated_attn: bool = False, cross_attn_mod: bool = False, audio_in_channels: int = 128, audio_out_channels: int | None = 128, audio_patch_size: int = 1, audio_patch_size_t: int = 1, audio_num_attention_heads: int = 32, audio_attention_head_dim: int = 64, audio_cross_attention_dim: int = 2048, audio_scale_factor: int = 4, audio_pos_embed_max_pos: int = 20, audio_sampling_rate: int = 16000, audio_hop_length: int = 160, audio_gated_attn: bool = False, audio_cross_attn_mod: bool = False, num_layers: int = 48, activation_fn: str = 'gelu-approximate', qk_norm: str = 'rms_norm_across_heads', norm_elementwise_affine: bool = False, norm_eps: float = 1e-06, caption_channels: int = 3840, attention_bias: bool = True, attention_out_bias: bool = True, rope_theta: float = 10000.0, rope_double_precision: bool = True, causal_offset: int = 1, timestep_scale_multiplier: int = 1000, cross_attn_timestep_scale_multiplier: int = 1000, rope_type: str = 'interleaved', use_prompt_embeddings = True, perturbed_attn: bool = False, ff_bias: bool = True, audio_ff_bias: bool = True, use_prompt_adaln_single: bool = True, use_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 layer).

num_attention_heads (int، القيمة الافتراضية 32) : عدد الرؤوس المستخدمة في الانتباه متعدد الرؤوس.

attention_head_dim (int، القيمة الافتراضية 64) : عدد القنوات في كل رأس.

cross_attention_dim (int، القيمة الافتراضية 2048 ) : عدد القنوات لرؤوس الانتباه المتقاطع.

num_layers (int، القيمة الافتراضية 28) : عدد طبقات كتل Transformer المستخدمة.

activation_fn (str، القيمة الافتراضية "gelu-approximate") : دالة التنشيط المستخدمة في الشبكة العصبية الأمامية.

qk_norm (str، الافتراضي "rms_norm_across_heads") : طبقة التطبيع المستخدمة.

ff_bias (bool، القيمة الافتراضية True) : ما إذا كانت الطبقات الخطية في طبقة التغذية الأمامية للفيديو تتضمن حدًا للانحياز. False في LTX-2.5.

audio_ff_bias (bool، القيمة الافتراضية True) : ما إذا كانت الطبقات الخطية في طبقة التغذية الأمامية للصوت تتضمن حدًا ثابتًا (bias).

use_prompt_adaln_single (bool، القيمة الافتراضية True) : ما إذا كانت تعديل مفتاح/قيمة الانتباه المتقاطع (Key/Value) الخاص بالموجّه (prompt) تعتمد على خطوة الزمن (timestep). عند تعيين False، يتم استخدام جدول ثابت لكل طبقة بدلاً من ذلك، مما يجعل قيم مفتاح/قيمة الانتباه المتقاطع قابلة للتخزين المؤقت (cacheable) عبر خطوات إزالة الضوضاء (denoising) لموجّه معين.

use_keyframes_abs_pos_embedding (bool، القيمة الافتراضية False) : ما إذا كان سيتم تخزين تضمين موضع مطلق متعلم بأبعاد (1, inner_dim) لرموز إطارات المفتاح المولّدة (LTX-2.5). عند تعيين True، تتلقى الرموز المحددة بواسطة video_keyframes_mask هذا التضمين. هذا الحجة اختيارية؛ وإهماله يترك مسار الأمامي المُقطّر دون تغيير.

نموذج Transformer لبيانات تشبه الفيديو يُستخدم في LTX.

forward[[diffusers.LTX2VideoTransformer3DModel.forward]]

forward(hidden_states: Tensor, audio_hidden_states: Tensor, encoder_hidden_states: Tensor, audio_encoder_hidden_states: Tensor, timestep: LongTensor, audio_timestep: typing.Optional[torch.LongTensor] = None, sigma: typing.Optional[torch.Tensor] = None, audio_sigma: typing.Optional[torch.Tensor] = None, encoder_attention_mask: typing.Optional[torch.Tensor] = None, audio_encoder_attention_mask: typing.Optional[torch.Tensor] = None, num_frames: int | None = None, height: int | None = None, width: int | None = None, fps: float = 24.0, audio_num_frames: int | None = None, video_coords: typing.Optional[torch.Tensor] = None, audio_coords: typing.Optional[torch.Tensor] = None, isolate_modalities: bool = False, spatio_temporal_guidance_blocks: list[int] | None = None, perturbation_mask: typing.Optional[torch.Tensor] = None, use_cross_timestep: bool = False, attention_kwargs: dict[str, typing.Any] | None = None, video_self_attention_mask: typing.Optional[torch.Tensor] = None, video_keyframes_mask: typing.Optional[torch.Tensor] = None, return_dict: bool = True)

المصدر

المعاملات:

hidden_states (torch.Tensor) : مدخلات فيديو مُجزّأة (patchified) على شكل (batch_size, num_video_tokens, in_channels).

audio_hidden_states (torch.Tensor) : مدخلات صوتية مُجزّأة (patchified) على شكل (batch_size, num_audio_tokens, audio_in_channels).

encoder_hidden_states (torch.Tensor) : تمثيلات نص الفيديو المدخلة ذات الشكل (batch_size, text_seq_len, self.config.caption_channels).

audio_encoder_hidden_states (torch.Tensor) : تمثيلات نصوص الصوت المدخلة ذات الشكل (batch_size, text_seq_len, self.config.caption_channels).

timestep (torch.Tensor) : خطوة الزمن المُدخلة ذات الشكل (batch_size, num_video_tokens). يجب أن تكون هذه الخطوات مُقيَّسة مسبقًا بواسطة self.config.timestep_scale_multiplier.

audio_timestep (torch.Tensor، اختياري) : خطوة الإدخال (timestep) ذات الشكل (batch_size,) أو (batch_size, num_audio_tokens) لمعاملات تعديل الصوت. يُستخدم هذا فقط في بعض خطوط الأنابيب مثل خط أنابيب I2V.

sigma (torch.Tensor، اختياري) : خطوة زمنية مُقيّمة مدخلية من الشكل (batch_size,)، تُستخدم في تعديل الانتباه المتقاطع لموجّه الفيديو في نماذج مثل LTX-2.3.

audio_sigma (torch.Tensor, اختياري) : خطوة زمنية مُقيّمة مدخلية من الشكل (batch_size,). تُستخدم في تعديل الانتباه المتقاطع لموجّهات الصوت في نماذج مثل LTX-2.3. إذا تم تقديم sigma دون تقديم audio_sigma، فسيتم تعيين audio_sigma إلى قيمة sigma المُقدَّمة.

encoder_attention_mask (torch.Tensor، اختياري) : قناع انتباه نصي اختياري مضاعف، على شكل (batch_size, text_seq_len).

audio_encoder_attention_mask (torch.Tensor، اختياري) : قناع انتباه نصي اختياري مضاعف، بأبعاد (batch_size, text_seq_len)، لنمذجة الصوت.

num_frames (int, اختياري) : عدد إطارات الفيديو الكامنة. يُستخدم عند حساب إحداثيات الفيديو لـ RoPE.

height (int، اختياري) : ارتفاع الفيديو الكامن. يُستخدم عند حساب إحداثيات الفيديو لـ RoPE.

width (int, اختياري) : عرض الفيديو الكامن. يُستخدم عند حساب إحداثيات الفيديو لـ RoPE.

fps : (float، اختياري، القيمة الافتراضية 24.0): عدد الإطارات في الثانية المطلوب للفيديو المولّد. يُستخدم عند حساب إحداثيات الفيديو لـ RoPE.

audio_num_frames : (int, اختياري): عدد إطارات الصوت الكامنة. يُستخدم عند حساب إحداثيات الصوت لـ RoPE.

video_coords (torch.Tensor، اختياري) : إحداثيات الفيديو المستخدمة عند حساب التضمينات الموضعية الدوارة (RoPE) ذات الشكل (batch_size, 3, num_video_tokens, 2). إذا لم تُقدَّم، فسيتم حسابها داخل forward.

audio_coords (torch.Tensor, اختياري) : إحداثيات الصوت المستخدمة عند حساب التضمينات الموضعية الدوارة (RoPE) ذات الشكل (batch_size, 1, num_audio_tokens, 2). إذا لم تُقدَّم، فسيتم حسابها داخل forward.

isolate_modalities (bool، اختياري، القيمة الافتراضية False) : ما إذا كان يجب عزل كل نمط (modality) عن طريق تعطيل الانتباه المتقاطع بين الأنماط (من الصوت إلى الفيديو ومن الفيديو إلى الصوت) (لكل الكتل). يُستخدم للإرشاد حسب النمط في LTX-2.3.

spatio_temporal_guidance_blocks (list[int]، اختياري، القيمة الافتراضية None) : فهارس كتل التحويل التي تُطبَّق فيها التوجيه المكاني-الزمني (STG)، والذي يختصر عمليات الانتباه الذاتي عن طريق استخدام القيم مباشرةً بدلاً من عملية الانتباه بنقطة الضرب المُقيَّسة الكاملة (SDPA). إذا كانت None أو فارغة، فلن يُطبَّق STG على أي كتلة.

perturbation_mask (torch.Tensor, اختياري) : قناع الاضطراب لـ STG من الشكل (batch_size,) أو (batch_size, 1, 1). يجب أن يكون 0 في عناصر الدفعة التي يجب تطبيق STG عليها و 1 في بقية العناصر. إذا كان STG قيد الاستخدام ولم يُقدَّم perturbation_mask، فسيتم افتراضياً تطبيق STG (اضطراب) على جميع عناصر الدفعة.

use_cross_timestep (bool اختياري، القيمة الافتراضية False) : ما إذا كان سيتم استخدام سيجما (sigma) الخاص بالوضعيات المتقاطعة (الصوت هو الوضعية المتقاطعة للفيديو، والعكس صحيح) عند حساب معاملات تعديل الانتباه المتقاطع. True هو السلوك الأحدث (مثل LTX-2.3)؛ False هو السلوك القديم الخاص بـ LTX-2.0.

attention_kwargs (dict[str, Any]، اختياري) : قاموس اختياري من حُجج الكلمات المفتاحية التي سيتم تمريرها إلى معالج الانتباه.

video_self_attention_mask (torch.Tensor, اختياري) : قناع انتباه ذاتي اختياري من نوع الضرب، بأبعاد (batch_size, num_video_tokens, num_video_tokens)، يُطبَّق على الانتباه الذاتي للفيديو في كل كتلة تحويل. القيم ضمن [0, 1] حيث يعني 1 انتباهًا كاملًا ويعني 0 تمويهًا. يُستخدم مثلًا في خط أنابيب IC-LoRA للتحكم في قوة الانتباه بين الرموز الضجيجية والرموز المرجعية المضافة. لا يتأثر الانتباه الذاتي للصوت.

video_keyframes_mask (torch.Tensor, اختياري) : علامة اختيارية لكل رمز على شكل (batch_size, num_video_tokens, 1)، تكون غير صفرية على رموز الفيديو التي ترمز إطارها الكامن إلى إطار بكسل واحد. تتلقى هذه الرموز keyframes_abs_pos_embedding. يتم تجاهلها عندما تم بناء النموذج دون use_keyframes_abs_pos_embedding.

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

يعيد: AudioVisualModelOutput أو tuple

إذا كان return_dict هو True، تُرجع مخرجات منظمة من النوع AudioVisualModelOutput، وإلا تُرجع tuple حيث يكون العنصر الأول تسلسل رقعات الكامنة للفيديو بعد إزالة الضوضاء، والعنصر الثاني تسلسل رقعات الكامنة للصوت بعد إزالة الضوضاء.

المرور الأمامي لمحوّل الفيديو الصوتي المرئي LTX-2.0.