# LTX2VideoTransformer3DModel

أُدخل نموذج Diffusion Transformer للبيانات ثلاثية الأبعاد من [LTX](https://huggingface.co/Lightricks/LTX-2) بواسطة Lightricks.

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

```python
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]]

```python
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)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_ltx2.py#L1069)

**المعاملات:**

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](https://huggingface.co/Lightricks/LTX-Video).

#### forward[[diffusers.LTX2VideoTransformer3DModel.forward]]

```python
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)
```

[المصدر](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_ltx2.py#L1353)

**المعاملات:**

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.