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

ControlNetUnionModel

ControlNetUnionModel は、Stable Diffusion XL 向けの ControlNet の実装です。

ControlNetモデルは、xinsir6によってControlNetPlusで導入されました。計算量を増やすことなく、複数の条件付け入力をサポートします。

条件付きテキストから画像への生成において10種類以上の制御タイプをサポートし、Midjourneyと視覚的に比較可能な高解像度画像を生成できる新しいアーキテクチャを設計しました。このネットワークは元のControlNetアーキテクチャをベースとしており、2つの新しいモジュールを提案しています。1. 同じネットワークパラメータを使用して異なる画像条件をサポートするように元のControlNetを拡張する。2. 計算オフロードを増やさずに複数の条件入力をサポートする。これは、画像を詳細に編集したいデザイナーにとって特に重要であり、異なる条件は同じ条件エンコーダを使用するため、追加の計算やパラメータは不要です。

読み込み中

デフォルトでは、ControlNetUnionModelは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)

ソース

パラメータ:

in_channels (int、デフォルトは 4) : 入力サンプルのチャネル数。

flip_sin_to_cos (bool、デフォルトはTrue) : 時間埋め込みにおいて sin を cos に反転させるかどうか。

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) : mid block に使用するスケール係数。

act_fn (str、デフォルトは "silu") : 使用する活性化関数。

norm_num_groups (int、任意、デフォルトは 32) : 正規化に使用するグループ数。None の場合、後処理で正規化層と活性化層がスキップされます。

norm_eps (float、デフォルトは 1e-5) : 正規化に使用する epsilon。

cross_attention_dim (int、デフォルトは 1280) : クロスアテンション特徴量の次元数。

transformer_layers_per_block (int または tuple[int]、省略可能、デフォルト値は 1) : BasicTransformerBlock 型の Transformer ブロックの数。~models.unet_2d_blocks.CrossAttnDownBlock2D、~models.unet_2d_blocks.CrossAttnUpBlock2D、~models.unet_2d_blocks.UNetMidBlock2DCrossAttn の場合にのみ関連します。

encoder_hid_dim (int、任意、デフォルトは None) : encoder_hid_dim_type が定義されている場合、encoder_hidden_states は encoder_hid_dim 次元から cross_attention_dim へ射影されます。

encoder_hid_dim_type (str、任意、デフォルトはNone) : 指定された場合、encoder_hidden_statesおよびその他の埋め込みが、encoder_hid_dim_typeに従って、次元cross_attentionのテキスト埋め込みにダウンプロジェクトされます。

attention_head_dim (int | tuple[int]、デフォルトは 8) : アテンションヘッドの次元数。

use_linear_projection (bool、デフォルトは False) --

class_embed_type (str、任意、デフォルトはNone) : 最終的に time embeddings と加算される class embedding の種類を指定します。None、"timestep"、"identity"、"projection"、または"simple_projection"から選択してください。

addition_embed_type (str、任意、デフォルトはNone) : 時間埋め込みと加算される任意の埋め込みを設定します。Noneまたは"text"から選択します。"text"を指定すると、TextTimeEmbeddingレイヤーが使用されます。

num_class_embeds (int、任意、デフォルト値は 0) : class_embed_type が None に等しい場合のクラス条件付けにおいて、学習可能な埋め込み行列の time_embed_dim への射影対象となる入力次元。

upcast_attention (bool、デフォルトは False) --

resnet_time_scale_shift (str、デフォルトは "default") : ResNet ブロック用の時間スケールシフト設定（ResnetBlock2D を参照）。default または scale_shift から選択します。

projection_class_embeddings_input_dim (int、任意、デフォルトは None) : class_embed_type="projection" の場合の class_labels 入力の次元。class_embed_type="projection" の場合は必須です。

controlnet_conditioning_channel_order (str、デフォルトは "rgb") : 条件付き画像のチャネル順序。bgr の場合は rgb に変換されます。

