diffusers/main/ko/api/models/unet2d-cond.md

UNet2DConditionModel

UNet 모델은 Ronneberger et al.에 의해 바이오메디컬 이미지 분할을 위해 처음 소개되었지만, 입력과 동일한 크기의 이미지를 출력하기 때문에 🤗 Diffusers에서도 널리 사용됩니다. 실제 확산(diffusion) 과정을 담당하는 핵심 구성 요소 중 하나입니다. 🤗 Diffusers에는 차원 수와 조건부 모델 여부(conditional model)에 따라 UNet 모델의 여러 변형(variant)이 있습니다. 여기서는 2D UNet 조건부 모델입니다.

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

딥 네트워크의 성공적인 학습에는 수천 개의 라벨이 붙은 학습 샘플이 필요하다는 데에 큰 합의가 있습니다. 본 논문에서는 데이터 증강을 강하게 활용하여 사용 가능한 라벨 샘플을 더 효율적으로 사용하는 네트워크와 학습 전략을 제시합니다. 아키텍처는 컨텍스트를 포착하기 위한 수축 경로와 정확한 위치 파악을 가능하게 하는 대칭적인 확장 경로로 구성됩니다. 이러한 네트워크가 매우 적은 이미지로 끝에서 끝까지(end-to-end) 학습될 수 있으며, 전자 현미경 스택의 신경 구조 분할을 위한 ISBI 챌린지에서 이전의 최선 방법(슬라이딩 윈도우 컨볼루션 네트워크)보다 우수한 성능을 보임을 보여줍니다. 동일한 네트워크를 투과광 현미경 이미지(위상 대비 및 DIC)로 학습하여, 해당 카테고리에서 ISBI 세포 추적 챌린지 2015를 큰 격차로 우승했습니다. 또한, 이 네트워크는 빠릅니다. 최신 GPU에서 512x512 이미지의 분할은 1초 미만으로 수행됩니다. 전체 구현(Caffe 기반)과 학습된 네트워크는 http://lmb.informatik.uni-freiburg.de/people/ronneber/u-net에서 사용할 수 있습니다.

UNet2DConditionModel[[diffusers.UNet2DConditionModel]]

diffusers.UNet2DConditionModel[[diffusers.UNet2DConditionModel]]

diffusers.UNet2DConditionModel(sample_size: int | tuple[int, int] | None = None, in_channels: int = 4, out_channels: int = 4, center_input_sample: bool = False, flip_sin_to_cos: bool = True, freq_shift: int = 0, down_block_types: tuple = ('CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'DownBlock2D'), mid_block_type: str | None = 'UNetMidBlock2DCrossAttn', up_block_types: tuple = ('UpBlock2D', 'CrossAttnUpBlock2D', 'CrossAttnUpBlock2D', 'CrossAttnUpBlock2D'), only_cross_attention: bool | tuple[bool] = False, block_out_channels: tuple = (320, 640, 1280, 1280), layers_per_block: int | tuple[int] = 2, downsample_padding: int = 1, mid_block_scale_factor: float = 1, dropout: float = 0.0, act_fn: str = 'silu', norm_num_groups: int | None = 32, norm_eps: float = 1e-05, cross_attention_dim: int | tuple[int] = 1280, transformer_layers_per_block: int | tuple[int] | tuple[tuple] = 1, reverse_transformer_layers_per_block: tuple[tuple[int]] | None = None, 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, dual_cross_attention: bool = False, 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', resnet_skip_time_act: bool = False, resnet_out_scale_factor: float = 1.0, time_embedding_type: str = 'positional', time_embedding_dim: int | None = None, time_embedding_act_fn: str | None = None, timestep_post_act: str | None = None, time_cond_proj_dim: int | None = None, conv_in_kernel: int = 3, conv_out_kernel: int = 3, projection_class_embeddings_input_dim: int | None = None, attention_type: str = 'default', class_embeddings_concat: bool = False, mid_block_only_cross_attention: bool | None = None, cross_attention_norm: str | None = None, addition_embed_type_num_heads: int = 64)

소스

매개변수:

sample_size (int 또는 tuple[int, int], 선택 사항, 기본값 None) : 입력/출력 샘플의 높이와 너비.

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

out_channels (int, 선택 사항, 기본값 4) : 출력의 채널 수.

center_input_sample (bool, 선택 사항, 기본값 False) : 입력 샘플을 중앙에 위치시킬지 여부.

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

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

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

mid_block_type (str, 선택 사항, 기본값 "UNetMidBlock2DCrossAttn") : UNet 중간 부분의 블록 유형으로, UNetMidBlock2DCrossAttn, UNetMidBlock2D, UNetMidBlock2DSimpleCrossAttn 중 하나일 수 있습니다. None인 경우 중간 블록 레이어가 건너뜁니다.

up_block_types (tuple[str], 선택 사항, 기본값 ("UpBlock2D", "CrossAttnUpBlock2D", "CrossAttnUpBlock2D", "CrossAttnUpBlock2D")) : 사용할 업샘플 블록의 튜플입니다.

only_cross_attention(bool 또는 tuple[bool], 선택 사항, 기본값 False) : 기본 transformer 블록에 self-attention을 포함할지 여부, BasicTransformerBlock 참고.

block_out_channels (tuple[int], 선택 사항, 기본값 (320, 640, 1280, 1280)) : 각 블록의 출력 채널 튜플입니다.

layers_per_block (int, 선택 사항, 기본값 2) : 블록당 레이어 수.

downsample_padding (int, 선택 사항, 기본값 1) : 다운샘플링 컨볼루션에 사용할 패딩입니다.

mid_block_scale_factor (float, 선택 사항, 기본값 1.0) : mid block에 사용할 스케일 팩터입니다.

dropout (float, 선택 사항, 기본값 0.0) : 사용할 dropout 확률입니다.

act_fn (str, 선택 사항, 기본값 "silu") : 사용할 활성화 함수입니다.

norm_num_groups (int, 선택 사항, 기본값 32) : 정규화에 사용할 그룹의 수입니다. None인 경우 후처리에서 정규화 및 활성화 레이어가 건너뜁니다.

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

cross_attention_dim (int 또는 tuple[int], 선택 사항, 기본값 1280) : 크로스 어텐션 특징의 차원입니다.

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

reverse_transformer_layers_per_block : (tuple[tuple], 선택 사항, 기본값 None): U-Net의 업샘플링 블록에서 BasicTransformerBlock 유형의 transformer 블록 수입니다. transformer_layers_per_block의 유형이 tuple[tuple]이고 CrossAttnDownBlock2D, CrossAttnUpBlock2D, 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, 선택 사항, 기본값 8) : 어텐션 헤드의 차원입니다.

