# AnyFlowFARTransformer3DModel

Причинный (FAR) 3D-трансформер, используемый в [`AnyFlowFARPipeline`](../pipelines/anyflow#diffusers.AnyFlowFARPipeline) — вариант FAR для [AnyFlow](https://huggingface.co/papers/2605.13724). См. страницу [`AnyFlowFARPipeline`](../pipelines/anyflow) для информации о статье, авторах и опубликованных контрольных точках. Он расширяет базовую архитектуру Wan2.1 версии v0.35.1 тремя дополнениями:

1. **Причинная блок-маска FAR** с использованием `torch.nn.attention.flex_attention`, поддерживающая поштучную авторегрессионную генерацию, как описано в [FAR](https://huggingface.co/papers/2503.19325).
2. **Встраивание патчей сжатых кадров** (`far_patch_embedding`) для контекстных (уже сгенерированных) кадров, инициализируемое при создании из полноразрешающего `patch_embedding` методом трилинейной интерполяции.
3. **Встраивание потока с двумя временными шагами** (аналогично [`AnyFlowTransformer3DModel`](anyflow_transformer3d)) — каждый вызов forward использует в качестве условия и исходный временной шаг ``t``, и целевой временной шаг ``r``.

Расписание по умолчанию (`chunk_partition`) хранится в конфигурации модели; опубликованные контрольные точки NVIDIA AnyFlow-FAR используют `[1, 3, 3, 3, 3, 3, 3, 2]` для стандартной настройки на 81 кадр. Метод `forward` принимает переопределение `chunk_partition` для каждого вызова, поэтому одна и та же контрольная точка также обрабатывает другие конфигурации `num_frames` без дообучения.

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

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_anyflow_far.py#L961)

**Параметры:**

patch_size (*Tuple[int]*, по умолчанию *(1, 2, 2)*) : размеры 3D-патчей для фрагментов полного разрешения.

compressed_patch_size (*Tuple[int]*, по умолчанию *(1, 4, 4)*) : Большие размеры патчей для FAR-сжатых (контекстных) фрагментов.

full_chunk_limit (*int*, по умолчанию *3*) : Максимальное количество чанков полного разрешения, прежде чем более ранние чанки будут понижены до сжатого контекста FAR. В выпущенных контрольных точках используется `3`.

num_attention_heads (*int*, по умолчанию *40*) : Количество головок внимания.

attention_head_dim (*int*, по умолчанию *128*) : количество каналов в каждой голове.

in_channels (*int*, по умолчанию *16*) : Количество каналов во входном латентном представлении.

out_channels (*int*, по умолчанию *16*) : Количество каналов в выходном латентном представлении.

text_dim (*int*, по умолчанию *4096*) : Размерность входных данных для текстовых эмбеддингов (UMT5).

freq_dim (*int*, по умолчанию *256*) : Размерность для синусоидных временных эмбеддингов.

ffn_dim (*int*, по умолчанию *13824*) : Промежуточное измерение в полносвязной сети.

num_layers (*int*, по умолчанию *40*) : Количество блоков трансформера.

cross_attn_norm (*bool*, по умолчанию *True*) : Включает нормализацию кросс-внимания.

eps (*float*, по умолчанию *1e-6*) : Эпсилон для слоёв нормализации.

image_dim (*Optional[int]*, *optional*, по умолчанию *None*) : Размерность эмбеддинга изображения для I2V-условия.

rope_max_seq_len (*int*, по умолчанию *1024*) : Максимальная длина последовательности, используемая для предварительного вычисления частот ротационных позиционных кодировок.

gate_value (*float*, по умолчанию *0.25*) : Шлюз смешивания между эмбеддингами исходного временного шага и дельта-шага.

deltatime_type (*str*, по умолчанию *'r'*) : либо `"r"` (delta — целевой шаг), либо `"t-r"` (delta — абсолютный интервал).

chunk_partition (*Tuple[int, ...]*, по умолчанию *(1, 3, 3, 3, 3, 3, 3, 2)*) : Количество кадров на чанк по умолчанию, используемое конвейером. Опубликованные чекпоинты NVIDIA AnyFlow-FAR рассчитаны на `num_frames=81` (21 латентных кадров при временном шаге VAE, равном 4) с разбиением `1 + 3*6 + 2`. Для другого значения `num_frames` необходимо передать соответствующее переопределение `chunk_partition` в [AnyFlowFARPipeline.__call__()](/docs/diffusers/v0.43.0/ru/api/pipelines/anyflow#diffusers.AnyFlowFARPipeline.__call__) (и аналогично в `forward`).

Causal (FAR) 3D-трансформер для выборки карт потоков AnyFlow с поштучной авто регрессивной генерацией.

Расширяет базовую модель Wan2.1 версии v0.35.1:

- **Причинная блок-маска FAR** с использованием `torch.nn.attention.flex_attention`, поддерживающая поштучную авторегрессионную генерацию ([FAR](https://huggingface.co/papers/2503.19325)).
- **Встраивание патчей сжатых кадров** `far_patch_embedding` для контекстных (уже сгенерированных) кадров, инициализируемое из `patch_embedding` с помощью трилинейной интерполяции, чтобы только что сконструированная модель уже находилась в разумной стартовой точке даже до дообучения с помощью LoRA.
- **Встраивание потока с двойным шагом времени** для выборки с любым шагом (аналогично `AnyFlowTransformer3DModel`).

Для простого двунаправленного T2V используйте `AnyFlowTransformer3DModel` — этот вариант пропускает причинное маскирование FAR и `far_patch_embedding` и примерно на 5–10% меньше по размеру.

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

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_anyflow_far.py#L1237)

**Параметры:**

chunk_partition : количество кадров в каждом чанке (сумма должна равняться общему числу латентных кадров).

height, width : пространственные размеры латентного представления.

has_clean_context : `True`, если `clean_hidden_states` будет передаваться в `forward` (обучение V2V/I2V); только наличие этого флага влияет на структуру маски.

device : устройство для результирующего `BlockMask`. Маска не перемещается автоматически с помощью `device_map="auto"`; создавайте её на том же устройстве, где будут находиться входные данные трансформера.

mode : `"train"` (соответствует `_forward_train`) или `"cache"` (соответствует `_forward_cache`). Авто регрессионный путь `_forward_inference` обращается через KV-кэш и не имеет режима в этом контексте.

**Возвращает:** `~torch.nn.attention.flex_attention.BlockMask`

causal mask, охватывающая раскладку FAR, дополненная нулями до кратного 128 значения по размерности последовательности (требование к размеру блока BlockMask).

**Исключения:** `ValueError`

- `ValueError` -- если `mode` не является ни `"train"`, ни `"cache"`.

Предварительно создайте каузальную `~torch.nn.attention.flex_attention.BlockMask` вне `forward`.

Передайте результат через аргумент `attention_mask` метода `forward`, чтобы сделать весь трансформер совместимым с `torch.compile(fullgraph=True)`. Без заранее созданной маски `forward` переходит к внутреннему построению — этот путь использует `flex_attention.create_block_mask(_compile=False)` и нарушает граф компиляции.

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

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_anyflow_far.py#L1098)

**Параметры:**

hidden_states (*torch.Tensor*) : Латентный вход с формой `(B, F, C, H, W)`.

timestep (*torch.Tensor*) : исходный (более шумный) шаг временной шкалы flow-map *t*.

r_timestep (*torch.Tensor*) : целевой (более чистый) шаг временной шкалы потока *r*.

encoder_hidden_states (*torch.Tensor*) : Векторные представления текста UMT5.

chunk_partition (*List[int]*) : Количество кадров в каждом чанке; общее количество должно совпадать с числом латентных кадров в `hidden_states`.

encoder_hidden_states_image (*torch.Tensor*, *optional*) : эмбеддинг изображения для I2V; конкатенируется перед текстовыми токенами, если указан.

clean_hidden_states (*torch.Tensor*, *optional*) : Чистые (без шума) кадры, используемые в качестве условия для тренировочного rollout.

clean_timestep (*torch.Tensor*, *optional*) : Шаги для чистых кадров условий в тренировочном rollout.

kv_cache (*List[Dict[str, torch.Tensor]]*, *optional*) : Кэш KV по блокам для авторегрессионного вывода. *None* выбирает режим обучения.

kv_cache_flag (*Dict[str, Any]*, *необязательный*) : метаданные KV-кэша (например, флаг `is_cache_step` и количество токенов).

attention_mask (*BlockMask*, *optional*) : Готовая каузальная маска, как правило, создаваемая с помощью `build_attention_mask`. Используется в путях обучения и префилла KV-кэша; путь авторегрессионного вывода обращается через KV-кэш и не использует полную маску. Если `None`, пути обучения / кэша создают маску внутренне; этот запасной вариант несовместим с компиляцией (базовая функция `flex_attention.create_block_mask` нарушает граф при `fullgraph=True`), поэтому передавайте готовую маску при обёртке `forward` в `torch.compile`.

attention_kwargs (*dict*, *optional*) : Передаётся в обработчики внимания.

return_dict (*bool*, *optional*, по умолчанию *True*) : Если *False*, возвращает позиционные кортежи вместо выходного dataclass.

**Возвращает:** [*~models.transformer_2d.Transformer2DModelOutput*], [*AnyFlowFARTransformerOutput*] или *tuple*

Если *return_dict* равно *False*, возвращается обычный *tuple*. В противном случае, при обучении с каузальным развёртыванием (*kv_cache is None*) возвращается [*~models.transformer_2d.Transformer2DModelOutput*], а при префилле кэша и авторегрессионном выводе — [*AnyFlowFARTransformerOutput*].

Прямой проход FAR с причинной зависимостью. Направляет выполнение на один из трёх внутренних путей:

- `kv_cache is None` → rollout для обучения с каузальностью (возвращает `Transformer2DModelOutput`).
- `kv_cache is not None` и `kv_cache_flag["is_cache_step"]` → cache-prefill (возвращает `AnyFlowFARTransformerOutput` с `sample=None`).
- В противном случае → шаг авто-регрессивного вывода (возвращает `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)
```

[Источник](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_anyflow_far.py#L55)

**Параметры:**

sample (*torch.Tensor* или *None*) : Предсказанная цель денойзинга для авто-регрессивного чанка. `None` для пути кэширования префилла, который только записывает KV-кэш и не производит пригодных для использования образцов.

kv_cache (*list[dict[str, torch.Tensor]]*, *optional*) : Состояние KV-кэша по блокам, используемое последующими шагами авто-регрессивного генерирования.

Данные класса для вывода в каузальных путах прямого прохода `AnyFlowFARTransformer3DModel`.