Hugging Face's logo

Diffusers documentation

ControlNetUnionModel

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

ControlNetUnionModel

ControlNetUnionModel é uma implementação do ControlNet para Stable Diffusion XL.

O modelo ControlNet foi introduzido em ControlNetPlus por xinsir6. Ele suporta múltiplas entradas de condicionamento sem aumentar a computação.

Projetamos uma nova arquitetura que pode suportar mais de 10 tipos de controle na geração de imagens a partir de texto condicional e que pode gerar imagens de alta resolução visualmente comparáveis às do midjourney. A rede é baseada na arquitetura original do ControlNet; propomos dois novos módulos para: 1 Estender o ControlNet original para suportar diferentes condições de imagem usando o mesmo parâmetro de rede. 2 Suportar a entrada de múltiplas condições sem aumentar o offload de computação, o que é especialmente importante para designers que desejam editar imagens em detalhes; diferentes condições usam o mesmo codificador de condição, sem adicionar computações ou parâmetros extras.

Carregando

Por padrão, o ControlNetUnionModel deve ser carregado com from_pretrained().

from diffusers import StableDiffusionXLControlNetUnionPipeline, ControlNetUnionModel

controlnet = ControlNetUnionModel.from_pretrained("xinsir/controlnet-union-sdxl-1.0")
pipe = StableDiffusionXLControlNetUnionPipeline.from_pretrained("stabilityai/stable-diffusion-xl-base-1.0", controlnet=controlnet)

ControlNetUnionModel

classe diffusers.ControlNetUnionModel

< >

