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

UNet3DConditionModel

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

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

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

UNet3DConditionModel[[diffusers.UNet3DConditionModel]]

diffusers.UNet3DConditionModel[[diffusers.UNet3DConditionModel]]

diffusers.UNet3DConditionModel(sample_size: int | None = None, in_channels: int = 4, out_channels: int = 4, down_block_types: tuple = ('CrossAttnDownBlock3D', 'CrossAttnDownBlock3D', 'CrossAttnDownBlock3D', 'DownBlock3D'), up_block_types: tuple = ('UpBlock3D', 'CrossAttnUpBlock3D', 'CrossAttnUpBlock3D', 'CrossAttnUpBlock3D'), 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 = 1024, attention_head_dim: int | tuple[int] = 64, num_attention_heads: int | tuple[int] | None = None, time_cond_proj_dim: int | None = None)

소스

매개변수:

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

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

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

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

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

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에 사용할 스케일 팩터입니다.

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

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

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

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

attention_head_dim (int, 선택 사항, 기본값 64) : 어텐션 헤드의 차원입니다.

num_attention_heads (int, 선택 사항) : 어텐션 헤드의 수.

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

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

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

disable_freeu[[diffusers.UNet3DConditionModel.disable_freeu]]

disable_freeu()

소스

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

enable_forward_chunking[[diffusers.UNet3DConditionModel.enable_forward_chunking]]

enable_forward_chunking(chunk_size: int | None = None, dim: int = 0)

소스

매개변수:

chunk_size (int, 선택 사항) : 피드포워드 레이어의 청크 크기입니다. 지정하지 않으면 dim 차원의 각 텐서에 대해 피드포워드 레이어를 개별적으로 실행합니다.

dim (int, 선택 사항, 기본값 0) : 피드포워드 계산을 청킹할 차원입니다. dim=0 (배치) 또는 dim=1 (시퀀스 길이) 중 하나를 선택합니다.

feed forward chunking을 사용할 attention processor를 설정합니다.

enable_freeu[[diffusers.UNet3DConditionModel.enable_freeu]]

enable_freeu(s1, s2, b1, b2)

소스

매개변수:

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.UNet3DConditionModel.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, down_block_additional_residuals: tuple[torch.Tensor] | None = None, mid_block_additional_residual: typing.Optional[torch.Tensor] = None, return_dict: bool = True)

소스

매개변수:

sample (torch.Tensor) : 다음 형태 (batch, num_channels, num_frames, 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 사전입니다.

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

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

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

cross_attention_kwargs (dict, 선택 사항) : 지정된 경우 AttnProcessor에 전달되는 kwargs 사전입니다.

반환값: UNet3DConditionOutput 또는 tuple

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

UNet3DConditionModel의 forward 메서드입니다.

fuse_qkv_projections[[diffusers.UNet3DConditionModel.fuse_qkv_projections]]

fuse_qkv_projections()

소스

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

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

set_attention_slice[[diffusers.UNet3DConditionModel.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.UNet3DConditionModel.set_default_attn_processor]]

set_default_attn_processor()

소스

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

unfuse_qkv_projections[[diffusers.UNet3DConditionModel.unfuse_qkv_projections]]

unfuse_qkv_projections()

소스

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

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

UNet3DConditionOutput[[diffusers.models.unets.unet_3d_condition.UNet3DConditionOutput]]

diffusers.models.unets.unet_3d_condition.UNet3DConditionOutput[[diffusers.models.unets.unet_3d_condition.UNet3DConditionOutput]]

diffusers.models.unets.unet_3d_condition.UNet3DConditionOutput(sample: Tensor)

소스

매개변수:

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

UNet3DConditionModel의 출력입니다.