# 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 = (128, 240, 240), patch_size: tuple = (1, 2, 2), rope_scale: tuple = (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`) : multi-head attention에 사용할 헤드 수입니다.

attention_head_dim (`int`, 기본값 `128`) : 각 attention head의 채널 수입니다.

num_layers (`int`, 기본값 `28`) : 사용할 transformer 블록의 레이어 수입니다.

mlp_ratio (`float`, 기본값 `4.0`) : 피드포워드 네트워크에서 은닉층 크기와 입력 크기의 비율입니다.

text_embed_dim (`int`, 기본값 `4096`) : 텍스트 인코더에서 생성된 텍스트 임베딩의 입력 차원입니다.

adaln_lora_dim (`int`, 기본값 `256`) : Adaptive LayerNorm LoRA 레이어의 숨겨진 차원(hidden dimension)입니다.

max_size (`tuple[int, int, int]`, 기본값 `(128, 240, 240)`) : 시간, 높이, 너비 차원에서의 입력 latent 텐서의 최대 크기입니다.

patch_size (`tuple[int, int, int]`, 기본값 `(1, 2, 2)`) : 시간, 높이, 너비 차원에서 입력 latent 텐서를 패치화할 때 사용할 패치 크기입니다.

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`, *선택 사항*) : 제어 잔차를 받아야 하는 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`, shape `(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`, *선택 사항*) : 지정된 경우, Transformer 블록의 잔차(residuals)에 추가되는 텐서 목록입니다.

attention_mask (`torch.Tensor`, *선택 사항*) : attention 과정에서 `encoder_hidden_states`에 적용되는 마스크입니다.

fps (`int`, *선택 사항*) : 회전 위치 임베딩을 계산하는 데 사용되는 입력 비디오의 초당 프레임 수.

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/ko/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/ko/api/models/transformer2d#diffusers.Transformer2DModel)이 discrete인 경우 `(batch size, num_vector_embeds - 1, num_latent_pixels)`) : `encoder_hidden_states` 입력에 조건부인 hidden states 출력입니다. discrete인 경우, 노이즈가 제거된 latent 픽셀에 대한 확률 분포를 반환합니다.

[Transformer2DModel](/docs/diffusers/main/ko/api/models/transformer2d#diffusers.Transformer2DModel)의 출력입니다.