# AnyFlowFARTransformer3DModel

El Transformer 3D causal (FAR) utilizado por [`AnyFlowFARPipeline`](../pipelines/anyflow#diffusers.AnyFlowFARPipeline) — la variante FAR de [AnyFlow](https://huggingface.co/papers/2605.13724). Consulte la página de [`AnyFlowFARPipeline`](../pipelines/anyflow) para ver el paper, los autores y los checkpoints publicados. Extiende el backbone de Wan2.1 v0.35.1 con tres adiciones:

1. **Máscara de bloques causal de FAR** mediante `torch.nn.attention.flex_attention`, que admite la generación autoregresiva por fragmentos tal como se introdujo en [FAR](https://huggingface.co/papers/2503.19325).
2. **Incrustado de parches de fotogramas comprimidos** (`far_patch_embedding`) para los fotogramas de contexto (ya generados), inicializado a partir del `patch_embedding` de resolución completa en el momento de la construcción mediante interpolación trilineal.
3. **Incrustado de flujo-mapa de doble paso temporal** (igual que [`AnyFlowTransformer3DModel`](anyflow_transformer3d)) — cada llamada de adelante se condiciona tanto en el paso temporal de origen ``t`` como en el paso temporal de destino ``r``.

El programa de bloques predeterminado (`chunk_partition`) se almacena en la configuración del modelo; los puntos de control NVIDIA AnyFlow-FAR publicados utilizan `[1, 3, 3, 3, 3, 3, 3, 2]` para la configuración canónica de 81 fotogramas. `forward` acepta una sobrescritura de `chunk_partition` por llamada, por lo que el mismo punto de control también maneja otras configuraciones de `num_frames` sin necesidad de volver a entrenar.

```python
from diffusers import AnyFlowFARTransformer3DModel

# Causal AnyFlow checkpoint (FAR):
transformer = AnyFlowFARTransformer3DModel.from_pretrained(
    "nvidia/AnyFlow-FAR-Wan2.1-1.3B-Diffusers", subfolder="transformer"
)
```

## AnyFlowFARTransformer3DModel[[diffusers.AnyFlowFARTransformer3DModel]]

#### diffusers.AnyFlowFARTransformer3DModel[[diffusers.AnyFlowFARTransformer3DModel]]

```python
diffusers.AnyFlowFARTransformer3DModel(patch_size: typing.Tuple[int] = (1, 2, 2), compressed_patch_size: typing.Tuple[int] = (1, 4, 4), full_chunk_limit: int = 3, num_attention_heads: int = 40, attention_head_dim: int = 128, in_channels: int = 16, out_channels: int = 16, text_dim: int = 4096, freq_dim: int = 256, ffn_dim: int = 13824, num_layers: int = 40, cross_attn_norm: bool = True, eps: float = 1e-06, image_dim: typing.Optional[int] = None, rope_max_seq_len: int = 1024, gate_value: float = 0.25, deltatime_type: str = 'r', chunk_partition: typing.Tuple[int, ...] = (1, 3, 3, 3, 3, 3, 3, 2))
```

[Fuente](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_anyflow_far.py#L961)

**Parámetros:**

patch_size (*Tuple[int]*, por defecto *(1, 2, 2)*) : dimensiones de parche 3D para fragmentos de resolución completa.

compressed_patch_size (*Tuple[int]*, por defecto *(1, 4, 4)*) : Dimensiones de parche más grandes para los fragmentos (contexto) comprimidos con FAR.

full_chunk_limit (*int*, por defecto *3*) : Número máximo de fragmentos de resolución completa antes de que los fragmentos anteriores se degraden a contexto FAR comprimido. Los puntos de control publicados usan `3`.

num_attention_heads (*int*, por defecto *40*) : Número de cabezas de atención.

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

in_channels (*int*, por defecto *16*) : El número de canales en el latente de entrada.

out_channels (*int*, por defecto *16*) : El número de canales en el latente de salida.

text_dim (*int*, por defecto *4096*) : Dimensión de entrada para las incrustaciones de texto (UMT5).

freq_dim (*int*, por defecto *256*) : Dimensión para las incrustaciones sinusoidales de tiempo.

ffn_dim (*int*, por defecto *13824*) : Dimensión intermedia en la red feed-forward.

num_layers (*int*, por defecto *40*) : Número de bloques de transformer.

cross_attn_norm (*bool*, por defecto *True*) : Habilita la normalización de la atención cruzada.

eps (*float*, por defecto *1e-6*) : Epsilon para las capas de normalización.

image_dim (*Optional[int]*, *opcional*, valor predeterminado *None*) : Dimensión del incrustado de imagen para el condicionamiento de I2V.

rope_max_seq_len (*int*, por defecto *1024*) : Longitud máxima de secuencia utilizada para precalcular las frecuencias de posición rotativa.

gate_value (*float*, por defecto *0.25*) : Puerta de mezcla entre las incrustaciones de paso de origen y paso delta.

deltatime_type (*str*, por defecto *'r'*) : Ya sea `"r"` (delta es el paso de tiempo objetivo) o `"t-r"` (delta es el intervalo absoluto).

chunk_partition (*Tuple[int, ...]*, por defecto *(1, 3, 3, 3, 3, 3, 3, 2)*) : Número de fotogramas por bloque utilizado por defecto en el pipeline. Los puntos de control NVIDIA AnyFlow-FAR publicados apuntan a `num_frames=81` (21 fotogramas latentes con un paso temporal de VAE de 4) divididos como `1 + 3*6 + 2`. Un `num_frames` diferente requiere una sobrecarga coincidente de `chunk_partition` pasada a [AnyFlowFARPipeline.__call__()](/docs/diffusers/main/es/api/pipelines/anyflow#diffusers.AnyFlowFARPipeline.__call__) (y de forma similar a `forward`).

Causal (FAR) 3D Transformer para el muestreo de mapas de flujo de AnyFlow con generación autoregresiva por bloques.

Extiende el backbone de Wan2.1 v0.35.1 con:

- **Máscara de bloque causal FAR** mediante `torch.nn.attention.flex_attention`, con soporte para generación autoregresiva por bloques ([FAR](https://huggingface.co/papers/2503.19325)).
- **Embedding de parches de fotogramas comprimidos** `far_patch_embedding` para los fotogramas de contexto (ya generados), inicializado a partir de `patch_embedding` mediante interpolación trilineal, de modo que un modelo recién construido ya parte de un punto de partida razonable incluso antes del ajuste fino con LoRA.
- **Incrustado de flujo-mapa de doble paso de tiempo** para muestreo de cualquier paso (igual que `AnyFlowTransformer3DModel`).

Usa `AnyFlowTransformer3DModel` en su lugar para T2V bidireccional simple: esa variante omite el enmascaramiento causal de FAR y `far_patch_embedding`, y es un 5–10 % más pequeña.

#### build_attention_mask[[diffusers.AnyFlowFARTransformer3DModel.build_attention_mask]]

```python
build_attention_mask(chunk_partition: typing.List[int], height: int, width: int, has_clean_context: bool = False, device: typing.Optional[torch.device] = None, mode: str = 'train')
```

[Fuente](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_anyflow_far.py#L1232)

**Parámetros:**

chunk_partition : número de fotogramas por bloque (deben sumar el número de fotogramas latentes).

height, width : dimensiones espaciales latentes.

has_clean_context : `True` cuando `clean_hidden_states` se transmitirá a través de `forward` (entrenamiento V2V/I2V); solo esta bandera de presencia afecta al diseño de la máscara.

device : dispositivo para el `BlockMask` resultante. La máscara no se mueve automáticamente con `device_map="auto"`; créala en el mismo dispositivo donde estarán las entradas del transformador.

mode : `"train"` (coincide con `_forward_train`) o `"cache"` (coincide con `_forward_cache`). La ruta autoregresiva `_forward_inference` atiende a través de la caché KV y no tiene modo aquí.

**Devuelve:** `~torch.nn.attention.flex_attention.BlockMask`

máscara causal que abarca el diseño FAR, rellena hasta un múltiplo de 128 a lo largo de la dimensión de secuencia (el requisito de tamaño de bloque de BlockMask).

**Excepciones:** `ValueError`

- `ValueError` -- si `mode` no es ni `"train"` ni `"cache"`.

Construya previamente la `~torch.nn.attention.flex_attention.BlockMask` causal fuera de `forward`.

Pase el resultado a través del argumento `attention_mask` de `forward` para hacer que todo el transformador sea compatible con `torch.compile(fullgraph=True)`. Sin una máscara preestablecida, `forward` recurre a construirla internamente; esa ruta utiliza `flex_attention.create_block_mask(_compile=False)` y rompe el grafo de compilación.

#### forward[[diffusers.AnyFlowFARTransformer3DModel.forward]]

```python
forward(hidden_states: Tensor, timestep: Tensor, r_timestep: Tensor, encoder_hidden_states: Tensor, chunk_partition: typing.List[int], encoder_hidden_states_image: typing.Optional[torch.Tensor] = None, clean_hidden_states: typing.Optional[torch.Tensor] = None, clean_timestep: typing.Optional[torch.Tensor] = None, kv_cache: typing.Optional[typing.List[typing.Dict[str, torch.Tensor]]] = None, kv_cache_flag: typing.Optional[typing.Dict[str, typing.Any]] = None, attention_mask: typing.Optional[torch.nn.attention.flex_attention.BlockMask] = None, attention_kwargs: typing.Optional[typing.Dict[str, typing.Any]] = None, return_dict: bool = True)
```

[Fuente](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_anyflow_far.py#L1098)

**Parámetros:**

hidden_states (*torch.Tensor*) : Entrada latente de forma `(B, F, C, H, W)`.

timestep (*torch.Tensor*) : Paso temporal *t* del mapa de flujo de origen (más ruidoso).

r_timestep (*torch.Tensor*) : Paso temporal *r* del mapa de flujo objetivo (más limpio).

encoder_hidden_states (*torch.Tensor*) : Embeddings de texto de UMT5.

chunk_partition (*List[int]*) : Número de fotogramas por bloque; el total debe coincidir con el número de fotogramas latentes en `hidden_states`.

encoder_hidden_states_image (*torch.Tensor*, *opcional*) : incrustación de imagen I2V; se concatena antes de los tokens de texto cuando se proporciona.

clean_hidden_states (*torch.Tensor*, *opcional*) : Marcos de condicionamiento limpios (sin ruido) utilizados por el despliegue de entrenamiento.

clean_timestep (*torch.Tensor*, *opcional*) : Pasos de tiempo para los fotogramas de condicionamiento limpios en el despliegue de entrenamiento.

kv_cache (*List[Dict[str, torch.Tensor]]*, *opcional*) : Caché KV por bloque para inferencia autoregresiva. *None* selecciona la ruta de entrenamiento.

kv_cache_flag (*Dict[str, Any]*, *opcional*) : Metadatos de la caché KV (p. ej., la bandera `is_cache_step` y los recuentos de tokens).

attention_mask (*BlockMask*, *opcional*) : Máscara causal predefinida, generalmente construida mediante `build_attention_mask`. Se utiliza en las rutas de entrenamiento y de prellenado de la caché KV; la ruta de inferencia autoregresiva atiende a través de la caché KV y no utiliza una máscara completa. Cuando es `None`, las rutas de entrenamiento / caché construyen la máscara internamente; esa alternativa no es segura para la compilación (la función subyacente `flex_attention.create_block_mask` rompe el grafo bajo `fullgraph=True`), por lo que se debe pasar una máscara predefinida siempre que se envuelva `forward` en `torch.compile`.

attention_kwargs (*dict*, *opcional*) : Se reenvía a los procesadores de atención.

return_dict (*bool*, *opcional*, valor predeterminado *True*) : Si es *False*, devuelve tuplas posicionales en lugar de una dataclass de salida.

**Devuelve:** [*~models.transformer_2d.Transformer2DModelOutput*], [*AnyFlowFARTransformerOutput*] o *tuple*

Cuando *return_dict* es *False*, se devuelve una *tuple* simple. En caso contrario, el despliegue de entrenamiento causal (*kv_cache is None*) devuelve un [*~models.transformer_2d.Transformer2DModelOutput*], mientras que las rutas de prellenado de caché e inferencia autoregresiva devuelven un [*AnyFlowFARTransformerOutput*].

Paso de propagación hacia adelante causal de FAR. Se despacha a una de tres rutas internas:

- `kv_cache is None` → despliegue de entrenamiento causal (devuelve `Transformer2DModelOutput`).
- `kv_cache is not None` y `kv_cache_flag["is_cache_step"]` → cache-prefill (devuelve `AnyFlowFARTransformerOutput` con `sample=None`).
- En caso contrario → paso de inferencia autoregresivo (devuelve `AnyFlowFARTransformerOutput`).

## AnyFlowFARTransformerOutput[[diffusers.models.transformers.transformer_anyflow_far.AnyFlowFARTransformerOutput]]

#### diffusers.models.transformers.transformer_anyflow_far.AnyFlowFARTransformerOutput[[diffusers.models.transformers.transformer_anyflow_far.AnyFlowFARTransformerOutput]]

```python
diffusers.models.transformers.transformer_anyflow_far.AnyFlowFARTransformerOutput(sample: typing.Optional[torch.Tensor] = None, kv_cache: typing.Optional[typing.List[typing.Dict[str, torch.Tensor]]] = None)
```

[Fuente](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_anyflow_far.py#L55)

**Parámetros:**

sample (*torch.Tensor* o *None*) : Objetivo de desruido predicho para el fragmento autoregresivo. `None` para la ruta de prellenado de caché, que solo escribe la caché KV y no produce ninguna muestra utilizable.

kv_cache (*list[dict[str, torch.Tensor]]*, *opcional*) : Estado de la caché KV por bloque utilizado por los pasos autoregresivos posteriores.

Clase de datos de salida para las rutas de propagación causal de `AnyFlowFARTransformer3DModel`.