Diffusers documentation
SparseControlNetModel
SparseControlNetModel
SparseControlNetModel là một triển khai của ControlNet cho AnimateDiff.
ControlNet được giới thiệu trong Adding Conditional Control to Text-to-Image Diffusion Models 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 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.
Ví dụ về việc nạp SparseControlNetModel
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 parameterSparseControlNetModel
lớp diffusers.SparseControlNetModel
< source >( in_channels: int = 4conditioning_channels: int = 4flip_sin_to_cos: bool = Truefreq_shift: int = 0down_block_types: tuple = ('CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'CrossAttnDownBlockMotion', 'DownBlockMotion')only_cross_attention: bool | tuple[bool] = Falseblock_out_channels: tuple = (320, 640, 1280, 1280)layers_per_block: int = 2downsample_padding: int = 1mid_block_scale_factor: float = 1act_fn: str = 'silu'norm_num_groups: int | None = 32norm_eps: float = 1e-05cross_attention_dim: int = 768transformer_layers_per_block: int | tuple[int, ...] = 1transformer_layers_per_mid_block: int | tuple[int] | None = Nonetemporal_transformer_layers_per_block: int | tuple[int, ...] = 1attention_head_dim: int | tuple[int, ...] = 8num_attention_heads: int | tuple[int, ...] | None = Noneuse_linear_projection: bool = Falseupcast_attention: bool = Falseresnet_time_scale_shift: str = 'default'conditioning_embedding_out_channels: tuple[int, ...] | None = (16, 32, 96, 256)global_pool_conditions: bool = Falsecontrolnet_conditioning_channel_order: str = 'rgb'motion_max_seq_length: int = 32motion_num_attention_heads: int = 8concat_conditioning_mask: bool = Trueuse_simplified_condition_embedding: bool = True )
Tham số
- in_channels (
int, mặc định là 4) — Số lượng 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ếuconcat_condition_embeddinglà 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 time embedding hay không. - freq_shift (
int, mặc định là 0) — Lệ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 hạ mẫu (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) — Độ đệm (padding) được sử dụng cho phép tích chập hạ mẫu (downsampling convolution). - mid_block_scale_factor (
float, mặc định là 1) — Hệ số tỷ lệ 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, tùy chọn, 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) — Giá trị epsilon 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 (
inthoặctuple[int], tùy chọn, mặc định là 1) — Số lượng khối transformer có kiểuBasicTransformerBlock. 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 (
inthoặctuple[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 (
inthoặctuple[int], mặc định là 8) — Kích thước của các đầu chú ý (attention heads). - num_attention_heads (
inthoặctuple[int], tùy chọn) — Số lượng đầu (heads) được 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 (xemResnetBlock2D). Chọn từdefaulthoặcscale_shift. - conditioning_embedding_out_channels (
tuple[int], mặc định là(16, 32, 96, 256)) — Bộ tuple các kênh đầu ra cho mỗi khối trong lớpconditioning_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) — Chiều dài chuỗi tối đa được sử dụng trong module chuyển động. - motion_num_attention_heads (
inthoặctuple[int], mặc định là8) — Số lượng đầu (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.
forward
< source >( sample: Tensortimestep: typing.Union[torch.Tensor, float, int]encoder_hidden_states: Tensorcontrolnet_cond: Tensorconditioning_scale: float = 1.0timestep_cond: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Nonecross_attention_kwargs: dict[str, typing.Any] | None = Noneconditioning_mask: typing.Optional[torch.Tensor] = Noneguess_mode: bool = Falsereturn_dict: bool = True ) → ~models.controlnet.ControlNetOutput or tuple
Tham số
- sample (
torch.Tensor) — Tensor đầu vào có nhiễu. - timestep (
torch.Tensor | float | int) — Số lượng 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ớpself.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 choencoder_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 chú ý tương ứng với các token “bị 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 trongcontrolnet_condlà 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 đếnAttnProcessor. - 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 ngay cả khi bạn xóa tất cả các prompt. Khuyến nghị sử dụngguidance_scaletrong 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.ControlNetOutputthay 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.
from_unet
< source >( unet: UNet2DConditionModelcontrolnet_conditioning_channel_order: str = 'rgb'conditioning_embedding_out_channels: tuple[int, ...] | None = (16, 32, 96, 256)load_weights_from_unet: bool = Trueconditioning_channels: int = 3 )
Tham số
- unet (
UNet2DConditionModel) — Trọng số của mô hình UNet để sao chép sang 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 từ UNet2DConditionModel.
set_attention_slice
< source >( slice_size: str | int | list[int] )
Tham số
- slice_size (
strhoặcinthoặclist(int), tùy chọn, mặc định là"auto") — Khi là"auto", đầu vào của các attention head được chia đôi, do đó attention được tính toán trong hai bước. Nếu là"max", lượng bộ nhớ được tiết kiệm tối đa bằng cách chỉ chạy một slice tại một thời điểm. Nếu cung cấp một số, số lượng slice được sử dụng bằngattention_head_dim // slice_size. Trong trường hợp này,attention_head_dimphải là bội số củaslice_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ỏ.
Tắt các bộ xử lý chú ý tùy chỉnh và đặt cài đặt chú ý mặc định.
SparseControlNetOutput
lớp diffusers.models.controlnets.SparseControlNetOutput
< source >( down_block_res_samples: tuplemid_block_res_sample: Tensor )
Tham số
- down_block_res_samples (
tuple[torch.Tensor]) — Một tuple chứa các kích hoạt hạ mẫu ở các độ phân giải khác nhau cho mỗi khối hạ mẫu. Mỗi tensor nên có hình dạng(batch_size, channel * resolution, height //resolution, width // resolution). Đầu ra có thể được dùng để điều kiện hóa các kích hoạt hạ mẫu 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 nên có hình dạng(batch_size, channel * lowest_resolution, height // lowest_resolution, width // lowest_resolution). Đầu ra có thể được dùng để điều kiện hóa kích hoạt của khối trung tâm trong UNet gốc.
Đầu ra của SparseControlNetModel.