Diffusers documentation
SD3ControlNetModel
SD3ControlNetModel
SD3ControlNetModel は、Stable Diffusion 3 向けの ControlNet の実装です。
ControlNetモデルは、Lvmin Zhang、Anyi Rao、Maneesh Agrawala による Adding Conditional Control to Text-to-Image Diffusion Models で紹介されました。エッジマップ、深度マップ、セグメンテーションマップ、ポーズ検出用のキーポイントなどの追加入力に対してモデルを条件付けすることで、テキストから画像を生成する際の制御性を高めます。
論文の抄録は以下の通りです：
本稿では、大規模な事前学習済みテキストから画像への拡散モデルに空間的条件付け制御を追加するためのニューラルネットワークアーキテクチャであるControlNetを提案します。ControlNetは、実運用可能な大規模拡散モデルを固定し、数十億枚の画像で事前学習された深く頑健なエンコーディング層を強力なバックボーンとして再利用することで、多様な条件付け制御のセットを学習します。このニューラルアーキテクチャは、「ゼロ畳み込み」（ゼロ初期化された畳み込み層）によって接続されており、パラメータをゼロから段階的に増加させ、有害なノイズがファインチューニングに影響を与えないことを保証します。Stable Diffusionを用いて、エッジ、深度、セグメンテーション、人間のポーズなどの様々な条件付け制御を、プロンプトの有無にかかわらず、単一または複数の条件を用いてテストしました。ControlNetの学習は、小規模（<50k）および大規模（>1m）のデータセットのいずれにおいても頑健であることが示されています。広範な結果から、ControlNetは画像拡散モデルの制御に関するより幅広いアプリケーションを促進し得ることが示されました。
元の形式から読み込む
デフォルトでは、SD3ControlNetModelはfrom_pretrained()で読み込む必要があります。
from diffusers import StableDiffusion3ControlNetPipeline
from diffusers.models import SD3ControlNetModel, SD3MultiControlNetModel
controlnet = SD3ControlNetModel.from_pretrained("InstantX/SD3-Controlnet-Canny")
pipe = StableDiffusion3ControlNetPipeline.from_pretrained("stabilityai/stable-diffusion-3-medium-diffusers", controlnet=controlnet)SD3ControlNetModel
クラス diffusers.SD3ControlNetModel
< source >( sample_size: int = 128patch_size: int = 2in_channels: int = 16num_layers: int = 18attention_head_dim: int = 64num_attention_heads: int = 18joint_attention_dim: int = 4096caption_projection_dim: int = 1152pooled_projection_dim: int = 2048out_channels: int = 16pos_embed_max_size: int = 96extra_conditioning_channels: int = 0dual_attention_layers: tuple[int, ...] = ()qk_norm: str | None = Nonepos_embed_type: str | None = 'sincos'use_pos_embed: bool = Trueforce_zeros_for_pooled_projection: bool = True )
パラメータ
- sample_size (
int、デフォルトは128) — 潜在変数の幅/高さです。これは位置埋め込みの数を学習するために使用されるため、トレーニング中は固定されます。 - patch_size (
int、デフォルトは2) — 入力データを小さなパッチに変換するためのパッチサイズ。 - in_channels (
int、デフォルトは16) — 入力における潜在チャネルの数です。 - num_layers (
int、デフォルトは18) — 使用する transformer ブロックの層数です。 - attention_head_dim (
int, デフォルトは64) — 各ヘッドのチャネル数です。 - num_attention_heads (
int、デフォルトは18) — マルチヘッドアテンションに使用するヘッドの数。 - joint_attention_dim (
int、デフォルトは4096) — テキストと画像の結合アテンションに使用する埋め込み次元数。 - caption_projection_dim (
int、デフォルトは1152) — キャプション埋め込みの次元数です。 - pooled_projection_dim (
int, デフォルトは2048) — プーリングされたテキスト投影の埋め込み次元です。 - out_channels (
int、デフォルトは16) — 出力の潜在チャネル数です。 - pos_embed_max_size (
int、デフォルトは96) — 位置埋め込みの潜在高さ/幅の最大値。 - extra_conditioning_channels (
int、デフォルトは0) — パッチ埋め込みの条件付けに使用する追加チャネルの数です。 - dual_attention_layers (
tuple[int, ...]、デフォルトは()) — 使用するデュアルストリームtransformerブロックの数です。 - qk_norm (
str、省略可、デフォルトはNone) — アテンション層のクエリとキーに使用する正規化です。Noneの場合、正規化は行われません。 - pos_embed_type (
str、デフォルトは"sincos") — 使用する位置埋め込みの種類です。"sincos"とNoneから選択します。 - use_pos_embed (
bool、デフォルトはTrue) — 位置埋め込みを使用するかどうか。 - force_zeros_for_pooled_projection (
bool、デフォルトはTrue) — プールされた投影埋め込みにゼロを強制するかどうか。これは、パイプライン内で ControlNet モデルの config 値を読み取ることで処理されます。
Stable Diffusion 3用のControlNetモデル。
enable_forward_chunking
< source >( chunk_size: int | None = Nonedim: int = 0 )
フィードフォワードチャンク分割を使用するアテンションプロセッサを設定します。
forward
< source >( hidden_states: Tensorcontrolnet_cond: Tensorconditioning_scale: float = 1.0encoder_hidden_states: Tensor = Nonepooled_projections: Tensor = Nonetimestep: LongTensor = Nonejoint_attention_kwargs: dict[str, typing.Any] | None = Nonereturn_dict: bool = True )
パラメータ
- hidden_states (
torch.Tensor、形状(batch size, channel, height, width)) — 入力となるhidden_states。 - controlnet_cond (
torch.Tensor) —(batch_size, sequence_length, hidden_size)の形状を持つ条件付き入力テンソルです。 - conditioning_scale (
float、デフォルト値は1.0) — ControlNet の出力に対するスケール係数です。 - encoder_hidden_states (
torch.Tensor、形状(batch size, sequence_len, embed_dims)) — 使用する条件埋め込み（プロンプトなどの入力条件から計算される埋め込み）。 - pooled_projections（
torch.Tensor、形状(batch_size, projection_dim)）— 入力条件の埋め込みから投影された埋め込み。 - timestep (
torch.LongTensor) — デノイジングステップを示すために使用されます。 - joint_attention_kwargs (
dict、省略可) — 指定された場合、diffusers.models.attention_processor で定義されているself.processor配下のAttentionProcessorに渡される kwargs の辞書です。 - return_dict (
bool、任意、デフォルトはTrue) — プレーンなタプルではなく~models.transformer_2d.Transformer2DModelOutputを返すかどうか。
SD3Transformer2DModelのforwardメソッド。
融合された QKV 投影を有効にします。自己注意モジュールでは、すべての投影行列（つまり、クエリ、キー、バリュー）が融合されます。相互注意モジュールでは、キーとバリューの投影行列が融合されます。
> このAPIは🧪実験的です。
SD3ControlNetOutput
クラス diffusers.models.controlnets.SD3ControlNetOutput
< source >( controlnet_block_samples: tuple[torch.Tensor] )