num_attention_heads (int, 선택 사항) : 어텐션 헤드의 수. 정의되지 않으면 기본값은 attention_head_dim입니다.

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

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

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

addition_time_embed_dim : (int, 선택 사항, 기본값 None): timestep 임베딩의 차원.

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

time_embedding_type (str, 선택 사항, 기본값 positional) : timesteps에 사용할 위치 임베딩의 유형입니다. positional 또는 fourier 중 하나를 선택합니다.

time_embedding_dim (int, 선택 사항, 기본값 None) : 투영된 시간 임베딩의 차원을 선택적으로 재정의합니다.

time_embedding_act_fn (str, 선택 사항, 기본값 None) : UNet의 나머지 부분으로 전달되기 전에 시간 임베딩에 한 번만 사용할 선택적 활성화 함수입니다. silu, mish, gelu, swish 중에서 선택할 수 있습니다.

timestep_post_act (str, 선택 사항, 기본값 None) : timestep 임베딩에 사용할 두 번째 활성화 함수입니다. silu, mish, gelu 중 하나를 선택할 수 있습니다.

time_cond_proj_dim (int, 선택 사항, 기본값 None) : timestep 임베딩의 cond_proj 레이어 차원입니다.

conv_in_kernel (int, 선택 사항, 기본값 3) : conv_in 레이어의 커널 크기.

conv_out_kernel (int, 선택 사항, 기본값 3) : conv_out 레이어의 커널 크기.

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

class_embeddings_concat (bool, 선택 사항, 기본값 False) : 시간 임베딩을 클래스 임베딩과 연결할지 여부.

mid_block_only_cross_attention (bool, 선택 사항, 기본값 None) : UNetMidBlock2DSimpleCrossAttn을 사용할 때 mid block에 cross attention을 사용할지 여부입니다. only_cross_attention가 단일 boolean으로 주어지고 mid_block_only_cross_attention이 None인 경우, only_cross_attention의 값이 mid_block_only_cross_attention의 값으로 사용됩니다. 그 외의 경우 기본값은 False입니다.

노이즈 샘플, 조건 상태, 타임스텝을 입력으로 받아 샘플 모양의 출력을 반환하는 조건부 2D UNet 모델입니다.

이 모델은 ModelMixin에서 상속됩니다. 모든 모델에 대해 구현된 일반적 메서드(다운로드 또는 저장 등)에 대해서는 상위 클래스 문서를 확인하세요.

disable_freeu[[diffusers.UNet2DConditionModel.disable_freeu]]

disable_freeu()

소스

FreeU 메커니즘을 비활성화합니다.

enable_freeu[[diffusers.UNet2DConditionModel.enable_freeu]]

enable_freeu(s1: float, s2: float, b1: float, b2: float)

소스

매개변수:

s1 (float) : 스킵 특징의 기여도를 감쇠시키기 위한 1단계의 스케일링 계수입니다. 이는 강화된 노이즈 제거 과정에서 "과도한 매끄러움 효과(oversmoothing effect)"를 완화하기 위해 수행됩니다.

s2 (float) : 스킵 특징의 기여도를 감쇠시키기 위한 2단계의 스케일링 계수입니다. 이는 강화된 노이즈 제거 과정에서 "과도한 매끄러움 효과(oversmoothing effect)"를 완화하기 위해 수행됩니다.

b1 (float) : 1단계에서 백본 특징의 기여도를 증폭하기 위한 스케일링 계수.

