Hugging Face's logo

Diffusers documentation

ControlNetUnionModel

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[str, ...] = ('CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'DownBlock2D')only_cross_attention: bool | tuple[bool] = Falseblock_out_channels: tuple[int, ...] = (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: list[torch.Tensor]control_type: Tensorcontrol_type_idx: list[int]conditioning_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→