# SanaWMLTX2RefinerTransformer3DModel

[SanaWMPipeline](/docs/diffusers/main/tr/api/pipelines/sana_wm#diffusers.SanaWMPipeline)'in 2. aşaması olarak kullanılan, [SanaWMLTX2Refiner](/docs/diffusers/main/tr/api/pipelines/sana_wm#diffusers.SanaWMLTX2Refiner) tarafından yönlendirilen parça-nedensel otoregresif iyileştirici DiT.

[LTX2VideoTransformer3DModel](/docs/diffusers/main/tr/api/models/ltx2_video_transformer3d#diffusers.LTX2VideoTransformer3DModel) ile mimari olarak özdeştir — aynı yapılandırma argümanları, aynı alt modüller, aynı parametre adları — bu nedenle yayınlanmış bir LTX-2 kontrol noktası, değişiklik yapılmadan içine yüklenir. İleri geçiş farklıdır:

* yalnızca video akışı çalıştırılır (ses ve ses/video çapraz dikkat dalları atlanır),
* self-attention, açık bir kayan pencere KV önbelleği (`SanaWMRefinerKVCache`) ile çalışır; bu önbellek dikkat çukurunu (attention sink) ve son zamanlardaki rafine edilmiş geçmişi barındırır, böylece blok başına hesaplama sınırlı kalır ve toplam rafine etme maliyeti video uzunluğuyla doğrusal olarak ölçeklenir,
* çağrıcı, video RoPE'yi sağlar; bu sayede her otoregresif pencere, kaynak videodaki her karenin mutlak indeksini koruyabilir (bkz. [SanaWMLTX2RefinerTransformer3DModel.build_rotary_emb_for_absolute_positions()](/docs/diffusers/main/tr/api/models/sana_wm_refiner_transformer3d#diffusers.SanaWMLTX2RefinerTransformer3DModel.build_rotary_emb_for_absolute_positions)).

Model şu şekilde yüklenebilir:

```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 = (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)
```

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_sana_wm_refiner.py#L1122)

**Parametreler:**

in_channels (`int`, varsayılan `128`) : Girdideki kanal sayısı.

out_channels (`int`, varsayılan `128`) : Çıktıdaki kanal sayısı.

patch_size (`int`, varsayılan `1`) : Yama gömme katmanında kullanılacak uzamsal yamaların boyutu.

patch_size_t (`int`, varsayılan `1`) : Yama gömme katmanında kullanılacak zamansal yamaların boyutu.

num_attention_heads (`int`, varsayılan `32`) : Çok başlı dikkat için kullanılacak baş sayısı.

attention_head_dim (`int`, varsayılan `128`) : Her baştaki kanal sayısı.

cross_attention_dim (`int`, varsayılan `4096`) : Çapraz dikkat başlıkları için kanal sayısı.

num_layers (`int`, varsayılan `48`) : Kullanılacak Transformer bloğu katman sayısı.

activation_fn (`str`, varsayılan `"gelu-approximate"`) : İleri beslemeli ağda kullanılacak aktivasyon fonksiyonu.

qk_norm (`str`, varsayılan `"rms_norm_across_heads"`) : Kullanılacak normalizasyon katmanı.

rope_type (`str`, varsayılan `"interleaved"`) : Hangi RoPE uygulamasının kullanılacağı (`"interleaved"` veya `"split"`).

SANA-WM'nin 2. aşaması olarak kullanılan parça-nedensel otoregresif rafineleyici dönüştürücü.

[LTX2VideoTransformer3DModel](/docs/diffusers/main/tr/api/models/ltx2_video_transformer3d#diffusers.LTX2VideoTransformer3DModel) ile mimari olarak aynıdır — aynı yapılandırma argümanları, aynı alt modüller, aynı parametre adları — bu nedenle yayınlanmış bir LTX-2 kontrol noktası, değişiklik yapılmadan içine yüklenir. Farklı olan ileri geçiştir:

* yalnızca video akışı çalıştırılır (ses ve ses/video çapraz dikkat dalları atlanır),
* self-attention, açık bir kayan pencere KV önbelleği (`SanaWMRefinerKVCache`) ile çalışır; bu önbellek dikkat çukurunu (attention sink) ve son zamanlardaki rafine edilmiş geçmişi barındırır, böylece rafine etme maliyeti AR blok başına sınırlı kalır ve video uzunluğuyla doğrusal olarak ölçeklenir,
* çağrıcı, video RoPE'yi sağlar; bu sayede her AR penceresi, kaynak videodaki her karenin mutlak indeksini koruyabilir (bkz. [build_rotary_emb_for_absolute_positions()](/docs/diffusers/main/tr/api/models/sana_wm_refiner_transformer3d#diffusers.SanaWMLTX2RefinerTransformer3DModel.build_rotary_emb_for_absolute_positions)).

Kalan argümanlar [LTX2VideoTransformer3DModel](/docs/diffusers/main/tr/api/models/ltx2_video_transformer3d#diffusers.LTX2VideoTransformer3DModel) ile birebir örtüşür. Ses tarafındaki argümanlar ve alt modüller, yalnızca kontrol noktasındaki ses ağırlıklarının geri dönüşümünü sağlamak için korunur; refiner ileri geçişinde kullanılmazlar.

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

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

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_sana_wm_refiner.py#L1388)

**Parametreler:**

batch_size (`int`) : Koordinatların yayınlanacağı batch boyutu.

frame_positions (`list[int]`) : Bu pencere tarafından kapsanan mutlak gizli çerçeve indeksleri.

height (`int`), genişlik (`int`) : Gizli uzamsal çözünürlük.

device (`torch.device`) : Koordinatların oluşturulacağı cihaz.

fps (`float`) : LTX-2'nin zamansal RoPE ölçeklemesini belirleyen video kare hızı.

**Dönüş:** `tuple[torch.Tensor, torch.Tensor]`

`(cos, sin)` RoPE demeti.

Belirli bir mutlak gizli çerçeve indeksi listesi için video RoPE'yi oluşturun.

`SanaWMLTX2AudioVideoRotaryPosEmbed.prepare_video_coords`, ardışık bir `torch.arange(num_frames)` dizisi varsayar; bu, çift yönlü çıkarım için uygundur. Kayan pencere AR iyileştiricisi ise her karenin kaynak videodaki mutlak indeksini korumalıdır, böylece RoPE, `[sink + recent + active]` penceresi boyunca doğru zaman fazını yakalar.

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

```python
forward(hidden_states: Tensor, encoder_hidden_states: Tensor, timestep: Tensor, video_rotary_emb: tuple, 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)
```

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_sana_wm_refiner.py#L1445)

**Parametreler:**

hidden_states (`torch.Tensor`) : Aktif bloğun patchlenmiş video latentleri, şekli `(batch_size, num_video_tokens, in_channels)`.

encoder_hidden_states (`torch.Tensor`) : `(batch_size, text_seq_len, caption_channels)` biçiminde metin gömme değerleri.

timestep (`torch.Tensor`) : `(batch_size, num_video_tokens)` biçiminde, `self.config.timestep_scale_multiplier` ile ölçeklenmiş zaman adımı.

video_rotary_emb (`tuple[torch.Tensor, torch.Tensor]`) : Aktif bloğun mutlak çerçeve konumları için [build_rotary_emb_for_absolute_positions()](/docs/diffusers/main/tr/api/models/sana_wm_refiner_transformer3d#diffusers.SanaWMLTX2RefinerTransformer3DModel.build_rotary_emb_for_absolute_positions) tarafından döndürülen `(cos, sin)` RoPE.

encoder_attention_mask (`torch.Tensor`, *isteğe bağlı*) : `(batch_size, text_seq_len)` biçiminde çarpımsal metin dikkat maskesi.

kv_cache (`SanaWMRefinerKVCache`, *isteğe bağlı*) : Katman başına dikkat çukuru (attention sink) ve son zamanlarda rafine edilmiş geçmişi tutan kayan pencere KV önbelleği, ayrıca paylaşılan `sink_pe` RoPE. `kv_cache_mode` ayarlandığında her zaman gereklidir.

kv_cache_mode (`str`, *isteğe bağlı*) : Şunlardan biri: - `"inject"`: `[sink + history + current]` K/V'lerine (gürültü azaltma adımları) dikkat edin. - `"capture_pre_rope"`: önek yok; bu ileri geçişin RoPE öncesi K/V'lerini önbelleğe kaydedin (dikkat çukurunu ham 1. aşama gürültülerinden tohumlamak için bir kez kullanılır). - `"inject_and_capture_post_rope"`: `[sink + history + current]` K/V'lerine dikkat edin ve bu bloğun RoPE sonrası K/V'lerini önbelleğe kaydedin, böylece geçmişe eklenebilir. `None` olduğunda, blok yalnızca geçerli jetonlar üzerinde düz tam öz-dikkat çalıştırır.

attention_kwargs (`dict`, *isteğe bağlı*) : LoRA ölçek işleme iletilen isteğe bağlı kwargs.

return_dict (`bool`, *isteğe bağlı*, varsayılan `True`) : Düz bir tuple yerine [Transformer2DModelOutput](/docs/diffusers/main/tr/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput) döndürülüp döndürülmemesi.

**Dönüş:** [Transformer2DModelOutput](/docs/diffusers/main/tr/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput) veya `tuple`

aktif blok için tahmini hız, şekli `(batch_size, num_video_tokens, out_channels)`.

Tek bir AR bloğu üzerinde yalnızca video ileri geçişi.

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

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_sana_wm_refiner.py#L757)

**Parametreler:**

num_layers (*int*) : Katman başına bir önbellek ayırmak için tahsis edilecek dönüştürücü bloklarının sayısı.

Her dönüştürücü bloğu için bir [*SanaWMRefinerKVLayerCache*] ve paylaşılan sink RoPE içeren konteyner.

Bu, SANA-WM 2. aşama iyileştiricisinin eğitildiği `rf_shifted_sink` KV önbellek sözleşmesini uygular. İyileştirme parça-nedenseldir: *block_size* gizli çerçeve bir anda gürültüden arındırılırken, *[dikkat çukuru + yakın geçmiş + aktif blok]* sınırlı penceresindeki K/V'lerine dikkat edilir.

- `sink_pe`: *(cos, sin)* RoPE demeti, kayan `sink_rope_offset` üzerinde her AR penceresi için yeniden oluşturulur; böylece sink, sınırlı çalışma önbelleğinin hemen öncesinde konumlanır. RoPE katmana bağlı olmadığı için katmanlar arasında paylaşıldır.

## 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()
```

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_sana_wm_refiner.py#L668)

SANA-WM stage-2 chunk-causal AR refiner için katman başına KV önbelleği.

Refiner'in kendine dikkat (self-attention) mekanizmasının odaklandığı kayan pencere önekinin iki yarısını ve son ileri geçişin yakaladığı K/V'yi geri okumak için bir yuva tutar. Tüm tensörler *(batch_size, num_tokens, inner_dim)* biçimindedir (yani baş başına unflatten işleminden önce) ve refiner'in kendine dikkat mekanizmasının birleştirdiği yerleşimle eşleşir.

- `sink_k_pre` / `sink_v`: **pre**-RoPE K/V, dikkat çukur (attention-sink) karelerine ait, ham 1. aşama latentlerinden bir kez yakalanan değerler. RoPE uygulanmadan önce saklanırlar; böylece her AR penceresi, kendi kaydırılmış çukur ofsetinde RoPE'yi yeniden uygulayabilir (`SanaWMRefinerKVCache.sink_pe`).
- `history_k` / `history_v`: **post**-RoPE K/V, zaten iyileştirilmiş son karelerin, olduğu gibi birleştirilmeye hazır hali.
- `captured_k_pre` / `captured_v_pre` ve `captured_k_post` / `captured_v_post`: yakalama `kv_cache_mode`leri tarafından yazılan geri okuma yuvaları.

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

```python
get_captured_post_rope()
```

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_sana_wm_refiner.py#L736)

Son ileri geçişte yakalanan RoPE sonrası K/V'yi çıkarın.

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

```python
get_captured_pre_rope()
```

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_sana_wm_refiner.py#L722)

Son ileri geçişte yakalanan RoPE öncesi K/V değerlerini çıkarın.

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

```python
get_history()
```

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_sana_wm_refiner.py#L711)

RoPE sonrası son tarihli K/V'yi döndürür, boşsa `None`.

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

```python
get_sink()
```

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_sana_wm_refiner.py#L700)

Pre-RoPE sink K/V'yi döndürür, yakalanmamışsa (veya boşsa) `None` döndürür.

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

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_sana_wm_refiner.py#L731)

Mevcut ileri geçiş tarafından üretilen RoPE sonrası K/V'yi saklayın.

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

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_sana_wm_refiner.py#L717)

Mevcut ileri yayılım tarafından üretilen RoPE öncesi K/V değerlerini saklayın.

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

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

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_sana_wm_refiner.py#L706)

RoPE sonrası son tarihli K/V'yi saklayın.

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

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

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_sana_wm_refiner.py#L695)

RoPE öncesi sink K/V'lerini saklayın.

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

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/modeling_outputs.py#L21)

**Parametreler:**

sample (`torch.Tensor`, şekli `(batch_size, num_channels, height, width)` veya [Transformer2DModel](/docs/diffusers/main/tr/api/models/transformer2d#diffusers.Transformer2DModel) ayrık (discrete) ise `(batch size, num_vector_embeds - 1, num_latent_pixels)`) : `encoder_hidden_states` girdisine koşullu gizli durum (hidden states) çıktısı. Ayrık (discrete) ise, gürültüsü olmayan (unnoised) gizli (latent) pikseller için olasılık dağılımlarını döndürür.

[Transformer2DModel](/docs/diffusers/main/tr/api/models/transformer2d#diffusers.Transformer2DModel)'nin çıktısı.