diffusers/main/ja/api/models/unet3d-cond.md

UNet3DConditionModel

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

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

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

UNet3DConditionModel[[diffusers.UNet3DConditionModel]]

diffusers.UNet3DConditionModel[[diffusers.UNet3DConditionModel]]

diffusers.UNet3DConditionModel(sample_size: int | None = None, in_channels: int = 4, out_channels: int = 4, down_block_types: tuple[str, ...] = ('CrossAttnDownBlock3D', 'CrossAttnDownBlock3D', 'CrossAttnDownBlock3D', 'DownBlock3D'), up_block_types: tuple[str, ...] = ('UpBlock3D', 'CrossAttnUpBlock3D', 'CrossAttnUpBlock3D', 'CrossAttnUpBlock3D'), 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 = 1024, attention_head_dim: int | tuple[int] = 64, num_attention_heads: int | tuple[int] | None = None, time_cond_proj_dim: int | None = None)

ソース

パラメータ:

sample_size (int または tuple[int, int]、省略可能、デフォルトは None) : 入力/出力サンプルの高さと幅。

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

out_channels (int、任意、デフォルトは 4) : 出力のチャネル数。

down_block_types (tuple[str]、任意、デフォルトは("CrossAttnDownBlock3D", "CrossAttnDownBlock3D", "CrossAttnDownBlock3D", "DownBlock3D")) : 使用するダウンサンプルブロックのタプル。

up_block_types (tuple[str], optional, デフォルトは ("UpBlock3D", "CrossAttnUpBlock3D", "CrossAttnUpBlock3D", "CrossAttnUpBlock3D")) : 使用するアップサンプルブロックのタプルです。

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

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

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

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

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

attention_head_dim (int、任意、デフォルトは 64) : アテンションヘッドの次元数。

num_attention_heads (int, 任意) : アテンションヘッドの数。

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

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

このモデルは ModelMixin を継承しています。すべてのモデルに実装されている汎用的なメソッド（ダウンロードや保存など）については、スーパークラスのドキュメントを参照してください。

disable_freeu[[diffusers.UNet3DConditionModel.disable_freeu]]

disable_freeu()

ソース

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

enable_forward_chunking[[diffusers.UNet3DConditionModel.enable_forward_chunking]]

enable_forward_chunking(chunk_size: int | None = None, dim: int = 0)

ソース

パラメータ:

chunk_size (int, optional) : フィードフォワード層のチャンクサイズ。指定しない場合、dim次元の各テンソルに対してフィードフォワード層を個別に実行します。

dim (int、optional、デフォルトは0) : フィードフォワード計算をチャンク分割する次元です。dim=0（バッチ）またはdim=1（シーケンス長）のいずれかを選択します。

フィードフォワードチャンク分割を使用するようにアテンションプロセッサを設定します。

enable_freeu[[diffusers.UNet3DConditionModel.enable_freeu]]

enable_freeu(s1, s2, b1, b2)

ソース

パラメータ:

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 などの異なるパイプラインで良好に動作することが知られている値の組み合わせについては、公式リポジトリを参照してください。

forward[[diffusers.UNet3DConditionModel.forward]]

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, down_block_additional_residuals: tuple[torch.Tensor] | None = None, mid_block_additional_residual: typing.Optional[torch.Tensor] = None, return_dict: bool = True)

ソース

パラメータ:

sample (torch.Tensor) : 以下の形状 (batch, num_channels, num_frames, 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 の self.processor で定義されている AttentionProcessor に渡される kwargs の辞書です。

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

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

return_dict (bool、任意、デフォルトはTrue) : プレーンなタプルではなく、UNet3DConditionOutputを返すかどうか。

cross_attention_kwargs (dict, 任意) : 指定された場合、AttnProcessor に渡される kwargs の辞書です。

戻り値: UNet3DConditionOutput または tuple

return_dict が True の場合、UNet3DConditionOutput が返され、それ以外の場合は、最初の要素がサンプルテンソルである tuple が返されます。

UNet3DConditionModelのforwardメソッドです。

fuse_qkv_projections[[diffusers.UNet3DConditionModel.fuse_qkv_projections]]

fuse_qkv_projections()

ソース

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

> このAPIは🧪実験的です。

set_attention_slice[[diffusers.UNet3DConditionModel.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.UNet3DConditionModel.set_default_attn_processor]]

set_default_attn_processor()

ソース

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

unfuse_qkv_projections[[diffusers.UNet3DConditionModel.unfuse_qkv_projections]]

unfuse_qkv_projections()

ソース

有効化されている場合、融合された QKV 投影を無効にします。

> このAPIは🧪実験的です。

UNet3DConditionOutput[[diffusers.models.unets.unet_3d_condition.UNet3DConditionOutput]]

diffusers.models.unets.unet_3d_condition.UNet3DConditionOutput[[diffusers.models.unets.unet_3d_condition.UNet3DConditionOutput]]

diffusers.models.unets.unet_3d_condition.UNet3DConditionOutput(sample: Tensor)

ソース

パラメータ:

sample (torch.Tensor、shape (batch_size, num_channels, num_frames, height, width)) : encoder_hidden_states 入力で条件付けられた隠れ状態の出力。モデルの最終層の出力です。

UNet3DConditionModelの出力です。