# ControlNet với Hunyuan-DiT

HunyuanDiTControlNetPipeline là một triển khai của ControlNet cho [Hunyuan-DiT](https://huggingface.co/papers/2405.08748).

ControlNet được giới thiệu trong [Adding Conditional Control to Text-to-Image Diffusion Models](https://huggingface.co/papers/2302.05543) bởi Lvmin Zhang, Anyi Rao và Maneesh Agrawala.

Với một mô hình ControlNet, bạn có thể cung cấp một hình ảnh điều khiển bổ sung để điều kiện hóa và kiểm soát quá trình tạo hình ảnh của Hunyuan-DiT. Ví dụ, nếu bạn cung cấp một bản đồ độ sâu, mô hình ControlNet sẽ tạo ra một hình ảnh giữ lại thông tin không gian từ bản đồ độ sâu. Đây là một cách linh hoạt và chính xác hơn để kiểm soát quá trình tạo hình ảnh.

Tóm tắt từ bài báo là:

*Chúng tôi giới thiệu ControlNet, một kiến trúc mạng nơ-ron để thêm các điều khiển điều kiện không gian vào các mô hình khuếch tán từ văn bản sang ảnh lớn, được huấn luyện trước. ControlNet khóa các mô hình khuếch tán lớn sẵn sàng cho sản xuất, và tái sử dụng các lớp mã hóa sâu và mạnh mẽ của chúng, được huấn luyện trước với hàng tỷ hình ảnh, làm xương sống vững chắc để học một tập hợp đa dạng các điều khiển có điều kiện. Kiến trúc mạng nơ-ron được kết nối bằng các "cuộn không" (các lớp tích chập khởi tạo bằng không) giúp tăng dần số tham số từ không và đảm bảo rằng không có nhiễu có hại nào có thể ảnh hưởng đến quá trình tinh chỉnh. Chúng tôi kiểm tra các điều khiển điều kiện khác nhau, ví dụ như cạnh, độ sâu, phân đoạn, tư thế con người, v.v., với Stable Diffusion, sử dụng một hoặc nhiều điều kiện, có hoặc không có lời nhắc. Chúng tôi cho thấy rằng việc huấn luyện ControlNet là mạnh mẽ với các bộ dữ liệu nhỏ (<50k) và lớn (>1m). Các kết quả mở rộng cho thấy ControlNet có thể thúc đẩy các ứng dụng rộng hơn để kiểm soát các mô hình khuếch tán ảnh.*

Mã này được triển khai bởi Tencent Hunyuan Team. Bạn có thể tìm thấy các checkpoint được huấn luyện trước cho Hunyuan-DiT ControlNets trên [Tencent Hunyuan](https://huggingface.co/Tencent-Hunyuan).

> [!TIP]
> Hãy chắc chắn xem qua [hướng dẫn](../../using-diffusers/schedulers) về Schedulers để tìm hiểu cách khám phá sự đánh đổi giữa tốc độ và chất lượng của scheduler, và xem phần [tái sử dụng các thành phần giữa các pipeline](../../using-diffusers/loading#reusing-models-in-multiple-pipelines) để tìm hiểu cách nạp các thành phần giống nhau vào nhiều pipeline một cách hiệu quả.

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

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

**Tham số:**

vae ([AutoencoderKL](/docs/diffusers/v0.43.0/vi/api/models/autoencoderkl#diffusers.AutoencoderKL)) : Mô hình Variational Auto-Encoder (VAE) để mã hóa và giải mã hình ảnh sang và từ các biểu diễn ẩn. Chúng tôi sử dụng `sdxl-vae-fp16-fix`.

text_encoder (`~transformers.BertModel`, `~transformers.CLIPTextModel` | None) : Bộ mã hóa văn bản đóng băng ([clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14)). HunyuanDiT sử dụng [CLIP song ngữ] đã tinh chỉnh.

tokenizer (`~transformers.BertTokenizer`, `~transformers.CLIPTokenizer` | None) : Một `BertTokenizer` hoặc `CLIPTokenizer` để phân tách văn bản.

transformer ([HunyuanDiT2DModel](/docs/diffusers/v0.43.0/vi/api/models/hunyuan_transformer2d#diffusers.HunyuanDiT2DModel)) : Mô hình HunyuanDiT do Tencent Hunyuan thiết kế.

text_encoder_2 (`T5EncoderModel`) : Bộ nhúng mT5. Cụ thể, nó là 't5-v1_1-xxl'.

tokenizer_2 (`T5Tokenizer`) : Bộ phân từ cho bộ nhúng mT5.

scheduler ([DDPMScheduler](/docs/diffusers/v0.43.0/vi/api/schedulers/ddpm#diffusers.DDPMScheduler)) : Một trình lập lịch được sử dụng kết hợp với HunyuanDiT để khử nhiễu các ẩn hình ảnh đã mã hóa.

controlnet ([HunyuanDiT2DControlNetModel](/docs/diffusers/v0.43.0/vi/api/models/controlnet_hunyuandit#diffusers.HunyuanDiT2DControlNetModel) hoặc `list[HunyuanDiT2DControlNetModel]` hoặc [HunyuanDiT2DControlNetModel](/docs/diffusers/v0.43.0/vi/api/models/controlnet_hunyuandit#diffusers.HunyuanDiT2DControlNetModel)) : Cung cấp điều kiện bổ sung cho `unet` trong quá trình khử nhiễu. Nếu bạn đặt nhiều ControlNet dưới dạng danh sách, đầu ra từ mỗi ControlNet sẽ được cộng lại với nhau để tạo thành một điều kiện bổ sung kết hợp.

Pipeline để tạo ảnh từ tiếng Anh/tiếng Trung sử dụng HunyuanDiT.

Mô hình này kế thừa từ [DiffusionPipeline](/docs/diffusers/v0.43.0/vi/api/pipelines/overview#diffusers.DiffusionPipeline). Xem tài liệu của lớp cha để biết các phương thức chung mà thư viện triển khai cho tất cả các pipeline (chẳng hạn như tải xuống hoặc lưu, chạy trên một thiết bị cụ thể, v.v.)

HunyuanDiT sử dụng hai bộ mã hóa văn bản: [mT5](https://huggingface.co/google/mt5-base) và [bilingual CLIP](được chúng tôi tinh chỉnh)

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

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/controlnet_hunyuandit/pipeline_hunyuandit_controlnet.py#L632)

**Tham số:**

prompt (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt để hướng dẫn tạo ảnh. Nếu không được định nghĩa, bạn cần truyền `prompt_embeds`.

height (`int`) : Chiều cao của hình ảnh được tạo ra, tính bằng pixel.

width (`int`) : Độ rộng của hình ảnh được tạo ra, tính bằng pixel.

num_inference_steps (`int`, *optional*, mặc định là 50) : Số bước khử nhiễu. Số bước khử nhiễu nhiều hơn thường dẫn đến hình ảnh có chất lượng cao hơn, đổi lại là suy luận chậm hơn. Tham số này được điều chỉnh bởi `strength`.

guidance_scale (`float`, *optional*, mặc định là 7.5) : Giá trị guidance scale cao hơn khuyến khích mô hình tạo ra các hình ảnh gắn kết chặt chẽ với `prompt` văn bản, với cái giá là chất lượng hình ảnh thấp hơn. Guidance scale được kích hoạt khi `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]]` hoặc `list[list[PIL.Image.Image]]`): Điều kiện đầu vào của ControlNet để cung cấp hướng dẫn cho `unet` trong quá trình tạo ảnh. Nếu kiểu được chỉ định là `torch.Tensor`, nó sẽ được truyền vào ControlNet nguyên vẹn. `PIL.Image.Image` cũng có thể được chấp nhận dưới dạng ảnh. Kích thước của ảnh đầu ra mặc định là kích thước của `image`. Nếu chiều cao và/hoặc chiều rộng được truyền vào, `image` sẽ được thay đổi kích thước cho phù hợp. Nếu nhiều ControlNet được chỉ định trong `init`, các ảnh phải được truyền dưới dạng danh sách sao cho mỗi phần tử của danh sách có thể được nhóm (batch) chính xác để làm đầu vào cho một ControlNet duy nhất.

controlnet_conditioning_scale (`float` hoặc `list[float]`, *tuỳ chọn*, mặc định là 1.0) : Đầu ra của ControlNet được nhân với `controlnet_conditioning_scale` trước khi được cộng vào phần dư trong `unet` gốc. Nếu nhiều ControlNet được chỉ định trong `init`, bạn có thể đặt thang đo tương ứng dưới dạng danh sách.

negative_prompt (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt để hướng dẫn những gì không nên bao gồm trong quá trình tạo ảnh. Nếu không được định nghĩa, bạn cần truyền `negative_prompt_embeds` thay thế. Bỏ qua khi không sử dụng guidance (`guidance_scale < 1`).

num_images_per_prompt (`int`, *tuỳ chọn*, mặc định là 1) : Số lượng hình ảnh cần tạo cho mỗi prompt.

eta (`float`, *tuỳ chọn*, mặc định là 0.0) : Tương ứng với tham số eta (η) trong bài báo [DDIM](https://huggingface.co/papers/2010.02502). Chỉ áp dụng cho [DDIMScheduler](/docs/diffusers/v0.43.0/vi/api/schedulers/ddim#diffusers.DDIMScheduler) và bị bỏ qua ở các trình lập lịch khác.

generator (`torch.Generator` hoặc `list[torch.Generator]`, *tùy chọn*) : Một [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html) để đảm bảo quá trình sinh là tất định.

latents (`torch.Tensor`, *tùy chọn*) : Các latents nhiễu được tạo trước, lấy mẫu từ phân phối Gaussian, dùng làm đầu vào cho việc tạo ảnh. Có thể dùng để tinh chỉnh cùng một quá trình tạo với các prompt khác nhau. Nếu không được cung cấp, một tensor latents sẽ được tạo bằng cách lấy mẫu sử dụng `generator` ngẫu nhiên được cung cấp.

prompt_embeds (`torch.Tensor`, *tùy chọn*) : Các vector nhúng văn bản đã được tạo trước. Có thể được sử dụng để dễ dàng điều chỉnh các đầu vào văn bản (trọng số prompt). Nếu không được cung cấp, các vector nhúng văn bản sẽ được tạo từ đối số đầu vào `prompt`.

prompt_embeds_2 (`torch.Tensor`, *tùy chọn*) : Các vector nhúng văn bản đã được tạo trước. Có thể được sử dụng để dễ dàng điều chỉnh các đầu vào văn bản (trọng số prompt). Nếu không được cung cấp, các vector nhúng văn bản sẽ được tạo từ đối số đầu vào `prompt`.

negative_prompt_embeds (`torch.Tensor`, *tùy chọn*) : Các vector nhúng văn bản âm đã được tạo trước. Có thể được sử dụng để dễ dàng điều chỉnh các đầu vào văn bản (trọng số prompt). Nếu không được cung cấp, `negative_prompt_embeds` sẽ được tạo từ đối số đầu vào `negative_prompt`.

negative_prompt_embeds_2 (`torch.Tensor`, *tùy chọn*) : Các vector nhúng văn bản âm đã được tạo trước. Có thể được sử dụng để dễ dàng điều chỉnh các đầu vào văn bản (trọng số prompt). Nếu không được cung cấp, `negative_prompt_embeds` sẽ được tạo từ đối số đầu vào `negative_prompt`.

prompt_attention_mask (`torch.Tensor`, *tùy chọn*) : Mặt nạ chú ý cho prompt. Bắt buộc khi `prompt_embeds` được truyền trực tiếp.

prompt_attention_mask_2 (`torch.Tensor`, *tùy chọn*) : Mặt nạ chú ý cho prompt. Bắt buộc khi `prompt_embeds_2` được truyền trực tiếp.

negative_prompt_attention_mask (`torch.Tensor`, *tùy chọn*) : Mặt nạ chú ý cho prompt âm. Bắt buộc khi `negative_prompt_embeds` được truyền trực tiếp.

negative_prompt_attention_mask_2 (`torch.Tensor`, *tùy chọn*) : Mặt nạ chú ý cho prompt âm. Bắt buộc khi `negative_prompt_embeds_2` được truyền trực tiếp.

output_type (`str`, *tùy chọn*, mặc định là `"pil"`) : Định dạng đầu ra của hình ảnh được tạo ra. Chọn giữa `PIL.Image` hoặc `np.array`.

return_dict (`bool`, *tùy chọn*, mặc định là `True`) : Có nên trả về một [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/vi/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) thay vì một tuple thông thường hay không.

callback_on_step_end (`Callable[[int, int], None]`, `PipelineCallback`, `MultiPipelineCallbacks`, *optional*) : Một hàm callback hoặc danh sách các hàm callback sẽ được gọi vào cuối mỗi bước khử nhiễu.

callback_on_step_end_tensor_inputs (`list[str]`, *tùy chọn*) : Một danh sách các đầu vào tensor cần được truyền đến hàm callback. Nếu không được định nghĩa, tất cả các đầu vào tensor sẽ được truyền.

guidance_rescale (`float`, *tuỳ chọn*, mặc định là 0.0) : Thang lại noise_cfg theo `guidance_rescale`. Dựa trên các phát hiện của [Common Diffusion Noise Schedules and Sample Steps are Flawed](https://huggingface.co/papers/2305.08891). Xem Mục 3.4

original_size (`tuple[int, int]`, *tùy chọn*, mặc định là `(1024, 1024)`) : Kích thước gốc của hình ảnh. Được sử dụng để tính toán các id thời gian.

target_size (`tuple[int, int]`, *tùy chọn*) : Kích thước đích của hình ảnh. Được sử dụng để tính toán các id thời gian.

crops_coords_top_left (`tuple[int, int]`, *tùy chọn*, mặc định là `(0, 0)`) : Tọa độ góc trên bên trái của vùng cắt. Được sử dụng để tính toán các id thời gian.

use_resolution_binning (`bool`, *tùy chọn*, mặc định là `True`) : Có sử dụng phân loại độ phân giải hay không. Nếu `True`, độ phân giải đầu vào sẽ được ánh xạ đến độ phân giải chuẩn gần nhất. Các độ phân giải được hỗ trợ là 1024x1024, 1280x1280, 1024x768, 1152x864, 1280x960, 768x1024, 864x1152, 960x1280, 1280x768 và 768x1280. Khuyến nghị đặt giá trị này thành `True`.

**Trả về:** [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/vi/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) hoặc `tuple`

Nếu `return_dict` là `True`, [StableDiffusionPipelineOutput](/docs/diffusers/v0.43.0/vi/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) sẽ được trả về, ngược lại một `tuple` sẽ được trả về trong đó phần tử đầu tiên là một danh sách chứa các hình ảnh đã tạo và phần tử thứ hai là một danh sách các `bool` cho biết hình ảnh tương ứng có chứa nội dung "không an toàn" (nsfw) hay không.

Hàm gọi pipeline để tạo nội dung với HunyuanDiT.

Ví dụ:
```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)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/controlnet_hunyuandit/pipeline_hunyuandit_controlnet.py#L276)

**Tham số:**

prompt (`str` hoặc `list[str]`, *tùy chọn*) : prompt cần được mã hóa

device : (`torch.device`): thiết bị torch

dtype (`torch.dtype`) : kiểu dữ liệu torch

num_images_per_prompt (`int`) : số lượng hình ảnh cần được tạo cho mỗi prompt

do_classifier_free_guidance (`bool`) : có sử dụng classifier free guidance hay không

negative_prompt (`str` hoặc `list[str]`, *tùy chọn*) : Prompt hoặc các prompt không được dùng để hướng dẫn việc tạo ảnh. Nếu không được định nghĩa, bạn phải truyền `negative_prompt_embeds` thay thế. Bỏ qua khi không sử dụng guidance (tức là bị bỏ qua nếu `guidance_scale` nhỏ hơn `1`).

prompt_embeds (`torch.Tensor`, *tùy chọn*) : Các vector nhúng văn bản đã được tạo trước. Có thể được sử dụng để dễ dàng điều chỉnh các đầu vào văn bản, *vd.* trọng số prompt. Nếu không được cung cấp, các vector nhúng văn bản sẽ được tạo từ đối số đầu vào `prompt`.

negative_prompt_embeds (`torch.Tensor`, *tùy chọn*) : Các vector nhúng văn bản âm đã được tạo trước. Có thể được sử dụng để dễ dàng điều chỉnh các đầu vào văn bản, *vd.* trọng số prompt. Nếu không được cung cấp, negative_prompt_embeds sẽ được tạo từ đối số đầu vào `negative_prompt`.

prompt_attention_mask (`torch.Tensor`, *tùy chọn*) : Mặt nạ chú ý cho prompt. Bắt buộc khi `prompt_embeds` được truyền trực tiếp.

negative_prompt_attention_mask (`torch.Tensor`, *tùy chọn*) : Mặt nạ chú ý cho prompt âm. Bắt buộc khi `negative_prompt_embeds` được truyền trực tiếp.

max_sequence_length (`int`, *tuỳ chọn*) : độ dài tối đa của chuỗi để sử dụng cho prompt.

text_encoder_index (`int`, *optional*) : Chỉ số của text encoder cần sử dụng. `0` cho clip và `1` cho T5.

Mã hóa prompt thành các trạng thái ẩn của text encoder.