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

[Hunyuan-DiT: um poderoso Diffusion Transformer multi-resolução com compreensão detalhada do chinês](https://huggingface.co/papers/2405.08748) da Tencent Hunyuan.

O resumo do artigo é:

*Apresentamos o Hunyuan-DiT, um difusão transformer de texto para imagem com compreensão detalhada tanto do inglês quanto do chinês. Para construir o Hunyuan-DiT, projetamos cuidadosamente a estrutura do transformer, o codificador de texto e a codificação posicional. Também construímos do zero um pipeline de dados completo para atualizar e avaliar dados para otimização iterativa do modelo. Para a compreensão linguística detalhada, treinamos um Modelo de Linguagem Grande Multimodal para refinar as legendas das imagens. Por fim, o Hunyuan-DiT pode realizar diálogos multimodais de múltiplas rodadas com usuários, gerando e refinando imagens de acordo com o contexto. Por meio de nosso protocolo holístico de avaliação humana com mais de 50 avaliadores humanos profissionais, o Hunyuan-DiT estabelece um novo estado da arte na geração de imagens a partir do chinês em comparação com outros modelos de código aberto.*

Você pode encontrar a base de código original em [Tencent/HunyuanDiT](https://github.com/Tencent/HunyuanDiT) e todos os checkpoints disponíveis em [Tencent-Hunyuan](https://huggingface.co/Tencent-Hunyuan/HunyuanDiT).

**Destaques**: HunyuanDiT suporta geração de imagem a partir de texto em chinês/inglês e geração em múltiplas resoluções.

O HunyuanDiT possui os seguintes componentes:
* Ele usa um transformer de difusão como espinha dorsal
* Ele combina dois codificadores de texto, um CLIP bilíngue e um codificador T5 multilíngue

> [!TIP]
> Certifique-se de consultar o [guia](../../using-diffusers/schedulers) de Schedulers para aprender a explorar o compromisso entre a velocidade e a qualidade do scheduler, e veja a seção [reutilização de componentes entre pipelines](../../using-diffusers/loading#reusing-models-in-multiple-pipelines) para aprender a carregar eficientemente os mesmos componentes em vários pipelines.

> [!TIP]
> Você pode melhorar ainda mais a qualidade da geração passando a imagem gerada pelo `HungyuanDiTPipeline` para o modelo [SDXL refiner](./stable_diffusion/stable_diffusion_xl#base-to-refiner-model).

## Otimização

Você pode otimizar o tempo de execução e o consumo de memória do pipeline com torch.compile e feed-forward chunking. Para saber sobre outros métodos de otimização, consulte os guias [Acelerar a inferência](../../optimization/fp16) e [Reduzir o uso de memória](../../optimization/memory).

### Inferência

Use [`torch.compile`](https://huggingface.co/docs/diffusers/main/en/tutorials/fast_diffusion#torchcompile) para reduzir a latência de inferência.

Primeiro, carregue o 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"
```

Em seguida, altere o layout de memória dos componentes `transformer` e `vae` dos pipelines para `torch.channels-last`:

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

Por fim, compile os componentes e execute a inferência:

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

Os resultados do [benchmark](https://gist.github.com/sayakpaul/29d3a14905cfcbf611fe71ebd22e9b23) em uma máquina A100 de 80GB são:

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

### Otimização de memória

Ao carregar o codificador de texto T5 em 8 bits, você pode executar o pipeline com menos de 6 GB de VRAM na GPU. Consulte [este script](https://gist.github.com/sayakpaul/3154605f6af05b98a41081aaba5ca43e) para mais detalhes.

Além disso, você pode usar o método [enable_forward_chunking()](/docs/diffusers/v0.43.0/pt/api/models/hunyuan_transformer2d#diffusers.HunyuanDiT2DModel.enable_forward_chunking) para reduzir o uso de memória. O feed-forward chunking executa as camadas feed-forward em um bloco de transformer em um loop, em vez de tudo de uma vez. Isso oferece um compromisso entre o consumo de memória e o tempo de execução da inferência.

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

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

**Parâmetros:**

vae ([AutoencoderKL](/docs/diffusers/v0.43.0/pt/api/models/autoencoderkl#diffusers.AutoencoderKL)) : Modelo de Variational Auto-Encoder (VAE) para codificar e decodificar imagens para e a partir de representações latentes. Usamos `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)). O HunyuanDiT usa um [CLIP bilíngue] ajustado finamente.

tokenizer (`~transformers.BertTokenizer`, `~transformers.CLIPTokenizer` | None) : Um `BertTokenizer` ou `CLIPTokenizer` para tokenizar texto.

transformer ([HunyuanDiT2DModel](/docs/diffusers/v0.43.0/pt/api/models/hunyuan_transformer2d#diffusers.HunyuanDiT2DModel)) : O modelo HunyuanDiT desenvolvido pelo Tencent Hunyuan.

text_encoder_2 (`T5EncoderModel`) : O incorporador mT5. Especificamente, é o 't5-v1_1-xxl'.

tokenizer_2 (`T5Tokenizer`) : O tokenizador do incorporador mT5.

scheduler ([DDPMScheduler](/docs/diffusers/v0.43.0/pt/api/schedulers/ddpm#diffusers.DDPMScheduler)) : Um agendador a ser usado em combinação com HunyuanDiT para desruidar os latentes de imagem codificados.

Pipeline para geração de imagens a partir de inglês/chinês usando HunyuanDiT.

Este modelo herda de [DiffusionPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/overview#diffusers.DiffusionPipeline). Consulte a documentação da superclasse para os métodos genéricos que a biblioteca implementa para todos os pipelines (como download ou salvamento, execução em um dispositivo específico, etc.)

HunyuanDiT usa dois codificadores de texto: [mT5](https://huggingface.co/google/mt5-base) e [CLIP bilíngue](ajustado por nós mesmos)

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

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

**Parâmetros:**

prompt (`str` ou `list[str]`, *opcional*) : O prompt ou os prompts para orientar a geração de imagens. Se não definido, você precisa passar `prompt_embeds`.

height (`int`) : A altura, em pixels, da imagem gerada.

width (`int`) : A largura, em pixels, da imagem gerada.

num_inference_steps (`int`, *opcional*, padrão 50) : O número de etapas de desruidamento. Mais etapas de desruidamento geralmente resultam em uma imagem de maior qualidade, às custas de uma inferência mais lenta. Este parâmetro é modulado por `strength`.

guidance_scale (`float`, *opcional*, padrão 7.5) : Um valor mais alto de guidance scale incentiva o modelo a gerar imagens fortemente ligadas ao `prompt` de texto, em detrimento de uma menor qualidade de imagem. O guidance scale é ativado quando `guidance_scale > 1`.

negative_prompt (`str` ou `list[str]`, *opcional*) : O prompt ou os prompts para orientar o que não incluir na geração de imagem. Se não definido, você precisa passar `negative_prompt_embeds` em vez disso. Ignorado quando não está usando orientação (`guidance_scale < 1`).

num_images_per_prompt (`int`, *opcional*, padrão 1) : O número de imagens a serem geradas por prompt.

eta (`float`, *opcional*, padrão 0.0) : Corresponde ao parâmetro eta (η) do paper [DDIM](https://huggingface.co/papers/2010.02502). Aplica-se apenas ao [DDIMScheduler](/docs/diffusers/v0.43.0/pt/api/schedulers/ddim#diffusers.DDIMScheduler) e é ignorado em outros agendadores.

generator (`torch.Generator` ou `list[torch.Generator]`, *opcional*) : Um [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html) para tornar a geração determinística.

latents (`torch.Tensor`, *opcional*) : Latentes ruidosos pré-gerados, amostrados de uma distribuição gaussiana, a serem usados como entradas para a geração de imagens. Pode ser usado para ajustar a mesma geração com diferentes prompts. Se não for fornecido, um tensor de latentes é gerado por amostragem usando o `generator` aleatório fornecido.

prompt_embeds (`torch.Tensor`, *opcional*) : Incorporações de texto pré-geradas. Podem ser usadas para ajustar facilmente as entradas de texto (ponderação do prompt). Se não forem fornecidas, as incorporações de texto são geradas a partir do argumento de entrada `prompt`.

prompt_embeds_2 (`torch.Tensor`, *opcional*) : Incorporações de texto pré-geradas. Podem ser usadas para ajustar facilmente as entradas de texto (ponderação do prompt). Se não forem fornecidas, as incorporações de texto são geradas a partir do argumento de entrada `prompt`.

negative_prompt_embeds (`torch.Tensor`, *opcional*) : Embeddings de texto negativo pré-gerados. Podem ser usados para ajustar facilmente as entradas de texto (ponderação do prompt). Se não forem fornecidos, `negative_prompt_embeds` são gerados a partir do argumento de entrada `negative_prompt`.

negative_prompt_embeds_2 (`torch.Tensor`, *opcional*) : Embeddings de texto negativo pré-gerados. Podem ser usados para ajustar facilmente as entradas de texto (ponderação do prompt). Se não forem fornecidos, `negative_prompt_embeds` são gerados a partir do argumento de entrada `negative_prompt`.

prompt_attention_mask (`torch.Tensor`, *opcional*) : Máscara de atenção para o prompt. Obrigatória quando `prompt_embeds` é passado diretamente.

prompt_attention_mask_2 (`torch.Tensor`, *opcional*) : Máscara de atenção para o prompt. Obrigatória quando `prompt_embeds_2` é passado diretamente.

negative_prompt_attention_mask (`torch.Tensor`, *opcional*) : Máscara de atenção para o prompt negativo. Obrigatória quando `negative_prompt_embeds` é passado diretamente.

negative_prompt_attention_mask_2 (`torch.Tensor`, *opcional*) : Máscara de atenção para o prompt negativo. Obrigatória quando `negative_prompt_embeds_2` é passado diretamente.

output_type (`str`, *opcional*, padrão `"pil"`) : O formato de saída da imagem gerada. Escolha entre `PIL.Image` ou `np.array`.

return_dict (`bool`, *opcional*, padrão `True`) : Se deve ou não retornar um [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/pt/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) em vez de uma tupla simples.

callback_on_step_end (`Callable[[int, int], None]`, `PipelineCallback`, `MultiPipelineCallbacks`, *opcional*) : Uma função de callback ou uma lista de funções de callback a serem chamadas no final de cada etapa de remoção de ruído.

callback_on_step_end_tensor_inputs (`list[str]`, *opcional*) : Uma lista de entradas de tensor que devem ser passadas para a função de callback. Se não for definida, todas as entradas de tensor serão passadas.

guidance_rescale (`float`, *opcional*, padrão 0.0) : Reescala o noise_cfg de acordo com `guidance_rescale`. Baseado nas descobertas de [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891). Veja a Seção 3.4

original_size (`tuple[int, int]`, *opcional*, padrão `(1024, 1024)`) : O tamanho original da imagem. Usado para calcular os ids de tempo.

target_size (`tuple[int, int]`, *opcional*) : O tamanho alvo da imagem. Usado para calcular os ids de tempo.

crops_coords_top_left (`tuple[int, int]`, *opcional*, padrão `(0, 0)`) : As coordenadas do canto superior esquerdo do recorte. Usado para calcular os ids de tempo.

use_resolution_binning (`bool`, *opcional*, padrão `True`) : Se deve usar binning de resolução ou não. Se `True`, a resolução de entrada será mapeada para a resolução padrão mais próxima. As resoluções suportadas são 1024x1024, 1280x1280, 1024x768, 1152x864, 1280x960, 768x1024, 864x1152, 960x1280, 1280x768 e 768x1280. Recomenda-se definir este valor como `True`.

**Retorna:** [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/pt/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) ou `tuple`

Se `return_dict` for `True`, [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/pt/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) é retornado; caso contrário, uma `tuple` é retornada, em que o primeiro elemento é uma lista com as imagens geradas e o segundo elemento é uma lista de `bool`s indicando se a imagem gerada correspondente contém conteúdo "not-safe-for-work" (nsfw).

A função de chamada do pipeline para geração com HunyuanDiT.

Exemplos:
```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)
```

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

**Parâmetros:**

prompt (`str` ou `list[str]`, *opcional*) : prompt a ser codificado

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

dtype (`torch.dtype`) : dtype do torch

num_images_per_prompt (`int`) : número de imagens que devem ser geradas por prompt

do_classifier_free_guidance (`bool`) : se deve ou não usar classifier free guidance

negative_prompt (`str` ou `list[str]`, *opcional*) : O prompt ou os prompts que não devem orientar a geração da imagem. Se não definido, é necessário passar `negative_prompt_embeds` em vez disso. Ignorado quando não se usa orientação (ou seja, ignorado se `guidance_scale` for menor que `1`).

prompt_embeds (`torch.Tensor`, *opcional*) : Embeddings de texto pré-gerados. Podem ser usados para ajustar facilmente as entradas de texto, *por exemplo*, ponderação de prompts. Se não forem fornecidos, os embeddings de texto serão gerados a partir do argumento de entrada `prompt`.

negative_prompt_embeds (`torch.Tensor`, *opcional*) : Embeddings de texto negativos pré-gerados. Podem ser usados para ajustar facilmente as entradas de texto, *por exemplo*, ponderação de prompts. Se não forem fornecidos, negative_prompt_embeds será gerado a partir do argumento de entrada `negative_prompt`.

prompt_attention_mask (`torch.Tensor`, *opcional*) : Máscara de atenção para o prompt. Obrigatória quando `prompt_embeds` é passado diretamente.

negative_prompt_attention_mask (`torch.Tensor`, *opcional*) : Máscara de atenção para o prompt negativo. Obrigatória quando `negative_prompt_embeds` é passado diretamente.

max_sequence_length (`int`, *opcional*) : comprimento máximo da sequência a ser usado para o prompt.

text_encoder_index (`int`, *opcional*) : Índice do codificador de texto a ser usado. `0` para clip e `1` para T5.

Codifica o prompt em estados ocultos do codificador de texto.