# SanaWMLTX2RefinerTransformer3DModel

Refiner DiT autoregresif kausal-chunk yang digunakan sebagai tahap 2 dari [SanaWMPipeline](/docs/diffusers/main/id/api/pipelines/sana_wm#diffusers.SanaWMPipeline), digerakkan oleh [SanaWMLTX2Refiner](/docs/diffusers/main/id/api/pipelines/sana_wm#diffusers.SanaWMLTX2Refiner).

Secara arsitektur, model ini identik dengan [LTX2VideoTransformer3DModel](/docs/diffusers/main/id/api/models/ltx2_video_transformer3d#diffusers.LTX2VideoTransformer3DModel) — argumen konfigurasi yang sama, submodul yang sama, nama parameter yang sama — sehingga checkpoint LTX-2 yang dirilis dapat dimuat ke dalamnya tanpa perubahan. Jalur forward-nya berbeda:

* hanya stream video yang dijalankan (cabang cross-attention audio dan audio/video dilewati),
* self-attention berjalan terhadap KV cache sliding-window eksplisit (`SanaWMRefinerKVCache`) yang menyimpan attention sink serta riwayat refined yang baru, sehingga komputasi per blok dibatasi dan total biaya refinement berskala linear dengan panjang video,
* pemanggil menyediakan video RoPE, yang memungkinkan setiap jendela autoregresif mempertahankan indeks absolut setiap frame dalam video sumber (lihat [SanaWMLTX2RefinerTransformer3DModel.build_rotary_emb_for_absolute_positions()](/docs/diffusers/main/id/api/models/sana_wm_refiner_transformer3d#diffusers.SanaWMLTX2RefinerTransformer3DModel.build_rotary_emb_for_absolute_positions)).

Model dapat dimuat dengan:

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

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

**Parameter:**

in_channels (`int`, defaultnya `128`) : Jumlah channel pada input.

out_channels (`int`, defaultnya `128`) : Jumlah channel pada output.

patch_size (`int`, defaultnya `1`) : Ukuran patch spasial yang akan digunakan di lapisan patch embedding.

patch_size_t (`int`, defaultnya `1`) : Ukuran patch temporal yang akan digunakan di lapisan patch embedding.

num_attention_heads (`int`, defaultnya `32`) : Jumlah kepala yang digunakan untuk multi-head attention.

attention_head_dim (`int`, defaultnya `128`) : Jumlah channel di setiap head.

cross_attention_dim (`int`, defaultnya `4096`) : Jumlah channel untuk cross attention heads.

num_layers (`int`, defaultnya `48`) : Jumlah lapisan blok Transformer yang akan digunakan.

activation_fn (`str`, defaultnya `"gelu-approximate"`) : Fungsi aktivasi yang digunakan dalam feed-forward.

qk_norm (`str`, defaultnya `"rms_norm_across_heads"`) : Lapisan normalisasi yang akan digunakan.

rope_type (`str`, defaultnya `"interleaved"`) : Aplikasi RoPE mana yang akan digunakan (`"interleaved"` atau `"split"`).

Transformer autoregresif penyempurna kausal-chunk yang digunakan sebagai tahap 2 SANA-WM.

Secara arsitektur identik dengan [LTX2VideoTransformer3DModel](/docs/diffusers/main/id/api/models/ltx2_video_transformer3d#diffusers.LTX2VideoTransformer3DModel) — argumen konfigurasi yang sama, submodul yang sama, nama parameter yang sama — sehingga checkpoint LTX-2 yang dirilis dapat dimuat ke dalamnya tanpa perubahan. Yang berbeda adalah jalur forward:

* hanya stream video yang dijalankan (cabang cross-attention audio dan audio/video dilewati),
* self-attention berjalan terhadap cache KV sliding-window eksplisit (`SanaWMRefinerKVCache`) yang menyimpan attention sink plus riwayat refined terbaru, sehingga biaya refinement dibatasi per blok AR dan berskala linear dengan panjang video,
* pemanggil menyediakan RoPE video, yang memungkinkan setiap jendela AR mempertahankan indeks absolut setiap frame dalam video sumber (lihat [build_rotary_emb_for_absolute_positions()](/docs/diffusers/main/id/api/models/sana_wm_refiner_transformer3d#diffusers.SanaWMLTX2RefinerTransformer3DModel.build_rotary_emb_for_absolute_positions)).

Argumen yang tersisa mencerminkan [LTX2VideoTransformer3DModel](/docs/diffusers/main/id/api/models/ltx2_video_transformer3d#diffusers.LTX2VideoTransformer3DModel) satu per satu. Argumen dan submodul sisi audio dipertahankan murni agar bobot audio checkpoint dapat di-round-trip; mereka tidak digunakan oleh forward refiner.

#### 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[int], height: int, width: int, device: device, fps: float)
```

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

**Parameter:**

batch_size (`int`) : Ukuran batch untuk menyiarkan koordinat.

frame_positions (`list[int]`) : Indeks frame laten absolut yang dicakup oleh jendela ini.

height (`int`), lebar (`int`) : Resolusi spasial laten.

device (`torch.device`) : Perangkat untuk membangun koordinat di atasnya.

fps (`float`) : Laju bingkai video, yang menggerakkan penskalaan RoPE temporal LTX-2.

**Mengembalikan:** `tuple[torch.Tensor, torch.Tensor]`

tuple RoPE `(cos, sin)`.

Bangun video RoPE untuk daftar eksplisit indeks frame laten absolut.

`SanaWMLTX2AudioVideoRotaryPosEmbed.prepare_video_coords` mengasumsikan `torch.arange(num_frames)` yang berurutan, yang tidak masalah untuk inferensi bidireksional. Refiner AR sliding-window justru perlu mempertahankan indeks absolut setiap frame dalam video sumber, sehingga RoPE menangkap fase temporal yang benar di seluruh jendela `[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)
```

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

**Parameter:**

hidden_states (`torch.Tensor`) : Laten video yang telah dipatch dari blok aktif, dengan bentuk `(batch_size, num_video_tokens, in_channels)`.

encoder_hidden_states (`torch.Tensor`) : Embedding teks dengan bentuk `(batch_size, text_seq_len, caption_channels)`.

timestep (`torch.Tensor`) : Timestep dengan bentuk `(batch_size, num_video_tokens)`, yang sudah diskalakan oleh `self.config.timestep_scale_multiplier`.

video_rotary_emb (`tuple[torch.Tensor, torch.Tensor]`) : RoPE `(cos, sin)` untuk posisi frame absolut dari blok aktif, sebagaimana dikembalikan oleh [build_rotary_emb_for_absolute_positions()](/docs/diffusers/main/id/api/models/sana_wm_refiner_transformer3d#diffusers.SanaWMLTX2RefinerTransformer3DModel.build_rotary_emb_for_absolute_positions).

encoder_attention_mask (`torch.Tensor`, *opsional*) : Mask perhatian teks multiplikatif dengan bentuk `(batch_size, text_seq_len)`.

kv_cache (`SanaWMRefinerKVCache`, *opsional*) : KV cache sliding-window yang menyimpan attention sink per-lapisan dan riwayat refined terbaru, serta `sink_pe` RoPE bersama. Wajib digunakan setiap kali `kv_cache_mode` disetel.

kv_cache_mode (`str`, *opsional*) : Salah satu dari: - `"inject"`: perhatikan `[sink + history + current]` K/V (langkah-langkah denoising). - `"capture_pre_rope"`: tanpa prefiks; rekam K/V pre-RoPE dari forward ini ke dalam cache (digunakan sekali untuk menabur attention sink dari latens stage-1 mentah). - `"inject_and_capture_post_rope"`: perhatikan `[sink + history + current]` K/V dan rekam K/V post-RoPE dari blok ini ke dalam cache agar dapat ditambahkan ke history. Ketika `None`, blok menjalankan self-attention penuh biasa hanya pada token saat ini.

attention_kwargs (`dict`, *opsional*) : Kwargs opsional yang diteruskan ke penanganan skala LoRA.

return_dict (`bool`, *opsional*, defaultnya `True`) : Apakah akan mengembalikan [Transformer2DModelOutput](/docs/diffusers/main/id/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput) alih-alih tuple biasa.

**Mengembalikan:** [Transformer2DModelOutput](/docs/diffusers/main/id/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput) atau `tuple`

kecepatan yang diprediksi untuk blok aktif, dengan bentuk `(batch_size, num_video_tokens, out_channels)`.

Lewatan maju hanya video atas satu blok 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)
```

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

**Parameter:**

num_layers (*int*) : Jumlah blok transformer untuk mengalokasikan cache per lapisan.

Wadah yang menyimpan satu [*SanaWMRefinerKVLayerCache*] per blok transformer, ditambah sink RoPE bersama.

Ini mengimplementasikan kontrak KV-cache `rf_shifted_sink` yang digunakan saat pelatihan refiner stage-2 SANA-WM. Penyempurnaan bersifat chunk-causal: *block_size* frame laten didenois sekaligus sambil memperhatikan jendela terbatas dari *[attention sink + riwayat terbaru + blok aktif]* K/V.

- `sink_pe`: tuple RoPE *(cos, sin)* untuk frame sink, dibangun ulang per jendela AR pada `sink_rope_offset` yang bergeser sehingga sink berada tepat sebelum cache kerja yang terbatas. Dibagikan antar lapisan karena RoPE tidak bergantung pada lapisan.

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

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

Cache KV per layer untuk refiner AR chunk-causal tahap-2 SANA-WM.

Menyimpan dua bagian dari prefix sliding-window yang menjadi fokus self-attention refiner, ditambah slot untuk membaca kembali K/V yang ditangkap oleh forward terakhir. Semua tensor berukuran *(batch_size, num_tokens, inner_dim)* (yaitu sebelum unflatten per-head), sesuai dengan layout yang digabungkan oleh self-attention refiner.

- `sink_k_pre` / `sink_v`: **pre**-RoPE K/V dari frame attention-sink, diambil sekali dari latens stage-1 mentah. Nilai ini disimpan dalam bentuk pre-RoPE sehingga setiap jendela AR dapat menerapkan ulang RoPE pada offset sink yang digeser sesuai posisinya (`SanaWMRefinerKVCache.sink_pe`).
- `history_k` / `history_v`: K/V **post**-RoPE dari frame-frame terbaru yang sudah disempurnakan, siap untuk digabungkan apa adanya.
- `captured_k_pre` / `captured_v_pre` dan `captured_k_post` / `captured_v_post`: slot readback yang ditulis oleh `kv_cache_mode` capture.

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

```python
get_captured_post_rope()
```

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

Ambil K/V pasca-RoPE yang ditangkap oleh forward terakhir.

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

```python
get_captured_pre_rope()
```

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

Ambil K/V pra-RoPE yang ditangkap oleh forward terakhir.

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

```python
get_history()
```

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

Kembalikan K/V riwayat-recent pasca-RoPE, atau `None` jika kosong.

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

```python
get_sink()
```

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

Kembalikan sink K/V pre-RoPE, atau `None` jika belum ditangkap (atau kosong).

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

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

Simpan K/V pasca-RoPE yang dihasilkan oleh forward saat ini.

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

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

Simpan K/V pra-RoPE yang dihasilkan oleh forward saat ini.

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

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

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

Simpan K/V riwayat terbaru pasca-RoPE.

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

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

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

Simpan K/V sink pra-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)
```

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

**Parameter:**

sample (`torch.Tensor` dengan bentuk `(batch_size, num_channels, height, width)` atau `(batch size, num_vector_embeds - 1, num_latent_pixels)` jika [Transformer2DModel](/docs/diffusers/main/id/api/models/transformer2d#diffusers.Transformer2DModel) bersifat diskrit) : Output hidden states yang dikondisikan pada input `encoder_hidden_states`. Jika diskrit, mengembalikan distribusi probabilitas untuk piksel laten yang tidak berisik.

Output dari [Transformer2DModel](/docs/diffusers/main/id/api/models/transformer2d#diffusers.Transformer2DModel).