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

SD3ControlNetModel

SD3ControlNetModel은 Stable Diffusion 3용 ControlNet의 구현입니다.

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은 이미지 확산 모델에 대한 제어를 가능하게 하여 더 넓은 응용 분야로의 확장을 촉진할 수 있습니다.

원래 형식에서 로드

기본적으로 SD3ControlNetModel은 from_pretrained()로 로드해야 합니다.

from diffusers import StableDiffusion3ControlNetPipeline
from diffusers.models import SD3ControlNetModel, SD3MultiControlNetModel

controlnet = SD3ControlNetModel.from_pretrained("InstantX/SD3-Controlnet-Canny")
pipe = StableDiffusion3ControlNetPipeline.from_pretrained("stabilityai/stable-diffusion-3-medium-diffusers", controlnet=controlnet)

SD3ControlNetModel[[diffusers.SD3ControlNetModel]]

diffusers.SD3ControlNetModel[[diffusers.SD3ControlNetModel]]

diffusers.SD3ControlNetModel(sample_size: int = 128, patch_size: int = 2, in_channels: int = 16, num_layers: int = 18, attention_head_dim: int = 64, num_attention_heads: int = 18, joint_attention_dim: int = 4096, caption_projection_dim: int = 1152, pooled_projection_dim: int = 2048, out_channels: int = 16, pos_embed_max_size: int = 96, extra_conditioning_channels: int = 0, dual_attention_layers: tuple = (), qk_norm: str | None = None, pos_embed_type: str | None = 'sincos', use_pos_embed: bool = True, force_zeros_for_pooled_projection: bool = True)

소스

매개변수:

sample_size (int, 기본값 128) : latents의 너비/높이입니다. 학습 중에 position embeddings의 수를 학습하는 데 사용되므로 고정됩니다.

patch_size (int, 기본값 2) : 입력 데이터를 작은 패치로 변환하기 위한 패치 크기.

in_channels (int, 기본값 16) : 입력의 잠재 채널 수입니다.

num_layers (int, 기본값 18) : 사용할 transformer 블록의 레이어 수입니다.

attention_head_dim (int, 기본값 64) : 각 헤드(head)의 채널 수.

num_attention_heads (int, 기본값 18) : multi-head attention에 사용할 헤드 수입니다.

joint_attention_dim (int, 기본값 4096) : 텍스트-이미지 결합 주의를 사용할 임베딩 차원입니다.

caption_projection_dim (int, 기본값 1152) : 캡션 임베딩의 임베딩 차원입니다.

pooled_projection_dim (int, 기본값 2048) : 풀링된 텍스트 투영의 임베딩 차원입니다.

out_channels (int, 기본값 16) : 출력의 잠재 채널 수입니다.

pos_embed_max_size (int, 기본값 96) : 위치 임베딩의 최대 잠재 높이/너비.

extra_conditioning_channels (int, 기본값 0) : patch embedding 조건화에 사용할 추가 채널 수.

dual_attention_layers (tuple[int, ...], 기본값 ()) : 사용할 dual-stream transformer 블록의 수입니다.

qk_norm (str, 선택 사항, 기본값 None) : attention 레이어에서 query와 key에 사용할 정규화입니다. None인 경우 정규화를 사용하지 않습니다.

pos_embed_type (str, 기본값 "sincos") : 사용할 위치 임베딩의 유형입니다. "sincos"와 None 중에서 선택합니다.

use_pos_embed (bool, 기본값 True) : 위치 임베딩을 사용할지 여부.

force_zeros_for_pooled_projection (bool, 기본값 True) : 풀링된 투영 임베딩에 제로를 강제할지 여부입니다. 이는 ControlNet 모델의 config 값을 읽는 방식으로 파이프라인에서 처리됩니다.

Stable Diffusion 3용 ControlNet 모델.

enable_forward_chunking[[diffusers.SD3ControlNetModel.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를 설정합니다.

forward[[diffusers.SD3ControlNetModel.forward]]

forward(hidden_states: Tensor, controlnet_cond: Tensor, conditioning_scale: float = 1.0, encoder_hidden_states: Tensor = None, pooled_projections: Tensor = None, timestep: LongTensor = None, joint_attention_kwargs: dict[str, typing.Any] | None = None, return_dict: bool = True)

소스

매개변수:

hidden_states (torch.Tensor, shape (batch size, channel, height, width)) : 입력 hidden_states.

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

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

encoder_hidden_states (torch.Tensor, shape (batch size, sequence_len, embed_dims)) : 사용할 조건 임베딩(프롬프트와 같은 입력 조건에서 계산된 임베딩).

pooled_projections (torch.Tensor, shape (batch_size, projection_dim)) : 입력 조건의 임베딩에서 투영된 임베딩.

timestep ( torch.LongTensor) : 노이즈 제거 단계를 나타내는 데 사용됩니다.

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

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

반환값:

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

SD3Transformer2DModel의 forward 메서드입니다.

fuse_qkv_projections[[diffusers.SD3ControlNetModel.fuse_qkv_projections]]

fuse_qkv_projections()

소스

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

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

unfuse_qkv_projections[[diffusers.SD3ControlNetModel.unfuse_qkv_projections]]

unfuse_qkv_projections()

소스

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

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

SD3ControlNetOutput[[diffusers.models.controlnets.SD3ControlNetOutput]]

diffusers.models.controlnets.SD3ControlNetOutput[[diffusers.models.controlnets.SD3ControlNetOutput]]

diffusers.models.controlnets.SD3ControlNetOutput(controlnet_block_samples: tuple)

소스