diffusers/main/ko/api/models/controlnet.md

ControlNetModel

ControlNet 모델은 Lvmin Zhang, Anyi Rao, Maneesh Agrawala의 Adding Conditional Control to Text-to-Image Diffusion Models에서 소개되었습니다. 이 모델은 엣지 맵, 깊이 맵, 분할 맵, 자세 감지를 위한 키포인트와 같은 추가 입력을 조건으로 사용하여 텍스트-이미지 생성에 대한 제어 수준을 높여줍니다.

해당 논문의 초록은 다음과 같습니다:

ControlNet을 소개합니다. ControlNet은 대규모 사전 학습된 텍스트-이미지 확산 모델에 공간 조건 제어 기능을 추가하는 신경망 아키텍처입니다. ControlNet은 프로덕션에 바로 적용 가능한 대규모 확산 모델을 고정(lock)하고, 수십억 장의 이미지로 사전 학습된 깊고 견고한 인코딩 레이어를 강력한 백본으로 재사용하여 다양한 조건 제어 세트를 학습합니다. 이 신경 아키텍처는 "zero convolutions"(제로 초기화 컨볼루션 레이어)로 연결되어 매개변수를 0에서 점진적으로 증가시키고, 유해한 노이즈가 파인튜닝에 영향을 미치지 않도록 보장합니다. Stable Diffusion을 사용하여 엣지, 깊이, 분할, 인간 자세 등 다양한 조건 제어를 단일 또는 복수의 조건, 프롬프트 유무와 함께 테스트했습니다. ControlNet의 학습이 소규모(<50k) 및 대규모(>1m) 데이터셋 모두에서 견고함을 보임을 확인했습니다. 광범위한 결과에 따르면 ControlNet은 이미지 확산 모델에 대한 제어를 가능하게 하여 더 넓은 응용 분야로의 확장을 촉진할 수 있습니다.

원래 형식에서 로드

기본적으로 ControlNetModel은 from_pretrained()로 로드해야 하지만, 다음과 같이 FromOriginalModelMixin.from_single_file를 사용하여 원래 형식에서도 로드할 수 있습니다:

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)

Control LoRA에서 로드

Control-LoRA는 Stability AI가 stabilityai/control-lora에서 ControlNet에 저랭크(low-rank) 파라미터 효율적 파인 튜닝을 추가하여 도입했습니다. 이 접근 방식은 더 효율적이고 컴팩트한 방법으로 다양한 소비자용 GPU에 모델 제어를 적용할 수 있게 해줍니다.

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]]

