diffusers/main/pt/api/models/controlnet_union.md

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[[diffusers.ControlNetUnionModel]]

diffusers.ControlNetUnionModel[[diffusers.ControlNetUnionModel]]

diffusers.ControlNetUnionModel(in_channels: int = 4, conditioning_channels: int = 3, flip_sin_to_cos: bool = True, freq_shift: int = 0, down_block_types: tuple[str, ...] = ('CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'CrossAttnDownBlock2D', 'DownBlock2D'), only_cross_attention: bool | tuple[bool] = False, block_out_channels: tuple[int, ...] = (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 = 1280, transformer_layers_per_block: int | tuple[int, ...] = 1, 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, 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', projection_class_embeddings_input_dim: int | None = None, controlnet_conditioning_channel_order: str = 'rgb', conditioning_embedding_out_channels: tuple[int, ...] | None = (48, 96, 192, 384), global_pool_conditions: bool = False, addition_embed_type_num_heads: int = 64, num_control_type: int = 6, num_trans_channel: int = 320, num_trans_head: int = 8, num_trans_layer: int = 1, num_proj_channel: int = 320)

Fonte

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 de 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[[diffusers.ControlNetUnionModel.forward]]

forward(sample: Tensor, timestep: typing.Union[torch.Tensor, float, int], encoder_hidden_states: Tensor, controlnet_cond: list[torch.Tensor], control_type: Tensor, control_type_idx: list[int], conditioning_scale: float | list[float] = 1.0, class_labels: typing.Optional[torch.Tensor] = None, timestep_cond: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, added_cond_kwargs: dict[str, torch.Tensor] | None = None, cross_attention_kwargs: dict[str, typing.Any] | None = None, from_multi: bool = False, guess_mode: bool = False, return_dict: bool = True)

Fonte

Parâmetros:

sample (torch.Tensor) : O tensor de entrada com ruído.

timestep (torch.Tensor | float | int) : O número de passos de tempo 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 se o tipo de controle é usado.

control_type_idx (list[int]) : Os índices de control_type.

conditioning_scale (float, padrão 1.0) : O fator de escala para as saídas do ControlNet.

class_labels (torch.Tensor, opcional, padrão None) : Rótulos de classe opcionais para condicionamento. Seus embeddings serão somados aos embeddings de timestep.

timestep_cond (torch.Tensor, opcional, padrão None) : Incorporações condicionais adicionais para o passo de tempo. Se fornecidas, as incorporações serão somadas com a timestep_embedding passada pela camada self.time_embedding para obter as incorporações finais do passo de tempo.

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 valores negativos grandes à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[[diffusers.ControlNetUnionModel.from_unet]]

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

Fonte

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

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

Fonte

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 é reduzida pela metade, 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 esta 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[[diffusers.ControlNetUnionModel.set_default_attn_processor]]

set_default_attn_processor()

Fonte

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