# Hunyuan-DiT
![chinese elements understanding](https://github.com/gnobitab/diffusers-hunyuan/assets/1157982/39b99036-c3cb-4f16-bb1a-40ec25eda573)

[Hunyuan-DiT: un potente difusor Transformer multi-resolución con comprensión detallada del chino](https://huggingface.co/papers/2405.08748) de Tencent Hunyuan.

El resumen del artículo es:

*Presentamos Hunyuan-DiT, un transformer de difusión de texto a imagen con una comprensión detallada tanto del inglés como del chino. Para construir Hunyuan-DiT, diseñamos cuidadosamente la estructura del transformer, el codificador de texto y la codificación posicional. También construimos desde cero un pipeline de datos completo para actualizar y evaluar los datos con el fin de optimizar iterativamente el modelo. Para la comprensión lingüística detallada, entrenamos un Modelo de Lenguaje Grande Multimodal para refinar las descripciones de las imágenes. Finalmente, Hunyuan-DiT puede realizar diálogos multimodales de varios turnos con los usuarios, generando y refinando imágenes según el contexto. A través de nuestro protocolo de evaluación humana integral con más de 50 evaluadores humanos profesionales, Hunyuan-DiT establece un nuevo estado del arte en la generación de imágenes a partir de chino en comparación con otros modelos de código abierto.*

Puedes encontrar el código original en [Tencent/HunyuanDiT](https://github.com/Tencent/HunyuanDiT) y todos los puntos de control disponibles en [Tencent-Hunyuan](https://huggingface.co/Tencent-Hunyuan/HunyuanDiT).

**Aspectos destacados**: HunyuanDiT admite la generación de imágenes a partir de texto en chino e inglés, así como la generación a múltiples resoluciones.

HunyuanDiT tiene los siguientes componentes:
* Utiliza un transformador de difusión como columna vertebral
* Combina dos codificadores de texto, un CLIP bilingüe y un codificador T5 multilingüe

> [!TIP]
> Asegúrate de consultar la [guía de Schedulers](../../using-diffusers/schedulers) para aprender a explorar el equilibrio entre la velocidad y la calidad del scheduler, y consulta la sección [reutilizar componentes entre pipelines](../../using-diffusers/loading#reusing-models-in-multiple-pipelines) para aprender a cargar eficientemente los mismos componentes en múltiples pipelines.

> [!TIP]
> Puedes mejorar aún más la calidad de la generación pasando la imagen generada por `HungyuanDiTPipeline` al modelo [SDXL refiner](./stable_diffusion/stable_diffusion_xl#base-to-refiner-model).

## Optimización

Puedes optimizar el tiempo de ejecución y el consumo de memoria del pipeline con torch.compile y el chunking de feed-forward. Para conocer otros métodos de optimización, consulta [Optimizar y escalar](../../optimization/overview#optimization-techniques).

### Inferencia

Use [`torch.compile`](../../optimization/fp16#torchcompile) para reducir la latencia de inferencia.

Primero, carga el pipeline:

```python
from diffusers import HunyuanDiTPipeline
import torch

pipeline = HunyuanDiTPipeline.from_pretrained(
	"Tencent-Hunyuan/HunyuanDiT-Diffusers", dtype=torch.float16
).to("cuda")  # or "mps", "xpu", "cpu"
```

Luego, cambia el diseño de memoria de los componentes `transformer` y `vae` de los pipelines a `torch.channels-last`:

```python
pipeline.transformer.to(memory_format=torch.channels_last)
pipeline.vae.to(memory_format=torch.channels_last)
```

Por último, compile los componentes y ejecute la inferencia:

```python
pipeline.transformer = torch.compile(pipeline.transformer, mode="max-autotune", fullgraph=True)
pipeline.vae.decode = torch.compile(pipeline.vae.decode, mode="max-autotune", fullgraph=True)

image = pipeline(prompt="一个宇航员在骑马").images[0]
```

Los resultados del [benchmark](https://gist.github.com/sayakpaul/29d3a14905cfcbf611fe71ebd22e9b23) en una máquina A100 de 80 GB son:

```bash
With torch.compile(): Average inference time: 12.470 seconds.
Without torch.compile(): Average inference time: 20.570 seconds.
```

### Optimización de memoria

Al cargar el codificador de texto T5 en 8 bits, puedes ejecutar la tubería con menos de 6 GB de VRAM de GPU. Consulta [este script](https://gist.github.com/sayakpaul/3154605f6af05b98a41081aaba5ca43e) para más detalles.

Además, puedes usar el método [enable_forward_chunking()](/docs/diffusers/main/es/api/models/hunyuan_transformer2d#diffusers.HunyuanDiT2DModel.enable_forward_chunking) para reducir el uso de memoria. El chunking de feed-forward ejecuta las capas feed-forward de un bloque transformer en un bucle en lugar de todas a la vez. Esto te ofrece un equilibrio entre el consumo de memoria y el tiempo de ejecución de la inferencia.

```diff
+ pipeline.transformer.enable_forward_chunking(chunk_size=1, dim=1)
```

## HunyuanDiTPipeline[[diffusers.HunyuanDiTPipeline]]

#### diffusers.HunyuanDiTPipeline[[diffusers.HunyuanDiTPipeline]]

```python
diffusers.HunyuanDiTPipeline(vae: AutoencoderKL, text_encoder: BertModel, tokenizer: BertTokenizer, transformer: HunyuanDiT2DModel, scheduler: DDPMScheduler, safety_checker: StableDiffusionSafetyChecker, feature_extractor: CLIPImageProcessorPil, requires_safety_checker: bool = True, text_encoder_2: transformers.models.t5.modeling_t5.T5EncoderModel | None = None, tokenizer_2: transformers.models.t5.tokenization_t5.T5Tokenizer | None = None)
```

[Fuente](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/hunyuandit/pipeline_hunyuandit.py#L149)

**Parámetros:**

vae ([AutoencoderKL](/docs/diffusers/main/es/api/models/autoencoderkl#diffusers.AutoencoderKL)) : Modelo de Variational Auto-Encoder (VAE) para codificar y decodificar imágenes hacia y desde representaciones latentes. Utilizamos `sdxl-vae-fp16-fix`.

text_encoder (`~transformers.BertModel`, `~transformers.CLIPTextModel` | None) : Codificador de texto congelado ([clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14)). HunyuanDiT utiliza un [CLIP bilingüe] afinado.

tokenizer (`~transformers.BertTokenizer`, `~transformers.CLIPTokenizer` | None) : Un `BertTokenizer` o `CLIPTokenizer` para tokenizar el texto.

transformer ([HunyuanDiT2DModel](/docs/diffusers/main/es/api/models/hunyuan_transformer2d#diffusers.HunyuanDiT2DModel)) : El modelo HunyuanDiT diseñado por Tencent Hunyuan.

text_encoder_2 (`T5EncoderModel`) : El incrustador mT5. Específicamente, es 't5-v1_1-xxl'.

tokenizer_2 (`T5Tokenizer`) : El tokenizador del incrustador mT5.

scheduler ([DDPMScheduler](/docs/diffusers/main/es/api/schedulers/ddpm#diffusers.DDPMScheduler)) : Un programador para usar en combinación con HunyuanDiT para desruidar los latentes de imagen codificados.

Pipeline para la generación de imágenes a partir de inglés/chino usando HunyuanDiT.

Este modelo hereda de [DiffusionPipeline](/docs/diffusers/main/es/api/pipelines/overview#diffusers.DiffusionPipeline). Consulta la documentación de la clase superior para los métodos genéricos que la biblioteca implementa para todos los pipelines (como la descarga o el guardado, la ejecución en un dispositivo específico, etc.)

HunyuanDiT utiliza dos codificadores de texto: [mT5](https://huggingface.co/google/mt5-base) y [CLIP bilingüe](fine-tuned by ourselves)

#### __call__[[diffusers.HunyuanDiTPipeline.__call__]]

```python
__call__(prompt: str | list[str] = None, height: int | None = None, width: int | None = None, num_inference_steps: int | None = 50, guidance_scale: float | None = 5.0, negative_prompt: str | list[str] | None = None, num_images_per_prompt: int | None = 1, eta: float | None = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_embeds_2: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds_2: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, prompt_attention_mask_2: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask_2: typing.Optional[torch.Tensor] = None, output_type: str | None = 'pil', return_dict: bool = True, callback_on_step_end: typing.Union[typing.Callable[[int, int], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'], guidance_rescale: float = 0.0, original_size: tuple[int, int] | None = (1024, 1024), target_size: tuple[int, int] | None = None, crops_coords_top_left: tuple[int, int] = (0, 0), use_resolution_binning: bool = True)
```

[Fuente](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/hunyuandit/pipeline_hunyuandit.py#L568)

**Parámetros:**

prompt (`str` o `list[str]`, *opcional*) : El prompt o los prompts para guiar la generación de imágenes. Si no se define, debe pasar `prompt_embeds`.

height (`int`) : La altura en píxeles de la imagen generada.

width (`int`) : El ancho en píxeles de la imagen generada.

num_inference_steps (`int`, *opcional*, valor predeterminado 50) : El número de pasos de desruido. Más pasos de desruido suelen conducir a una imagen de mayor calidad a costa de una inferencia más lenta. Este parámetro se modula por `strength`.

guidance_scale (`float`, *opcional*, valor predeterminado 7.5) : Un valor más alto de la escala de guía anima al modelo a generar imágenes estrechamente vinculadas al `prompt` de texto a costa de una menor calidad de imagen. La escala de guía se habilita cuando `guidance_scale > 1`.

negative_prompt (`str` o `list[str]`, *opcional*) : El prompt o los prompts para guiar lo que no debe incluirse en la generación de la imagen. Si no se define, debe pasar `negative_prompt_embeds` en su lugar. Se ignora cuando no se usa guía (`guidance_scale < 1`).

num_images_per_prompt (`int`, *opcional*, valor predeterminado 1) : El número de imágenes a generar por indicación.

eta (`float`, *opcional*, valor predeterminado 0.0) : Corresponde al parámetro eta (η) del artículo [DDIM](https://huggingface.co/papers/2010.02502). Solo se aplica al [DDIMScheduler](/docs/diffusers/main/es/api/schedulers/ddim#diffusers.DDIMScheduler) y se ignora en otros programadores.

generator (`torch.Generator` o `list[torch.Generator]`, *opcional*) : Un [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html) para hacer la generación determinista.

latents (`torch.Tensor`, *opcional*) : Latentes ruidosos pregenerados muestreados de una distribución gaussiana, que se utilizarán como entradas para la generación de imágenes. Se pueden usar para ajustar la misma generación con diferentes prompts. Si no se proporciona, se genera un tensor de latentes mediante muestreo usando el `generator` aleatorio suministrado.

prompt_embeds (`torch.Tensor`, *opcional*) : Incrustaciones de texto pregeneradas. Se pueden usar para ajustar fácilmente las entradas de texto (ponderación del prompt). Si no se proporcionan, las incrustaciones de texto se generan a partir del argumento de entrada `prompt`.

prompt_embeds_2 (`torch.Tensor`, *opcional*) : Incrustaciones de texto pregeneradas. Se pueden usar para ajustar fácilmente las entradas de texto (ponderación del prompt). Si no se proporcionan, las incrustaciones de texto se generan a partir del argumento de entrada `prompt`.

negative_prompt_embeds (`torch.Tensor`, *opcional*) : Embeddings de texto negativos pregenerados. Se pueden usar para ajustar fácilmente las entradas de texto (ponderación del prompt). Si no se proporcionan, `negative_prompt_embeds` se generan a partir del argumento de entrada `negative_prompt`.

negative_prompt_embeds_2 (`torch.Tensor`, *opcional*) : Embeddings de texto negativos pregenerados. Se pueden usar para ajustar fácilmente las entradas de texto (ponderación del prompt). Si no se proporcionan, `negative_prompt_embeds` se generan a partir del argumento de entrada `negative_prompt`.

prompt_attention_mask (`torch.Tensor`, *opcional*) : Máscara de atención para el prompt. Obligatorio cuando se pasa `prompt_embeds` directamente.

prompt_attention_mask_2 (`torch.Tensor`, *opcional*) : Máscara de atención para el prompt. Obligatorio cuando se pasa `prompt_embeds_2` directamente.

negative_prompt_attention_mask (`torch.Tensor`, *opcional*) : Máscara de atención para el prompt negativo. Obligatorio cuando se pasa `negative_prompt_embeds` directamente.

negative_prompt_attention_mask_2 (`torch.Tensor`, *opcional*) : Máscara de atención para el prompt negativo. Obligatorio cuando se pasa `negative_prompt_embeds_2` directamente.

output_type (`str`, *opcional*, por defecto `"pil"`) : El formato de salida de la imagen generada. Elija entre `PIL.Image` o `np.array`.

return_dict (`bool`, *opcional*, valor predeterminado `True`) : Indica si se debe devolver un [StableDiffusionPipelineOutput](/docs/diffusers/main/es/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) en lugar de una tupla simple.

callback_on_step_end (`Callable[[int, int], None]`, `PipelineCallback`, `MultiPipelineCallbacks`, *opcional*) : Una función de callback o una lista de funciones de callback que se llamarán al final de cada paso de denoising.

callback_on_step_end_tensor_inputs (`list[str]`, *opcional*) : Una lista de entradas de tensor que deben pasarse a la función de callback. Si no se define, se pasarán todas las entradas de tensor.

guidance_rescale (`float`, *opcional*, valor predeterminado 0.0) : Reescala el ruido_cfg según `guidance_rescale`. Basado en los hallazgos de [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891). Ver la sección 3.4

original_size (`tuple[int, int]`, *opcional*, valor predeterminado `(1024, 1024)`) : El tamaño original de la imagen. Se utiliza para calcular los ids de tiempo.

target_size (`tuple[int, int]`, *opcional*) : El tamaño objetivo de la imagen. Se utiliza para calcular los ids de tiempo.

crops_coords_top_left (`tuple[int, int]`, *opcional*, valor predeterminado `(0, 0)`) : Las coordenadas de la esquina superior izquierda del recorte. Se utiliza para calcular los ids de tiempo.

use_resolution_binning (`bool`, *opcional*, valor predeterminado `True`) : Si se usa el agrupamiento por resolución o no. Si es `True`, la resolución de entrada se mapeará a la resolución estándar más cercana. Las resoluciones admitidas son 1024x1024, 1280x1280, 1024x768, 1152x864, 1280x960, 768x1024, 864x1152, 960x1280, 1280x768 y 768x1280. Se recomienda establecerlo en `True`.

**Devuelve:** [StableDiffusionPipelineOutput](/docs/diffusers/main/es/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) o `tuple`

Si `return_dict` es `True`, se devuelve [StableDiffusionPipelineOutput](/docs/diffusers/main/es/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput); en caso contrario, se devuelve una `tuple` cuyo primer elemento es una lista con las imágenes generadas y cuyo segundo elemento es una lista de `bool` que indica si la imagen generada correspondiente contiene contenido "not-safe-for-work" (nsfw).

La función de llamada a la pipeline para la generación con HunyuanDiT.

Ejemplos:
```py
>>> import torch
>>> from diffusers import HunyuanDiTPipeline

>>> pipe = HunyuanDiTPipeline.from_pretrained(
...     "Tencent-Hunyuan/HunyuanDiT-Diffusers", torch_dtype=torch.float16
... )
>>> pipe.to("cuda")

>>> # You may also use English prompt as HunyuanDiT supports both English and Chinese
>>> # prompt = "An astronaut riding a horse"
>>> prompt = "一个宇航员在骑马"
>>> image = pipe(prompt).images[0]
```

#### encode_prompt[[diffusers.HunyuanDiTPipeline.encode_prompt]]

```python
encode_prompt(prompt: str, device: device = None, dtype: dtype = None, num_images_per_prompt: int = 1, do_classifier_free_guidance: bool = True, negative_prompt: str | None = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_attention_mask: typing.Optional[torch.Tensor] = None, negative_prompt_attention_mask: typing.Optional[torch.Tensor] = None, max_sequence_length: int | None = None, text_encoder_index: int = 0)
```

[Fuente](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/hunyuandit/pipeline_hunyuandit.py#L248)

**Parámetros:**

prompt (`str` o `list[str]`, *opcional*) : prompt a codificar

device : (`torch.device`): dispositivo de torch

dtype (`torch.dtype`) : dtype de torch

num_images_per_prompt (`int`) : número de imágenes que deben generarse por prompt

do_classifier_free_guidance (`bool`) : si se debe usar o no la guía libre de clasificador

negative_prompt (`str` o `list[str]`, *opcional*) : El prompt o prompts que no deben guiar la generación de la imagen. Si no se define, se debe pasar `negative_prompt_embeds` en su lugar. Se ignora cuando no se usa guía (es decir, se ignora si `guidance_scale` es menor que `1`).

prompt_embeds (`torch.Tensor`, *opcional*) : Embeddings de texto pregenerados. Se pueden usar para ajustar fácilmente las entradas de texto, *p. ej.* ponderación de prompts. Si no se proporcionan, los embeddings de texto se generarán a partir del argumento de entrada `prompt`.

negative_prompt_embeds (`torch.Tensor`, *opcional*) : Embeddings de texto negativos pregenerados. Se pueden utilizar para ajustar fácilmente las entradas de texto, *p. ej.* el ponderado de prompts. Si no se proporcionan, negative_prompt_embeds se generará a partir del argumento de entrada `negative_prompt`.

prompt_attention_mask (`torch.Tensor`, *opcional*) : Máscara de atención para el prompt. Obligatorio cuando se pasa `prompt_embeds` directamente.

negative_prompt_attention_mask (`torch.Tensor`, *opcional*) : Máscara de atención para el prompt negativo. Obligatorio cuando se pasa `negative_prompt_embeds` directamente.

max_sequence_length (`int`, *opcional*) : longitud máxima de la secuencia a utilizar para el prompt.

text_encoder_index (`int`, *opcional*) : Índice del codificador de texto a utilizar. `0` para clip y `1` para T5.

Codifica el prompt en estados ocultos del codificador de texto.