b2 (float) : 2단계에서 백본 특징의 기여도를 증폭하기 위한 스케일링 계수.

https://huggingface.co/papers/2309.11497의 FreeU 메커니즘을 활성화합니다.

스케일링 인자 뒤에 붙는 접미사는 해당 인자가 적용되는 스테이지 블록을 나타냅니다.

Stable Diffusion v1, v2, Stable Diffusion XL과 같은 다양한 파이프라인에서 잘 작동하는 것으로 알려진 값 조합에 대해서는 공식 저장소를 참고하세요.

forward[[diffusers.UNet2DConditionModel.forward]]

forward(sample: Tensor, timestep: typing.Union[torch.Tensor, float, int], encoder_hidden_states: Tensor, class_labels: typing.Optional[torch.Tensor] = None, timestep_cond: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, cross_attention_kwargs: dict[str, typing.Any] | None = None, added_cond_kwargs: dict[str, torch.Tensor] | None = None, down_block_additional_residuals: tuple[torch.Tensor] | None = None, mid_block_additional_residual: typing.Optional[torch.Tensor] = None, down_intrablock_additional_residuals: tuple[torch.Tensor] | None = None, encoder_attention_mask: typing.Optional[torch.Tensor] = None, return_dict: bool = True)

소스

매개변수:

sample (torch.Tensor) : 다음 형태 (batch, channel, height, width)를 가진 노이즈 입력 텐서.

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

encoder_hidden_states (torch.Tensor) : (batch, sequence_length, feature_dim) 모양의 인코더 히든 상태입니다.

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

timestep_cond : (torch.Tensor, 선택 사항, 기본값 None): timestep을 위한 조건부 임베딩입니다. 값이 제공되면, self.time_embedding 레이어를 통과한 샘플과 합산되어 timestep 임베딩을 얻습니다.

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

cross_attention_kwargs (dict, 선택 사항) : 지정된 경우 diffusers.models.attention_processor의 self.processor 아래에서 정의된 AttentionProcessor로 전달되는 kwargs 사전입니다.

added_cond_kwargs : (dict, 선택 사항): 지정된 경우 UNet 블록으로 전달되는 임베딩에 추가되는 추가 임베딩을 포함하는 kwargs 사전입니다.

down_block_additional_residuals : (tuple of torch.Tensor, 선택 사항): 지정된 경우, down unet 블록의 잔차(residuals)에 추가되는 텐서들의 튜플입니다.

mid_block_additional_residual : (torch.Tensor, 선택 사항): 지정된 경우, 중간 unet 블록의 잔차(residual)에 추가되는 텐서입니다.

down_intrablock_additional_residuals (tuple of torch.Tensor, 선택 사항) : UNet 다운 블록 내에서 추가될 잔차, 예를 들어 T2I-Adapter 사이드 모델에서 오는 값

encoder_attention_mask (torch.Tensor) : (batch, sequence_length) 모양의 cross-attention mask가 encoder_hidden_states에 적용됩니다. True인 경우 mask가 유지되고, False인 경우 폐기됩니다. Mask는 bias로 변환되어 "discard" 토큰에 해당하는 attention score에 큰 음의 값을 더합니다.

return_dict (bool, 선택 사항, 기본값 True) : 일반 튜플 대신 UNet2DConditionOutput을 반환할지 여부.

반환값: UNet2DConditionOutput 또는 tuple

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

UNet2DConditionModel의 forward 메서드입니다.

fuse_qkv_projections[[diffusers.UNet2DConditionModel.fuse_qkv_projections]]

fuse_qkv_projections()

소스

융합된 QKV 투영을 활성화합니다. 셀프 어텐션 모듈의 경우, 모든 투영 행렬(즉, 쿼리, 키, 값)이 융합됩니다. 크로스 어텐션 모듈의 경우, 키와 값 투영 행렬이 융합됩니다.

> 이 API는 🧪 실험적입니다.

set_attention_slice[[diffusers.UNet2DConditionModel.set_attention_slice]]

set_attention_slice(slice_size: str | int | list[int] = 'auto')

소스

매개변수:

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.UNet2DConditionModel.set_default_attn_processor]]

set_default_attn_processor()

소스

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

unfuse_qkv_projections[[diffusers.UNet2DConditionModel.unfuse_qkv_projections]]

unfuse_qkv_projections()

소스

활성화된 경우, 융합된 QKV 투영을 비활성화합니다.

> 이 API는 🧪 실험적입니다.

UNet2DConditionOutput[[diffusers.models.unets.unet_2d_condition.UNet2DConditionOutput]]

diffusers.models.unets.unet_2d_condition.UNet2DConditionOutput[[diffusers.models.unets.unet_2d_condition.UNet2DConditionOutput]]

diffusers.models.unets.unet_2d_condition.UNet2DConditionOutput(sample: Tensor = None)

소스

매개변수:

sample (torch.Tensor, shape (batch_size, num_channels, height, width)) : encoder_hidden_states 입력에 조건부인 히든 스테이트 출력. 모델의 마지막 레이어 출력입니다.

UNet2DConditionModel의 출력입니다.