# CosmosTransformer3DModel

NVIDIAによる[Cosmos World Foundation Model Platform for Physical AI](https://huggingface.co/papers/2501.03575)では、3Dの動画のようなデータ向けのDiffusion Transformerモデルが紹介されました。

モデルは、以下のコードスニペットで読み込むことができます。

```python
from diffusers import CosmosTransformer3DModel

transformer = CosmosTransformer3DModel.from_pretrained("nvidia/Cosmos-1.0-Diffusion-7B-Text2World", subfolder="transformer", dtype=torch.bfloat16)
```

## CosmosTransformer3DModel[[diffusers.CosmosTransformer3DModel]]

#### diffusers.CosmosTransformer3DModel[[diffusers.CosmosTransformer3DModel]]

```python
diffusers.CosmosTransformer3DModel(in_channels: int = 16, out_channels: int = 16, num_attention_heads: int = 32, attention_head_dim: int = 128, num_layers: int = 28, mlp_ratio: float = 4.0, text_embed_dim: int = 1024, adaln_lora_dim: int = 256, max_size: tuple[int, int, int] = (128, 240, 240), patch_size: tuple[int, int, int] = (1, 2, 2), rope_scale: tuple[float, float, float] = (2.0, 1.0, 1.0), concat_padding_mask: bool = True, extra_pos_embed_type: str | None = 'learnable', use_crossattn_projection: bool = False, crossattn_proj_in_channels: int = 1024, encoder_hidden_states_channels: int = 1024, controlnet_block_every_n: int | None = None, img_context_dim_in: int | None = None, img_context_num_tokens: int = 256, img_context_dim_out: int = 2048)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_cosmos.py#L554)

**パラメータ:**

in_channels (`int`、デフォルトは`16`) : 入力におけるチャネル数。

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

num_attention_heads (`int`、デフォルトは`32`) : マルチヘッドアテンションで使用するヘッド数。

attention_head_dim (`int`、デフォルトは`128`) : 各アテンションヘッドのチャネル数。

num_layers (`int`、デフォルトは`28`) : 使用するtransformerブロックの層数。

mlp_ratio (`float`、デフォルトは`4.0`) : フィードフォワードネットワークにおける、隠れ層サイズと入力サイズの比率。

text_embed_dim (`int`、デフォルトは`4096`) : テキストエンコーダーからのテキスト埋め込みの入力次元数。

adaln_lora_dim (`int`、デフォルトは`256`) : Adaptive LayerNorm LoRA 層の隠れ次元です。

max_size (`tuple[int, int, int]`、デフォルトは`(128, 240, 240)`) : 入力潜在テンソルの時間軸、高さ、幅の各次元における最大サイズ。

patch_size (`tuple[int, int, int]`、デフォルトは`(1, 2, 2)`) : 時間、高さ、幅の各次元で、入力潜在テンソルをパッチ化するために使用するパッチサイズ。

rope_scale (`tuple[float, float, float]`、デフォルトは`(2.0, 1.0, 1.0)`) : RoPEの時間、高さ、幅の各次元に使用するスケーリング係数。

concat_padding_mask (`bool`、デフォルトは`True`) : パディングマスクを入力潜在テンソルに連結するかどうか。

extra_pos_embed_type (`str`、*任意*、デフォルトは`learnable`) : 使用する追加の位置埋め込みの種類。`None`または`learnable`のいずれかです。

controlnet_block_every_n (`int`, *optional*) : 制御残差を適用すべき Transformer ブロックの間隔（例：`7` を指定すると、7 個目のブロックごとに注入されます）。Cosmos Transfer2.5 では必須です。

img_context_dim_in (`int`、*任意*) : 入力画像コンテキスト特徴量ベクトルの次元、つまり [B, N, D] の D です。

img_context_num_tokens (`int`) : 画像コンテキスト特徴ベクトルに含まれるトークン数、つまり [B, N, D] の N です。`img_context_dim_in` が指定されていない場合、このパラメータは無視されます。

img_context_dim_out (`int`) : 画像コンテキスト投影層の出力次元。`img_context_dim_in` が指定されていない場合、このパラメータは無視されます。

[Cosmos](https://github.com/NVIDIA/Cosmos)で使用される、動画のようなデータ向けのTransformerモデル。

#### forward[[diffusers.CosmosTransformer3DModel.forward]]

```python
forward(hidden_states: Tensor, timestep: Tensor, encoder_hidden_states: Tensor, block_controlnet_hidden_states: list[torch.Tensor] | None = None, attention_mask: typing.Optional[torch.Tensor] = None, fps: int | None = None, condition_mask: typing.Optional[torch.Tensor] = None, padding_mask: typing.Optional[torch.Tensor] = None, return_dict: bool = True)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/transformer_cosmos.py#L688)

**パラメータ:**

hidden_states (`torch.Tensor`、形状 `(batch_size, num_channels, num_frames, height, width)`) : 入力 `hidden_states`。

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

encoder_hidden_states (`torch.Tensor`、shape `(batch_size, sequence_len, embed_dims)`) : 使用する条件埋め込み（プロンプトなどの入力条件から計算される埋め込み）。

block_controlnet_hidden_states (`list` of `torch.Tensor`, *optional*) : 指定された場合、transformer ブロックの残差に追加されるテンソルのリスト。

attention_mask (`torch.Tensor`, *任意*) : 注意機構において`encoder_hidden_states`に適用されるマスク。

fps (`int`, *optional*) : 回転位置埋め込みを計算するために使用される入力動画の秒あたりのフレーム数。

condition_mask (`torch.Tensor`, *任意*) : 条件付け領域を示すために`hidden_states`に連結されるマスクチャネル。

padding_mask (`torch.Tensor`, *任意*) : `concat_padding_mask` が有効な場合、`hidden_states` に連結されるパディングマスク。

return_dict (`bool`、*任意*、デフォルトは`True`) : プレーンなタプルではなく`~models.transformer_2d.Transformer2DModelOutput`を返すかどうか。

**戻り値:**

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

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

## Transformer2DModelOutput[[diffusers.models.modeling_outputs.Transformer2DModelOutput]]

#### diffusers.models.modeling_outputs.Transformer2DModelOutput[[diffusers.models.modeling_outputs.Transformer2DModelOutput]]

```python
diffusers.models.modeling_outputs.Transformer2DModelOutput(sample: torch.Tensor)
```

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

**パラメータ:**

sample (`torch.Tensor`、shape は `(batch_size, num_channels, height, width)`、または [Transformer2DModel](/docs/diffusers/main/ja/api/models/transformer2d#diffusers.Transformer2DModel) が離散型の場合 `(batch size, num_vector_embeds - 1, num_latent_pixels)`) : `encoder_hidden_states` 入力を条件とする隠れ状態の出力です。離散型の場合、ノイズ除去されていない潜在ピクセルの確率分布を返します。

[Transformer2DModel](/docs/diffusers/main/ja/api/models/transformer2d#diffusers.Transformer2DModel)の出力です。