diffusers.ControlNetModel(in_channels: int = 4, conditioning_channels: int = 3, flip_sin_to_cos: bool = True, freq_shift: int = 0, down_block_types: tuple = ('CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'DownBlock2D'), mid_block_type: str | None = 'UNetMidBlock2DCrossAttn', only_cross_attention: bool | tuple[bool] = False, block_out_channels: tuple = (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)

소스

매개변수:

in_channels (int, 기본값 4) : 입력 샘플의 채널 수.

flip_sin_to_cos (bool, 기본값 True) : 시간 임베딩에서 sin을 cos로 전환할지 여부.

freq_shift (int, 기본값 0) : 시간 임베딩에 적용할 주파수 시프트입니다.

down_block_types (tuple[str], 기본값 ("CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "DownBlock2D")) : 사용할 다운샘플 블록의 튜플입니다.

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, 선택 사항, 기본값 32) : 정규화에 사용할 그룹의 수입니다. None인 경우 후처리에서 정규화 및 활성화 레이어가 건너뜁니다.

norm_eps (float, 기본값 1e-5) : 정규화에 사용할 epsilon입니다.

cross_attention_dim (int, 기본값 1280) : 크로스 어텐션 특징의 차원입니다.

transformer_layers_per_block (int 또는 tuple[int], 선택 사항, 기본값 1) : BasicTransformerBlock 유형의 transformer 블록 수입니다. ~models.unet_2d_blocks.CrossAttnDownBlock2D, ~models.unet_2d_blocks.CrossAttnUpBlock2D, ~models.unet_2d_blocks.UNetMidBlock2DCrossAttn에만 관련이 있습니다.

encoder_hid_dim (int, 선택 사항, 기본값 None) : encoder_hid_dim_type가 정의된 경우, encoder_hidden_states는 encoder_hid_dim 차원에서 cross_attention_dim으로 투영됩니다.

encoder_hid_dim_type (str, 선택 사항, 기본값 None) : 값이 지정되면 encoder_hid_dim_type에 따라 encoder_hidden_states 및 기타 임베딩이 cross_attention 차원의 텍스트 임베딩으로 다운프로젝트됩니다.

attention_head_dim (int | tuple[int], 기본값 8) : 어텐션 헤드의 차원입니다.

use_linear_projection (bool, 기본값은 False) --

class_embed_type (str, 선택 사항, 기본값 None) : 최종적으로 time embeddings와 합산되는 class embedding의 유형입니다. None, "timestep", "identity", "projection", "simple_projection" 중 하나를 선택합니다.

addition_embed_type (str, 선택 사항, 기본값 None) : 시간 임베딩과 합산될 선택적 임베딩을 구성합니다. None 또는 "text" 중 하나를 선택합니다. "text"를 선택하면 TextTimeEmbedding 레이어가 사용됩니다.

num_class_embeds (int, 선택 사항, 기본값 0) : class_embed_type가 None인 경우 클래스 조건화를 수행할 때 time_embed_dim으로 투영되는 학습 가능한 임베딩 행렬의 입력 차원.

upcast_attention (bool, 기본값은 False) --

resnet_time_scale_shift (str, 기본값 "default") : ResNet 블록의 시간 스케일 시프트 설정(자세한 내용은 ResnetBlock2D 참조). default 또는 scale_shift 중 하나를 선택합니다.

projection_class_embeddings_input_dim (int, 선택 사항, 기본값 None) : class_embed_type="projection"일 때 class_labels 입력의 차원입니다. class_embed_type="projection"일 때 필수입니다.

controlnet_conditioning_channel_order (str, 기본값 "rgb") : 조건부 이미지의 채널 순서입니다. bgr인 경우 rgb로 변환됩니다.

conditioning_embedding_out_channels (tuple[int], 선택 사항, 기본값 (16, 32, 96, 256)) : conditioning_embedding 레이어의 각 블록에 대한 출력 채널 튜플입니다.

global_pool_conditions (bool, 기본값은 False) : TODO(Patrick) - 사용되지 않는 매개변수.

addition_embed_type_num_heads (int, 기본값 64) : TextTimeEmbedding 레이어에 사용할 헤드 수입니다.

ControlNet 모델.

forward[[diffusers.ControlNetModel.forward]]

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)

소스

매개변수:

sample (torch.Tensor) : 노이즈가 포함된 입력 텐서.

timestep (torch.Tensor | float | int) : 입력을 디노이즈할 타임스텝 수.

encoder_hidden_states (torch.Tensor) : 인코더 히든 상태입니다.

controlnet_cond (torch.Tensor) : (batch_size, sequence_length, hidden_size) 모양의 조건부 입력 텐서.

conditioning_scale (float, 기본값 1.0) : ControlNet 출력의 스케일 팩터입니다.

class_labels (torch.Tensor, 선택 사항, 기본값 None) : 조건부 생성을 위한 선택적 클래스 라벨입니다. 이 라벨의 임베딩은 타임스텝 임베딩과 합산됩니다.

timestep_cond (torch.Tensor, 선택 사항, 기본값 None) : timestep에 대한 추가 조건부 임베딩입니다. 제공되면, self.time_embedding 레이어를 통해 전달된 timestep_embedding과 합산되어 최종 timestep 임베딩을 얻습니다.

attention_mask (torch.Tensor, 선택 사항, 기본값 None) : (batch, key_tokens) 모양의 attention mask가 encoder_hidden_states에 적용됩니다. 1인 경우 mask가 유지되고, 0인 경우 폐기됩니다. Mask는 bias로 변환되어 "폐기" 토큰에 해당하는 attention score에 큰 음의 값을 더합니다.

added_cond_kwargs (dict) : Stable Diffusion XL UNet에 대한 추가 조건.

cross_attention_kwargs (dict[str], 선택 사항, 기본값 None) : 지정된 경우 AttnProcessor에 전달되는 kwargs 사전입니다.

guess_mode (bool, 기본값 False) : 이 모드에서는 모든 프롬프트를 제거하더라도 ControlNet 인코더가 입력 콘텐츠의 내용을 인식하도록 최선을 다합니다. guidance_scale은 3.0에서 5.0 사이로 설정하는 것이 권장됩니다.

return_dict (bool, 기본값 True) : 일반 튜플 대신 ControlNetOutput를 반환할지 여부.

반환값: ControlNetOutput 또는 tuple

return_dict가 True인 경우 ControlNetOutput가 반환되고, 그렇지 않으면 첫 번째 요소가 샘플 텐서인 튜플이 반환됩니다.

ControlNetModel의 forward 메서드입니다.

from_unet[[diffusers.ControlNetModel.from_unet]]

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)

소스

매개변수:

unet (UNet2DConditionModel) : ControlNetModel에 복사할 UNet 모델 가중치입니다. 적용 가능한 모든 구성 옵션도 함께 복사됩니다.

UNet2DConditionModel에서 ControlNetModel을(를) 초기화합니다.

set_attention_slice[[diffusers.ControlNetModel.set_attention_slice]]

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

소스

매개변수:

slice_size (str 또는 int 또는 list(int), 선택 사항, 기본값은 "auto") : "auto"인 경우, attention head에 입력되는 값이 절반으로 줄어 attention이 두 단계로 계산됩니다. "max"인 경우, 한 번에 하나의 slice만 실행하여 최대의 메모리를 절약합니다. 숫자가 제공되면 attention_head_dim // slice_size만큼의 slice를 사용합니다. 이 경우 attention_head_dim은 slice_size의 배수여야 합니다.

슬라이스된 어텐션 계산을 활성화합니다.

이 옵션이 활성화되면 attention 모듈은 입력 텐서를 슬라이스로 분할하여 여러 단계에 걸쳐 attention을 계산합니다. 이는 속도가 약간 감소하는 대신 일부 메모리를 절약하는 데 유용합니다.

set_default_attn_processor[[diffusers.ControlNetModel.set_default_attn_processor]]

set_default_attn_processor()

소스

커스텀 어텐션 프로세서를 비활성화하고 기본 어텐션 구현을 설정합니다.

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

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

diffusers.models.controlnets.ControlNetOutput(down_block_res_samples: tuple, mid_block_res_sample: Tensor)

소스

매개변수:

down_block_res_samples (tuple[torch.Tensor]) : 각 다운샘플링 블록에 대해 서로 다른 해상도의 다운샘플 활성화 값으로 구성된 튜플입니다. 각 텐서는 (batch_size, channel * resolution, height //resolution, width // resolution) 형태여야 합니다. 출력은 원래 UNet의 다운샘플 활성화 값을 조건으로 설정하는 데 사용할 수 있습니다.

mid_down_block_re_sample (torch.Tensor) : 중간 블록의 활성화 값(가장 낮은 샘플 해상도). 각 텐서는 (batch_size, channel * lowest_resolution, height // lowest_resolution, width // lowest_resolution) 형태여야 합니다. 출력은 원래 UNet의 중간 블록 활성화 값을 조건부로 제어하는 데 사용할 수 있습니다.

ControlNetModel의 출력입니다.