conditioning_embedding_out_channels (tuple[int]、optional、デフォルトは(48, 96, 192, 384)) : conditioning_embeddingレイヤー内の各ブロックの出力チャネル数を表すタプルです。

global_pool_conditions (bool、デフォルトは False) --

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)

ソース

パラメータ:

sample (torch.Tensor) : ノイズ付きの入力テンソル。

timestep (torch.Tensor | float | int) : 入力をデノイズするためのタイムステップ数。

encoder_hidden_states (torch.Tensor) : エンコーダーの隠れ状態。

controlnet_cond (list[torch.Tensor]) : 条件付き入力テンソル。

control_type (torch.Tensor) : 制御タイプが使用されているかどうかに応じて、値が0または1となる、形状(batch, num_control_type)のテンソル。

control_type_idx (list[int]) : control_typeのインデックスです。

conditioning_scale (float、デフォルトは1.0) : ControlNet の出力に対するスケール係数。

class_labels (torch.Tensor、任意、デフォルトはNone) : 条件付け用の任意のクラスラベル。その埋め込みは、タイムステップの埋め込みと加算されます。

timestep_cond (torch.Tensor、任意、デフォルトはNone) : タイムステップ用の追加の条件埋め込みです。指定された場合、これらの埋め込みはself.time_embedding層を介して渡されるtimestep_embeddingに足し合わされ、最終的なタイムステップ埋め込みが得られます。

attention_mask (torch.Tensor, 任意、デフォルトはNone) : 形状(batch, key_tokens)のattention maskがencoder_hidden_statesに適用されます。1の場合はマスクが保持され、0の場合は破棄されます。マスクはバイアスに変換され、「破棄」トークンに対応するattention scoreに大きな負の値が加算されます。

added_cond_kwargs (dict) : Stable Diffusion XL UNet 用の追加条件。

cross_attention_kwargs (dict[str]、任意、デフォルトはNone) : 指定された場合、AttnProcessorに渡される kwargs 辞書。

from_multi (bool、デフォルトはFalse) : MultiControlNetUnionModelから呼び出された場合、標準スケーリングを使用します。

guess_mode (bool、デフォルトはFalse) : このモードでは、すべてのプロンプトを削除した場合でも、ControlNet エンコーダーは入力内容の認識に最大限努めます。guidance_scaleは3.0から5.0の範囲が推奨されます。

return_dict (bool、デフォルトはTrue) : プレーンなタプルではなく~models.controlnet.ControlNetOutputを返すかどうか。

戻り値: ~models.controlnet.ControlNetOutput または tuple

return_dict が True の場合、~models.controlnet.ControlNetOutput が返され、それ以外の場合は、最初の要素がサンプルテンソルであるタプルが返されます。

ControlNetUnionModelのforwardメソッド。

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)

ソース

パラメータ:

unet (UNet2DConditionModel) : ControlNetUnionModel にコピーする UNet モデルの重みです。適用可能なすべての設定オプションもコピーされます。

UNet2DConditionModelからControlNetUnionModelをインスタンス化します。

set_attention_slice[[diffusers.ControlNetUnionModel.set_attention_slice]]

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

ソース

パラメータ:

slice_size (str または int または list(int)、任意、デフォルトは "auto") : "auto" の場合、アテンションヘッドへの入力が半分になり、アテンションは2段階で計算されます。"max" の場合、一度に1つのスライスのみを実行することで、最大限のメモリを節約します。数値が指定された場合、attention_head_dim // slice_size 個のスライスを使用します。この場合、attention_head_dim は slice_size の倍数である必要があります。

スライスされたアテンションの計算を有効にします。

このオプションを有効にすると、attention モジュールは入力テンソルをスライスに分割し、複数ステップで attention を計算します。これは、わずかな速度低下を代償にメモリを節約するのに役立ちます。

set_default_attn_processor[[diffusers.ControlNetUnionModel.set_default_attn_processor]]

set_default_attn_processor()

ソース

カスタムアテンションプロセッサを無効にし、デフォルトのアテンション実装を設定します。