diffusers/v0.43.0/fr/api/models/controlnet_union.md

ControlNetUnionModel

ControlNetUnionModel est une implémentation de ControlNet pour Stable Diffusion XL.

Le modèle ControlNet a été introduit dans ControlNetPlus par xinsir6. Il prend en charge plusieurs entrées de conditionnement sans augmenter les calculs.

Nous concevons une nouvelle architecture capable de prendre en charge plus de 10 types de contrôle dans la génération d'images texte-vers-image conditionnelle et de produire des images haute résolution visuellement comparables à celles de midjourney. Le réseau est basé sur l'architecture ControlNet d'origine ; nous proposons deux nouveaux modules pour : 1 étendre le ControlNet d'origine afin de supporter différentes conditions d'image en utilisant les mêmes paramètres de réseau. 2 prendre en charge l'entrée de multiples conditions sans augmenter le déchargement de calcul, ce qui est particulièrement important pour les concepteurs souhaitant éditer une image en détail, les différentes conditions utilisant le même encodeur de condition, sans ajouter de calculs ou de paramètres supplémentaires.

Chargement

Par défaut, le ControlNetUnionModel doit être chargé avec 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)

Source

Paramètres :

in_channels (int, par défaut 4) : Le nombre de canaux dans l'échantillon d'entrée.

flip_sin_to_cos (bool, par défaut True) : Indique s'il faut inverser le sin en cos dans l'encodage temporel.

freq_shift (int, par défaut 0) : Le décalage de fréquence à appliquer à l'embedding temporel.

