# CogVideoXTransformer3DModel

Um modelo Diffusion Transformer para dados 3D do [CogVideoX](https://github.com/THUDM/CogVideo) foi introduzido em [CogVideoX: Text-to-Video Diffusion Models with An Expert Transformer](https://huggingface.co/papers/2408.06072) pela Universidade de Tsinghua & ZhipuAI.

O modelo pode ser carregado com o seguinte trecho de código.

```python
from diffusers import CogVideoXTransformer3DModel

transformer = CogVideoXTransformer3DModel.from_pretrained("THUDM/CogVideoX-2b", subfolder="transformer", dtype=torch.float16).to("cuda")  # or "mps", "xpu", "cpu"
```

## CogVideoXTransformer3DModel[[diffusers.CogVideoXTransformer3DModel]]

#### diffusers.CogVideoXTransformer3DModel[[diffusers.CogVideoXTransformer3DModel]]

```python
diffusers.CogVideoXTransformer3DModel(num_attention_heads: int = 30, attention_head_dim: int = 64, in_channels: int = 16, out_channels: int | None = 16, flip_sin_to_cos: bool = True, freq_shift: int = 0, time_embed_dim: int = 512, ofs_embed_dim: int | None = None, text_embed_dim: int = 4096, num_layers: int = 30, dropout: float = 0.0, attention_bias: bool = True, sample_width: int = 90, sample_height: int = 60, sample_frames: int = 49, patch_size: int = 2, patch_size_t: int | None = None, temporal_compression_ratio: int = 4, max_text_seq_length: int = 226, activation_fn: str = 'gelu-approximate', timestep_activation_fn: str = 'silu', norm_elementwise_affine: bool = True, norm_eps: float = 1e-05, spatial_interpolation_scale: float = 1.875, temporal_interpolation_scale: float = 1.0, use_rotary_positional_embeddings: bool = False, use_learned_positional_embeddings: bool = False, patch_bias: bool = True)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/cogvideox_transformer_3d.py#L160)

**Parâmetros:**

num_attention_heads (`int`, padrão `30`) : O número de cabeças a serem usadas para a atenção multi-cabeça.

attention_head_dim (`int`, padrão `64`) : O número de canais em cada head.

in_channels (`int`, padrão `16`) : O número de canais na entrada.

out_channels (`int`, *opcional*, padrão `16`) : O número de canais na saída.

flip_sin_to_cos (`bool`, padrão `True`) : Se deve inverter o sin para cos no embedding de tempo.

time_embed_dim (`int`, padrão `512`) : Dimensão de saída dos embeddings de timestep.

ofs_embed_dim (`int`, padrão `512`) : Dimensão de saída dos embeddings "ofs" usados no CogVideoX-5b-I2B na versão 1.5

text_embed_dim (`int`, padrão `4096`) : Dimensão de entrada dos embeddings de texto do codificador de texto.

num_layers (`int`, padrão `30`) : O número de blocos de Transformer a serem usados.

dropout (`float`, padrão `0.0`) : A probabilidade de dropout a ser utilizada.

attention_bias (`bool`, padrão `True`) : Se deve usar viés nas camadas de projeção de atenção.

sample_width (`int`, padrão `90`) : A largura dos latentes de entrada.

sample_height (`int`, padrão `60`) : A altura dos latentes de entrada.

sample_frames (`int`, padrão `49`) : O número de quadros nos latentes de entrada. Observe que este parâmetro foi inicializado incorretamente como 49 em vez de 13, pois o CogVideoX processava 13 quadros latentes de uma vez em suas configurações padrão e recomendadas, mas não pode ser alterado para o valor correto para garantir compatibilidade reversa. Para criar um transformer com K quadros latentes, o valor correto a ser passado aqui seria: ((K - 1) * temporal_compression_ratio + 1).

patch_size (`int`, padrão `2`) : O tamanho dos patches a serem usados na camada de incorporação de patches.

temporal_compression_ratio (`int`, padrão `4`) : A taxa de compressão ao longo da dimensão temporal. Consulte a documentação de `sample_frames`.

max_text_seq_length (`int`, padrão `226`) : O comprimento máximo da sequência dos embeddings de texto de entrada.

activation_fn (`str`, padrão `"gelu-approximate"`) : Função de ativação a ser usada no feed-forward.

timestep_activation_fn (`str`, padrão `"silu"`) : Função de ativação a ser usada ao gerar os embeddings de timestep.

norm_elementwise_affine (`bool`, padrão `True`) : Se deve usar afinidade elementar em camadas de normalização.

norm_eps (`float`, padrão `1e-5`) : O valor de epsilon a ser usado nas camadas de normalização.

spatial_interpolation_scale (`float`, padrão `1.875`) : Fator de escala a ser aplicado nos embeddings posicionais 3D ao longo das dimensões espaciais.

temporal_interpolation_scale (`float`, padrão `1.0`) : Fator de escala a ser aplicado nos embeddings posicionais 3D ao longo das dimensões temporais.

Um modelo Transformer para dados semelhantes a vídeo no [CogVideoX](https://github.com/THUDM/CogVideo).

#### forward[[diffusers.CogVideoXTransformer3DModel.forward]]

```python
forward(hidden_states: Tensor, encoder_hidden_states: Tensor, timestep: typing.Union[int, float, torch.LongTensor], timestep_cond: typing.Optional[torch.Tensor] = None, ofs: typing.Union[int, float, torch.LongTensor, NoneType] = None, image_rotary_emb: tuple[torch.Tensor, torch.Tensor] | None = None, attention_kwargs: dict[str, typing.Any] | None = None, return_dict: bool = True)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/cogvideox_transformer_3d.py#L366)

**Parâmetros:**

hidden_states (`torch.Tensor` de forma `(batch_size, num_frames, channels, height, width)`) : `hidden_states` de entrada.

encoder_hidden_states (`torch.Tensor` de forma `(batch_size, sequence_len, embed_dims)`) : Embeddings condicionais (embeddings calculados a partir das condições de entrada, como prompts) a serem usados.

timestep (`torch.LongTensor`) : Usado para indicar o passo de desruidamento.

timestep_cond (`torch.Tensor`, *opcional*) : Embebimentos condicionais para o passo de tempo. Se fornecidos, os embebimentos serão somados às amostras passadas pela camada `self.time_embedding` para obter os embebimentos finais do passo de tempo.

ofs (`torch.Tensor`, *opcional*) : Embeddings de deslocamento usados no CogVideoX-5b-I2V.

image_rotary_emb (`tuple` de `torch.Tensor`, *opcional*) : Incorporações posicionais rotativas pré-computadas.

attention_kwargs (`dict`, *opcional*) : Um dicionário de kwargs que, se especificado, é passado para o `AttentionProcessor` conforme definido em `self.processor` em [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py).

return_dict (`bool`, *opcional*, padrão `True`) : Indica se deve retornar um `~models.transformer_2d.Transformer2DModelOutput` em vez de uma tupla simples.

**Retorna:**

Se `return_dict` for True, um `~models.transformer_2d.Transformer2DModelOutput` é retornado; caso contrário, uma `tuple` onde o primeiro elemento é o tensor da amostra.

O método forward do [CogVideoXTransformer3DModel](/docs/diffusers/v0.43.0/pt/api/models/cogvideox_transformer3d#diffusers.CogVideoXTransformer3DModel).

#### fuse_qkv_projections[[diffusers.CogVideoXTransformer3DModel.fuse_qkv_projections]]

```python
fuse_qkv_projections()
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/cogvideox_transformer_3d.py#L335)

Ativa as projeções QKV fundidas. Para os módulos de autoatenção, todas as matrizes de projeção (ou seja, query, key, value) são fundidas. Para os módulos de atenção cruzada, as matrizes de projeção de key e value são fundidas.

> [!WARNING] > Esta API é 🧪 experimental.

#### unfuse_qkv_projections[[diffusers.CogVideoXTransformer3DModel.unfuse_qkv_projections]]

```python
unfuse_qkv_projections()
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/cogvideox_transformer_3d.py#L357)

Desativa a projeção QKV fundida, se estiver habilitada.

> [!WARNING] > Esta API é 🧪 experimental.

## 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)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/modeling_outputs.py#L21)

**Parâmetros:**

sample (`torch.Tensor` de forma `(batch_size, num_channels, height, width)` ou `(batch size, num_vector_embeds - 1, num_latent_pixels)` se [Transformer2DModel](/docs/diffusers/v0.43.0/pt/api/models/transformer2d#diffusers.Transformer2DModel) for discreto) : A saída dos estados ocultos condicionada à entrada `encoder_hidden_states`. Se discreto, retorna distribuições de probabilidade para os pixels latentes sem ruído.

A saída de [Transformer2DModel](/docs/diffusers/v0.43.0/pt/api/models/transformer2d#diffusers.Transformer2DModel).