# SparseControlNetModel

SparseControlNetModel là một triển khai của ControlNet cho [AnimateDiff](https://huggingface.co/papers/2307.04725).

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.

Phiên bản SparseCtrl của ControlNet được giới thiệu trong [SparseCtrl: Adding Sparse Controls to Text-to-Video Diffusion Models](https://huggingface.co/papers/2311.16933) nhằm đạt được sinh có kiểm soát trong các mô hình khuếch tán từ văn bản sang video, do Yuwei Guo, Ceyuan Yang, Anyi Rao, Maneesh Agrawala, Dahua Lin và Bo Dai thực hiện.

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

*Việc phát triển text-to-video (T2V), tức là tạo video từ một prompt văn bản cho trước, đã được thúc đẩy đáng kể trong những năm gần đây. Tuy nhiên, việc chỉ dựa vào prompt văn bản thường dẫn đến bố cục khung hình mơ hồ do sự không chắc chắn về không gian. Do đó, cộng đồng nghiên cứu tận dụng các tín hiệu cấu trúc dày đặc, chẳng hạn như chuỗi depth/edge cho từng khung hình, để tăng cường khả năng kiểm soát, nhưng việc thu thập các tín hiệu này làm tăng gánh nặng suy luận. Trong công trình này, chúng tôi giới thiệu SparseCtrl để cho phép kiểm soát cấu trúc linh hoạt bằng các tín hiệu thưa theo thời gian, chỉ yêu cầu một hoặc một vài đầu vào, như minh họa trong Hình 1. Phương pháp này tích hợp một bộ mã hóa điều kiện bổ sung để xử lý các tín hiệu thưa này trong khi giữ nguyên mô hình T2V đã được huấn luyện trước. Cách tiếp cận đề xuất tương thích với nhiều loại dữ liệu khác nhau, bao gồm phác thảo, bản đồ depth và hình ảnh RGB, cung cấp khả năng kiểm soát thực tế hơn cho việc tạo video và thúc đẩy các ứng dụng như storyboarding, depth rendering, keyframe animation và nội suy. Các thí nghiệm rộng rãi chứng minh khả năng tổng quát hóa của SparseCtrl trên cả các bộ tạo T2V gốc và T2V cá nhân hóa. Mã nguồn và mô hình sẽ được công bố công khai tại [this https URL](https://guoyww.github.io/projects/SparseCtrl).*

## Ví dụ về việc nạp SparseControlNetModel

```python
import torch
from diffusers import SparseControlNetModel

# fp32 variant in float16
# 1. Scribble checkpoint
controlnet = SparseControlNetModel.from_pretrained("guoyww/animatediff-sparsectrl-scribble", dtype=torch.float16)

# 2. RGB checkpoint
controlnet = SparseControlNetModel.from_pretrained("guoyww/animatediff-sparsectrl-rgb", dtype=torch.float16)

# For loading fp16 variant, pass `variant="fp16"` as an additional parameter
```

## SparseControlNetModel[[diffusers.SparseControlNetModel]]

#### diffusers.SparseControlNetModel[[diffusers.SparseControlNetModel]]

```python
diffusers.SparseControlNetModel(in_channels: int = 4, conditioning_channels: int = 4, flip_sin_to_cos: bool = True, freq_shift: int = 0, down_block_types: tuple[str, ...] = ('CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'DownBlockMotion'), 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 = 768, transformer_layers_per_block: int | tuple[int, ...] = 1, transformer_layers_per_mid_block: int | tuple[int] | None = None, temporal_transformer_layers_per_block: int | tuple[int, ...] = 1, attention_head_dim: int | tuple[int, ...] = 8, num_attention_heads: int | tuple[int, ...] | None = None, use_linear_projection: bool = False, upcast_attention: bool = False, resnet_time_scale_shift: str = 'default', conditioning_embedding_out_channels: tuple[int, ...] | None = (16, 32, 96, 256), global_pool_conditions: bool = False, controlnet_conditioning_channel_order: str = 'rgb', motion_max_seq_length: int = 32, motion_num_attention_heads: int = 8, concat_conditioning_mask: bool = True, use_simplified_condition_embedding: bool = True)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L97)

**Tham số:**

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

conditioning_channels (`int`, mặc định là 4) : Số lượng kênh đầu vào trong module nhúng điều kiện của controlnet. Nếu `concat_condition_embedding` là True, giá trị được cung cấp ở đây sẽ tăng thêm 1.

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

transformer_layers_per_mid_block (`int` hoặc `tuple[int]`, *tùy chọn*, mặc định là 1) : Số lượng lớp transformer được sử dụng trong mỗi lớp của khối ở giữa.

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

num_attention_heads (`int` hoặc `tuple[int]`, *tùy chọn*) : Số lượng đầu (heads) cần sử dụng cho cơ chế chú ý đa đầu (multi-head attention).

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

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

conditioning_embedding_out_channels (`tuple[int]`, mặc định là `(16, 32, 96, 256)`) : Bộ tuple số 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

controlnet_conditioning_channel_order (`str`, mặc định là `rgb`) --

motion_max_seq_length (`int`, mặc định là `32`) : Độ dài chuỗi tối đa để sử dụng trong module chuyển động.

motion_num_attention_heads (`int` hoặc `tuple[int]`, mặc định là `8`) : Số lượng heads được sử dụng trong mỗi lớp attention của motion module.

concat_conditioning_mask (`bool`, mặc định là `True`) --

use_simplified_condition_embedding (`bool`, mặc định là `True`) --

Một mô hình SparseControlNet như được mô tả trong [SparseCtrl: Adding Sparse Controls to Text-to-Video Diffusion Models](https://huggingface.co/papers/2311.16933).

#### forward[[diffusers.SparseControlNetModel.forward]]

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

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L534)

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

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ỏ".

conditioning_mask (`torch.Tensor`, *tùy chọn*, mặc định là `None`) : Mặt nạ tùy chọn chỉ ra các khung hình nào trong `controlnet_cond` là các khung hình điều kiện hợp lệ.

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 `~models.controlnet.ControlNetOutput` thay vì một tuple thông thường hay không.

**Trả về:** `~models.controlnet.ControlNetOutput` **hoặc** `tuple`

Nếu `return_dict` là `True`, một `~models.controlnet.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 [SparseControlNetModel](/docs/diffusers/v0.43.0/vi/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel).

#### from_unet[[diffusers.SparseControlNetModel.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/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L388)

**Tham số:**

unet (`UNet2DConditionModel`) : Trọng số của mô hình UNet để sao chép sang [SparseControlNetModel](/docs/diffusers/v0.43.0/vi/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel). 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 [SparseControlNetModel](/docs/diffusers/v0.43.0/vi/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel) từ [UNet2DConditionModel](/docs/diffusers/v0.43.0/vi/api/models/unet2d-cond#diffusers.UNet2DConditionModel).

#### set_attention_slice[[diffusers.SparseControlNetModel.set_attention_slice]]

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

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L469)

**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.SparseControlNetModel.set_default_attn_processor]]

```python
set_default_attn_processor()
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L453)

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

## SparseControlNetOutput[[diffusers.models.controlnets.SparseControlNetOutput]]

#### diffusers.models.controlnets.SparseControlNetOutput[[diffusers.models.controlnets.SparseControlNetOutput]]

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

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet_sparsectrl.py#L44)

**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 [SparseControlNetModel](/docs/diffusers/v0.43.0/vi/api/models/controlnet_sparsectrl#diffusers.SparseControlNetModel).