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

[Hunyuan-DiT: A Powerful Multi-Resolution Diffusion Transformer with Fine-Grained Chinese Understanding](https://huggingface.co/papers/2405.08748) dari Tencent Hunyuan.

Abstrak dari makalah tersebut adalah:

*Kami memperkenalkan Hunyuan-DiT, sebuah diffusion transformer untuk teks-ke-gambar dengan pemahaman yang rinci terhadap bahasa Inggris dan Mandarin. Untuk membangun Hunyuan-DiT, kami merancang dengan cermat struktur transformer, text encoder, dan positional encoding. Kami juga membangun dari nol seluruh pipeline data untuk memperbarui dan mengevaluasi data guna optimasi model secara iteratif. Untuk pemahaman bahasa yang rinci, kami melatih Multimodal Large Language Model untuk menyempurnakan caption dari gambar-gambar tersebut. Akhirnya, Hunyuan-DiT dapat melakukan dialog multimodal multi-turn dengan pengguna, menghasilkan dan menyempurnakan gambar sesuai dengan konteks. Melalui protokol evaluasi manusia holistik kami yang melibatkan lebih dari 50 evaluator manusia profesional, Hunyuan-DiT menetapkan state-of-the-art baru dalam generasi gambar dari bahasa Mandarin dibandingkan dengan model open-source lainnya.*

Anda dapat menemukan basis kode asli di [Tencent/HunyuanDiT](https://github.com/Tencent/HunyuanDiT) dan semua checkpoint yang tersedia di [Tencent-Hunyuan](https://huggingface.co/Tencent-Hunyuan/HunyuanDiT).

**Highlight**: HunyuanDiT mendukung teks bahasa Mandarin/Inggris ke gambar, serta generasi multi-resolusi.

HunyuanDiT memiliki komponen-komponen berikut:
* Model ini menggunakan diffusion transformer sebagai backbone
* Itu menggabungkan dua pengkode teks, CLIP dwibahasa dan pengkode T5 multibahasa

> [!TIP]
> Pastikan untuk melihat [panduan](../../using-diffusers/schedulers) Schedulers untuk mempelajari cara mengeksplorasi tradeoff antara kecepatan dan kualitas scheduler, serta lihat bagian [reuse components across pipelines](../../using-diffusers/loading#reusing-models-in-multiple-pipelines) untuk mempelajari cara memuat komponen yang sama secara efisien ke dalam beberapa pipeline.

> [!TIP]
> Anda dapat meningkatkan kualitas generasi lebih lanjut dengan meneruskan gambar yang dihasilkan dari `HungyuanDiTPipeline` ke model [SDXL refiner](./stable_diffusion/stable_diffusion_xl#base-to-refiner-model).

## Optimasi

Anda dapat mengoptimalkan waktu eksekusi dan konsumsi memori pipeline dengan torch.compile dan feed-forward chunking. Untuk mempelajari metode optimasi lainnya, lihat panduan [Speed up inference](../../optimization/fp16) dan [Reduce memory usage](../../optimization/memory).

### Inferensi

Gunakan [`torch.compile`](https://huggingface.co/docs/diffusers/main/en/tutorials/fast_diffusion#torchcompile) untuk mengurangi latensi inferensi.

Pertama, muat 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"
```

Lalu ubah tata letak memori komponen `transformer` dan `vae` menjadi `torch.channels-last`:

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

Terakhir, kompilasi komponen dan jalankan inferensi:

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

Hasil [benchmark](https://gist.github.com/sayakpaul/29d3a14905cfcbf611fe71ebd22e9b23) pada mesin A100 80GB adalah:

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

### Optimasi memori

Dengan memuat T5 text encoder dalam 8 bit, Anda dapat menjalankan pipeline dengan VRAM GPU kurang dari 6 GB. Lihat [skrip ini](https://gist.github.com/sayakpaul/3154605f6af05b98a41081aaba5ca43e) untuk detailnya.

Selain itu, Anda dapat menggunakan metode [enable_forward_chunking()](/docs/diffusers/v0.43.0/id/api/models/hunyuan_transformer2d#diffusers.HunyuanDiT2DModel.enable_forward_chunking) untuk mengurangi penggunaan memori. Feed-forward chunking menjalankan lapisan feed-forward dalam blok transformer secara berurutan dalam sebuah loop, bukan sekaligus. Hal ini memberikan Anda trade-off antara konsumsi memori dan waktu runtime inferensi.

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

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

**Parameter:**

vae ([AutoencoderKL](/docs/diffusers/v0.43.0/id/api/models/autoencoderkl#diffusers.AutoencoderKL)) : Model Variational Auto-Encoder (VAE) untuk mengodekan dan mendekodekan gambar ke dan dari representasi laten. Kami menggunakan `sdxl-vae-fp16-fix`.

text_encoder (`~transformers.BertModel`, `~transformers.CLIPTextModel` | None) : Text-encoder beku ([clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14)). HunyuanDiT menggunakan [bilingual CLIP] yang telah dihaluskan.

tokenizer (`~transformers.BertTokenizer`, `~transformers.CLIPTokenizer` | None) : `BertTokenizer` atau `CLIPTokenizer` untuk melakukan tokenisasi teks.

transformer ([HunyuanDiT2DModel](/docs/diffusers/v0.43.0/id/api/models/hunyuan_transformer2d#diffusers.HunyuanDiT2DModel)) : Model HunyuanDiT yang dirancang oleh Tencent Hunyuan.

text_encoder_2 (`T5EncoderModel`) : Embedder mT5. Secara spesifik, modelnya adalah 't5-v1_1-xxl'.

tokenizer_2 (`T5Tokenizer`) : Tokenizer untuk embedder mT5.

scheduler ([DDPMScheduler](/docs/diffusers/v0.43.0/id/api/schedulers/ddpm#diffusers.DDPMScheduler)) : Penjadwal yang digunakan bersama HunyuanDiT untuk menghilangkan noise pada latens gambar yang telah dikodekan.

Pipeline untuk generasi gambar dari bahasa Inggris/Tionghoa menggunakan HunyuanDiT.

Model ini mewarisi dari [DiffusionPipeline](/docs/diffusers/v0.43.0/id/api/pipelines/overview#diffusers.DiffusionPipeline). Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan oleh pustaka untuk semua pipeline (seperti mengunduh atau menyimpan, menjalankan pada perangkat tertentu, dll.)

HunyuanDiT menggunakan dua pengkode teks: [mT5](https://huggingface.co/google/mt5-base) dan [CLIP dwibahasa](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)
```

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

**Parameter:**

prompt (`str` atau `list[str]`, *opsional*) : Prompt atau prompt-prompt untuk memandu generasi gambar. Jika tidak didefinisikan, Anda perlu meneruskan `prompt_embeds`.

height (`int`) : Tinggi gambar yang dihasilkan dalam piksel.

width (`int`) : Lebar gambar yang dihasilkan dalam piksel.

num_inference_steps (`int`, *opsional*, default 50) : Jumlah langkah denoising. Semakin banyak langkah denoising, biasanya menghasilkan gambar dengan kualitas lebih tinggi, namun dengan biaya inferensi yang lebih lambat. Parameter ini dimodulasi oleh `strength`.

guidance_scale (`float`, *opsional*, default 7.5) : Nilai guidance scale yang lebih tinggi mendorong model untuk menghasilkan gambar yang sangat terkait dengan `prompt` teks, dengan mengorbankan kualitas gambar yang lebih rendah. Guidance scale diaktifkan ketika `guidance_scale > 1`.

negative_prompt (`str` atau `list[str]`, *opsional*) : Prompt atau prompt-prompt untuk mengarahkan apa yang tidak boleh disertakan dalam pembuatan gambar. Jika tidak didefinisikan, Anda perlu meneruskan `negative_prompt_embeds` sebagai gantinya. Diabaikan saat tidak menggunakan panduan (`guidance_scale < 1`).

num_images_per_prompt (`int`, *opsional*, default 1) : Jumlah gambar yang akan dihasilkan per prompt.

eta (`float`, *opsional*, default 0.0) : Bersesuaian dengan parameter eta (η) dari paper [DDIM](https://huggingface.co/papers/2010.02502). Hanya berlaku untuk [DDIMScheduler](/docs/diffusers/v0.43.0/id/api/schedulers/ddim#diffusers.DDIMScheduler), dan diabaikan pada scheduler lainnya.

generator (`torch.Generator` atau `list[torch.Generator]`, *opsional*) : Sebuah [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html) untuk membuat proses generasi menjadi deterministik.

latents (`torch.Tensor`, *opsional*) : Laten berisik yang telah dibuat sebelumnya, diambil dari distribusi Gaussian, untuk digunakan sebagai input untuk generasi gambar. Dapat digunakan untuk menyesuaikan generasi yang sama dengan prompt yang berbeda. Jika tidak disediakan, tensor laten akan dibuat dengan pengambilan sampel menggunakan `generator` acak yang diberikan.

prompt_embeds (`torch.Tensor`, *opsional*) : Embedding teks yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks (pemberian bobot pada prompt). Jika tidak disediakan, embedding teks akan dihasilkan dari argumen input `prompt`.

prompt_embeds_2 (`torch.Tensor`, *opsional*) : Embedding teks yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks (pemberian bobot pada prompt). Jika tidak disediakan, embedding teks akan dihasilkan dari argumen input `prompt`.

negative_prompt_embeds (`torch.Tensor`, *opsional*) : Embedding teks negatif yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks (pemberian bobot pada prompt). Jika tidak disediakan, `negative_prompt_embeds` akan dibuat dari argumen input `negative_prompt`.

negative_prompt_embeds_2 (`torch.Tensor`, *opsional*) : Embedding teks negatif yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks (pemberian bobot pada prompt). Jika tidak disediakan, `negative_prompt_embeds` akan dibuat dari argumen input `negative_prompt`.

prompt_attention_mask (`torch.Tensor`, *opsional*) : Attention mask untuk prompt. Wajib diisi ketika `prompt_embeds` dilewatkan secara langsung.

prompt_attention_mask_2 (`torch.Tensor`, *opsional*) : Attention mask untuk prompt. Wajib diisi ketika `prompt_embeds_2` dilewatkan secara langsung.

negative_prompt_attention_mask (`torch.Tensor`, *opsional*) : Attention mask untuk negative prompt. Diperlukan ketika `negative_prompt_embeds` dilewatkan secara langsung.

negative_prompt_attention_mask_2 (`torch.Tensor`, *opsional*) : Attention mask untuk negative prompt. Diperlukan ketika `negative_prompt_embeds_2` dilewatkan secara langsung.

output_type (`str`, *opsional*, defaultnya `"pil"`) : Format output dari gambar yang dihasilkan. Pilih antara `PIL.Image` atau `np.array`.

return_dict (`bool`, *opsional*, defaultnya `True`) : Apakah akan mengembalikan [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/id/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) alih-alih tuple biasa.

callback_on_step_end (`Callable[[int, int], None]`, `PipelineCallback`, `MultiPipelineCallbacks`, *opsional*) : Fungsi callback atau daftar fungsi callback yang akan dipanggil di akhir setiap langkah denoising.

callback_on_step_end_tensor_inputs (`list[str]`, *opsional*) : Daftar input tensor yang harus diteruskan ke fungsi callback. Jika tidak didefinisikan, semua input tensor akan diteruskan.

guidance_rescale (`float`, *opsional*, default 0.0) : Skala ulang noise_cfg sesuai dengan `guidance_rescale`. Berdasarkan temuan dari [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891). Lihat Bagian 3.4

original_size (`tuple[int, int]`, *opsional*, defaultnya `(1024, 1024)`) : Ukuran asli gambar. Digunakan untuk menghitung time ids.

target_size (`tuple[int, int]`, *opsional*) : Ukuran target dari gambar. Digunakan untuk menghitung time ids.

crops_coords_top_left (`tuple[int, int]`, *opsional*, defaultnya `(0, 0)`) : Koordinat kiri atas dari crop. Digunakan untuk menghitung time ids.

use_resolution_binning (`bool`, *opsional*, defaultnya `True`) : Apakah akan menggunakan resolusi binning atau tidak. Jika `True`, resolusi input akan dipetakan ke resolusi standar terdekat. Resolusi yang didukung adalah 1024x1024, 1280x1280, 1024x768, 1152x864, 1280x960, 768x1024, 864x1152, 960x1280, 1280x768, dan 768x1280. Disarankan untuk mengatur ini ke `True`.

**Mengembalikan:** [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/id/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) atau `tuple`

Jika `return_dict` adalah `True`, [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/id/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) dikembalikan, selain itu sebuah `tuple` dikembalikan di mana elemen pertama adalah daftar dengan gambar yang dihasilkan dan elemen kedua adalah daftar `bool` yang menunjukkan apakah gambar yang dihasilkan yang sesuai mengandung konten "not-safe-for-work" (nsfw).

Fungsi panggilan untuk pipeline generasi dengan HunyuanDiT.

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

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

**Parameter:**

prompt (`str` atau `list[str]`, *opsional*) : prompt yang akan dienkod

device : (`torch.device`): perangkat torch

dtype (`torch.dtype`) : dtype torch

num_images_per_prompt (`int`) : jumlah gambar yang harus dihasilkan per prompt

do_classifier_free_guidance (`bool`) : apakah akan menggunakan classifier free guidance atau tidak

negative_prompt (`str` atau `list[str]`, *opsional*) : Prompt atau prompt-prompt yang tidak akan memandu generasi gambar. Jika tidak didefinisikan, Anda harus meneruskan `negative_prompt_embeds` sebagai gantinya. Diabaikan saat tidak menggunakan guidance (yaitu, diabaikan jika `guidance_scale` kurang dari `1`).

prompt_embeds (`torch.Tensor`, *opsional*) : Embedding teks yang sudah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, *misalnya* penimbangan prompt. Jika tidak disediakan, embedding teks akan dihasilkan dari argumen input `prompt`.

negative_prompt_embeds (`torch.Tensor`, *opsional*) : Embedding teks negatif yang telah dibuat sebelumnya. Dapat digunakan untuk dengan mudah menyesuaikan input teks, *misalnya* penimbangan prompt. Jika tidak disediakan, negative_prompt_embeds akan dibuat dari argumen input `negative_prompt`.

prompt_attention_mask (`torch.Tensor`, *opsional*) : Attention mask untuk prompt. Wajib diisi ketika `prompt_embeds` dilewatkan secara langsung.

negative_prompt_attention_mask (`torch.Tensor`, *opsional*) : Attention mask untuk negative prompt. Diperlukan ketika `negative_prompt_embeds` dilewatkan secara langsung.

max_sequence_length (`int`, *opsional*) : panjang maksimum urutan yang akan digunakan untuk prompt.

text_encoder_index (`int`, *opsional*) : Indeks dari text encoder yang akan digunakan. `0` untuk clip dan `1` untuk T5.

Mengkodekan prompt menjadi hidden states dari text encoder.