Diffusers documentation
ControlNetUnionModel
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
< source >( 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 )
パラメータ
- 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 ブロック用の time scale shift 設定(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]、任意、デフォルトは(48, 96, 192, 384)) —conditioning_embeddingレイヤー内の各ブロックの出力チャネル数を表すタプルです。 - global_pool_conditions（
bool、デフォルトはFalse）—
ControlNetUnionモデル。
forward
< source >( 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
パラメータ
- 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) — timestep 用の追加の条件埋め込みです。指定された場合、これらの埋め込みはself.time_embeddingレイヤーを介して渡される timestep_embedding に加算され、最終的な timestep 埋め込みが得られます。 - attention_mask (
torch.Tensor、任意、デフォルトはNone) —encoder_hidden_statesに適用される、形状が(batch, key_tokens)のアテンションマスクです。1の場合はマスクが保持され、0の場合は破棄されます。マスクはバイアスに変換され、「破棄」対象のトークンに対応するアテンションスコアに大きな負の値が加算されます。 - 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
< source >( unet: UNet2DConditionModelcontrolnet_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
< source >( slice_size: str | int | list[int] )
スライスされたアテンションの計算を有効にします。
このオプションが有効な場合、attention モジュールは入力テンソルをスライスに分割し、複数ステップで attention を計算します。これは、わずかな速度低下を代償にメモリを節約するために有用です。
カスタムアテンションプロセッサを無効にし、デフォルトのアテンション実装を設定します。