# MiniMaxH3Transformer3DModel

Модель Diffusion Transformer для совместной генерации видео и аудио, представленная в [MiniMax-H3](https://huggingface.co/MiniMaxAI/MiniMax-H3) от MiniMax.

MiniMax-H3 выполняет пропуск через единый стек блоков по **одной упакованной одномерной последовательности**, которая одновременно содержит текстовые условия, строки изображения-условия и видео, строки аудио и целевые строки видео. Вниманием является полное само-внимание по этой последовательности, поэтому кросс-внимания и отдельных весов блоков для каждой модальности нет. Поведение, специфичное для модальности, обеспечивается только двумя входными проекциями патчей, тегом модальности для каждой строки, который выбирает параметры модуляции AdaLN, и двумя выходными головами.

Создание упакованной раскладки — задача вызывающего кода, поэтому сигнатура forward принимает раскладку отдельно от латентов: сетку позиций `(t, h, w)`, теги модальности для каждой строки, индексы временных шагов для каждой строки и три тензора индексов, указывающие на строки видео, аудио и текста. [MiniMaxH3Blocks](/docs/diffusers/main/ru/api/pipelines/minimax_h3#diffusers.MiniMaxH3Blocks) и `MiniMaxH3Ref2VABlocks` формируют всё это.

Раскладка, содержащая строки отступов (тег `-1`), требует бэкенда маскированного внимания, поскольку эти строки сохраняются в собственном документе внимания с помощью булевой маски; последовательность без отступов не требует маски и сохраняет доступность всех бэкендов.

Один репозиторий содержит как выпущенные, так и контрольные точки, поэтому подпапка определяет задачу: `transformer/` для задач с текстом и ключевыми кадрами, `transformer_ref/` для задачи omni-reference.

```python
import torch
from diffusers import MiniMaxH3Transformer3DModel

transformer = MiniMaxH3Transformer3DModel.from_pretrained(
    "MiniMaxAI/MiniMax-H3", subfolder="transformer", dtype=torch.bfloat16
).to("cuda")  # or "mps", "xpu", "cpu"
```

Чекпоинт использует смешанную точность: два входных проекционных слоя патчей, MLP временных шагов и два выходных слоя имеют тип float32, а стек блоков — bfloat16. `from_pretrained` сохраняет эту структуру благодаря `_keep_in_fp32_modules`, поэтому передавайте `dtype=torch.bfloat16` и позвольте функции разместить модули float32, а не приводить модель к типу bfloat16 с помощью `.to(torch.bfloat16)` после загрузки.

## MiniMaxH3Transformer3DModel[[diffusers.MiniMaxH3Transformer3DModel]]

#### diffusers.MiniMaxH3Transformer3DModel[[diffusers.MiniMaxH3Transformer3DModel]]

```python
diffusers.MiniMaxH3Transformer3DModel(num_attention_heads: int = 56, attention_head_dim: int = 128, hidden_size: int = 5376, num_layers: int = 50, num_refiner_layers: int = 2, ffn_dim: int = 14336, in_channels: int = 24, audio_in_channels: int = 32, patch_size: tuple[int, int, int] = (1, 2, 2), text_dim: int = 5120, freq_dim: int = 256, time_embed_hidden_dim: int = 5376, time_embed_dim: int = 2688, rope_freq_dim: int = 16, rope_theta: float = 10000.0, norm_eps: float = 1e-05, qk_norm_eps: float = 1e-05, final_norm_eps: float = 1e-05)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_minimax_h3.py#L379)

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

num_attention_heads (`int`, по умолчанию `56`) : Количество головок для использования в механизме внимания с несколькими головками.

attention_head_dim (`int`, по умолчанию `128`) : количество каналов в каждой голове внимания. Обратите внимание, что `num_attention_heads * attention_head_dim` *больше*, чем `hidden_size` в MiniMax-H3.

hidden_size (`int`, по умолчанию `5376`) : количество каналов упакованной последовательности (остаточного потока).

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

num_refiner_layers (`int`, по умолчанию `2`) : Количество блоков уточнения токенов, применяемых к спроектированному текстовому потоку.

ffn_dim (`int`, по умолчанию `14336`) : Внутреннее измерение полносвязных слоёв SwiGLU.

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

audio_in_channels (`int`, по умолчанию `32`) : Количество каналов аудиолатентов.

patch_size (`tuple[int, int, int]`, по умолчанию `(1, 2, 2)`) : Пакет `(t, h, w)`, используемый для упаковки латентов видео в строки.

text_dim (`int`, по умолчанию `5120`) : Количество каналов текстового условия, создаваемого текстовым энкодером.

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

time_embed_hidden_dim (`int`, по умолчанию `5376`) : Внутреннее измерение MLP для временных шагов.

time_embed_dim (`int`, по умолчанию `2688`) : Выходное измерение MLP для временного шага, то есть вход для каждого проекционного слоя AdaLN.

rope_freq_dim (`int`, по умолчанию `16`) : Количество частот вращения на ось. Оси `(t, h, w)` используют общий буфер `inv_freq` этой длины, а `2 * 3 * rope_freq_dim` из каналов `attention_head_dim` подвергаются вращению.

rope_theta (`float`, по умолчанию `10000.0`) : Основание расписания частот поворота, из которого вычисляется буфер `rope.inv_freq`.

norm_eps (`float`, по умолчанию `1e-5`) : Epsilon для нормализаций до внимания и до полносвязного слоя.

qk_norm_eps (`float`, по умолчанию `1e-5`) : Epsilon для норм запросов/ключей по каждой голове.

final_norm_eps (`float`, по умолчанию `1e-5`) : Epsilon для нормализации вывода token refiner и для `norm_out`.

Модель Transformer для совместной генерации видео и аудио, представленная в MiniMax-H3.

MiniMax-H3 выполняет пропуск через единый стек блоков по **одной упакованной одномерной последовательности**, содержащей текстовое условие, строки изображения/видео для условия, строки аудио и целевые строки видео. Вниманием является полное само-внимание по этой последовательности; кросс-внимания и отдельных весов блоков для каждой модальности нет. Поведение, специфичное для модальности, обеспечивается только двумя входными проекциями патчей, тегом модальности AdaLN для каждой строки и двумя выходными головами.

Вызывающая сторона отвечает за формирование упакованной раскладки: патчификацию латентов видео, упорядочивание строк и построение сетки позиций `(t, h, w)`, модальных тегов для каждой строки и индексов временных шагов для каждой строки. Последовательность не содержит заполнителей — эталонная реализация дополняет её до кратного 64 для FlashAttention и отрезает хвост с помощью `cu_seqlens = [0, used, S]`, что в данном порту не требуется, — поэтому внимание выполняется без маски по одному документу, и остаются доступными все бэкенды внимания.

Ось батча является осью чистой репликации: структурные аргументы (`timestep`, `timestep_indices`, `token_tags`, `position_ids` и три тензора индексов) описывают один упакованный макет, общий для всех элементов батча, при этом каждый элемент представляет собой один документ внимания.

#### forward[[diffusers.MiniMaxH3Transformer3DModel.forward]]

```python
forward(hidden_states: Tensor, audio_hidden_states: Tensor, encoder_hidden_states: Tensor, timestep: Tensor, timestep_indices: Tensor, token_tags: Tensor, position_ids: Tensor, video_indices: Tensor, audio_indices: Tensor, text_indices: Tensor, attention_kwargs: dict[str, typing.Any] | None = None, return_dict: bool = True)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_minimax_h3.py#L605)

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

hidden_states (`torch.Tensor` формы `(batch_size, num_video_tokens, in_channels * prod(patch_size))`) : Строки латентного представления видео после патчирования — строки условий и целевые строки — в том порядке, в котором они появляются в упакованной последовательности, то есть в соответствии с `video_indices`.

audio_hidden_states (`torch.Tensor` формы `(batch_size, num_audio_tokens, audio_in_channels)`) : Строки аудиовыходных латентов, упорядоченные в соответствии с `audio_indices`.

encoder_hidden_states (`torch.Tensor` формы `(batch_size, num_text_tokens, text_dim)`) : Текстовое условие, упорядоченное в соответствии с `text_indices`.

timestep (`torch.Tensor` формы `(num_timesteps,)`) : *различные* значения временных шагов, присутствующие в упакованной последовательности, в диапазоне `[0, 1]` и без масштабирования. Один прямой проход обрабатывает строки с разными уровнями шума (целевое видео, целевой звук, строки условий).

timestep_indices (`torch.Tensor` формы `(seq_len,)`) : Для каждой строки упакованной последовательности — индекс её временного шага в `timestep`.

token_tags (`torch.Tensor` формы `(seq_len,)`) : Для каждой строки упакованной последовательности её модальность: `0` видео, `1` текст, `2` аудио.

position_ids (`torch.Tensor` формы `(seq_len, 3)`) : `(t, h, w)` координаты вращения для каждой строки упакованной последовательности.

video_indices (`torch.Tensor` формы `(num_video_tokens,)`) : Позиции строк видео в упакованной последовательности.

audio_indices (`torch.Tensor` формы `(num_audio_tokens,)`) : Позиции строк аудио в упакованной последовательности.

text_indices (`torch.Tensor` формы `(num_text_tokens,)`) : Позиции строк текста в упакованной последовательности.

attention_kwargs (`dict`, *необязательный*) : Словарь kwargs, который, если указан, может содержать запись `scale`, применяемую к слоям LoRA.

return_dict (`bool`, по умолчанию `True`) : Возвращать ли `MiniMaxH3TransformerOutput` вместо обычного кортежа.

**Возвращает:** `MiniMaxH3TransformerOutput` или `tuple`

Скорость видео с формой `(batch_size, num_video_tokens, in_channels * prod(patch_size))` и скорость аудио с формой `(batch_size, num_audio_tokens, audio_in_channels)`, в порядке строк `video_indices` и `audio_indices`.

## MiniMaxH3TransformerOutput[[diffusers.models.transformers.transformer_minimax_h3.MiniMaxH3TransformerOutput]]

#### diffusers.models.transformers.transformer_minimax_h3.MiniMaxH3TransformerOutput[[diffusers.models.transformers.transformer_minimax_h3.MiniMaxH3TransformerOutput]]

```python
diffusers.models.transformers.transformer_minimax_h3.MiniMaxH3TransformerOutput(sample: Tensor, audio_sample: typing.Optional[torch.Tensor] = None)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_minimax_h3.py#L42)

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

sample (`torch.Tensor` формы `(batch_size, num_video_tokens, in_channels * prod(patch_size))`) : Прогноз скорости видео для строк, указанных в `video_indices`, в том же порядке. Строки условий возвращаются без маски — их маскирование перед шагом планировщика является обязанностью вызывающей стороны.

audio_sample (`torch.Tensor` формы `(batch_size, num_audio_tokens, audio_in_channels)`, по умолчанию `None`) : Предсказание скорости аудио для строк, указанных в `audio_indices`, в том же порядке. `forward` всегда заполняет это поле; оно принимает значение `None` по умолчанию только для того, чтобы выход можно было восстановить из обычного словаря его полей, именно так хуки offload в accelerate возвращают `BaseOutput` на устройство ввода.

Вывод [MiniMaxH3Transformer3DModel](/docs/diffusers/main/ru/api/models/minimax_h3_transformer3d#diffusers.MiniMaxH3Transformer3DModel).