# ControlNetModel

Mô hình 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, Maneesh Agrawala. Nó cung cấp mức độ kiểm soát cao hơn đối với việc tạo ảnh từ văn bản bằng cách điều kiện hóa mô hình dựa trên các đầu vào bổ sung như bản đồ cạnh, bản đồ độ sâu, bản đồ phân đoạn và các điểm chính cho phát hiện tư thế.

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

## Tải từ định dạng gốc

Mặc định, [ControlNetModel](/docs/diffusers/main/vi/api/models/controlnet#diffusers.ControlNetModel) nên được tải bằng [from_pretrained()](/docs/diffusers/main/vi/api/models/overview#diffusers.ModelMixin.from_pretrained), nhưng nó cũng có thể được tải từ định dạng gốc bằng cách sử dụng `FromOriginalModelMixin.from_single_file` như sau:

```py
from diffusers import StableDiffusionControlNetPipeline, ControlNetModel

url = "https://huggingface.co/lllyasviel/ControlNet-v1-1/blob/main/control_v11p_sd15_canny.pth"  # can also be a local path
controlnet = ControlNetModel.from_single_file(url)

url = "https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/blob/main/v1-5-pruned.safetensors"  # can also be a local path
pipe = StableDiffusionControlNetPipeline.from_single_file(url, controlnet=controlnet)
```

## Tải từ Control LoRA

Control-LoRA được Stability AI giới thiệu trong [stabilityai/control-lora](https://huggingface.co/stabilityai/control-lora) bằng cách thêm fine-tuning tham số hiệu quả bậc thấp (low-rank) vào ControlNet. Phương pháp này cung cấp một cách tiếp cận hiệu quả và gọn nhẹ hơn để mang lại khả năng kiểm soát mô hình cho nhiều loại GPU tiêu dùng hơn.

```py
from diffusers import ControlNetModel, UNet2DConditionModel

lora_id = "stabilityai/control-lora"
lora_filename = "control-LoRAs-rank128/control-lora-canny-rank128.safetensors"

unet = UNet2DConditionModel.from_pretrained("stabilityai/stable-diffusion-xl-base-1.0", subfolder="unet", dtype=torch.bfloat16).to("cuda")  # or "mps", "xpu", "cpu"
controlnet = ControlNetModel.from_unet(unet).to(device="cuda", dtype=torch.bfloat16)
controlnet.load_lora_adapter(lora_id, weight_name=lora_filename, prefix=None, controlnet_config=controlnet.config)
```

## ControlNetModel[[diffusers.ControlNetModel]]

#### diffusers.ControlNetModel[[diffusers.ControlNetModel]]

```python
diffusers.ControlNetModel(in_channels: int = 4, conditioning_channels: int = 3, flip_sin_to_cos: bool = True, freq_shift: int = 0, down_block_types: tuple[str, ...] = ('CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'DownBlock2D'), mid_block_type: str | None = 'UNetMidBlock2DCrossAttn', only_cross_attention: bool | tuple[bool] = False, block_out_channels: tuple[int, ...] = (320, 640, 1280, 1280), layers_per_block: int = 2, downsample_padding: int = 1, mid_block_scale_factor: float = 1, act_fn: str = 'silu', norm_num_groups: int | None = 32, norm_eps: float = 1e-05, cross_attention_dim: int = 1280, transformer_layers_per_block: int | tuple[int, ...] = 1, encoder_hid_dim: int | None = None, encoder_hid_dim_type: str | None = None, attention_head_dim: int | tuple[int, ...] = 8, num_attention_heads: int | tuple[int, ...] | None = None, use_linear_projection: bool = False, class_embed_type: str | None = None, addition_embed_type: str | None = None, addition_time_embed_dim: int | None = None, num_class_embeds: int | None = None, upcast_attention: bool = False, resnet_time_scale_shift: str = 'default', projection_class_embeddings_input_dim: int | None = None, controlnet_conditioning_channel_order: str = 'rgb', conditioning_embedding_out_channels: tuple[int, ...] | None = (16, 32, 96, 256), global_pool_conditions: bool = False, addition_embed_type_num_heads: int = 64)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/controlnets/controlnet.py#L111)

**Tham số:**

in_channels (`int`, mặc định là 4) : Số kênh trong mẫu đầu vào.

flip_sin_to_cos (`bool`, mặc định là `True`) : Có nên đảo sin thành cos trong nhúng thời gian hay không.

freq_shift (`int`, mặc định là 0) : Độ dịch tần số cần áp dụng cho nhúng thời gian.

down_block_types (`tuple[str]`, mặc định là `("CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "DownBlock2D")`) : Bộ tuple các khối downsample cần sử dụng.

only_cross_attention (`bool | tuple[bool]`, mặc định là `False`) --

block_out_channels (`tuple[int]`, mặc định là `(320, 640, 1280, 1280)`) : Bộ tuple các kênh đầu ra cho mỗi khối.

layers_per_block (`int`, mặc định là 2) : Số lượng lớp trong mỗi khối.

downsample_padding (`int`, mặc định là 1) : Padding được sử dụng cho phép tích chập hạ mẫu.

mid_block_scale_factor (`float`, mặc định là 1) : Hệ số tỷ lệ cần sử dụng cho khối giữa.

act_fn (`str`, mặc định là "silu") : Hàm kích hoạt cần sử dụng.

norm_num_groups (`int`, *optional*, mặc định là 32) : Số nhóm được sử dụng cho phép chuẩn hóa. Nếu là None, các lớp chuẩn hóa và kích hoạt sẽ bị bỏ qua trong xử lý hậu kỳ.

norm_eps (`float`, mặc định là 1e-5) : Epsilon được sử dụng cho phép chuẩn hóa.

cross_attention_dim (`int`, mặc định là 1280) : Kích thước của các đặc trưng chú ý chéo (cross attention).

transformer_layers_per_block (`int` hoặc `tuple[int]`, *tuỳ chọn*, mặc định là 1) : Số lượng khối transformer có kiểu `BasicTransformerBlock`. Chỉ liên quan đến `~models.unet_2d_blocks.CrossAttnDownBlock2D`, `~models.unet_2d_blocks.CrossAttnUpBlock2D`, `~models.unet_2d_blocks.UNetMidBlock2DCrossAttn`.

encoder_hid_dim (`int`, *tuỳ chọn*, mặc định là None) : Nếu `encoder_hid_dim_type` được định nghĩa, `encoder_hidden_states` sẽ được chiếu từ chiều `encoder_hid_dim` sang `cross_attention_dim`.

encoder_hid_dim_type (`str`, *tùy chọn*, mặc định là `None`) : Nếu được cung cấp, `encoder_hidden_states` và các embedding khác (nếu có) sẽ được down-project xuống các embedding văn bản có chiều `cross_attention` theo `encoder_hid_dim_type`.

attention_head_dim (`int | tuple[int]`, mặc định là 8) : Kích thước của các đầu chú ý (attention heads).

use_linear_projection (`bool`, mặc định là `False`) --

class_embed_type (`str`, *tùy chọn*, mặc định là `None`) : Loại class embedding được sử dụng, cuối cùng sẽ được cộng với các time embeddings. Chọn từ None, `"timestep"`, `"identity"`, `"projection"` hoặc `"simple_projection"`.

addition_embed_type (`str`, *tùy chọn*, mặc định là `None`) : Cấu hình một embedding tùy chọn sẽ được cộng với các time embeddings. Chọn từ `None` hoặc "text". "text" sẽ sử dụng lớp `TextTimeEmbedding`.

num_class_embeds (`int`, *optional*, mặc định là 0) : Kích thước đầu vào của ma trận nhúng có thể học được để chiếu sang `time_embed_dim`, khi thực hiện điều kiện hóa theo lớp với `class_embed_type` bằng `None`.

upcast_attention (`bool`, mặc định là `False`) --

resnet_time_scale_shift (`str`, mặc định là `"default"`) : Cấu hình dịch chuyển thang thời gian cho các khối ResNet (xem `ResnetBlock2D`). Chọn từ `default` hoặc `scale_shift`.

projection_class_embeddings_input_dim (`int`, *tuỳ chọn*, mặc định là `None`) : Kích thước của đầu vào `class_labels` khi `class_embed_type="projection"`. Bắt buộc khi `class_embed_type="projection"`.

controlnet_conditioning_channel_order (`str`, mặc định là `"rgb"`) : Thứ tự kênh của ảnh điều kiện. Sẽ chuyển sang `rgb` nếu là `bgr`.

conditioning_embedding_out_channels (`tuple[int]`, *optional*, mặc định là `(16, 32, 96, 256)`) : Bộ tuple các kênh đầu ra cho mỗi khối trong lớp `conditioning_embedding`.

global_pool_conditions (`bool`, mặc định là `False`) : TODO(Patrick) - tham số không được sử dụng.

addition_embed_type_num_heads (`int`, mặc định là 64) : Số lượng đầu (heads) được sử dụng cho lớp `TextTimeEmbedding`.

Một mô hình ControlNet.

#### forward[[diffusers.ControlNetModel.forward]]

```python
forward(sample: Tensor, timestep: typing.Union[torch.Tensor, float, int], encoder_hidden_states: Tensor, controlnet_cond: Tensor, conditioning_scale: float = 1.0, class_labels: typing.Optional[torch.Tensor] = None, timestep_cond: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, added_cond_kwargs: dict[str, torch.Tensor] | None = None, cross_attention_kwargs: dict[str, typing.Any] | None = None, guess_mode: bool = False, return_dict: bool = True)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/controlnets/controlnet.py#L602)

**Tham số:**

sample (`torch.Tensor`) : Tensor đầu vào có nhiễu.

timestep (`torch.Tensor | float | int`) : Số bước thời gian để khử nhiễu một đầu vào.

encoder_hidden_states (`torch.Tensor`) : Trạng thái ẩn của bộ mã hóa.

controlnet_cond (`torch.Tensor`) : Tensor đầu vào có điều kiện với hình dạng `(batch_size, sequence_length, hidden_size)`.

conditioning_scale (`float`, mặc định là `1.0`) : Hệ số tỷ lệ cho đầu ra của ControlNet.

class_labels (`torch.Tensor`, *tùy chọn*, mặc định là `None`) : Nhãn lớp tùy chọn để điều kiện. Các embedding của chúng sẽ được cộng với các embedding của bước thời gian.

timestep_cond (`torch.Tensor`, *tùy chọn*, mặc định là `None`) : Các embedding điều kiện bổ sung cho timestep. Nếu được cung cấp, các embedding này sẽ được cộng với timestep_embedding được truyền qua lớp `self.time_embedding` để thu được các embedding timestep cuối cùng.

attention_mask (`torch.Tensor`, *tùy chọn*, mặc định là `None`) : Một attention mask có shape `(batch, key_tokens)` được áp dụng cho `encoder_hidden_states`. Nếu là `1`, mask được giữ lại; ngược lại, nếu là `0`, nó sẽ bị loại bỏ. Mask sẽ được chuyển đổi thành một bias, thêm các giá trị âm lớn vào các điểm attention tương ứng với các token "loại bỏ".

added_cond_kwargs (`dict`) : Các điều kiện bổ sung cho UNet của Stable Diffusion XL.

cross_attention_kwargs (`dict[str]`, *tùy chọn*, mặc định là `None`) : Một từ điển kwargs mà nếu được chỉ định sẽ được truyền đến `AttnProcessor`.

guess_mode (`bool`, mặc định là `False`) : Ở chế độ này, bộ mã hóa ControlNet sẽ cố gắng hết sức để nhận diện nội dung đầu vào của input ngay cả khi bạn xóa tất cả các prompt. Khuyến nghị sử dụng `guidance_scale` trong khoảng từ 3.0 đến 5.0.

return_dict (`bool`, mặc định là `True`) : Có nên trả về một [ControlNetOutput](/docs/diffusers/main/vi/api/models/controlnet#diffusers.models.controlnets.ControlNetOutput) thay vì một tuple thông thường hay không.

**Trả về:** [ControlNetOutput](/docs/diffusers/main/vi/api/models/controlnet#diffusers.models.controlnets.ControlNetOutput) **hoặc** `tuple`

Nếu `return_dict` là `True`, một [ControlNetOutput](/docs/diffusers/main/vi/api/models/controlnet#diffusers.models.controlnets.ControlNetOutput) sẽ được trả về, ngược lại một tuple sẽ được trả về trong đó phần tử đầu tiên là tensor mẫu.

Phương thức forward của [ControlNetModel](/docs/diffusers/main/vi/api/models/controlnet#diffusers.ControlNetModel).

#### from_unet[[diffusers.ControlNetModel.from_unet]]

```python
from_unet(unet: UNet2DConditionModel, controlnet_conditioning_channel_order: str = 'rgb', conditioning_embedding_out_channels: tuple[int, ...] | None = (16, 32, 96, 256), load_weights_from_unet: bool = True, conditioning_channels: int = 3)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/controlnets/controlnet.py#L444)

**Tham số:**

unet (`UNet2DConditionModel`) : Trọng số của mô hình UNet để sao chép sang [ControlNetModel](/docs/diffusers/main/vi/api/models/controlnet#diffusers.ControlNetModel). Tất cả các tùy chọn cấu hình cũng được sao chép khi phù hợp.

Tạo một [ControlNetModel](/docs/diffusers/main/vi/api/models/controlnet#diffusers.ControlNetModel) từ [UNet2DConditionModel](/docs/diffusers/main/vi/api/models/unet2d-cond#diffusers.UNet2DConditionModel).

#### set_attention_slice[[diffusers.ControlNetModel.set_attention_slice]]

```python
set_attention_slice(slice_size: str | int | list[int])
```

[Nguồn](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/controlnets/controlnet.py#L537)

**Tham số:**

slice_size (`str` hoặc `int` hoặc `list(int)`, *tuỳ chọn*, mặc định là `"auto"`) : Khi `"auto"`, đầu vào cho các đầu chú ý sẽ được chia đôi, do đó chú ý được tính toán trong hai bước. Nếu `"max"`, lượng bộ nhớ tối đa được tiết kiệm bằng cách chỉ chạy một lát một lần. Nếu cung cấp một số, sẽ sử dụng nhiều lát bằng `attention_head_dim // slice_size`. Trong trường hợp này, `attention_head_dim` phải là bội số của `slice_size`.

Bật tính toán chú ý dạng lát cắt.

Khi tùy chọn này được bật, module attention sẽ chia tensor đầu vào thành các lát để tính toán attention qua nhiều bước. Điều này hữu ích để tiết kiệm một phần bộ nhớ, đổi lại là sự giảm tốc độ nhỏ.

#### set_default_attn_processor[[diffusers.ControlNetModel.set_default_attn_processor]]

```python
set_default_attn_processor()
```

[Nguồn](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/controlnets/controlnet.py#L521)

Tắt các bộ xử lý chú ý tùy chỉnh và đặt cài đặt chú ý mặc định.

## ControlNetOutput[[diffusers.models.controlnets.ControlNetOutput]]

#### diffusers.models.controlnets.ControlNetOutput[[diffusers.models.controlnets.ControlNetOutput]]

```python
diffusers.models.controlnets.ControlNetOutput(down_block_res_samples: tuple[torch.Tensor], mid_block_res_sample: Tensor)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/controlnets/controlnet.py#L47)

**Tham số:**

down_block_res_samples (`tuple[torch.Tensor]`) : Một tuple chứa các activation downsample ở các độ phân giải khác nhau cho mỗi khối downsampling. Mỗi tensor nên có shape `(batch_size, channel * resolution, height //resolution, width // resolution)`. Kết quả đầu ra có thể được dùng để điều kiện hóa các activation downsampling của UNet gốc.

mid_down_block_re_sample (`torch.Tensor`) : Kích hoạt của khối trung tâm (độ phân giải mẫu thấp nhất). Mỗi tensor phải có hình dạng `(batch_size, channel * lowest_resolution, height // lowest_resolution, width // lowest_resolution)`. Đầu ra có thể được sử dụng để điều kiện kích hoạt khối trung tâm của UNet gốc.

Đầu ra của [ControlNetModel](/docs/diffusers/main/vi/api/models/controlnet#diffusers.ControlNetModel).