# SanaWMLTX2RefinerTransformer3DModel

[SanaWMPipeline](/docs/diffusers/main/ko/api/pipelines/sana_wm#diffusers.SanaWMPipeline)의 2단계로 사용되며 [SanaWMLTX2Refiner](/docs/diffusers/main/ko/api/pipelines/sana_wm#diffusers.SanaWMLTX2Refiner)에 의해 구동되는 chunk-causal autoregressive refiner DiT입니다.

구조적으로 [LTX2VideoTransformer3DModel](/docs/diffusers/main/ko/api/models/ltx2_video_transformer3d#diffusers.LTX2VideoTransformer3DModel)과 동일합니다. 설정 인자, 서브모듈, 파라미터 이름이 모두 같으므로, 공개된 LTX-2 체크포인트를 그대로 로드할 수 있습니다. 포워드 패스만 다릅니다:

* 비디오 스트림만 실행됩니다(오디오 및 오디오/비디오 교차 주의력 브랜치는 건너뜁니다),
* self-attention은 attention sink와 최근 정제된 히스토리를 포함하는 명시적 슬라이딩 윈도우 KV 캐시(`SanaWMRefinerKVCache`)에 대해 실행되므로 블록당 계산량이 제한되고 전체 정제 비용은 비디오 길이에 선형적으로 비례합니다.
* 호출자가 비디오 RoPE를 제공하여, 각 자기회귀 윈도우가 소스 비디오에서 모든 프레임의 절대 인덱스를 유지할 수 있게 합니다(자세한 내용은 [SanaWMLTX2RefinerTransformer3DModel.build_rotary_emb_for_absolute_positions()](/docs/diffusers/main/ko/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 = (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#L1122)

**매개변수:**

in_channels (`int`, 기본값 `128`) : 입력의 채널 수.

out_channels (`int`, 기본값 `128`) : 출력의 채널 수.

patch_size (`int`, 기본값 `1`) : 패치 임베딩 레이어에서 사용할 공간 패치의 크기입니다.

patch_size_t (`int`, 기본값 `1`) : 패치 임베딩 레이어에서 사용할 시간적 패치의 크기입니다.

num_attention_heads (`int`, 기본값 `32`) : multi-head attention에 사용할 헤드 수입니다.

attention_head_dim (`int`, 기본값 `128`) : 각 헤드(head)의 채널 수입니다.

cross_attention_dim (`int`, 기본값 `4096`) : cross attention heads의 채널 수입니다.

num_layers (`int`, 기본값 `48`) : 사용할 Transformer 블록의 레이어 수입니다.

activation_fn (`str`, 기본값 `"gelu-approximate"`) : feed-forward에서 사용할 활성화 함수입니다.

qk_norm (`str`, 기본값 `"rms_norm_across_heads"`) : 사용할 정규화 레이어입니다.

rope_type (`str`, 기본값 `"interleaved"`) : 사용할 RoPE 적용 방식(`"interleaved"` 또는 `"split"`).

SANA-WM의 2단계로 사용되는 chunk-causal autoregressive refiner transformer입니다.

[LTX2VideoTransformer3DModel](/docs/diffusers/main/ko/api/models/ltx2_video_transformer3d#diffusers.LTX2VideoTransformer3DModel)와 아키텍처가 동일합니다. 설정 인자, 서브모듈, 파라미터 이름이 모두 같으므로, 공개된 LTX-2 체크포인트를 그대로 로드할 수 있습니다. 다른 점은 포워드 패스입니다:

* 비디오 스트림만 실행됩니다(오디오 및 오디오/비디오 교차 주의력 브랜치는 건너뜁니다),
* self-attention은 attention sink와 최근 정제된 히스토리를 포함하는 명시적 슬라이딩 윈도우 KV 캐시(`SanaWMRefinerKVCache`)에 대해 실행되므로, 정제 비용은 AR 블록당 상한이 설정되며 비디오 길이에 따라 선형으로 증가합니다.
* 호출자가 비디오 RoPE를 제공하여 각 AR 윈도우가 소스 비디오에서 모든 프레임의 절대 인덱스를 유지할 수 있게 합니다(자세한 내용은 [build_rotary_emb_for_absolute_positions()](/docs/diffusers/main/ko/api/models/sana_wm_refiner_transformer3d#diffusers.SanaWMLTX2RefinerTransformer3DModel.build_rotary_emb_for_absolute_positions) 참조).

나머지 인수는 [LTX2VideoTransformer3DModel](/docs/diffusers/main/ko/api/models/ltx2_video_transformer3d#diffusers.LTX2VideoTransformer3DModel)의 인수를 1:1로 그대로 따릅니다. 오디오 쪽 인수와 서브모듈은 체크포인트의 오디오 가중치가 왕복(round-trip)되도록 유지되는 것일 뿐이며, 리파이너 포워드에서는 사용되지 않습니다.

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

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

**매개변수:**

batch_size (`int`) : 좌표를 브로드캐스트할 배치 크기.

frame_positions (`list[int]`) : 이 윈도우가 포함하는 절대 잠재 프레임 인덱스.

height (`int`), width (`int`) : Latent 공간 해상도.

device (`torch.device`) : 좌표를 생성할 디바이스.

fps (`float`) : LTX-2의 시간적 RoPE 스케일링을 결정하는 비디오 프레임 속도입니다.

**반환값:** `tuple[torch.Tensor, torch.Tensor]`

`(cos, sin)` RoPE 튜플

명시된 절대 잠재 프레임 인덱스 목록에 대해 비디오 RoPE를 구성합니다.

`SanaWMLTX2AudioVideoRotaryPosEmbed.prepare_video_coords`는 연속적인 `torch.arange(num_frames)`을 가정하며, 이는 양방향 추론에는 문제가 없습니다. 반면, 슬라이딩 윈도우 AR 리파이너는 소스 비디오에서 각 프레임의 절대 인덱스를 유지해야 하므로, `[sink + recent + active]` 윈도우에 걸쳐 RoPE가 올바른 시간적 위상을 포착할 수 있습니다.

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

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

**매개변수:**

hidden_states (`torch.Tensor`) : 활성 블록의 패치화 된 비디오 latents. shape은 `(batch_size, num_video_tokens, in_channels)`입니다.

encoder_hidden_states (`torch.Tensor`) : `(batch_size, text_seq_len, caption_channels)` 형태의 텍스트 임베딩.

timestep (`torch.Tensor`) : `self.config.timestep_scale_multiplier`로 이미 스케일링된 `(batch_size, num_video_tokens)` 형태의 Timestep.

video_rotary_emb (`tuple[torch.Tensor, torch.Tensor]`) : [build_rotary_emb_for_absolute_positions()](/docs/diffusers/main/ko/api/models/sana_wm_refiner_transformer3d#diffusers.SanaWMLTX2RefinerTransformer3DModel.build_rotary_emb_for_absolute_positions)에서 반환된 활성 블록의 절대 프레임 위치를 위한 `(cos, sin)` RoPE입니다.

encoder_attention_mask (`torch.Tensor`, *선택 사항*) : `(batch_size, text_seq_len)` 형태의 곱셈 텍스트 어텐션 마스크.

kv_cache (`SanaWMRefinerKVCache`, *선택*) : 레이어별 attention sink와 최근 refined history를 저장하는 sliding-window KV 캐시이며, 공유 `sink_pe` RoPE를 포함합니다. `kv_cache_mode`가 설정된 경우 필수입니다.

kv_cache_mode (`str`, *선택 사항*) : 다음 중 하나: - `"inject"`: `[sink + history + current]` K/V(디노이징 단계)에 attend합니다. - `"capture_pre_rope"`: 접두사가 없으며, 이 forward의 pre-RoPE K/V를 캐시에 기록합니다(1단계 원시 잠재 변수로부터 attention sink를 시드하기 위해 한 번 사용됨). - `"inject_and_capture_post_rope"`: `[sink + history + current]` K/V에 attend하고, 이 블록의 post-RoPE K/V를 캐시에 기록하여 history에 추가할 수 있도록 합니다. `None`인 경우, 블록은 현재 토큰에 대해서만 일반 전체 자기 주의(full self-attention)를 실행합니다.

attention_kwargs (`dict`, *선택 사항*) : LoRA 스케일 처리로 전달되는 선택적 kwargs입니다.

return_dict (`bool`, *선택 사항*, 기본값 `True`) : 일반 튜플 대신 [Transformer2DModelOutput](/docs/diffusers/main/ko/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput)을 반환할지 여부.

**반환값:** [Transformer2DModelOutput](/docs/diffusers/main/ko/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput) 또는 `tuple`

`(batch_size, num_video_tokens, out_channels)` 모양의 활성 블록에 대한 예측 속도입니다.

단일 AR 블록에 대한 비디오 전용 forward pass.

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

**매개변수:**

num_layers (*int*) : 레이어별 캐시를 할당할 transformer 블록의 수.

각 transformer 블록마다 [*SanaWMRefinerKVLayerCache*] 하나를 포함하는 컨테이너이며, 공유 sink RoPE도 함께 포함합니다.

이 구현은 SANA-WM stage-2 refiner가 학습된 `rf_shifted_sink` KV-cache 계약을 따릅니다. 정제 과정은 chunk-causal 방식으로, *block_size*개의 latent 프레임을 한 번에 denoise하면서 *[attention sink + 최근 히스토리 + 활성 블록]*로 구성된 제한된 윈도우의 K/V에 attend합니다.

- `sink_pe`: sink 프레임에 대한 *(cos, sin)* RoPE 튜플입니다. 유한한 워킹 캐시 바로 앞에 sink가 위치하도록, 슬라이딩 `sink_rope_offset` 기준으로 각 AR 윈도우마다 재구성됩니다. 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#L668)

SANA-WM stage-2 chunk-causal AR refiner의 레이어별 KV 캐시.

refiner의 self-attention이 참조하는 sliding-window prefix의 두 부분을 보유하고, 마지막 forward에서 캡처한 K/V를 다시 읽기 위한 슬롯을 포함합니다. 모든 텐서는 *(batch_size, num_tokens, inner_dim)* 형태(즉, per-head unflatten 이전)이며, refiner의 self-attention이 연결(concatenate)하는 레이아웃과 일치합니다.

- `sink_k_pre` / `sink_v`: attention-sink 프레임의 **pre**-RoPE K/V입니다. raw stage-1 latents에서 한 번만 캡처됩니다. 각 AR 윈도우가 자체의 이동된 sink offset(`SanaWMRefinerKVCache.sink_pe`)에서 RoPE를 다시 적용할 수 있도록 pre-RoPE 상태로 저장됩니다.
- `history_k` / `history_v`: 이미 정제된 최근 프레임의 **post**-RoPE K/V로, 그대로 연결(concatenate)할 수 있는 상태입니다.
- `captured_k_pre` / `captured_v_pre` 및 `captured_k_post` / `captured_v_post`: 캡처 `kv_cache_mode`에 의해 기록되는 readback 슬롯입니다.

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

마지막 forward에서 포착한 post-RoPE K/V를 pop합니다.

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

마지막 forward에서 캡처된 pre-RoPE K/V를 pop합니다.

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

RoPE 적용 후 최근 히스토리 K/V를 반환하거나, 비어 있으면 `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#L700)

pre-RoPE sink K/V를 반환합니다. 캡처되지 않았거나(또는 비어 있으면) `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#L731)

현재 forward에서 생성된 post-RoPE K/V를 저장합니다.

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

현재 forward에서 생성된 pre-RoPE K/V를 저장합니다.

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

RoPE 적용 후 최근 히스토리의 K/V를 저장합니다.

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

RoPE 적용 전 sink K/V를 저장합니다.

## 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`, shape `(batch_size, num_channels, height, width)` 또는 [Transformer2DModel](/docs/diffusers/main/ko/api/models/transformer2d#diffusers.Transformer2DModel)이 discrete인 경우 `(batch size, num_vector_embeds - 1, num_latent_pixels)`) : `encoder_hidden_states` 입력에 조건부인 hidden states 출력입니다. discrete인 경우, 노이즈가 제거된 latent 픽셀에 대한 확률 분포를 반환합니다.

[Transformer2DModel](/docs/diffusers/main/ko/api/models/transformer2d#diffusers.Transformer2DModel)의 출력입니다.