#
# Bajo licencia Apache License, versión 2.0 (la "Licencia");
# no puede usar este archivo excepto en cumplimiento de la Licencia.
# Puede obtener una copia de la Licencia en
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# A menos que la ley aplicable lo exija o se haya acordado por escrito, el software
# distribuido bajo la Licencia se distribuye en una base "TAL CUAL",
# SIN GARANTÍAS NI CONDICIONES DE NINGÚN TIPO, ya sea expresa o implícita.
# Consulte la Licencia para el lenguaje específico que rige los permisos y
# limitaciones de la Licencia. -->

# Flux3Transformer2DModel

Un modelo Transformer para datos tipo imagen de [FLUX.3](https://bfl.ai/), para la generación de texto a imagen y de imagen a imagen. Tres modos de token comparten una secuencia conjunta: los tokens de imagen con ruido, los tokens de la imagen de referencia codificada por VAE y el contexto de texto. Cada modo primero pasa por sus propios bloques de transformer por modo, luego los modos se concatenan para los bloques únicos conjuntos, y los tokens de imagen pasan por las capas de salida. Los pasos de tiempo son por token: los tokens de imagen llevan el paso de tiempo de flujo, mientras que los tokens de referencia y el contexto de texto se sitúan en `0`.

```python
import torch
from diffusers import Flux3Transformer2DModel

transformer = Flux3Transformer2DModel.from_pretrained(
    "black-forest-labs/flux-3-image-klein-base", subfolder="transformer", dtype=torch.bfloat16
)
```

## Flux3Transformer2DModel[[diffusers.Flux3Transformer2DModel]]

#### diffusers.Flux3Transformer2DModel[[diffusers.Flux3Transformer2DModel]]

```python
diffusers.Flux3Transformer2DModel(in_channels: int = 128, cond_in_channels: int = 128, num_layers: int = 5, num_single_layers: int = 28, attention_head_dim: int = 128, num_attention_heads: int = 24, joint_attention_dim: int = 20480, timestep_channels: int = 256, mlp_ratio: float = 3.0, axes_dims_rope: tuple = (32, 32, 32, 32), rope_theta: int = 10000, eps: float = 1e-06, flow_map: bool = False)
```

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

**Parámetros:**

in_channels (`int`, por defecto `128`) : Ancho de canal de los tokens de imagen (los latentes VAE empaquetados, `latent_channels * 4`).

cond_in_channels (`int`, por defecto `128`) : Ancho de canal de los tokens de la imagen de referencia.

num_layers (`int`, por defecto `5`) : El número de bloques transformer por modo.

num_single_layers (`int`, por defecto `28`) : El número de bloques de transformador individuales conjuntos.

attention_head_dim (`int`, por defecto `128`) : El número de dimensiones a utilizar para cada cabeza de atención.

num_attention_heads (`int`, por defecto `24`) : El número de cabezas de atención a utilizar.

joint_attention_dim (`int`, por defecto `20480`) : La dimensión de embedding/canal de `encoder_hidden_states` (estados ocultos apilados de Qwen3-VL).

timestep_channels (`int`, por defecto `256`) : El número de canales de la incrustación sinusoidal del paso temporal.

mlp_ratio (`float`, por defecto `3.0`) : La ratio de expansión de los subbloques feedforward.

axes_dims_rope (`tuple[int]`, por defecto `(32, 32, 32, 32)`) : Las dimensiones a utilizar para los embeddings posicionales rotatorios, por eje de posición `(t, h, w, l)`.

rope_theta (`int`, por defecto `10000`) : La frecuencia base de los embeddings posicionales rotatorios.

eps (`float`, por defecto `1e-6`) : El epsilon de las normalizaciones de capa y de las normas QK.

flow_map (`bool`, por defecto `False`) : Indica si el modelo es un mapa de flujo (destilado por pasos): añade el `target_timestep_embedder` y requiere `target_timestep` en la pasada hacia adelante.

El modelo Transformer introducido en FLUX.3 para la generación de texto a imagen y de imagen a imagen.

Tres modos de tokens comparten una secuencia conjunta: los tokens de imagen con ruido (`hidden_states`), los tokens opcionales de la imagen de referencia codificada por VAE (`image_cond_hidden_states`) y el contexto de texto (`encoder_hidden_states`). Cada modo primero pasa por sus propios bloques de transformador por modo (`mode_blocks` para los modos de imagen, `txt_mode_blocks` para el contexto de texto), luego el contexto de texto y los modos de imagen activos se concatenan para los bloques únicos conjuntos, y solo los tokens de imagen pasan por las capas de salida. La modulación es por modo: los tokens de imagen se modulan por el paso de tiempo del flujo, mientras que los tokens de la imagen de referencia y el contexto de texto se modulan por el paso de tiempo `0`. Un punto de control de mapa de flujo (`flow_map=True`, los modelos destilados por pasos) incrusta adicionalmente el paso de tiempo al que salta cada paso de desruido y lo suma a la modulación de cada modo.

#### forward[[diffusers.Flux3Transformer2DModel.forward]]

```python
forward(hidden_states: Tensor, encoder_hidden_states: Tensor, timestep: Tensor, img_ids: Tensor, txt_ids: Tensor, image_cond_hidden_states: typing.Optional[torch.Tensor] = None, image_cond_ids: typing.Optional[torch.Tensor] = None, target_timestep: typing.Optional[torch.Tensor] = None, attention_kwargs: dict[str, typing.Any] | None = None, return_dict: bool = True)
```

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

**Parámetros:**

hidden_states (`torch.Tensor` de forma `(batch_size, image_seq_len, in_channels)`) : Tokens latentes de imagen con ruido.

encoder_hidden_states (`torch.Tensor` de forma `(batch_size, text_seq_len, joint_attention_dim)`) : Incrustaciones de contexto de texto (estados ocultos apilados de Qwen3-VL).

timestep (`torch.Tensor` de forma `(batch_size,)`) : Paso de tiempo del flujo en `[0, 1]` de los tokens de la imagen. Los tokens de la imagen de referencia y el contexto de texto se encuentran en el paso de tiempo `0`.

img_ids (`torch.Tensor` de forma `(image_seq_len, 4)`) : ids de posición `(t, h, w, l)` de los tokens de imagen, utilizados para los embeddings posicionales rotatorios y compartidos por todas las muestras del lote.

txt_ids (`torch.Tensor` de forma `(text_seq_len, 4)`) : ids de posición de los tokens del contexto de texto.

image_cond_hidden_states (`torch.Tensor` de forma `(batch_size, cond_seq_len, cond_in_channels)`, *opcional*) : tokens de imagen de referencia codificados por VAE (contenido de condicionamiento limpio, para generación de imagen a imagen).

image_cond_ids (`torch.Tensor` de forma `(cond_seq_len, 4)`, *opcional*) : ids de posición de los tokens de la imagen de referencia. Obligatorio con `image_cond_hidden_states`.

target_timestep (`torch.Tensor` de forma `(batch_size,)`, *opcional*) : Paso de tiempo del flujo en `[0, 1]` al que salta el paso actual de desruido. Requerido por, y solo por, un modelo de mapa de flujo (`flow_map=True`).

attention_kwargs (`dict`, *opcional*) : Un diccionario de kwargs cuya entrada `scale`, si se especifica, escala las capas LoRA para esta pasada de adelante.

return_dict (`bool`, *opcional*, valor predeterminado `True`) : Indica si se debe devolver un `~models.transformer_2d.Transformer2DModelOutput` en lugar de una tupla simple.

**Devuelve:**

Si `return_dict` es True, se devuelve un `~models.transformer_2d.Transformer2DModelOutput`; en caso contrario, se devuelve una `tuple` cuyo primer elemento es la velocidad predicha de los tokens de la imagen, con la misma forma que `hidden_states`.

El método forward de [Flux3Transformer2DModel](/docs/diffusers/main/es/api/models/flux3_transformer#diffusers.Flux3Transformer2DModel).

## Transformer2DModelOutput[[diffusers.models.modeling_outputs.Transformer2DModelOutput]]

#### diffusers.models.modeling_outputs.Transformer2DModelOutput[[diffusers.models.modeling_outputs.Transformer2DModelOutput]]

```python
diffusers.models.modeling_outputs.Transformer2DModelOutput(sample: torch.Tensor)
```

[Fuente](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/modeling_outputs.py#L21)

**Parámetros:**

sample (`torch.Tensor` de forma `(batch_size, num_channels, height, width)` o `(batch size, num_vector_embeds - 1, num_latent_pixels)` si [Transformer2DModel](/docs/diffusers/main/es/api/models/transformer2d#diffusers.Transformer2DModel) es discreto): las salidas de estados ocultos condicionadas a la entrada `encoder_hidden_states`. Si es discreto, devuelve distribuciones de probabilidad para los píxeles latentes sin ruido.

La salida de [Transformer2DModel](/docs/diffusers/main/es/api/models/transformer2d#diffusers.Transformer2DModel).