Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /v0.43.0 /ja /api /models /controlnet.md

mishig

2 days ago

preview code

download

raw

17.4 kB

# ControlNetModel

ControlNetモデルは、Lvmin Zhang、Anyi Rao、Maneesh Agrawala による [Adding Conditional Control to Text-to-Image Diffusion Models](https://huggingface.co/papers/2302.05543) で紹介されました。エッジマップ、深度マップ、セグメンテーションマップ、ポーズ検出用のキーポイントなどの追加入力に対してモデルを条件付けすることで、テキストから画像を生成する際の制御性を高めます。

論文の抄録は以下の通りです：

*本稿では、大規模な事前学習済みテキストから画像への拡散モデルに空間的条件付け制御を追加するためのニューラルネットワークアーキテクチャであるControlNetを提案します。ControlNetは、実運用可能な大規模拡散モデルを固定し、数十億枚の画像で事前学習された深く頑健なエンコーディング層を強力なバックボーンとして再利用することで、多様な条件付け制御のセットを学習します。このニューラルアーキテクチャは、「ゼロ畳み込み」（ゼロ初期化された畳み込み層）によって接続されており、パラメータをゼロから段階的に増加させ、有害なノイズがファインチューニングに影響を与えないことを保証します。Stable Diffusionを用いて、エッジ、深度、セグメンテーション、人間のポーズなどの様々な条件付け制御を、プロンプトの有無にかかわらず、単一または複数の条件を用いてテストしました。ControlNetの学習は、小規模（<50k）および大規模（>1m）のデータセットのいずれにおいても頑健であることが示されています。広範な結果から、ControlNetは画像拡散モデルの制御に関するより幅広いアプリケーションを促進し得ることが示されました。*

## 元の形式から読み込む

デフォルトでは、[ControlNetModel](/docs/diffusers/v0.43.0/ja/api/models/controlnet#diffusers.ControlNetModel)は[from_pretrained()](/docs/diffusers/v0.43.0/ja/api/models/overview#diffusers.ModelMixin.from_pretrained)で読み込む必要がありますが、`FromOriginalModelMixin.from_single_file`を使用して元の形式から読み込むこともできます。以下のようにします。

```py
from diffusers import StableDiffusionControlNetPipeline, ControlNetModel
url = "https://huggingface.co/lllyasviel/ControlNet-v1-1/blob/main/control_v11p_sd15_canny.pth"  # can also be a local path
controlnet = ControlNetModel.from_single_file(url)
url = "https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/blob/main/v1-5-pruned.safetensors"  # can also be a local path
pipe = StableDiffusionControlNetPipeline.from_single_file(url, controlnet=controlnet)
```

## Control LoRAからの読み込み

Control-LoRA は、Stability AI が [stabilityai/control-lora](https://huggingface.co/stabilityai/control-lora) で ControlNet に低ランクのパラメータ効率の良いファインチューニングを追加することによって導入されました。このアプローチにより、より効率的かつコンパクトな方法で、より幅広い消費者向け GPU に対してモデルの制御を可能にします。

```py
from diffusers import ControlNetModel, UNet2DConditionModel
lora_id = "stabilityai/control-lora"
lora_filename = "control-LoRAs-rank128/control-lora-canny-rank128.safetensors"
unet = UNet2DConditionModel.from_pretrained("stabilityai/stable-diffusion-xl-base-1.0", subfolder="unet", dtype=torch.bfloat16).to("cuda")  # or "mps", "xpu", "cpu"
controlnet = ControlNetModel.from_unet(unet).to(device="cuda", dtype=torch.bfloat16)
controlnet.load_lora_adapter(lora_id, weight_name=lora_filename, prefix=None, controlnet_config=controlnet.config)
```

## ControlNetModel[[diffusers.ControlNetModel]]

#### diffusers.ControlNetModel[[diffusers.ControlNetModel]]

```python
diffusers.ControlNetModel(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'), mid_block_type: str | None = 'UNetMidBlock2DCrossAttn', 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 = (16, 32, 96, 256), global_pool_conditions: bool = False, addition_embed_type_num_heads: int = 64)
```

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet.py#L111)

**パラメータ:**

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*、デフォルトは`(16, 32, 96, 256)`) : `conditioning_embedding`レイヤー内の各ブロックの出力チャネルのタプル。

global_pool_conditions (`bool`、デフォルトは`False`) : TODO(Patrick) - 未使用のパラメータ。

addition_embed_type_num_heads (`int`、デフォルトは 64) : `TextTimeEmbedding` レイヤーで使用するヘッド数。

ControlNetモデル。

#### forward[[diffusers.ControlNetModel.forward]]

```python
forward(sample: Tensor, timestep: typing.Union[torch.Tensor, float, int], encoder_hidden_states: Tensor, controlnet_cond: Tensor, conditioning_scale: 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, guess_mode: bool = False, return_dict: bool = True)
```

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet.py#L602)

**パラメータ:**

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

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

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

controlnet_cond (`torch.Tensor`) : 形状が `(batch_size, sequence_length, hidden_size)` の条件付き入力テンソル。

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 辞書。

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

return_dict (`bool`、デフォルトは`True`) : プレーンなタプルではなく[ControlNetOutput](/docs/diffusers/v0.43.0/ja/api/models/controlnet#diffusers.models.controlnets.ControlNetOutput)を返すかどうか。
**戻り値:** [ControlNetOutput](/docs/diffusers/v0.43.0/ja/api/models/controlnet#diffusers.models.controlnets.ControlNetOutput) **または** `tuple`
`return_dict` が `True` の場合、[ControlNetOutput](/docs/diffusers/v0.43.0/ja/api/models/controlnet#diffusers.models.controlnets.ControlNetOutput) が返され、それ以外の場合は、最初の要素がサンプルテンソルであるタプルが返されます。

[ControlNetModel](/docs/diffusers/v0.43.0/ja/api/models/controlnet#diffusers.ControlNetModel)のforwardメソッド。

#### from_unet[[diffusers.ControlNetModel.from_unet]]

```python
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, conditioning_channels: int = 3)
```

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet.py#L444)

**パラメータ:**

unet (`UNet2DConditionModel`) : [ControlNetModel](/docs/diffusers/v0.43.0/ja/api/models/controlnet#diffusers.ControlNetModel) にコピーする UNet モデルの重みです。適用可能なすべての設定オプションもコピーされます。

[UNet2DConditionModel](/docs/diffusers/v0.43.0/ja/api/models/unet2d-cond#diffusers.UNet2DConditionModel)から[ControlNetModel](/docs/diffusers/v0.43.0/ja/api/models/controlnet#diffusers.ControlNetModel)をインスタンス化します。

#### set_attention_slice[[diffusers.ControlNetModel.set_attention_slice]]

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

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet.py#L537)

**パラメータ:**

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.ControlNetModel.set_default_attn_processor]]
```python
set_default_attn_processor()
```
[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet.py#L521)
カスタムアテンションプロセッサを無効にし、デフォルトのアテンション実装を設定します。
## ControlNetOutput[[diffusers.models.controlnets.ControlNetOutput]]
#### diffusers.models.controlnets.ControlNetOutput[[diffusers.models.controlnets.ControlNetOutput]]
```python
diffusers.models.controlnets.ControlNetOutput(down_block_res_samples: tuple[torch.Tensor], mid_block_res_sample: Tensor)
```
[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet.py#L47)
**パラメータ:**
down_block_res_samples (`tuple[torch.Tensor]`) : 各ダウンサンプリングブロックにおける、異なる解像度のダウンサンプル活性化値のタプル。各テンソルは `(batch_size, channel * resolution, height //resolution, width // resolution)` の形状である必要があります。出力は、元の UNet のダウンサンプリング活性化値を条件付けするために使用できます。
mid_down_block_re_sample (`torch.Tensor`) : 中央ブロック（最も低いサンプル解像度）の活性化値です。各テンソルの形状は `(batch_size, channel * lowest_resolution, height // lowest_resolution, width // lowest_resolution)` である必要があります。出力は、元の UNet の中央ブロックの活性化値を条件付けするために使用できます。
[ControlNetModel](/docs/diffusers/v0.43.0/ja/api/models/controlnet#diffusers.ControlNetModel)の出力です。

Xet Storage Details

Size:: 17.4 kB
Xet hash:: f4989d4231d440fed3ec4ee0425a2097edb2c09e5b142779e02f9e222ae67431

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.

	# ControlNetModel

	ControlNetモデルは、Lvmin Zhang、Anyi Rao、Maneesh Agrawala による [Adding Conditional Control to Text-to-Image Diffusion Models](https://huggingface.co/papers/2302.05543) で紹介されました。エッジマップ、深度マップ、セグメンテーションマップ、ポーズ検出用のキーポイントなどの追加入力に対してモデルを条件付けすることで、テキストから画像を生成する際の制御性を高めます。

	論文の抄録は以下の通りです：

	本稿では、大規模な事前学習済みテキストから画像への拡散モデルに空間的条件付け制御を追加するためのニューラルネットワークアーキテクチャであるControlNetを提案します。ControlNetは、実運用可能な大規模拡散モデルを固定し、数十億枚の画像で事前学習された深く頑健なエンコーディング層を強力なバックボーンとして再利用することで、多様な条件付け制御のセットを学習します。このニューラルアーキテクチャは、「ゼロ畳み込み」（ゼロ初期化された畳み込み層）によって接続されており、パラメータをゼロから段階的に増加させ、有害なノイズがファインチューニングに影響を与えないことを保証します。Stable Diffusionを用いて、エッジ、深度、セグメンテーション、人間のポーズなどの様々な条件付け制御を、プロンプトの有無にかかわらず、単一または複数の条件を用いてテストしました。ControlNetの学習は、小規模（<50k）および大規模（>1m）のデータセットのいずれにおいても頑健であることが示されています。広範な結果から、ControlNetは画像拡散モデルの制御に関するより幅広いアプリケーションを促進し得ることが示されました。

	## 元の形式から読み込む

	デフォルトでは、[ControlNetModel](/docs/diffusers/v0.43.0/ja/api/models/controlnet#diffusers.ControlNetModel)は[from_pretrained()](/docs/diffusers/v0.43.0/ja/api/models/overview#diffusers.ModelMixin.from_pretrained)で読み込む必要がありますが、`FromOriginalModelMixin.from_single_file`を使用して元の形式から読み込むこともできます。以下のようにします。

	```py
	from diffusers import StableDiffusionControlNetPipeline, ControlNetModel

	url = "https://huggingface.co/lllyasviel/ControlNet-v1-1/blob/main/control_v11p_sd15_canny.pth" # can also be a local path
	controlnet = ControlNetModel.from_single_file(url)

	url = "https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/blob/main/v1-5-pruned.safetensors" # can also be a local path
	pipe = StableDiffusionControlNetPipeline.from_single_file(url, controlnet=controlnet)
	```

	## Control LoRAからの読み込み

	Control-LoRA は、Stability AI が [stabilityai/control-lora](https://huggingface.co/stabilityai/control-lora) で ControlNet に低ランクのパラメータ効率の良いファインチューニングを追加することによって導入されました。このアプローチにより、より効率的かつコンパクトな方法で、より幅広い消費者向け GPU に対してモデルの制御を可能にします。

	```py
	from diffusers import ControlNetModel, UNet2DConditionModel

	lora_id = "stabilityai/control-lora"
	lora_filename = "control-LoRAs-rank128/control-lora-canny-rank128.safetensors"

	unet = UNet2DConditionModel.from_pretrained("stabilityai/stable-diffusion-xl-base-1.0", subfolder="unet", dtype=torch.bfloat16).to("cuda") # or "mps", "xpu", "cpu"
	controlnet = ControlNetModel.from_unet(unet).to(device="cuda", dtype=torch.bfloat16)
	controlnet.load_lora_adapter(lora_id, weight_name=lora_filename, prefix=None, controlnet_config=controlnet.config)
	```

	## ControlNetModel[[diffusers.ControlNetModel]]

	#### diffusers.ControlNetModel[[diffusers.ControlNetModel]]

	```python
	diffusers.ControlNetModel(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'), mid_block_type: str \| None = 'UNetMidBlock2DCrossAttn', 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 = (16, 32, 96, 256), global_pool_conditions: bool = False, addition_embed_type_num_heads: int = 64)
	```

	[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet.py#L111)

	パラメータ:

	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、デフォルトは`(16, 32, 96, 256)`) : `conditioning_embedding`レイヤー内の各ブロックの出力チャネルのタプル。

	global_pool_conditions (`bool`、デフォルトは`False`) : TODO(Patrick) - 未使用のパラメータ。

	addition_embed_type_num_heads (`int`、デフォルトは 64) : `TextTimeEmbedding` レイヤーで使用するヘッド数。

	ControlNetモデル。

	#### forward[[diffusers.ControlNetModel.forward]]

	```python
	forward(sample: Tensor, timestep: typing.Union[torch.Tensor, float, int], encoder_hidden_states: Tensor, controlnet_cond: Tensor, conditioning_scale: 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, guess_mode: bool = False, return_dict: bool = True)
	```

	[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet.py#L602)

	パラメータ:

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

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

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

	controlnet_cond (`torch.Tensor`) : 形状が `(batch_size, sequence_length, hidden_size)` の条件付き入力テンソル。

	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 辞書。

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

	return_dict (`bool`、デフォルトは`True`) : プレーンなタプルではなく[ControlNetOutput](/docs/diffusers/v0.43.0/ja/api/models/controlnet#diffusers.models.controlnets.ControlNetOutput)を返すかどうか。

	戻り値: [ControlNetOutput](/docs/diffusers/v0.43.0/ja/api/models/controlnet#diffusers.models.controlnets.ControlNetOutput) または `tuple`

	`return_dict` が `True` の場合、[ControlNetOutput](/docs/diffusers/v0.43.0/ja/api/models/controlnet#diffusers.models.controlnets.ControlNetOutput) が返され、それ以外の場合は、最初の要素がサンプルテンソルであるタプルが返されます。

	[ControlNetModel](/docs/diffusers/v0.43.0/ja/api/models/controlnet#diffusers.ControlNetModel)のforwardメソッド。

	#### from_unet[[diffusers.ControlNetModel.from_unet]]

	```python
	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, conditioning_channels: int = 3)
	```

	[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet.py#L444)

	パラメータ:

	unet (`UNet2DConditionModel`) : [ControlNetModel](/docs/diffusers/v0.43.0/ja/api/models/controlnet#diffusers.ControlNetModel) にコピーする UNet モデルの重みです。適用可能なすべての設定オプションもコピーされます。

	[UNet2DConditionModel](/docs/diffusers/v0.43.0/ja/api/models/unet2d-cond#diffusers.UNet2DConditionModel)から[ControlNetModel](/docs/diffusers/v0.43.0/ja/api/models/controlnet#diffusers.ControlNetModel)をインスタンス化します。

	#### set_attention_slice[[diffusers.ControlNetModel.set_attention_slice]]

	```python
	set_attention_slice(slice_size: str \| int \| list[int])
	```

	[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet.py#L537)

	パラメータ:

	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.ControlNetModel.set_default_attn_processor]]

	```python
	set_default_attn_processor()
	```

	[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet.py#L521)

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

	## ControlNetOutput[[diffusers.models.controlnets.ControlNetOutput]]

	#### diffusers.models.controlnets.ControlNetOutput[[diffusers.models.controlnets.ControlNetOutput]]

	```python
	diffusers.models.controlnets.ControlNetOutput(down_block_res_samples: tuple[torch.Tensor], mid_block_res_sample: Tensor)
	```

	[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/controlnets/controlnet.py#L47)

	パラメータ:

	down_block_res_samples (`tuple[torch.Tensor]`) : 各ダウンサンプリングブロックにおける、異なる解像度のダウンサンプル活性化値のタプル。各テンソルは `(batch_size, channel * resolution, height //resolution, width // resolution)` の形状である必要があります。出力は、元の UNet のダウンサンプリング活性化値を条件付けするために使用できます。

	mid_down_block_re_sample (`torch.Tensor`) : 中央ブロック（最も低いサンプル解像度）の活性化値です。各テンソルの形状は `(batch_size, channel * lowest_resolution, height // lowest_resolution, width // lowest_resolution)` である必要があります。出力は、元の UNet の中央ブロックの活性化値を条件付けするために使用できます。

	[ControlNetModel](/docs/diffusers/v0.43.0/ja/api/models/controlnet#diffusers.ControlNetModel)の出力です。