# SanaWMLTX2RefinerTransformer3DModel

El refiner DiT autoregresivo causal por bloques utilizado como etapa 2 de [SanaWMPipeline](/docs/diffusers/v0.43.0/es/api/pipelines/sana_wm#diffusers.SanaWMPipeline), impulsado por [SanaWMLTX2Refiner](/docs/diffusers/v0.43.0/es/api/pipelines/sana_wm#diffusers.SanaWMLTX2Refiner).

Es arquitectónicamente idéntico a [LTX2VideoTransformer3DModel](/docs/diffusers/v0.43.0/es/api/models/ltx2_video_transformer3d#diffusers.LTX2VideoTransformer3DModel): mismos argumentos de configuración, mismos submódulos, mismos nombres de parámetros, por lo que un checkpoint de LTX-2 publicado se carga en él sin cambios. La pasada hacia adelante (forward pass) difiere:

* solo se ejecuta el flujo de video (se omiten las ramas de atención cruzada de audio y audio/video),
* self-attention se ejecuta contra una caché KV de ventana deslizante explícita (`SanaWMRefinerKVCache`) que mantiene el attention sink junto con el historial refinado reciente, de modo que el cómputo por bloque está acotado y el costo total de refinamiento escala linealmente con la longitud del video,
* el llamador proporciona el RoPE del video, lo que permite que cada ventana autoregresiva conserve el índice absoluto de cada fotograma en el video de origen (ver [SanaWMLTX2RefinerTransformer3DModel.build_rotary_emb_for_absolute_positions()](/docs/diffusers/v0.43.0/es/api/models/sana_wm_refiner_transformer3d#diffusers.SanaWMLTX2RefinerTransformer3DModel.build_rotary_emb_for_absolute_positions)).

El modelo se puede cargar con:

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

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

**Parámetros:**

in_channels (`int`, por defecto `128`) : El número de canales en la entrada.

out_channels (`int`, por defecto `128`) : El número de canales en la salida.

patch_size (`int`, por defecto `1`) : El tamaño de los parches espaciales a utilizar en la capa de incrustación de parches.

patch_size_t (`int`, por defecto `1`) : El tamaño de los parches temporales a utilizar en la capa de incrustación de parches.

num_attention_heads (`int`, por defecto `32`) : El número de cabezas a utilizar para la atención multi-cabeza.

attention_head_dim (`int`, por defecto `128`) : El número de canales en cada cabeza.

cross_attention_dim (`int`, por defecto `4096`) : El número de canales para las cabezas de atención cruzada.

num_layers (`int`, por defecto `48`) : El número de bloques de Transformer a utilizar.

activation_fn (`str`, por defecto `"gelu-approximate"`) : Función de activación a utilizar en la red feed-forward.

qk_norm (`str`, por defecto `"rms_norm_across_heads"`) : La capa de normalización a utilizar.

rope_type (`str`, por defecto `"interleaved"`) : Qué aplicación de RoPE usar (`"interleaved"` o `"split"`).

El transformer autoregresivo de refinamiento con causalidad por bloques utilizado como etapa 2 de SANA-WM.

Arquitectónicamente idéntico a [LTX2VideoTransformer3DModel](/docs/diffusers/v0.43.0/es/api/models/ltx2_video_transformer3d#diffusers.LTX2VideoTransformer3DModel): mismos argumentos de configuración, mismos submódulos, mismos nombres de parámetros, por lo que un checkpoint de LTX-2 publicado se carga en él sin cambios. Lo que difiere es el paso hacia adelante:

* solo se ejecuta el flujo de video (se omiten las ramas de atención cruzada de audio y audio/video),
* self-attention se ejecuta contra una caché KV de ventana deslizante explícita (`SanaWMRefinerKVCache`) que mantiene el attention sink junto con el historial refinado reciente, de modo que el costo de refinamiento está acotado por bloque AR y escala linealmente con la longitud del video,
* el llamador proporciona el RoPE del video, lo que permite que cada ventana de AR conserve el índice absoluto de cada fotograma en el video de origen (consulte [build_rotary_emb_for_absolute_positions()](/docs/diffusers/v0.43.0/es/api/models/sana_wm_refiner_transformer3d#diffusers.SanaWMLTX2RefinerTransformer3DModel.build_rotary_emb_for_absolute_positions)).

Los argumentos restantes replican uno a uno los de [LTX2VideoTransformer3DModel](/docs/diffusers/v0.43.0/es/api/models/ltx2_video_transformer3d#diffusers.LTX2VideoTransformer3DModel). Los argumentos y submódulos del lado de audio se conservan únicamente para que los pesos de audio del checkpoint se conserven al serializar y deserializar; no se utilizan en la propagación hacia adelante del 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)
```

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

**Parámetros:**

batch_size (`int`) : Tamaño del lote al que se deben difundir las coordenadas.

frame_positions (`list[int]`) : Índices absolutos de fotogramas latentes cubiertos por esta ventana.

height (`int`), anchura (`int`) : Resolución espacial latente.

device (`torch.device`) : Dispositivo en el que se construirán las coordenadas.

fps (`float`) : Tasa de fotogramas del video, que controla la escalada temporal de RoPE en LTX-2.

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

la tupla RoPE `(cos, sin)`.

Construya el RoPE de video para una lista explícita de índices absolutos de fotogramas latentes.

`SanaWMLTX2AudioVideoRotaryPosEmbed.prepare_video_coords` asume un `torch.arange(num_frames)` contiguo, lo cual es adecuado para la inferencia bidireccional. El refinador AR de ventana deslizante, en cambio, necesita mantener el índice absoluto de cada fotograma en el video de origen, de modo que RoPE capture la fase temporal correcta a lo largo de la ventana `[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)
```

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

**Parámetros:**

hidden_states (`torch.Tensor`) : Latentes de video parcheados del bloque activo, de forma `(batch_size, num_video_tokens, in_channels)`.

encoder_hidden_states (`torch.Tensor`) : Incrustaciones de texto de forma `(batch_size, text_seq_len, caption_channels)`.

timestep (`torch.Tensor`) : Paso temporal de forma `(batch_size, num_video_tokens)`, ya escalado por `self.config.timestep_scale_multiplier`.

video_rotary_emb (`tuple[torch.Tensor, torch.Tensor]`) : El RoPE `(cos, sin)` para las posiciones absolutas del marco activo del bloque, tal como lo devuelve [build_rotary_emb_for_absolute_positions()](/docs/diffusers/v0.43.0/es/api/models/sana_wm_refiner_transformer3d#diffusers.SanaWMLTX2RefinerTransformer3DModel.build_rotary_emb_for_absolute_positions).

encoder_attention_mask (`torch.Tensor`, *opcional*) : Máscara de atención de texto multiplicativa de forma `(batch_size, text_seq_len)`.

kv_cache (`SanaWMRefinerKVCache`, *opcional*) : Caché KV de ventana deslizante que almacena el sumidero de atención por capa y el historial refinado reciente, además del RoPE compartido `sink_pe`. Obligatorio siempre que se establezca `kv_cache_mode`.

kv_cache_mode (`str`, *opcional*) : Uno de:  - `"inject"`: prestar atención a `[sink + history + current]` K/V (los pasos de desruido). - `"capture_pre_rope"`: sin prefijo; registrar el K/V pre-RoPE de esta pasada en la caché (se usa una vez para inicializar el sumidero de atención desde los latentes crudos de la etapa 1). - `"inject_and_capture_post_rope"`: prestar atención a `[sink + history + current]` K/V y registrar el K/V post-RoPE de este bloque en la caché para que pueda agregarse al historial.  Cuando es `None`, el bloque ejecuta una autoatención completa simple solo sobre los tokens actuales.

attention_kwargs (`dict`, *opcional*) : Kwargs opcionales que se reenvían al manejo de la escala de LoRA.

return_dict (`bool`, *opcional*, valor predeterminado `True`) : Si se debe devolver un [Transformer2DModelOutput](/docs/diffusers/v0.43.0/es/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput) en lugar de una tupla simple.

**Devuelve:** [Transformer2DModelOutput](/docs/diffusers/v0.43.0/es/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput) o `tuple`

la velocidad predicha para el bloque activo, de forma `(batch_size, num_video_tokens, out_channels)`.

Paso de propagación hacia adelante solo de video sobre un solo bloque 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)
```

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

**Parámetros:**

num_layers (*int*) : Número de bloques de transformador para los que se asignará una caché por capa.

Contenedor que mantiene una instancia de *SanaWMRefinerKVLayerCache* por bloque de transformador, además del RoPE de sink compartido.

Esto implementa el contrato de KV-cache `rf_shifted_sink` con el que se entrenó el refinador de la etapa 2 de SANA-WM. El refinamiento es causal por bloques: se desruidifican *block_size* marcos latentes a la vez mientras se atiende a una ventana acotada de *[attention sink + historial reciente + bloque activo]* K/V.

- `sink_pe`: la tupla RoPE *(cos, sin)* para los cuadros de sink, reconstruida en cada ventana AR en el `sink_rope_offset` deslizante para que el sink se sitúe inmediatamente antes de la caché de trabajo acotada. Compartida entre capas porque RoPE no depende de la capa.

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

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

Cache KV por capa para el refinador AR causal por bloques de la etapa 2 de SANA-WM.

Contiene las dos mitades del prefijo de ventana deslizante al que atiende la autoatención del refiner, además de un espacio para leer de nuevo los K/V que capturó la última forward. Todos los tensores son *(batch_size, num_tokens, inner_dim)* (es decir, antes del unflatten por cabeza), coincidiendo con el layout que la autoatención del refiner concatena.

- `sink_k_pre` / `sink_v`: K/V **pre**-RoPE de los fotogramas de attention-sink, capturados una sola vez desde los latentes crudos de la etapa 1. Se almacenan pre-RoPE para que cada ventana AR pueda volver a aplicar RoPE en su propio desplazamiento de sink (`SanaWMRefinerKVCache.sink_pe`).
- `history_k` / `history_v`: K/V **post**-RoPE de los fotogramas recientes ya refinados, listos para concatenarse tal cual.
- `captured_k_pre` / `captured_v_pre` y `captured_k_post` / `captured_v_post`: ranuras de lectura escritas por los modos de captura `kv_cache_mode`.

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

```python
get_captured_post_rope()
```

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

Extrae los K/V posteriores a RoPE capturados por la última pasada hacia adelante.

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

```python
get_captured_pre_rope()
```

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

Extrae los K/V pre-RoPE capturados por el último paso de adelante.

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

```python
get_history()
```

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

Devuelve el K/V de historial reciente posterior a RoPE, o `None` si está vacío.

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

```python
get_sink()
```

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

Devuelve el K/V de sink pre-RoPE, o `None` si no se ha capturado (o está vacío).

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

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

Almacene el K/V posterior a RoPE generado por la propagación hacia adelante actual.

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

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

Almacene los K/V pre-RoPE generados por la propagación hacia adelante actual.

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

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

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

Almacene el K/V del historial reciente posterior a RoPE.

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

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

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

Almacene el K/V del sink pre-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)
```

[Fuente](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/modeling_outputs.py#L21)

**Parámetros:**

sample (`torch.Tensor` de forma `(batch_size, num_channels, height, width)` o `(batch size, num_vector_embeds - 1, num_latent_pixels)` si [Transformer2DModel](/docs/diffusers/v0.43.0/es/api/models/transformer2d#diffusers.Transformer2DModel) es discreto): las salidas de estados ocultos condicionadas a la entrada `encoder_hidden_states`. Si es discreto, devuelve distribuciones de probabilidad para los píxeles latentes sin ruido.

La salida de [Transformer2DModel](/docs/diffusers/v0.43.0/es/api/models/transformer2d#diffusers.Transformer2DModel).