down_block_types (tuple[str], par défaut ("CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "DownBlock2D")) : Le tuple de blocs de downsampling à utiliser.

only_cross_attention (bool | tuple[bool], par défaut False) --

block_out_channels (tuple[int], par défaut (320, 640, 1280, 1280)) : Le tuple des canaux de sortie pour chaque bloc.

layers_per_block (int, par défaut 2) : Le nombre de couches par bloc.

downsample_padding (int, par défaut 1) : Le padding à utiliser pour la convolution de downsampling.

mid_block_scale_factor (float, par défaut 1) : Le facteur d'échelle à utiliser pour le bloc intermédiaire.

act_fn (str, par défaut "silu") : La fonction d'activation à utiliser.

norm_num_groups (int, facultatif, valeur par défaut 32) : Le nombre de groupes à utiliser pour la normalisation. Si None, les couches de normalisation et d'activation sont ignorées lors du post-traitement.

norm_eps (float, par défaut 1e-5) : L'épsilon à utiliser pour la normalisation.

cross_attention_dim (int, par défaut 1280) : La dimension des fonctionnalités d'attention croisée.

transformer_layers_per_block (int ou tuple[int], facultatif, valeur par défaut 1) : Le nombre de blocs de transformateur de type BasicTransformerBlock. Ne concerne que ~models.unet_2d_blocks.CrossAttnDownBlock2D, ~models.unet_2d_blocks.CrossAttnUpBlock2D, ~models.unet_2d_blocks.UNetMidBlock2DCrossAttn.

encoder_hid_dim (int, facultatif, valeur par défaut None) : Si encoder_hid_dim_type est défini, encoder_hidden_states sera projeté de la dimension encoder_hid_dim vers cross_attention_dim.

encoder_hid_dim_type (str, facultatif, par défaut None) : Si fourni, les encoder_hidden_states et d'autres embeddings éventuels sont projetés vers des embeddings de texte de dimension cross_attention selon encoder_hid_dim_type.

attention_head_dim (int | tuple[int], par défaut 8) : La dimension des têtes d'attention.

use_linear_projection (bool, par défaut False) --

class_embed_type (str, facultatif, valeur par défaut None) : Le type d'embedding de classe à utiliser, qui est finalement additionné aux embeddings temporels. Choisissez parmi None, "timestep", "identity", "projection" ou "simple_projection".

addition_embed_type (str, facultatif, valeur par défaut None) : Configure un embedding facultatif qui sera additionné aux embeddings temporels. Choisissez entre None et "text". "text" utilisera la couche TextTimeEmbedding.

num_class_embeds (int, facultatif, valeur par défaut 0) : Dimension d'entrée de la matrice d'incorporation apprenable à projeter vers time_embed_dim, lors de l'utilisation d'un conditionnement par classe avec class_embed_type égal à None.

upcast_attention (bool, par défaut False) --

resnet_time_scale_shift (str, par défaut "default") : Configuration du décalage de l'échelle temporelle pour les blocs ResNet (voir ResnetBlock2D). Choisissez entre default et scale_shift.

projection_class_embeddings_input_dim (int, facultatif, par défaut None) : La dimension de l'entrée class_labels lorsque class_embed_type="projection". Obligatoire lorsque class_embed_type="projection".

controlnet_conditioning_channel_order (str, par défaut "rgb") : L'ordre des canaux de l'image conditionnelle. Sera converti en rgb s'il est bgr.

conditioning_embedding_out_channels (tuple[int], facultatif, par défaut (48, 96, 192, 384)) : Le tuple des canaux de sortie pour chaque bloc de la couche conditioning_embedding.

global_pool_conditions (bool, par défaut False) --

Un modèle 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)

Source

Paramètres :

sample (torch.Tensor) : Le tenseur d'entrée bruité.

timestep (torch.Tensor | float | int) : Le nombre de pas de temps pour débruitiser une entrée.

encoder_hidden_states (torch.Tensor) : Les états cachés de l'encodeur.

controlnet_cond (list[torch.Tensor]) : Les tenseurs d'entrée conditionnels.

control_type (torch.Tensor) : Un tenseur de forme (batch, num_control_type) dont les valeurs sont 0 ou 1 selon que le type de contrôle est utilisé ou non.

control_type_idx (list[int]) : Les indices de control_type.

conditioning_scale (float, par défaut 1.0) : Le facteur d'échelle pour les sorties de ControlNet.

class_labels (torch.Tensor, facultatif, valeur par défaut None) : Étiquettes de classe optionnelles pour le conditionnement. Leurs embeddings seront additionnés aux embeddings du timestep.

timestep_cond (torch.Tensor, facultatif, valeur par défaut None) : Incrustations conditionnelles supplémentaires pour le pas de temps. Si fournies, les incrustations seront additionnées à la timestep_embedding transmise à travers la couche self.time_embedding pour obtenir les incrustations de pas de temps finales.

attention_mask (torch.Tensor, facultatif, par défaut None) : Un masque d'attention de forme (batch, key_tokens) est appliqué à encoder_hidden_states. Si la valeur est 1, le masque est conservé ; sinon, si elle est 0, il est ignoré. Le masque est converti en biais, qui ajoute de grandes valeurs négatives aux scores d'attention correspondant aux jetons « ignorés ».

added_cond_kwargs (dict) : Conditions supplémentaires pour le UNet de Stable Diffusion XL.

cross_attention_kwargs (dict[str], facultatif, par défaut None) : Un dictionnaire de kwargs qui, s'il est spécifié, est transmis au AttnProcessor.

from_multi (bool, par défaut False) : Utiliser la mise à l'échelle standard lorsqu'il est appelé depuis MultiControlNetUnionModel.

guess_mode (bool, par défaut False) : Dans ce mode, l'encodeur ControlNet fait de son mieux pour reconnaître le contenu de l'entrée, même si vous supprimez tous les prompts. Un guidance_scale compris entre 3,0 et 5,0 est recommandé.

return_dict (bool, par défaut True) : Indique s'il faut retourner un ~models.controlnet.ControlNetOutput plutôt qu'un simple tuple.

Retourne : ~models.controlnet.ControlNetOutput ou tuple

Si return_dict est True, un ~models.controlnet.ControlNetOutput est renvoyé, sinon un tuple est renvoyé dont le premier élément est le tenseur d'échantillon.

La méthode forward du 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)

Source

Paramètres :

unet (UNet2DConditionModel) : Les poids du modèle UNet à copier vers le ControlNetUnionModel. Toutes les options de configuration sont également copiées lorsque cela est applicable.

Instanciez un ControlNetUnionModel à partir de UNet2DConditionModel.

set_attention_slice[[diffusers.ControlNetUnionModel.set_attention_slice]]

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

Source

Paramètres :

slice_size (str ou int ou list(int), facultatif, par défaut "auto") : lorsque la valeur est "auto", l’entrée des têtes d’attention est divisée par deux, de sorte que l’attention est calculée en deux étapes. Si la valeur est "max", la quantité maximale de mémoire est économisée en n’exécutant qu’une seule tranche à la fois. Si un nombre est fourni, autant de tranches sont utilisées que attention_head_dim // slice_size. Dans ce cas, attention_head_dim doit être un multiple de slice_size.

Activer le calcul de l'attention par tranches.

Lorsque cette option est activée, le module d'attention divise le tenseur d'entrée en tranches pour calculer l'attention en plusieurs étapes. Cela est utile pour économiser de la mémoire au prix d'une légère diminution de la vitesse.

set_default_attn_processor[[diffusers.ControlNetUnionModel.set_default_attn_processor]]

set_default_attn_processor()

Source

Désactive les processeurs d'attention personnalisés et définit l'implémentation d'attention par défaut.