# ControlNet dengan Hunyuan-DiT

HunyuanDiTControlNetPipeline adalah implementasi ControlNet untuk [Hunyuan-DiT](https://huggingface.co/papers/2405.08748).

ControlNet diperkenalkan dalam [Menambahkan Kontrol Kondisional ke Model Difusi Teks-ke-Gambar](https://huggingface.co/papers/2302.05543) oleh Lvmin Zhang, Anyi Rao, dan Maneesh Agrawala.

Dengan model ControlNet, Anda dapat menyediakan gambar kontrol tambahan untuk mengondisikan dan mengendalikan generasi Hunyuan-DiT. Misalnya, jika Anda menyediakan peta kedalaman, model ControlNet akan menghasilkan gambar yang mempertahankan informasi spasial dari peta kedalaman tersebut. Ini adalah cara yang lebih fleksibel dan akurat untuk mengendalikan proses generasi gambar.

Abstrak dari makalah tersebut adalah:

*Kami memperkenalkan ControlNet, sebuah arsitektur jaringan saraf untuk menambahkan kontrol kondisional spasial ke model difusi teks-ke-gambar besar yang telah dilatih sebelumnya. ControlNet mengunci model difusi besar yang siap produksi, dan memanfaatkan ulang lapisan enkoding yang dalam dan robust yang telah dilatih sebelumnya dengan miliaran gambar sebagai tulang punggung yang kuat untuk mempelajari berbagai set kontrol kondisional. Arsitektur saraf ini terhubung dengan "zero convolutions" (lapisan konvolusi yang diinisialisasi nol) yang secara bertahap meningkatkan parameter dari nol dan memastikan bahwa tidak ada noise berbahaya yang dapat memengaruhi finetuning. Kami menguji berbagai kontrol kondisional, misalnya, tepi, kedalaman, segmentasi, pose manusia, dll., dengan Stable Diffusion, menggunakan satu atau beberapa kondisi, dengan atau tanpa prompt. Kami menunjukkan bahwa pelatihan ControlNet bersifat robust dengan dataset kecil (<50k) dan besar (>1m). Hasil ekstensif menunjukkan bahwa ControlNet dapat memfasilitasi aplikasi yang lebih luas untuk mengontrol model difusi gambar.*

Kode ini diimplementasikan oleh Tencent Hunyuan Team. Anda dapat menemukan checkpoint pre-trained untuk Hunyuan-DiT ControlNets di [Tencent Hunyuan](https://huggingface.co/Tencent-Hunyuan).

> [!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.

## HunyuanDiTControlNetPipeline[[diffusers.HunyuanDiTControlNetPipeline]]

#### diffusers.HunyuanDiTControlNetPipeline[[diffusers.HunyuanDiTControlNetPipeline]]

```python
diffusers.HunyuanDiTControlNetPipeline(vae: AutoencoderKL, text_encoder: BertModel, tokenizer: BertTokenizer, transformer: HunyuanDiT2DModel, scheduler: DDPMScheduler, safety_checker: StableDiffusionSafetyChecker, feature_extractor: CLIPImageProcessorPil, controlnet: diffusers.models.controlnets.controlnet_hunyuan.HunyuanDiT2DControlNetModel | list[diffusers.models.controlnets.controlnet_hunyuan.HunyuanDiT2DControlNetModel] | tuple[diffusers.models.controlnets.controlnet_hunyuan.HunyuanDiT2DControlNetModel] | diffusers.models.controlnets.controlnet_hunyuan.HunyuanDiT2DMultiControlNetModel, text_encoder_2: transformers.models.t5.modeling_t5.T5EncoderModel | None = None, tokenizer_2: transformers.models.t5.tokenization_t5.T5Tokenizer | None = None, requires_safety_checker: bool = True)
```

[Sumber](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/controlnet_hunyuandit/pipeline_hunyuandit_controlnet.py#L165)

**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.

controlnet ([HunyuanDiT2DControlNetModel](/docs/diffusers/v0.43.0/id/api/models/controlnet_hunyuandit#diffusers.HunyuanDiT2DControlNetModel) atau `list[HunyuanDiT2DControlNetModel]` atau [HunyuanDiT2DControlNetModel](/docs/diffusers/v0.43.0/id/api/models/controlnet_hunyuandit#diffusers.HunyuanDiT2DControlNetModel)) : Menyediakan kondisioning tambahan untuk `unet` selama proses denoising. Jika Anda mengatur beberapa ControlNet sebagai list, output dari masing-masing ControlNet akan dijumlahkan untuk membuat satu kondisioning tambahan yang digabungkan.

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.HunyuanDiTControlNetPipeline.__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, control_image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor]] = None, controlnet_conditioning_scale: float | list[float] = 1.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/controlnet_hunyuandit/pipeline_hunyuandit_controlnet.py#L632)

**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`.

control_image (`torch.Tensor`, `PIL.Image.Image`, `np.ndarray`, `list[torch.Tensor]`, `list[PIL.Image.Image]`, `list[np.ndarray]`, : `list[list[torch.Tensor]]`, `list[list[np.ndarray]]` atau `list[list[PIL.Image.Image]]`): Kondisi input ControlNet untuk memberikan panduan kepada `unet` dalam proses generasi. Jika tipe yang ditentukan adalah `torch.Tensor`, data diteruskan ke ControlNet apa adanya. `PIL.Image.Image` juga dapat diterima sebagai gambar. Dimensi gambar output secara default mengikuti dimensi `image`. Jika tinggi dan/atau lebar diteruskan, `image` akan di-resize sesuai dengan nilai tersebut. Jika beberapa ControlNet ditentukan dalam `init`, gambar harus diteruskan sebagai daftar sehingga setiap elemen dalam daftar dapat di-batch dengan benar untuk input ke satu ControlNet.

controlnet_conditioning_scale (`float` atau `list[float]`, *opsional*, default 1.0) : Output dari ControlNet dikalikan dengan `controlnet_conditioning_scale` sebelum ditambahkan ke residual di `unet` asli. Jika beberapa ControlNet ditentukan di `init`, Anda dapat mengatur skala yang sesuai sebagai list.

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
from diffusers import HunyuanDiT2DControlNetModel, HunyuanDiTControlNetPipeline
import torch

controlnet = HunyuanDiT2DControlNetModel.from_pretrained(
    "Tencent-Hunyuan/HunyuanDiT-v1.1-ControlNet-Diffusers-Canny", torch_dtype=torch.float16
)

pipe = HunyuanDiTControlNetPipeline.from_pretrained(
    "Tencent-Hunyuan/HunyuanDiT-v1.1-Diffusers", controlnet=controlnet, torch_dtype=torch.float16
)
pipe.to("cuda")

from diffusers.utils import load_image

cond_image = load_image(
    "https://huggingface.co/Tencent-Hunyuan/HunyuanDiT-v1.1-ControlNet-Diffusers-Canny/resolve/main/canny.jpg?download=true"
)

## You may also use English prompt as HunyuanDiT supports both English and Chinese
prompt = "在夜晚的酒店门前，一座古老的中国风格的狮子雕像矗立着，它的眼睛闪烁着光芒，仿佛在守护着这座建筑。背景是夜晚的酒店前，构图方式是特写，平视，居中构图。这张照片呈现了真实摄影风格，蕴含了中国雕塑文化，同时展现了神秘氛围"
# prompt="At night, an ancient Chinese-style lion statue stands in front of the hotel, its eyes gleaming as if guarding the building. The background is the hotel entrance at night, with a close-up, eye-level, and centered composition. This photo presents a realistic photographic style, embodies Chinese sculpture culture, and reveals a mysterious atmosphere."
image = pipe(
    prompt,
    height=1024,
    width=1024,
    control_image=cond_image,
    num_inference_steps=50,
).images[0]
```

#### encode_prompt[[diffusers.HunyuanDiTControlNetPipeline.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/controlnet_hunyuandit/pipeline_hunyuandit_controlnet.py#L276)

**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.