( in_channels: int = 4conditioning_channels: int = 3flip_sin_to_cos: bool = Truefreq_shift: int = 0down_block_types: tuple = ('CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'DownBlock2D')only_cross_attention: bool | tuple[bool] = Falseblock_out_channels: tuple = (320, 640, 1280, 1280)layers_per_block: int = 2downsample_padding: int = 1mid_block_scale_factor: float = 1act_fn: str = 'silu'norm_num_groups: int | None = 32norm_eps: float = 1e-05cross_attention_dim: int = 1280transformer_layers_per_block: int | tuple[int, ...] = 1encoder_hid_dim: int | None = Noneencoder_hid_dim_type: str | None = Noneattention_head_dim: int | tuple[int, ...] = 8num_attention_heads: int | tuple[int, ...] | None = Noneuse_linear_projection: bool = Falseclass_embed_type: str | None = Noneaddition_embed_type: str | None = Noneaddition_time_embed_dim: int | None = Nonenum_class_embeds: int | None = Noneupcast_attention: bool = Falseresnet_time_scale_shift: str = 'default'projection_class_embeddings_input_dim: int | None = Nonecontrolnet_conditioning_channel_order: str = 'rgb'conditioning_embedding_out_channels: tuple[int, ...] | None = (48, 96, 192, 384)global_pool_conditions: bool = Falseaddition_embed_type_num_heads: int = 64num_control_type: int = 6num_trans_channel: int = 320num_trans_head: int = 8num_trans_layer: int = 1num_proj_channel: int = 320 )

Parâmetros

  • in_channels (int, padrão 4) — O número de canais na amostra de entrada.
  • flip_sin_to_cos (bool, padrão True) — Se deve inverter o sin para cos no embedding de tempo.
  • freq_shift (int, padrão 0) — O deslocamento de frequência a ser aplicado ao embedding de tempo.
  • down_block_types (tuple[str], padrão ("CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "DownBlock2D")) — A tupla de blocos de downsampling a serem usados.
  • only_cross_attention (bool | tuple[bool], padrão False) —
  • block_out_channels (tuple[int], padrão (320, 640, 1280, 1280)) — A tupla de canais de saída para cada bloco.
  • layers_per_block (int, padrão 2) — O número de camadas por bloco.
  • downsample_padding (int, padrão 1) — O padding a ser usado para a convolução de downsampling.
  • mid_block_scale_factor (float, padrão 1) — O fator de escala a ser usado para o bloco intermediário.
  • act_fn (str, padrão “silu”) — A função de ativação a ser utilizada.
  • norm_num_groups (int, opcional, padrão 32) — O número de grupos a serem usados para a normalização. Se for None, as camadas de normalização e ativação são ignoradas no pós-processamento.
  • norm_eps (float, padrão 1e-5) — O epsilon a ser usado para a normalização.
  • cross_attention_dim (int, padrão 1280) — A dimensão dos recursos de atenção cruzada.
  • transformer_layers_per_block (int ou tuple[int], opcional, padrão 1) — O número de blocos de transformador do tipo BasicTransformerBlock. Relevante apenas para ~models.unet_2d_blocks.CrossAttnDownBlock2D, ~models.unet_2d_blocks.CrossAttnUpBlock2D, ~models.unet_2d_blocks.UNetMidBlock2DCrossAttn.
  • encoder_hid_dim (int, opcional, padrão None) — Se encoder_hid_dim_type estiver definido, encoder_hidden_states será projetado da dimensão encoder_hid_dim para cross_attention_dim.
  • encoder_hid_dim_type (str, opcional, padrão None) — Se fornecido, o encoder_hidden_states e possivelmente outros embeddings são projetados para baixo para embeddings de texto de dimensão cross_attention de acordo com encoder_hid_dim_type.
  • attention_head_dim (int | tuple[int], padrão 8) — A dimensão dos cabeçalhos de atenção.
  • use_linear_projection (bool, padrão False) —
  • class_embed_type (str, opcional, padrão None) — O tipo de incorporação de classe a ser usado, que é somado às incorporações de tempo. Escolha entre None, "timestep", "identity", "projection" ou "simple_projection".
  • addition_embed_type (str, opcional, padrão None) — Configura um embedding opcional que será somado aos embeddings de tempo. Escolha entre None ou “text”. “text” usará a camada TextTimeEmbedding.
  • num_class_embeds (int, opcional, padrão 0) — Dimensão de entrada da matriz de incorporação aprendível a ser projetada para time_embed_dim, ao realizar condicionamento por classe com class_embed_type igual a None.
  • upcast_attention (bool, padrão False) —
  • resnet_time_scale_shift (str, padrão "default") — Configuração de deslocamento de escala de tempo para blocos ResNet (veja ResnetBlock2D). Escolha entre default ou scale_shift.
  • projection_class_embeddings_input_dim (int, opcional, padrão None) — A dimensão da entrada class_labels quando class_embed_type="projection". Obrigatório quando class_embed_type="projection".
  • controlnet_conditioning_channel_order (str, padrão "rgb") — A ordem dos canais da imagem condicional. Será convertida para rgb se for bgr.
  • conditioning_embedding_out_channels (tuple[int], opcional, padrão (48, 96, 192, 384)) — A tupla de canais de saída para cada bloco na camada conditioning_embedding.
  • global_pool_conditions (bool, padrão False) —

Um modelo ControlNetUnion.

forward

< >

( sample: Tensortimestep: typing.Union[torch.Tensor, float, int]encoder_hidden_states: Tensorcontrolnet_cond: listcontrol_type: Tensorcontrol_type_idx: listconditioning_scale: float | list[float] = 1.0class_labels: typing.Optional[torch.Tensor] = Nonetimestep_cond: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneadded_cond_kwargs: dict[str, torch.Tensor] | None = Nonecross_attention_kwargs: dict[str, typing.Any] | None = Nonefrom_multi: bool = Falseguess_mode: bool = Falsereturn_dict: bool = True ) → ~models.controlnet.ControlNetOutput or tuple

Parâmetros

  • sample (torch.Tensor) — O tensor de entrada com ruído.
  • timestep (torch.Tensor | float | int) — O número de timesteps para desruidar uma entrada.
  • encoder_hidden_states (torch.Tensor) — Os estados ocultos do codificador.
  • controlnet_cond (list[torch.Tensor]) — Os tensores de entrada condicional.
  • control_type (torch.Tensor) — Um tensor de forma (batch, num_control_type) com valores 0 ou 1 dependendo de o tipo de controle ser utilizado.
  • control_type_idx (list[int]) — Os índices de control_type.
  • conditioning_scale (float, padrão 1.0) — Fator de escala para as saídas do ControlNet.
  • class_labels (torch.Tensor, opcional, padrão None) — Rótulos de classe opcionais para condicionamento. Os embeddings deles serão somados aos embeddings de timestep.
  • timestep_cond (torch.Tensor, opcional, padrão None) — Incorporações condicionais adicionais para o timestep. Se fornecidas, as incorporações serão somadas com o timestep_embedding passado pela camada self.time_embedding para obter as incorporações finais de timestep.
  • attention_mask (torch.Tensor, opcional, padrão None) — Uma máscara de atenção com forma (batch, key_tokens) é aplicada a encoder_hidden_states. Se 1, a máscara é mantida; caso contrário, se 0, ela é descartada. A máscara será convertida em um viés, que adiciona grandes valores negativos às pontuações de atenção correspondentes aos tokens “descartados”.
  • added_cond_kwargs (dict) — Condições adicionais para o UNet do Stable Diffusion XL.
  • cross_attention_kwargs (dict[str], opcional, padrão None) — Um dicionário de kwargs que, se especificado, é passado para o AttnProcessor.
  • from_multi (bool, padrão False) — Use a escala padrão quando chamado de MultiControlNetUnionModel.
  • guess_mode (bool, padrão False) — Neste modo, o encoder do ControlNet faz o possível para reconhecer o conteúdo da entrada, mesmo que você remova todos os prompts. Recomenda-se um guidance_scale entre 3.0 e 5.0.
  • return_dict (bool, padrão True) — Se deve ou não retornar um ~models.controlnet.ControlNetOutput em vez de uma tupla simples.

Retorna

~models.controlnet.ControlNetOutput ou tuple

Se return_dict for True, um ~models.controlnet.ControlNetOutput é retornado; caso contrário, uma tupla é retornada, em que o primeiro elemento é o tensor da amostra.

O método forward do ControlNetUnionModel.

from_unet

< >

( unet: UNet2DConditionModelcontrolnet_conditioning_channel_order: str = 'rgb'conditioning_embedding_out_channels: tuple[int, ...] | None = (16, 32, 96, 256)load_weights_from_unet: bool = True )

Parâmetros

  • unet (UNet2DConditionModel) — Os pesos do modelo UNet a serem copiados para o ControlNetUnionModel. Todas as opções de configuração também são copiadas, quando aplicável.

Instanciar um ControlNetUnionModel a partir de UNet2DConditionModel.

set_attention_slice

< >

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

Parâmetros

  • slice_size (str ou int ou list(int), opcional, padrão "auto") — Quando "auto", a entrada para as cabeças de atenção é dividida ao meio, de modo que a atenção é calculada em duas etapas. Se "max", a quantidade máxima de memória é economizada executando apenas uma fatia por vez. Se um número for fornecido, usa tantas fatias quanto attention_head_dim // slice_size. Nesse caso, attention_head_dim deve ser um múltiplo de slice_size.

Ative o cálculo de atenção fatiado.

Quando essa opção está habilitada, o módulo de atenção divide o tensor de entrada em fatias para calcular a atenção em várias etapas. Isso é útil para economizar memória em troca de uma pequena diminuição na velocidade.

set_default_attn_processor

< >

( )

Desativa os processadores de atenção personalizados e define a implementação padrão de atenção.

Update on GitHub

←ControlNetModel FluxControlNetModel→