# MiniMaxH3ImageTransformer2DModel

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

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

Чекпоинт дистиллирован до шести шагов сэмплирования с помощью Parallel Decoding Distillation (PDD), который сохраняет один выходной слой на каждый шаг. Поэтому `forward` принимает `pdd_step_index`, указывающий текущий шаг, и выполняет проекцию с помощью выходного слоя этого шага.

```python
import torch
from diffusers import MiniMaxH3ImageTransformer2DModel

transformer = MiniMaxH3ImageTransformer2DModel.from_pretrained(
    "MiniMaxAI/MiniMax-H3-Image", subfolder="transformer_diffusers", 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)` после загрузки.

## MiniMaxH3ImageTransformer2DModel[[diffusers.MiniMaxH3ImageTransformer2DModel]]

#### diffusers.MiniMaxH3ImageTransformer2DModel[[diffusers.MiniMaxH3ImageTransformer2DModel]]

```python
diffusers.MiniMaxH3ImageTransformer2DModel(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, 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, num_pdd_heads: int = 6)
```

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

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

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

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

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

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

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

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

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

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

num_pdd_heads (`int`, по умолчанию `6`) : количество шагов сэмплирования, до которых был дистиллирован чекпоинт, каждый из которых имеет собственную выходную голову.

Модель Transformer для генерации и редактирования изображений, представленная в MiniMax-H3-Image.

Это трансформер MiniMax-H3 без аудиопотока: единый стек блоков обрабатывает **одну упакованную одномерную последовательность**, содержащую текстовое условие, строки референсных изображений и строки генерируемого изображения. Внимательность представляет собой полное само-внимательность по этой последовательности; кросс-внимательность отсутствует. Чекпоинт дистиллирован до фиксированного числа шагов сэмплирования с помощью Parallel Decoding Distillation (PDD), который сохраняет один выходной слой на каждый шаг, поэтому `forward` принимает индекс текущего шага.

Вызывающая сторона отвечает за формирование упакованной раскладки: патчификацию латентов, упорядочивание строк и создание позиционной сетки `(t, h, w)`, модальных тегов для каждой строки и индексов временных шагов для каждой строки. Последовательность не содержит заполнителей, поэтому внимание выполняется без маски по одному документу, и остаются доступными все бэкенды внимания.

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

#### forward[[diffusers.MiniMaxH3ImageTransformer2DModel.forward]]

```python
forward(hidden_states: Tensor, encoder_hidden_states: Tensor, timestep: Tensor, timestep_indices: Tensor, token_tags: Tensor, position_ids: Tensor, image_indices: Tensor, text_indices: Tensor, pdd_step_index: int, return_dict: bool = True)
```

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

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

hidden_states (`torch.Tensor` формы `(batch_size, num_image_tokens, in_channels * prod(patch_size))`) : Строки латентных представлений, разбитые на патчи — строки эталонных изображений и строки сгенерированного изображения — в том порядке, в котором они появляются в упакованной последовательности, то есть в соответствии с `image_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` текст.

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

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

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

pdd_step_index (`int`) : Шаг выборки, который выбирает выходную голову.

return_dict (`bool`, по умолчанию `True`) : следует ли возвращать [Transformer2DModelOutput](/docs/diffusers/main/ru/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput) вместо обычного кортежа.

**Возвращает:** [Transformer2DModelOutput](/docs/diffusers/main/ru/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput) или `tuple`

Скорость каждой строки изображения, с формой `(batch_size, num_image_tokens, in_channels * prod(patch_size))`, в порядке строк `image_indices`.