# MiniMaxH3ImageTransformer2DModel

Um modelo Diffusion Transformer para geração e edição de imagens, introduzido em [MiniMax-H3-Image](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image) pela MiniMax.

É o [MiniMaxH3Transformer3DModel](/docs/diffusers/main/pt/api/models/minimax_h3_transformer3d#diffusers.MiniMaxH3Transformer3DModel) sem seu fluxo de áudio: uma única pilha de blocos processa **uma sequência 1-D empacotada** que contém a condição de texto, as linhas das imagens de referência e as linhas da imagem gerada. A construção do layout empacotado é responsabilidade do chamador, motivo pelo qual a assinatura do forward recebe o layout separado dos latentes: a grade de posições `(t, h, w)`, as tags de modalidade por linha, os índices de timestep por linha e os dois tensores de índice que endereçam as linhas de imagem e texto. O [MiniMaxH3ImageBlocks](/docs/diffusers/main/pt/api/pipelines/minimax_h3_image#diffusers.MiniMaxH3ImageBlocks) constrói tudo isso.

O checkpoint é destilado para seis etapas de amostragem com Parallel Decoding Distillation (PDD), que mantém uma cabeça de saída por etapa. Portanto, `forward` recebe `pdd_step_index`, a etapa em execução, e projeta com a cabeça dessa etapa.

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

O checkpoint é de precisão mista: a projeção de entrada do patch, o MLP de timestep e as saídas são float32, enquanto a pilha de blocos é bfloat16. `from_pretrained` mantém esse layout por meio de `_keep_in_fp32_modules`, então passe `dtype=torch.bfloat16` e deixe que ele posicione os módulos float32, em vez de converter o modelo com `.to(torch.bfloat16)` depois.

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

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_minimax_h3_image.py#L365)

**Parâmetros:**

num_attention_heads (`int`, padrão `56`) : O número de cabeças a serem usadas para a atenção multi-cabeça.

attention_head_dim (`int`, padrão `128`) : O número de canais em cada cabeça de atenção. Observe que `num_attention_heads * attention_head_dim` é *maior* que `hidden_size`.

hidden_size (`int`, padrão `5376`) : O número de canais da sequência empacotada (o fluxo residual).

num_layers (`int`, padrão `50`) : O número de blocos do transformer.

num_refiner_layers (`int`, padrão `2`) : O número de blocos de refinamento de tokens aplicados ao fluxo de texto projetado.

ffn_dim (`int`, padrão `14336`) : A dimensão interna das camadas feed-forward SwiGLU.

in_channels (`int`, padrão `24`) : O número de canais dos latentes da imagem.

patch_size (`tuple[int, int, int]`, padrão `(1, 2, 2)`) : O patch `(t, h, w)` usado para empacotar os latentes em linhas.

text_dim (`int`, padrão `5120`) : O número de canais da condição de texto produzida pelo codificador de texto.

freq_dim (`int`, padrão `256`) : A dimensão do embedding sinusoidal de timestep. Os timesteps são consumidos sem escala em `[0, 1]`.

time_embed_hidden_dim (`int`, padrão `5376`) : A dimensão interna do MLP de timestep.

time_embed_dim (`int`, padrão `2688`) : A dimensão de saída do MLP de timestep, ou seja, a entrada de cada projeção AdaLN.

rope_freq_dim (`int`, padrão `16`) : O número de frequências rotativas por eixo. Os eixos `(t, h, w)` compartilham um buffer `inv_freq` deste comprimento e `2 * 3 * rope_freq_dim` dos canais de `attention_head_dim` são rotacionados.

rope_theta (`float`, padrão `10000.0`) : A base da agenda de frequência rotativa a partir da qual o buffer `rope.inv_freq` é calculado.

norm_eps (`float`, padrão `1e-5`) : Epsilon das normalizações pré-atenção e pré-feed-forward.

qk_norm_eps (`float`, padrão `1e-5`) : Epsilon das normas de query/key por cabeça.

final_norm_eps (`float`, padrão `1e-5`) : Epsilon da normalização da saída do refinador de tokens e de `norm_out`.

num_pdd_heads (`int`, padrão `6`) : O número de etapas de amostragem para as quais o checkpoint foi destilado, cada uma com seu próprio output head.

Um modelo Transformer para geração e edição de imagens, introduzido no MiniMax-H3-Image.

É o transformer MiniMax-H3 sem seu fluxo de áudio: uma única pilha de blocos processa **uma sequência 1-D empacotada** que contém a condição de texto, as linhas das imagens de referência e as linhas da imagem gerada. A atenção é autoatenção completa sobre essa sequência; não há atenção cruzada. O checkpoint é destilado para um número fixo de etapas de amostragem com Parallel Decoding Distillation (PDD), que mantém uma cabeça de saída por etapa, de modo que `forward` recebe o índice da etapa em execução.

O chamador é responsável por construir o layout empacotado: aplicar patchify aos latentes, ordenar as linhas e produzir a grade de posições `(t, h, w)`, as tags de modalidade por linha e os índices de timestep por linha. A sequência não possui padding, portanto a atenção é executada sem máscara sobre um único documento e todos os backends de atenção permanecem disponíveis.

O eixo de lote é um eixo de replicação pura: os argumentos estruturais (`timestep`, `timestep_indices`, `token_tags`, `position_ids` e os dois tensores de índice) descrevem um único layout empacotado que todos os itens do lote compartilham.

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

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_minimax_h3_image.py#L545)

**Parâmetros:**

hidden_states (`torch.Tensor` de forma `(batch_size, num_image_tokens, in_channels * prod(patch_size))`) : Linhas latentes em patches — as linhas das imagens de referência e as linhas da imagem gerada — ordenadas conforme aparecem na sequência empacotada, ou seja, correspondendo a `image_indices`.

encoder_hidden_states (`torch.Tensor` de forma `(batch_size, num_text_tokens, text_dim)`) : Condição de texto, ordenada para corresponder a `text_indices`.

timestep (`torch.Tensor` de forma `(num_timesteps,)`) : Os valores de timestep *distintos* presentes na sequência empacotada, em `[0, 1]` e sem escala. Uma única forward atende linhas em diferentes níveis de ruído (linhas geradas, linhas de referência).

timestep_indices (`torch.Tensor` de forma `(seq_len,)`) : Para cada linha da sequência empacotada, o índice de seu timestep em `timestep`.

token_tags (`torch.Tensor` de forma `(seq_len,)`) : Para cada linha da sequência empacotada, sua modalidade: `0` imagem, `1` texto.

position_ids (`torch.Tensor` de forma `(seq_len, 3)`) : As coordenadas rotacionais `(t, h, w)` de cada linha da sequência empacotada.

image_indices (`torch.Tensor` de forma `(num_image_tokens,)`) : Posições das linhas de imagem na sequência empacotada.

text_indices (`torch.Tensor` de forma `(num_text_tokens,)`) : Posições das linhas de texto na sequência empacotada.

pdd_step_index (`int`) : O passo de amostragem, que seleciona a cabeça de saída.

return_dict (`bool`, padrão `True`) : Se deve retornar um [Transformer2DModelOutput](/docs/diffusers/main/pt/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput) em vez de uma tupla simples.

**Retorna:** [Transformer2DModelOutput](/docs/diffusers/main/pt/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput) ou `tuple`

A velocidade de cada linha de imagem, de forma `(batch_size, num_image_tokens, in_channels * prod(patch_size))`, na ordem de linha de `image_indices`.