# SanaWMLTX2RefinerTransformer3DModel

نموذج DiT التوليفي الذاتي السببي المقسّم إلى أجزاء، المستخدم كمرحلة ثانية في [SanaWMPipeline](/docs/diffusers/main/ar/api/pipelines/sana_wm#diffusers.SanaWMPipeline)، ويعمل بواسطة [SanaWMLTX2Refiner](/docs/diffusers/main/ar/api/pipelines/sana_wm#diffusers.SanaWMLTX2Refiner).

إنه مطابق معمارياً لـ [LTX2VideoTransformer3DModel](/docs/diffusers/main/ar/api/models/ltx2_video_transformer3d#diffusers.LTX2VideoTransformer3DModel) — نفس حُجج الإعداد، ونفس الوحدات الفرعية، ونفس أسماء المعاملات — لذا يُحمَّل نقطة التفتيش LTX-2 المُصدَّرة فيه دون أي تغيير. يختلف مسار الأمامي (forward pass) كالتالي:

* يتم تشغيل تدفق الفيديو فقط (تُتخطى فروع الانتباه المتقاطع للصوت والصوت/الفيديو)،
* تعمل آلية الانتباه الذاتي (self-attention) مقابل ذاكرة KV منقّبة ذات نافذة منزلقة صريحة (`SanaWMRefinerKVCache`) تحتفظ بمغسّات الانتباه (attention sink) بالإضافة إلى السجل المُحسَّن الأخير، مما يجعل الحساب لكل كتلة محدوداً، ويتناسب إجمالي تكلفة التحسين خطياً مع طول الفيديو،
* يُوفّر المُستدعي RoPE للفيديو، مما يتيح لكل نافذة توليدية ذاتية الاستمرارية الاحتفاظ بالمؤشر المطلق لكل إطار في الفيديو المصدر (انظر [SanaWMLTX2RefinerTransformer3DModel.build_rotary_emb_for_absolute_positions()](/docs/diffusers/main/ar/api/models/sana_wm_refiner_transformer3d#diffusers.SanaWMLTX2RefinerTransformer3DModel.build_rotary_emb_for_absolute_positions)).

يمكن تحميل النموذج باستخدام:

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

#### diffusers.SanaWMLTX2RefinerTransformer3DModel[[diffusers.SanaWMLTX2RefinerTransformer3DModel]]

```python
diffusers.SanaWMLTX2RefinerTransformer3DModel(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/main/src/diffusers/models/transformers/transformer_sana_wm_refiner.py#L1110)

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

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`، القيمة الافتراضية `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](/docs/diffusers/main/ar/api/models/ltx2_video_transformer3d#diffusers.LTX2VideoTransformer3DModel) — نفس حُجج الإعداد، ونفس الوحدات الفرعية، ونفس أسماء المعاملات — لذا يُحمَّل نقطة التفتيش LTX-2 المُصدَّرة فيه دون أي تغيير. ما يختلف هو مسار الأمامي:

* يتم تشغيل تدفق الفيديو فقط (تُتخطى فروع الانتباه المتقاطع للصوت والصوت/الفيديو)،
* تعمل آلية الانتباه الذاتي (self-attention) مقابل ذاكرة KV متحركة بنافذة منزلقة صريحة (`SanaWMRefinerKVCache`) تحتفظ بمغسِّص الانتباه (attention sink) بالإضافة إلى السجل المُحسَّن الأخير، مما يجعل تكلفة التحسين محدودة لكل كتلة توليد تسلسلي (AR) وتتدرج خطياً مع طول الفيديو،
* يُوفّر المُستدعي RoPE للفيديو، مما يتيح لكل نافذة AR الاحتفاظ بالمؤشر المطلق لكل إطار في الفيديو المصدر (انظر [build_rotary_emb_for_absolute_positions()](/docs/diffusers/main/ar/api/models/sana_wm_refiner_transformer3d#diffusers.SanaWMLTX2RefinerTransformer3DModel.build_rotary_emb_for_absolute_positions)).

تعكس الحُجج المتبقية حُجج [LTX2VideoTransformer3DModel](/docs/diffusers/main/ar/api/models/ltx2_video_transformer3d#diffusers.LTX2VideoTransformer3DModel) بشكلٍ مطابقٍ واحدًا لواحد. تُحفظ حُجج وحدة الصوت والوحدات الفرعية الخاصة بها بشكلٍ خالص فقط حتى يتمكّن أوزان الصوت في نقطة الفحص من المرور ذهابًا وإيابًا؛ فهي غير مستخدمة في تمرير المُحسّن (refiner) الأمامي.

#### بناء التضمين الدوّاري للمواقع المطلقة[[diffusers.SanaWMLTX2RefinerTransformer3DModel.build_rotary_emb_for_absolute_positions]]

```python
build_rotary_emb_for_absolute_positions(batch_size: int, frame_positions: list[int], height: int, width: int, device: device, fps: float)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_sana_wm_refiner.py#L1376)

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

batch_size (`int`) : حجم الدفعة (Batch size) لبث الإحداثيات إليه.

frame_positions (`list[int]`) : الفهارس المطلقة لإطارات الكامنة التي تغطيها هذه النافذة.

height (`int`)، العرض (`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[[diffusers.SanaWMLTX2RefinerTransformer3DModel.forward]]

```python
forward(hidden_states: Tensor, encoder_hidden_states: Tensor, timestep: Tensor, video_rotary_emb: tuple[torch.Tensor, torch.Tensor], encoder_attention_mask: typing.Optional[torch.Tensor] = None, kv_cache: diffusers.models.transformers.transformer_sana_wm_refiner.SanaWMRefinerKVCache | None = None, kv_cache_mode: str | None = None, attention_kwargs: dict | None = None, return_dict: bool = True)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_sana_wm_refiner.py#L1433)

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

hidden_states (`torch.Tensor`) : كامنات الفيديو المُقطَّعة (Patchified) للكتلة النشطة، بأبعاد `(batch_size, num_video_tokens, in_channels)`.

encoder_hidden_states (`torch.Tensor`) : تمثيلات نصية (Text embeddings) بشكل `(batch_size, text_seq_len, caption_channels)`.

timestep (`torch.Tensor`) : خطوة زمنية (Timestep) بأبعاد `(batch_size, num_video_tokens)`، وقد تم توسيعها مسبقًا بمعامل `self.config.timestep_scale_multiplier`.

video_rotary_emb (`tuple[torch.Tensor, torch.Tensor]`) : `(cos, sin)` الخاص بـ RoPE لمواضع الإطار المطلق للكتلة النشطة، كما يُعاد بواسطة [build_rotary_emb_for_absolute_positions()](/docs/diffusers/main/ar/api/models/sana_wm_refiner_transformer3d#diffusers.SanaWMLTX2RefinerTransformer3DModel.build_rotary_emb_for_absolute_positions).

encoder_attention_mask (`torch.Tensor`، *اختياري*) : قناع انتباه نصي ضربي (Multiplicative) بأبعاد `(batch_size, text_seq_len)`.

kv_cache (`SanaWMRefinerKVCache`, *اختياري*) : ذاكرة KV بنافذة منزلقة تحتفظ بمصارف الانتباه لكل طبقة والتاريخ المُحسَّن الأخير، بالإضافة إلى RoPE المشترك `sink_pe`. مطلوب دائمًا عند تعيين `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`، *اختياري*) : معاملات اختيارية (kwargs) تُمرَّر إلى معالجة مقياس LoRA.

return_dict (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان يجب إرجاع [Transformer2DModelOutput](/docs/diffusers/main/ar/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput) بدلاً من tuple عادي.

**يعيد:** [Transformer2DModelOutput](/docs/diffusers/main/ar/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput) أو `tuple`

السرعة المتوقعة للكتلة النشطة، ذات الشكل `(batch_size, num_video_tokens, out_channels)`.

مرور أمامي يعتمد على الفيديو فقط عبر كتلة AR واحدة.

## SanaWMRefinerKVCache[[diffusers.models.transformers.transformer_sana_wm_refiner.SanaWMRefinerKVCache]]

#### diffusers.models.transformers.transformer_sana_wm_refiner.SanaWMRefinerKVCache[[diffusers.models.transformers.transformer_sana_wm_refiner.SanaWMRefinerKVCache]]

```python
diffusers.models.transformers.transformer_sana_wm_refiner.SanaWMRefinerKVCache(num_layers: int)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_sana_wm_refiner.py#L745)

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

num_layers (*int*) : عدد كتل التحويل التي سيتم تخصيص ذاكرة مؤقتة لكل طبقة لها.

حاوية تحتوي على [*SanaWMRefinerKVLayerCache*] واحد لكل كتلة محول، بالإضافة إلى RoPE المشترك للغرق.

تنفّذ هذه العملية عقد ذاكرة `rf_shifted_sink` التي تم تدريب مُحسّن المرحلة الثانية من 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]]

#### diffusers.models.transformers.transformer_sana_wm_refiner.SanaWMRefinerKVLayerCache[[diffusers.models.transformers.transformer_sana_wm_refiner.SanaWMRefinerKVLayerCache]]

```python
diffusers.models.transformers.transformer_sana_wm_refiner.SanaWMRefinerKVLayerCache()
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_sana_wm_refiner.py#L656)

ذاكرة KV لكل طبقة لمُحسّن AR السببي المقسّم في المرحلة الثانية من SANA-WM.

يحتفظ بالنصفين من بادئة نافذة الانزلاق التي يستهدفها الانتباه الذاتي في المُحسِّن، بالإضافة إلى خانة لقراءة قيم K/V التي التقطها التقدّم الأخير. جميع المصفوفات (تِنسورز) هي *(batch_size, num_tokens, inner_dim)* (أي قبل فكّ التسطيح لكل رأس)، بما يتوافق مع الترتيب الذي يدمجه الانتباه الذاتي في المُحسِّن.

- `sink_k_pre` / `sink_v`: **pre**-RoPE K/V للإطارات الخاصة بأطر حوض الانتباه (attention-sink frames)، وقد تم التقاطها مرة واحدة من كامنات المرحلة الأولى الخام. يتم تخزينها قبل تطبيق 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`.

#### get_captured_post_rope[[diffusers.models.transformers.transformer_sana_wm_refiner.SanaWMRefinerKVLayerCache.get_captured_post_rope]]

```python
get_captured_post_rope()
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_sana_wm_refiner.py#L724)

استخرج K/V بعد RoPE الذي التقطه آخر تمرير أمامي.

#### get_captured_pre_rope[[diffusers.models.transformers.transformer_sana_wm_refiner.SanaWMRefinerKVLayerCache.get_captured_pre_rope]]

```python
get_captured_pre_rope()
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_sana_wm_refiner.py#L710)

استخرج K/V قبل RoPE الذي التقطه التقدّم الأخير.

#### get_history[[diffusers.models.transformers.transformer_sana_wm_refiner.SanaWMRefinerKVLayerCache.get_history]]

```python
get_history()
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_sana_wm_refiner.py#L699)

أعدّ K/V لتاريخ حديث بعد تطبيق RoPE، أو `None` إذا كان فارغاً.

#### get_sink[[diffusers.models.transformers.transformer_sana_wm_refiner.SanaWMRefinerKVLayerCache.get_sink]]

```python
get_sink()
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_sana_wm_refiner.py#L688)

أعد ك/في (K/V) الخاص بمصارف ما قبل RoPE، أو `None` إذا لم يتم التقاطه (أو كان فارغاً).

#### store_captured_post_rope[[diffusers.models.transformers.transformer_sana_wm_refiner.SanaWMRefinerKVLayerCache.store_captured_post_rope]]

```python
store_captured_post_rope(key: Tensor, value: Tensor)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_sana_wm_refiner.py#L719)

احفظ K/V الناتج بعد RoPE من التمرير الأمامي الحالي.

#### store_captured_pre_rope[[diffusers.models.transformers.transformer_sana_wm_refiner.SanaWMRefinerKVLayerCache.store_captured_pre_rope]]

```python
store_captured_pre_rope(key: Tensor, value: Tensor)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_sana_wm_refiner.py#L705)

احفظ K/V قبل تطبيق RoPE الناتج عن التمرير الأمامي الحالي.

#### store_history[[diffusers.models.transformers.transformer_sana_wm_refiner.SanaWMRefinerKVLayerCache.store_history]]

```python
store_history(history_k: Tensor, history_v: Tensor)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_sana_wm_refiner.py#L694)

خزّن K/V لتاريخ حديث بعد تطبيق RoPE.

#### store_sink[[diffusers.models.transformers.transformer_sana_wm_refiner.SanaWMRefinerKVLayerCache.store_sink]]

```python
store_sink(sink_k_pre: Tensor, sink_v: Tensor)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_sana_wm_refiner.py#L683)

حفظ K/V الخاص بالـ sink قبل تطبيق RoPE.

## Transformer2DModelOutput[[diffusers.models.modeling_outputs.Transformer2DModelOutput]]

#### diffusers.models.modeling_outputs.Transformer2DModelOutput[[diffusers.models.modeling_outputs.Transformer2DModelOutput]]

```python
diffusers.models.modeling_outputs.Transformer2DModelOutput(sample: torch.Tensor)
```

[المصدر](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/modeling_outputs.py#L21)

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

sample (`torch.Tensor` من الشكل `(batch_size, num_channels, height, width)` أو `(batch size, num_vector_embeds - 1, num_latent_pixels)` إذا كان [Transformer2DModel](/docs/diffusers/main/ar/api/models/transformer2d#diffusers.Transformer2DModel) منفصلاً): مخرجات الحالات المخفية المشروطة على مدخل `encoder_hidden_states`. إذا كان منفصلاً، يعيد توزيعات الاحتمال للبكسلات الكامنة غير الملوثة.

مخرجات [Transformer2DModel](/docs/diffusers/main/ar/api/models/transformer2d#diffusers.Transformer2DModel).