Diffusers documentation
LTX2VideoTransformer3DModel
LTX2VideoTransformer3DModel
A Diffusion Transformer model for 3D data from LTX was introduced by 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
< 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 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) — ما إذا كانت الطبقات الخطية في طبقة التغذية الأمامية للصوت تتضمن حدّاً للانحياز. - use_prompt_adaln_single (
bool، القيمة الافتراضيةTrue) — ما إذا كانت عملية تعديل مفاتيح/القيم (Key/Value) في الانتباه المتقاطع (cross-attention) المرتبط بالموجّه (prompt) تعتمد على خطوة الزمن (timestep). عند تعيينFalse، يتم استخدام جدول ثابت لكل طبقة بدلاً من ذلك، مما يجعل قيم مفاتيح/القيم في الانتباه المتقاطع قابلة للتخزين المؤقت (cacheable) عبر خطوات إزالة الضوضاء (denoising) لموجّه (prompt) معين. - use_keyframes_abs_pos_embedding (
bool، القيمة الافتراضيةFalse) — ما إذا كان سيتم تخزين تضمين موضع مطلق متعلم(1, inner_dim)لرموز الإطارات المفتاحية المولّدة (LTX-2.5). عند تعيينTrue، تتلقى الرموز المحددة بواسطةvideo_keyframes_maskهذا التضمين. الحجة اختيارية؛ وإهمالها يترك مسار الأمامي المُقطّر دون تغيير.
نموذج Transformer لبيانات تشبه الفيديو يُستخدم في LTX.
forward
< source >( hidden_states: Tensoraudio_hidden_states: Tensorencoder_hidden_states: Tensoraudio_encoder_hidden_states: Tensortimestep: LongTensoraudio_timestep: typing.Optional[torch.LongTensor] = Nonesigma: typing.Optional[torch.Tensor] = Noneaudio_sigma: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.Tensor] = Noneaudio_encoder_attention_mask: typing.Optional[torch.Tensor] = Nonenum_frames: int | None = Noneheight: int | None = Nonewidth: int | None = Nonefps: float = 24.0audio_num_frames: int | None = Nonevideo_coords: typing.Optional[torch.Tensor] = Noneaudio_coords: typing.Optional[torch.Tensor] = Noneisolate_modalities: bool = Falsespatio_temporal_guidance_blocks: list[int] | None = Noneperturbation_mask: typing.Optional[torch.Tensor] = Noneuse_cross_timestep: bool = Falseattention_kwargs: dict[str, typing.Any] | None = Nonevideo_self_attention_mask: typing.Optional[torch.Tensor] = Nonevideo_keyframes_mask: typing.Optional[torch.Tensor] = Nonereturn_dict: bool = True ) → AudioVisualModelOutput or tuple
المعاملات
- hidden_states (
torch.Tensor) — كعوب الفيديو المُقطَّعة المُدخلة (input patchified video latents) ذات الشكل(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، اختياري) — خطوة الزمن المدخلة ذات الشكل(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) — مؤشرات كتل التحويل (transformer blocks) التي تُطبَّق عليها التوجيه المكاني-الزمني (STG)، حيث يُختصر تشغيل الانتباه الذاتي (self-attention) عن طريق استخدام القيم مباشرةً بدلاً من عملية الانتباه الكامل بنقطة الضرب المُقيَّسة (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.