# HunyuanDiT2DControlNetModel

HunyuanDiT2DControlNetModel は、[Hunyuan-DiT](https://huggingface.co/papers/2405.08748) 用の ControlNet の実装です。

ControlNetは、Lvmin Zhang、Anyi Rao、Maneesh Agrawalaによる論文[Adding Conditional Control to Text-to-Image Diffusion Models](https://huggingface.co/papers/2302.05543)で提案されました。

ControlNetモデルを使用すると、追加の制御画像を指定してHunyuan-DiTの生成を条件付け・制御できます。例えば、深度マップを指定すると、ControlNetモデルは深度マップの空間情報を保持した画像を生成します。これは、画像生成プロセスをより柔軟かつ正確に制御する方法です。

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

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

このコードは Tencent Hunyuan Team によって実装されています。Hunyuan-DiT ControlNets の事前学習済みチェックポイントは [Tencent Hunyuan](https://huggingface.co/Tencent-Hunyuan) で入手できます。

## HunyuanDiT2DControlNetModel を読み込む例

```py
from diffusers import HunyuanDiT2DControlNetModel
import torch
controlnet = HunyuanDiT2DControlNetModel.from_pretrained("Tencent-Hunyuan/HunyuanDiT-v1.1-ControlNet-Diffusers-Pose", dtype=torch.float16)
```

## HunyuanDiT2DControlNetModel[[diffusers.HunyuanDiT2DControlNetModel]]

#### diffusers.HunyuanDiT2DControlNetModel[[diffusers.HunyuanDiT2DControlNetModel]]

```python
diffusers.HunyuanDiT2DControlNetModel(conditioning_channels: int = 3, num_attention_heads: int = 16, attention_head_dim: int = 88, in_channels: int | None = None, patch_size: int | None = None, activation_fn: str = 'gelu-approximate', sample_size = 32, hidden_size = 1152, transformer_num_layers: int = 40, mlp_ratio: float = 4.0, cross_attention_dim: int = 1024, cross_attention_dim_t5: int = 2048, pooled_projection_dim: int = 1024, text_len: int = 77, text_len_t5: int = 256, use_style_cond_and_image_meta_size: bool = True)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/controlnets/controlnet_hunyuan.py#L40)

#### forward[[diffusers.HunyuanDiT2DControlNetModel.forward]]

```python
forward(hidden_states, timestep, controlnet_cond: Tensor, conditioning_scale: float = 1.0, encoder_hidden_states = None, text_embedding_mask = None, encoder_hidden_states_t5 = None, text_embedding_mask_t5 = None, image_meta_size = None, style = None, image_rotary_emb = None, return_dict = True)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/controlnets/controlnet_hunyuan.py#L215)

**パラメータ:**

hidden_states (`torch.Tensor`、形状 `(batch size, dim, height, width)`) : 入力テンソル。

timestep ( `torch.LongTensor`, *任意*) : デノイジングステップを示すために使用します。

controlnet_cond ( `torch.Tensor` ) : ControlNet への条件付け入力。

conditioning_scale ( `float` ) : 条件付けのスケールを指定します。

encoder_hidden_states ( `torch.Tensor`、形状 `(batch size, sequence len, embed dims)`、*任意*) : クロスアテンション層用の条件付きエンベディングです。これは `BertModel` の出力です。

text_embedding_mask : torch.Tensor `(batch, key_tokens)` の形状を持つアテンションマスクが `encoder_hidden_states` に適用されます。これは `BertModel` の出力です。

encoder_hidden_states_t5 ( `torch.Tensor`、形状 `(batch size, sequence len, embed dims)`、*任意*) : クロスアテンション層用の条件付き埋め込み。これは T5 Text Encoder の出力です。

text_embedding_mask_t5 : torch.Tensor `(batch, key_tokens)` の形状を持つアテンションマスクが `encoder_hidden_states` に適用されます。これは T5 Text Encoder の出力です。

image_meta_size (torch.Tensor) : 画像サイズを示す条件埋め込み

style : torch.Tensor: スタイルを示す条件埋め込み

image_rotary_emb (`torch.Tensor`) : 注意機構の計算時にクエリとキーのテンソルに適用する画像ロータリー埋め込み。

return_dict : bool 辞書を返すかどうか。

**戻り値:**

`return_dict`がTrueの場合、`HunyuanControlNetOutput`が返され、それ以外の場合は、最初の要素がControlNetブロックのサンプルのリストである`tuple`が返されます。

[HunyuanDiT2DControlNetModel](/docs/diffusers/main/ja/api/models/controlnet_hunyuandit#diffusers.HunyuanDiT2DControlNetModel)のforwardメソッドです。

#### set_attn_processor[[diffusers.HunyuanDiT2DControlNetModel.set_attn_processor]]

```python
set_attn_processor(processor: diffusers.models.attention_processor.AttnProcessor | diffusers.models.attention_processor.CustomDiffusionAttnProcessor | diffusers.models.attention_processor.AttnAddedKVProcessor | diffusers.models.attention_processor.AttnAddedKVProcessor2_0 | diffusers.models.attention_processor.JointAttnProcessor2_0 | diffusers.models.attention_processor.PAGJointAttnProcessor2_0 | diffusers.models.attention_processor.PAGCFGJointAttnProcessor2_0 | diffusers.models.attention_processor.FusedJointAttnProcessor2_0 | diffusers.models.attention_processor.AllegroAttnProcessor2_0 | diffusers.models.attention_processor.AuraFlowAttnProcessor2_0 | diffusers.models.attention_processor.FusedAuraFlowAttnProcessor2_0 | diffusers.models.attention_processor.FluxAttnProcessor2_0 | diffusers.models.attention_processor.FluxAttnProcessor2_0_NPU | diffusers.models.attention_processor.FusedFluxAttnProcessor2_0 | diffusers.models.attention_processor.FusedFluxAttnProcessor2_0_NPU | diffusers.models.attention_processor.CogVideoXAttnProcessor2_0 | diffusers.models.attention_processor.FusedCogVideoXAttnProcessor2_0 | diffusers.models.attention_processor.XFormersAttnAddedKVProcessor | diffusers.models.attention_processor.XFormersAttnProcessor | diffusers.models.attention_processor.XLAFlashAttnProcessor2_0 | diffusers.models.attention_processor.AttnProcessorNPU | diffusers.models.attention_processor.AttnProcessor2_0 | diffusers.models.attention_processor.MochiVaeAttnProcessor2_0 | diffusers.models.attention_processor.MochiAttnProcessor2_0 | diffusers.models.attention_processor.StableAudioAttnProcessor2_0 | diffusers.models.attention_processor.HunyuanAttnProcessor2_0 | diffusers.models.attention_processor.FusedHunyuanAttnProcessor2_0 | diffusers.models.attention_processor.PAGHunyuanAttnProcessor2_0 | diffusers.models.attention_processor.PAGCFGHunyuanAttnProcessor2_0 | diffusers.models.attention_processor.LuminaAttnProcessor2_0 | diffusers.models.attention_processor.FusedAttnProcessor2_0 | diffusers.models.attention_processor.CustomDiffusionXFormersAttnProcessor | diffusers.models.attention_processor.CustomDiffusionAttnProcessor2_0 | diffusers.models.attention_processor.SlicedAttnProcessor | diffusers.models.attention_processor.SlicedAttnAddedKVProcessor | diffusers.models.attention_processor.SanaLinearAttnProcessor2_0 | diffusers.models.attention_processor.PAGCFGSanaLinearAttnProcessor2_0 | diffusers.models.attention_processor.PAGIdentitySanaLinearAttnProcessor2_0 | diffusers.models.attention_processor.SanaMultiscaleLinearAttention | diffusers.models.attention_processor.SanaMultiscaleAttnProcessor2_0 | diffusers.models.attention_processor.SanaMultiscaleAttentionProjection | diffusers.models.attention_processor.IPAdapterAttnProcessor | diffusers.models.attention_processor.IPAdapterAttnProcessor2_0 | diffusers.models.attention_processor.IPAdapterXFormersAttnProcessor | diffusers.models.attention_processor.SD3IPAdapterJointAttnProcessor2_0 | diffusers.models.attention_processor.PAGIdentitySelfAttnProcessor2_0 | diffusers.models.attention_processor.PAGCFGIdentitySelfAttnProcessor2_0 | diffusers.models.attention_processor.LoRAAttnProcessor | diffusers.models.attention_processor.LoRAAttnProcessor2_0 | diffusers.models.attention_processor.LoRAXFormersAttnProcessor | diffusers.models.attention_processor.LoRAAttnAddedKVProcessor | dict[str, diffusers.models.attention_processor.AttnProcessor | diffusers.models.attention_processor.CustomDiffusionAttnProcessor | diffusers.models.attention_processor.AttnAddedKVProcessor | diffusers.models.attention_processor.AttnAddedKVProcessor2_0 | diffusers.models.attention_processor.JointAttnProcessor2_0 | diffusers.models.attention_processor.PAGJointAttnProcessor2_0 | diffusers.models.attention_processor.PAGCFGJointAttnProcessor2_0 | diffusers.models.attention_processor.FusedJointAttnProcessor2_0 | diffusers.models.attention_processor.AllegroAttnProcessor2_0 | diffusers.models.attention_processor.AuraFlowAttnProcessor2_0 | diffusers.models.attention_processor.FusedAuraFlowAttnProcessor2_0 | diffusers.models.attention_processor.FluxAttnProcessor2_0 | diffusers.models.attention_processor.FluxAttnProcessor2_0_NPU | diffusers.models.attention_processor.FusedFluxAttnProcessor2_0 | diffusers.models.attention_processor.FusedFluxAttnProcessor2_0_NPU | diffusers.models.attention_processor.CogVideoXAttnProcessor2_0 | diffusers.models.attention_processor.FusedCogVideoXAttnProcessor2_0 | diffusers.models.attention_processor.XFormersAttnAddedKVProcessor | diffusers.models.attention_processor.XFormersAttnProcessor | diffusers.models.attention_processor.XLAFlashAttnProcessor2_0 | diffusers.models.attention_processor.AttnProcessorNPU | diffusers.models.attention_processor.AttnProcessor2_0 | diffusers.models.attention_processor.MochiVaeAttnProcessor2_0 | diffusers.models.attention_processor.MochiAttnProcessor2_0 | diffusers.models.attention_processor.StableAudioAttnProcessor2_0 | diffusers.models.attention_processor.HunyuanAttnProcessor2_0 | diffusers.models.attention_processor.FusedHunyuanAttnProcessor2_0 | diffusers.models.attention_processor.PAGHunyuanAttnProcessor2_0 | diffusers.models.attention_processor.PAGCFGHunyuanAttnProcessor2_0 | diffusers.models.attention_processor.LuminaAttnProcessor2_0 | diffusers.models.attention_processor.FusedAttnProcessor2_0 | diffusers.models.attention_processor.CustomDiffusionXFormersAttnProcessor | diffusers.models.attention_processor.CustomDiffusionAttnProcessor2_0 | diffusers.models.attention_processor.SlicedAttnProcessor | diffusers.models.attention_processor.SlicedAttnAddedKVProcessor | diffusers.models.attention_processor.SanaLinearAttnProcessor2_0 | diffusers.models.attention_processor.PAGCFGSanaLinearAttnProcessor2_0 | diffusers.models.attention_processor.PAGIdentitySanaLinearAttnProcessor2_0 | diffusers.models.attention_processor.SanaMultiscaleLinearAttention | diffusers.models.attention_processor.SanaMultiscaleAttnProcessor2_0 | diffusers.models.attention_processor.SanaMultiscaleAttentionProjection | diffusers.models.attention_processor.IPAdapterAttnProcessor | diffusers.models.attention_processor.IPAdapterAttnProcessor2_0 | diffusers.models.attention_processor.IPAdapterXFormersAttnProcessor | diffusers.models.attention_processor.SD3IPAdapterJointAttnProcessor2_0 | diffusers.models.attention_processor.PAGIdentitySelfAttnProcessor2_0 | diffusers.models.attention_processor.PAGCFGIdentitySelfAttnProcessor2_0 | diffusers.models.attention_processor.LoRAAttnProcessor | diffusers.models.attention_processor.LoRAAttnProcessor2_0 | diffusers.models.attention_processor.LoRAXFormersAttnProcessor | diffusers.models.attention_processor.LoRAAttnAddedKVProcessor])
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/controlnets/controlnet_hunyuan.py#L141)

**パラメータ:**

processor (`dict` of `AttentionProcessor` or only `AttentionProcessor`) : `Attention`レイヤーのすべてに**すべて**プロセッサーとして設定される、インスタンス化されたプロセッサークラス、またはプロセッサークラスの辞書です。`processor`が辞書の 경우、キーは対応するクロスアテンションプロセッサーへのパスを定義する必要があります。学習可能なアテンションプロセッサーを設定する場合は、この方法が強く推奨されます。

アテンションの計算に使用するアテンションプロセッサを設定します。