Buckets:

hf-doc-build
/

doc

Files
xet
hf-doc-build/doc / diffusers /main /ja /api /models /unet2d-cond.md
mishig
3 days ago
preview code
download
raw
22.2 kB
# UNet2DConditionModel

[UNet](https://huggingface.co/papers/1505.04597)モデルは、Ronneberger らによって生体医用画像のセグメンテーションのために最初に提案されましたが、入力と同じサイズの画像を出力するため、🤗 Diffusers でも広く使用されています。実際の拡散プロセスを担うため、拡散システムにおいて最も重要なコンポーネントの一つです。🤗 Diffusers には、次元数や条件付きモデルかどうかによっていくつかの UNet モデルのバリアントが存在します。ここでは、2D の条件付き UNet モデルについて説明します。

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

*深層ネットワークの成功した学習には、数千枚のラベル付き訓練サンプルが必要であるという点について、大きな合意がある。本論文では、データ拡張を強力に活用することで、利用可能なラベル付きサンプルをより効率的に使用できるネットワークと学習戦略を提案する。このアーキテクチャは、コンテキストを捉えるための縮小パスと、正確な位置特定を可能にする対称的な拡大パスで構成される。このようなネットワークは、非常に少ない画像からエンドツーエンドで学習でき、電子顕微鏡スタックにおける神経構造のセグメンテーションに関するISBIチャレンジにおいて、従来の最良手法（スライディングウィンドウ畳み込みネットワーク）を上回ることを示す。透過光顕微鏡画像（位相差およびDIC）で学習した同じネットワークを用いて、ISBIセルトラッキングチャレンジ2015では、これらのカテゴリで大幅な差をつけて優勝した。さらに、このネットワークは高速である。最新のGPUでは、512x512画像のセグメンテーションに1秒未満しかかからない。完全な実装（Caffeベース）と学習済みネットワークは、http://lmb.informatik.uni-freiburg.de/people/ronneber/u-net で入手できる。*

## UNet2DConditionModel[[diffusers.UNet2DConditionModel]]

#### diffusers.UNet2DConditionModel[[diffusers.UNet2DConditionModel]]

```python
diffusers.UNet2DConditionModel(sample_size: int | tuple[int, int] | None = None, in_channels: int = 4, out_channels: int = 4, center_input_sample: bool = False, 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', up_block_types: tuple[str, ...] = ('UpBlock2D', 'CrossAttnUpBlock2D', 'CrossAttnUpBlock2D', 'CrossAttnUpBlock2D'), only_cross_attention: bool | tuple[bool] = False, block_out_channels: tuple[int, ...] = (320, 640, 1280, 1280), layers_per_block: int | tuple[int] = 2, downsample_padding: int = 1, mid_block_scale_factor: float = 1, dropout: float = 0.0, act_fn: str = 'silu', norm_num_groups: int | None = 32, norm_eps: float = 1e-05, cross_attention_dim: int | tuple[int] = 1280, transformer_layers_per_block: int | tuple[int] | tuple[tuple] = 1, reverse_transformer_layers_per_block: tuple[tuple[int]] | None = None, 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, dual_cross_attention: bool = False, 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', resnet_skip_time_act: bool = False, resnet_out_scale_factor: float = 1.0, time_embedding_type: str = 'positional', time_embedding_dim: int | None = None, time_embedding_act_fn: str | None = None, timestep_post_act: str | None = None, time_cond_proj_dim: int | None = None, conv_in_kernel: int = 3, conv_out_kernel: int = 3, projection_class_embeddings_input_dim: int | None = None, attention_type: str = 'default', class_embeddings_concat: bool = False, mid_block_only_cross_attention: bool | None = None, cross_attention_norm: str | None = None, addition_embed_type_num_heads: int = 64)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/unets/unet_2d_condition.py#L76)

**パラメータ:**

sample_size (`int` または `tuple[int, int]`、*省略可能*、デフォルトは `None`) : 入力/出力サンプルの高さと幅。
in_channels (`int`、*任意*、デフォルトは 4) : 入力サンプルのチャネル数。

out_channels (`int`、*任意*、デフォルトは 4) : 出力のチャネル数。
center_input_sample (`bool`、*任意*、デフォルトは`False`) : 入力サンプルを中央揃けにするかどうか。
flip_sin_to_cos (`bool`、*任意*、デフォルトは`True`) : 時間埋め込みにおいて sin を cos に反転させるかどうか。

freq_shift (`int`、*optional*、デフォルトは 0) : 時間埋め込みに適用する周波数シフト。
down_block_types (`tuple[str]`、*任意*、デフォルトは`("CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "CrossAttnDownBlock2D", "DownBlock2D")`) : 使用するダウンサンプルブロックのタプルです。
mid_block_type (`str`、*任意*、デフォルトは `"UNetMidBlock2DCrossAttn"`) : UNet の中央部分のブロックタイプです。`UNetMidBlock2DCrossAttn`、`UNetMidBlock2D`、または `UNetMidBlock2DSimpleCrossAttn` のいずれかになります。`None` の場合、中央ブロックのレイヤーはスキップされます。
up_block_types (`tuple[str]`、*optional*、デフォルトは`("UpBlock2D", "CrossAttnUpBlock2D", "CrossAttnUpBlock2D", "CrossAttnUpBlock2D")`) : 使用するアップサンプルブロックのタプル。
only_cross_attention(`bool`または`tuple[bool]`、*省略可*、デフォルトは`False`) : 基本的なtransformerブロックにself-attentionを含めるかどうか。詳細は`BasicTransformerBlock`を参照してください。
block_out_channels (`tuple[int]`、*optional*、デフォルトは`(320, 640, 1280, 1280)`) : 各ブロックの出力チャネル数を表すタプルです。
layers_per_block (`int`、*任意*、デフォルトは 2) : ブロックあたりのレイヤー数。
downsample_padding (`int`、*optional*、デフォルトは 1) : ダウンサンプリング畳み込みに使用するパディング。

mid_block_scale_factor (`float`、*任意*、デフォルトは 1.0) : mid block に使用するスケール係数。
dropout (`float`、*任意*、デフォルトは 0.0) : 使用する dropout の確率。
act_fn (`str`、*任意*、デフォルトは`"silu"`) : 使用する活性化関数。

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

norm_eps (`float`、*任意*、デフォルトは 1e-5) : 正規化に使用する epsilon。
cross_attention_dim (`int` または `tuple[int]`、*省略可能*、デフォルトは 1280) : クロスアテンション特徴量の次元数。
transformer_layers_per_block (`int`、`tuple[int]`、または `tuple[tuple]`、*省略可能*、デフォルトは 1) : `BasicTransformerBlock` 型の Transformer ブロックの数。`CrossAttnDownBlock2D`、`CrossAttnUpBlock2D`、`UNetMidBlock2DCrossAttn` の場合にのみ関連します。

reverse_transformer_layers_per_block : (`tuple[tuple]`、*任意*、デフォルトは None): U-Net のアップサンプリングブロックにおける `BasicTransformerBlock` 型の Transformer ブロックの数。`transformer_layers_per_block` が `tuple[tuple]` 型であり、`CrossAttnDownBlock2D`、`CrossAttnUpBlock2D`、`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`、*任意*、デフォルトは 8) : アテンションヘッドの次元数。
num_attention_heads (`int`, *任意*) : アテンションヘッドの数。定義されていない場合、デフォルトで`attention_head_dim`になります。
resnet_time_scale_shift (`str`、*任意*、デフォルトは `"default"`) : ResNet ブロック用の時間スケールシフト設定（`ResnetBlock2D` を参照）。`default` または `scale_shift` から選択します。

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

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

addition_time_embed_dim : (`int`, *任意*、デフォルトは `None`): タイムステップ埋め込みの次元数。
num_class_embeds (`int`、*任意*、デフォルトは `None`) : `class_embed_type` が `None` の場合にクラス条件付けを行う際、学習可能な埋め込み行列の入力次元であり、`time_embed_dim` に射影されます。
time_embedding_type (`str`、*任意*、デフォルトは`positional`) : タイムステップに使用する位置埋め込みの種類。`positional`または`fourier`から選択します。
time_embedding_dim (`int`、*任意*、デフォルトは`None`) : 投影された時間埋め込みの次元をオーバーライドするための任意の引数です。
time_embedding_act_fn (`str`、*任意*、デフォルトは`None`) : UNetの残りの部分に渡す前に、時間埋め込みに一度だけ適用する任意の活性化関数。`silu`、`mish`、`gelu`、`swish`から選択できます。

timestep_post_act (`str`、*任意*、デフォルトは `None`) : タイムステップ埋め込みで使用する第2の活性化関数。`silu`、`mish`、`gelu` から選択してください。

time_cond_proj_dim (`int`、*任意*、デフォルトは`None`) : 時間ステップ埋め込みにおける`cond_proj`レイヤーの次元数。

conv_in_kernel (`int`、*optional*、デフォルトは`3`) : `conv_in`層のカーネルサイズです。

conv_out_kernel (`int`、*任意*、デフォルトは`3`) : `conv_out`層のカーネルサイズ。

projection_class_embeddings_input_dim (`int`, *任意*) : `class_embed_type="projection"` の場合の `class_labels` 入力の次元。`class_embed_type="projection"` の場合に必須です。

class_embeddings_concat (`bool`、*任意*、デフォルトは`False`) : 時間埋め込みをクラス埋め込みと連結するかどうか。

mid_block_only_cross_attention (`bool`、*任意*、デフォルトは `None`) : `UNetMidBlock2DSimpleCrossAttn` を使用する場合に、mid block でクロスアテンションを使用するかどうか。`only_cross_attention` が単一のブール値として指定され、`mid_block_only_cross_attention` が `None` の場合、`only_cross_attention` の値が `mid_block_only_cross_attention` の値として使用されます。それ以外の場合はデフォルトで `False` になります。

ノイズ付きサンプル、条件付き状態、およびタイムステップを受け取り、サンプル形状の出力を返す条件付き2D UNetモデル。

このモデルは [ModelMixin](/docs/diffusers/main/ja/api/models/overview#diffusers.ModelMixin) を継承しています。すべてのモデルに実装されている汎用的なメソッド（ダウンロードや保存など）については、スーパークラスのドキュメントを参照してください。

#### disable_freeu[[diffusers.UNet2DConditionModel.disable_freeu]]

```python
disable_freeu()
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/unets/unet_2d_condition.py#L814)

FreeUメカニズムを無効にします。

#### enable_freeu[[diffusers.UNet2DConditionModel.enable_freeu]]

```python
enable_freeu(s1: float, s2: float, b1: float, b2: float)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/unets/unet_2d_condition.py#L790)

**パラメータ:**

s1 (`float`) : ステージ1におけるスキップ特徴の寄与を減衰させるためのスケーリング係数です。これは、強化されたノイズ除去プロセスにおける「過剰平滑化効果」を緩和するために使用されます。

s2 (`float`) : ステージ2におけるスキップ特徴の寄与を減衰させるためのスケーリング係数です。これは、強化されたノイズ除去プロセスにおける「過剰平滑化効果」を緩和するために使用されます。

b1 (`float`) : ステージ1のスケール係数。バックボーン特徴の寄与を強調するために使用します。

b2 (`float`) : ステージ2のスケール係数。バックボーン特徴の寄与を強調するために使用します。

https://huggingface.co/papers/2309.11497 の FreeU メカニズムを有効にします。

スケーリング係数の後ろの接尾辞は、それらが適用されるステージブロックを表しています。

Stable Diffusion v1、v2、Stable Diffusion XL などの異なるパイプラインで良好に動作することが知られている値の組み合わせについては、[公式リポジトリ](https://github.com/ChenyangSi/FreeU)を参照してください。

#### forward[[diffusers.UNet2DConditionModel.forward]]

```python
forward(sample: Tensor, timestep: typing.Union[torch.Tensor, float, int], encoder_hidden_states: Tensor, class_labels: typing.Optional[torch.Tensor] = None, timestep_cond: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, cross_attention_kwargs: dict[str, typing.Any] | None = None, added_cond_kwargs: dict[str, torch.Tensor] | None = None, down_block_additional_residuals: tuple[torch.Tensor] | None = None, mid_block_additional_residual: typing.Optional[torch.Tensor] = None, down_intrablock_additional_residuals: tuple[torch.Tensor] | None = None, encoder_attention_mask: typing.Optional[torch.Tensor] = None, return_dict: bool = True)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/unets/unet_2d_condition.py#L978)

**パラメータ:**

sample (`torch.Tensor`) : 以下の形状 `(batch, channel, height, width)` を持つノイズ付き入力テンソル。

timestep (`torch.Tensor` または `float` または `int`) : 入力からノイズを除去するためのタイムステップ数。

encoder_hidden_states (`torch.Tensor`) : 形状が `(batch, sequence_length, feature_dim)` のエンコーダーの隠れ状態。

class_labels (`torch.Tensor`、*任意*、デフォルトは`None`) : 条件付け用の任意のクラスラベル。その埋め込みは、タイムステップの埋め込みと加算されます。
timestep_cond : (`torch.Tensor`、*任意*、デフォルトは`None`): タイムステップ用の条件埋め込み。指定された場合、これらの埋め込みは`self.time_embedding`層を通過したサンプルに足し合わされ、タイムステップ埋め込みが得られます。

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

cross_attention_kwargs (`dict`, *任意*) : 指定された場合、[diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py) の `self.processor` で定義されている `AttentionProcessor` に渡される kwargs の辞書です。

added_cond_kwargs : (`dict`, *任意*): 追加の埋め込みを含む kwargs 辞書。指定された場合、UNet ブロックに渡される埋め込みに追加されます。

down_block_additional_residuals : (`tuple` of `torch.Tensor`, *任意*): 指定された場合、ダウンブロックの残差に追加されるテンソルのタプル。
mid_block_additional_residual : (`torch.Tensor`, *任意*): 指定された場合、中央の unet ブロックの残差に追加されるテンソル。

down_intrablock_additional_residuals (`tuple` of `torch.Tensor`, *任意*) : UNet のダウンブロック内で追加される追加の残差。例えば、T2I-Adapter のサイドモデルからのものである
encoder_attention_mask (`torch.Tensor`) : `encoder_hidden_states` に、`(batch, sequence_length)` の形状を持つクロスアテンションマスクが適用されます。`True` の場合はマスクが保持され、`False` の場合は破棄されます。マスクはバイアスに変換され、「破棄」対象のトークンに対応するアテンションスコアに大きな負の値が加算されます。

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

[UNet2DConditionModel](/docs/diffusers/main/ja/api/models/unet2d-cond#diffusers.UNet2DConditionModel)のforwardメソッドです。

#### fuse_qkv_projections[[diffusers.UNet2DConditionModel.fuse_qkv_projections]]

```python
fuse_qkv_projections()
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/unets/unet_2d_condition.py#L822)

融合されたQKV投影を有効にします。自己注意（self-attention）モジュールでは、すべての投影行列（つまり、クエリ、キー、バリュー）が融合されます。相互注意（cross-attention）モジュールでは、キーとバリューの投影行列が融合されます。

> [!WARNING] > このAPIは🧪実験的です。

#### set_attention_slice[[diffusers.UNet2DConditionModel.set_attention_slice]]

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

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/unets/unet_2d_condition.py#L725)

**パラメータ:**

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.UNet2DConditionModel.set_default_attn_processor]]
```python
set_default_attn_processor()
```
[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/unets/unet_2d_condition.py#L710)
カスタムアテンションプロセッサを無効にし、デフォルトのアテンション実装を設定します。
#### unfuse_qkv_projections[[diffusers.UNet2DConditionModel.unfuse_qkv_projections]]
```python
unfuse_qkv_projections()
```
[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/unets/unet_2d_condition.py#L843)
有効化されている場合、融合された QKV 投影を無効にします。
> [!WARNING] > このAPIは🧪実験的です。
## UNet2DConditionOutput[[diffusers.models.unets.unet_2d_condition.UNet2DConditionOutput]]
#### diffusers.models.unets.unet_2d_condition.UNet2DConditionOutput[[diffusers.models.unets.unet_2d_condition.UNet2DConditionOutput]]
```python
diffusers.models.unets.unet_2d_condition.UNet2DConditionOutput(sample: Tensor = None)
```
[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/unets/unet_2d_condition.py#L64)
**パラメータ:**
sample (`torch.Tensor`、形状 `(batch_size, num_channels, height, width)`) : `encoder_hidden_states` 入力を条件として出力される隠れ状態。モデルの最終層の出力です。
[UNet2DConditionModel](/docs/diffusers/main/ja/api/models/unet2d-cond#diffusers.UNet2DConditionModel)の出力です。
Xet Storage Details

Size:: 22.2 kB
Xet hash:: 7ca80f4314420bfcd544ae625f4bc35b5e944f3ec5202100a2651fa147dd418e
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.