Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /main /ko /api /models /controlnet.md

mishig

about 20 hours ago

preview code

download

raw

16.1 kB

# ControlNetModel

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

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

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

## 원래 형식에서 로드

기본적으로 [ControlNetModel](/docs/diffusers/main/ko/api/models/controlnet#diffusers.ControlNetModel)은 [from_pretrained()](/docs/diffusers/main/ko/api/models/overview#diffusers.ModelMixin.from_pretrained)로 로드해야 하지만, 다음과 같이 `FromOriginalModelMixin.from_single_file`를 사용하여 원래 형식에서도 로드할 수 있습니다:

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

## Control LoRA에서 로드

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

```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 = ('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)
```

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

**매개변수:**

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

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

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

**매개변수:**

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](/docs/diffusers/main/ko/api/models/controlnet#diffusers.models.controlnets.ControlNetOutput)를 반환할지 여부.
**반환값:** [ControlNetOutput](/docs/diffusers/main/ko/api/models/controlnet#diffusers.models.controlnets.ControlNetOutput) **또는** `tuple`
`return_dict`가 `True`인 경우 [ControlNetOutput](/docs/diffusers/main/ko/api/models/controlnet#diffusers.models.controlnets.ControlNetOutput)가 반환되고, 그렇지 않으면 첫 번째 요소가 샘플 텐서인 튜플이 반환됩니다.

[ControlNetModel](/docs/diffusers/main/ko/api/models/controlnet#diffusers.ControlNetModel)의 forward 메서드입니다.

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

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

**매개변수:**

unet (`UNet2DConditionModel`) : [ControlNetModel](/docs/diffusers/main/ko/api/models/controlnet#diffusers.ControlNetModel)에 복사할 UNet 모델 가중치입니다. 적용 가능한 모든 구성 옵션도 함께 복사됩니다.

[UNet2DConditionModel](/docs/diffusers/main/ko/api/models/unet2d-cond#diffusers.UNet2DConditionModel)에서 [ControlNetModel](/docs/diffusers/main/ko/api/models/controlnet#diffusers.ControlNetModel)을(를) 초기화합니다.

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

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

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

**매개변수:**

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]]
```python
set_default_attn_processor()
```
[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/controlnets/controlnet.py#L521)
커스텀 어텐션 프로세서를 비활성화하고 기본 어텐션 구현을 설정합니다.
## ControlNetOutput[[diffusers.models.controlnets.ControlNetOutput]]
#### diffusers.models.controlnets.ControlNetOutput[[diffusers.models.controlnets.ControlNetOutput]]
```python
diffusers.models.controlnets.ControlNetOutput(down_block_res_samples: tuple, mid_block_res_sample: Tensor)
```
[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/controlnets/controlnet.py#L47)
**매개변수:**
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](/docs/diffusers/main/ko/api/models/controlnet#diffusers.ControlNetModel)의 출력입니다.

Xet Storage Details

Size:: 16.1 kB
Xet hash:: 22a674d5c29ed68b0687c31852dce1cbb6764acbed1e50e79391320c06950145

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.

	# ControlNetModel

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

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

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

	## 원래 형식에서 로드

	기본적으로 [ControlNetModel](/docs/diffusers/main/ko/api/models/controlnet#diffusers.ControlNetModel)은 [from_pretrained()](/docs/diffusers/main/ko/api/models/overview#diffusers.ModelMixin.from_pretrained)로 로드해야 하지만, 다음과 같이 `FromOriginalModelMixin.from_single_file`를 사용하여 원래 형식에서도 로드할 수 있습니다:

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

	## Control LoRA에서 로드

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

	```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 = ('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)
	```

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

	매개변수:

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

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

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

	매개변수:

	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](/docs/diffusers/main/ko/api/models/controlnet#diffusers.models.controlnets.ControlNetOutput)를 반환할지 여부.

	반환값: [ControlNetOutput](/docs/diffusers/main/ko/api/models/controlnet#diffusers.models.controlnets.ControlNetOutput) 또는 `tuple`

	`return_dict`가 `True`인 경우 [ControlNetOutput](/docs/diffusers/main/ko/api/models/controlnet#diffusers.models.controlnets.ControlNetOutput)가 반환되고, 그렇지 않으면 첫 번째 요소가 샘플 텐서인 튜플이 반환됩니다.

	[ControlNetModel](/docs/diffusers/main/ko/api/models/controlnet#diffusers.ControlNetModel)의 forward 메서드입니다.

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

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

	매개변수:

	unet (`UNet2DConditionModel`) : [ControlNetModel](/docs/diffusers/main/ko/api/models/controlnet#diffusers.ControlNetModel)에 복사할 UNet 모델 가중치입니다. 적용 가능한 모든 구성 옵션도 함께 복사됩니다.

	[UNet2DConditionModel](/docs/diffusers/main/ko/api/models/unet2d-cond#diffusers.UNet2DConditionModel)에서 [ControlNetModel](/docs/diffusers/main/ko/api/models/controlnet#diffusers.ControlNetModel)을(를) 초기화합니다.

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

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

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

	매개변수:

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

	```python
	set_default_attn_processor()
	```

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

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

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

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

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

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

	매개변수:

	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](/docs/diffusers/main/ko/api/models/controlnet#diffusers.ControlNetModel)의 출력입니다.