# SanaWMTransformer3DModel

محوّل انتشار ثلاثي الأبعاد (1.6 مليار معامل) لتوليد الفيديو من الصور مع التحكم بالكاميرا، يُستخدم كمُعيّن المرحلة الأولى في [SanaWMPipeline](/docs/diffusers/main/ar/api/pipelines/sana_wm#diffusers.SanaWMPipeline). يجمع المحوّل بين:

* فرع رئيسي لانتباه خطي ثنائي الاتجاه GDN-Triton (عمق 20، مخفي 2240، 20 رأساً)،
* فرع تحكم بالكاميرا يعتمد على UCPE (تضمين موحّد لوضع الكاميرا) يستهلك خريطة أشعة (raymap) وتمثيل Plücker للمسار المطلوب، و
* تضمين موضع دوّار ثلاثي الأبعاد بنمط Wan بالإضافة إلى كتل انتباه softmax دورية تُحقن كل `softmax_every_n` طبقات.

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

```python
import torch
from diffusers import SanaWMTransformer3DModel

transformer = SanaWMTransformer3DModel.from_pretrained(
    "Efficient-Large-Model/SANA-WM_bidirectional-diffusers",
    subfolder="transformer",
    torch_dtype=torch.bfloat16,
)
```

## SanaWMTransformer3DModel[[diffusers.SanaWMTransformer3DModel]]

#### diffusers.SanaWMTransformer3DModel[[diffusers.SanaWMTransformer3DModel]]

```python
diffusers.SanaWMTransformer3DModel(in_channels: int = 128, num_layers: int = 20, hidden_size: int = 2240, num_attention_heads: int = 20, patch_size: tuple[int, int, int] = (1, 1, 1), softmax_every_n: int = 4, linear_head_dim: int = 112, ffn_type: str = 'GLUMBConvTemp', t_kernel_size: int = 3, conv_kernel_size: int = 4, k_conv_only: bool = True, pos_embed_type: str = 'wan_rope', qk_norm: bool = True, cross_norm: bool = True, y_norm: bool = True, cam_attn_compress: int = 1, init_cam_from_base: bool = True, use_chunk_plucker_post_attn: bool = True, chunk_plucker_channels: int = 48, chunk_plucker_post_attn_blocks: int = 20, fp32_attention: bool = True, image_size: int = 720, caption_channels: int = 2304, mlp_ratio: float = 3.0, mlp_acts: tuple = ('silu', 'silu', None), use_pe: bool = True, learn_sigma: bool = False, pred_sigma: bool = False, mixed_precision: str = 'bf16')
```

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

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

in_channels (*int*، القيمة الافتراضية 128) : قنوات VAE الكامنة (LTX-2).

softmax_every_n (*int*، القيمة الافتراضية 4) : استخدم كتلة انتباه softmax كل N كتل.

linear_head_dim (*int*، القيمة الافتراضية 112) : بُعد رأس GDN.

ffn_type (*str*، القيمة الافتراضية هي `"GLUMBConvTemp"`) : FFN.

t_kernel_size (*int*، القيمة الافتراضية 3) : نواة التحوّل الزمني.

conv_kernel_size (*int*، القيمة الافتراضية 4) : نواة الالتفاف المكاني داخل الانتباه.

k_conv_only (*bool*، القيمة الافتراضية True) : تطبيق عملية الالتفاف (conv) على K فقط.

pos_embed_type (*str*، الافتراضي `"wan_rope"`) : تضمين الموضع.

qk_norm (*bool*، القيمة الافتراضية True) : تطبيق RMSNorm على Q/K.

cross_norm (*bool*، القيمة الافتراضية True) : تطبيق RMSNorm على K في الانتباه المتقاطع.

y_norm (*bool*، القيمة الافتراضية True) : تطبيق `attention_y_norm` على تمثيلات النص.

init_cam_from_base (*bool*، القيمة الافتراضية True) : غير مستخدم؛ يتم تحميل فرع الكاميرا من نقطة الحفظ. يُحافظ عليه حتى يتم تحميل ملفات *config.json* المُصدَّرة.

use_chunk_plucker_post_attn (*bool*، القيمة الافتراضية True). --

chunk_plucker_channels (*int*، القيمة الافتراضية 48) : `6 dims * temporal_stride 8`.

chunk_plucker_post_attn_blocks (*int*، القيمة الافتراضية 20) : جميع الكتل.

fp32_attention (*bool*، القيمة الافتراضية True) : غير مستخدم؛ حيث تعمل آلية الانتباه دائمًا في fp32. تم الإبقاء عليها حتى يتم تحميل ملفات *config.json* المُصدَّرة.

image_size (*int*، القيمة الافتراضية 720) : الحجم الاسمي للصورة.

caption_channels (*int*، القيمة الافتراضية 2304) : حجم Gemma-2 المخفي.

SANA-WM 1600M DiT ثنائي الاتجاه يتحكم فيه الكاميرا.

نموذج DiT من فئة واحدة (depth=20, hidden_size=2240, patch_size=(1,1,1), num_heads=20 — أي الإصدار العام `Efficient-Large-Model/SANA-WM_bidirectional`). تعمل `save_pretrained` / `from_pretrained` مباشرةً عبر [ConfigMixin](/docs/diffusers/main/ar/api/configuration#diffusers.ConfigMixin).

تعمل كل كتلة على انتباه مشروط بالكاميرا (UCPE): [*BidirectionalGDNUCPESinglePathLiteLA*]، باستثناء كل كتلة رقمها `softmax_every_n` التي تعمل على نظيرها الخاص بـ softmax [*_SoftmaxUCPESinglePathLiteLA*].

يكون ملف الحالة (state-dict) مطابقًا تمامًا لنقطة التفتيش (checkpoint) العامة الخاصة بـ sana باستثناء مخزن `pos_embed` الذي تم حذفه عمدًا.

#### forward[[diffusers.SanaWMTransformer3DModel.forward]]

```python
forward(hidden_states: torch.Tensor, timestep: torch.Tensor, encoder_hidden_states: torch.Tensor, encoder_attention_mask: torch.Tensor | None = None, mask: torch.Tensor | None = None, return_dict: bool = True, data_info: Optional[dict] = None, camera_conditions: torch.Tensor | None = None, chunk_plucker: torch.Tensor | None = None, cam_pos_embeds: Optional[dict] = None, pos_embeds: torch.Tensor | None = None, raymats: torch.Tensor | None = None, frame_valid_mask: torch.Tensor | None = None, chunk_size: int | None = None)
```

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

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

hidden_states : `(B, C, T, H, W)` كامنات.

timestep : `(B, 1, T)` خطوات الانتشار لكل إطار (بأسلوب LTX).

encoder_hidden_states : `(B, 1, L, D_caption)` تمثيلات نصية.

encoder_attention_mask : `(B, L)` قناع الانتباه للنص (وفقًا لاتفاقية diffusers).

mask : اسم بديل لـ `encoder_attention_mask` يتطابق مع اسم معامل kwarg الخاص بـ sana DiT. إذا تم تمرير كلاهما، فإن `mask` له الأولوية.

return_dict : إذا كان `True` (الافتراضي)، يُرجع `Transformer2DModelOutput`؛ وإلا يُرجع tuple واحد `(sample,)`.

data_info : شروط إضافية؛ يُدمج `data_info["image_vae_embeds"]` مع الكمونات على محور القناة عند وجوده.

camera_conditions : `(B, T, 20)` شروط الكاميرا الخام التي تُشغّل فرع التحكم بالكاميرا (UCPE).

chunk_plucker : تضمينات أشعة Plucker `(B, C, T, H, W)`، تُستهلك عندما يتم تكوين النموذج باستخدام `use_chunk_plucker_input` / `use_chunk_plucker_post_attn`.

cam_pos_embeds : تضمينات موضعية للكاميرا محسوبة مسبقًا بشكل اختياري (عناصر `"absmap"` / `"P"`) تُعاد استخدامها بدلًا من إعادة حسابها.

pos_embeds : تضمينات مواقع دوّارة محسوبة مسبقًا اختيارية؛ عند كونها `None` يتم بناؤها من شكل الكمون.

raymats : مصفوفات أشعة UCPE المحسوبة مسبقًا (اختياري) (تُستخدم فقط عندما لا يحمل `cam_pos_embeds` `"P"`).

frame_valid_mask : قناع صلاحية اختياري لكل إطار، على شكل `(B, 1, T, 1, 1)`، `(B, 1, T)` أو `(B, T)`.

chunk_size : طول المقطع المُعاد إلى الكتل؛ في حال عدم توفره، يُعتمد على `chunk_size` المُهيأ لكل كتلة.

**يعيد:**

`Transformer2DModelOutput` مع `sample` من الشكل `(B, C, T, H, W)`.

شغّل SANA-WM DiT.

#### unpatchify[[diffusers.SanaWMTransformer3DModel.unpatchify]]

```python
unpatchify(x, post_patch_num_frames, post_patch_height, post_patch_width)
```

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

x: (N, T, patch_size**2 * C) imgs: (N, H, W, C)

## 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).