# CogVideoXTransformer3DModel

Một mô hình Diffusion Transformer cho dữ liệu 3D từ [CogVideoX](https://github.com/THUDM/CogVideo) đã được giới thiệu trong [CogVideoX: Text-to-Video Diffusion Models with An Expert Transformer](https://huggingface.co/papers/2408.06072) bởi Đại học Thanh Hoa & ZhipuAI.

Mô hình có thể được tải bằng đoạn mã sau.

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

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

**Tham số:**

num_attention_heads (`int`, mặc định là `30`) : Số lượng đầu (heads) được sử dụng cho chú ý đa đầu (multi-head attention).

attention_head_dim (`int`, mặc định là `64`) : Số lượng kênh trong mỗi head.

in_channels (`int`, mặc định là `16`) : Số lượng kênh trong đầu vào.

out_channels (`int`, *tuỳ chọn*, mặc định là `16`) : Số lượng kênh trong đầu ra.

flip_sin_to_cos (`bool`, mặc định là `True`) : Có nên đảo sin thành cos trong nhúng thời gian hay không.

time_embed_dim (`int`, mặc định là `512`) : Kích thước chiều đầu ra của các embedding bước thời gian.

ofs_embed_dim (`int`, mặc định là `512`) : Kích thước chiều đầu ra của các embedding "ofs" được sử dụng trong CogVideoX-5b-I2B ở phiên bản 1.5

text_embed_dim (`int`, mặc định là `4096`) : Kích thước chiều đầu vào của các vector nhúng văn bản từ bộ mã hóa văn bản.

num_layers (`int`, mặc định là `30`) : Số lượng lớp khối Transformer cần sử dụng.

dropout (`float`, mặc định là `0.0`) : Xác suất dropout cần sử dụng.

attention_bias (`bool`, mặc định là `True`) : Có sử dụng bias trong các lớp chiếu attention hay không.

sample_width (`int`, mặc định là `90`) : Độ rộng của các latents đầu vào.

sample_height (`int`, mặc định là `60`) : Chiều cao của các latents đầu vào.

sample_frames (`int`, mặc định là `49`) : Số lượng khung hình trong các latent đầu vào. Lưu ý rằng tham số này đã được khởi tạo sai thành 49 thay vì 13 vì CogVideoX xử lý 13 khung hình latent cùng lúc trong các cài đặt mặc định và được khuyến nghị, nhưng không thể thay đổi thành giá trị chính xác để đảm bảo tính tương thích ngược. Để tạo một transformer với K khung hình latent, giá trị chính xác cần truyền ở đây là: ((K - 1) * temporal_compression_ratio + 1).

patch_size (`int`, mặc định là `2`) : Kích thước của các patch được sử dụng trong lớp nhúng patch.

temporal_compression_ratio (`int`, mặc định là `4`) : Tỷ lệ nén theo chiều thời gian. Xem tài liệu cho `sample_frames`.

max_text_seq_length (`int`, mặc định là `226`) : Độ dài tối đa của chuỗi cho các nhúng văn bản đầu vào.

activation_fn (`str`, mặc định là `"gelu-approximate"`) : Hàm kích hoạt được sử dụng trong mạng truyền thẳng.

timestep_activation_fn (`str`, mặc định là `"silu"`) : Hàm kích hoạt được sử dụng khi tạo các nhúng bước thời gian (timestep embeddings).

norm_elementwise_affine (`bool`, mặc định là `True`) : Có sử dụng affine từng phần tử trong các lớp chuẩn hóa hay không.

norm_eps (`float`, mặc định là `1e-5`) : Giá trị epsilon được sử dụng trong các lớp chuẩn hóa.

spatial_interpolation_scale (`float`, mặc định là `1.875`) : Hệ số tỷ lệ để áp dụng trong các nhúng vị trí 3D trên các chiều không gian.

temporal_interpolation_scale (`float`, mặc định là `1.0`) : Hệ số tỷ lệ để áp dụng trong các nhúng vị trí 3D trên các chiều thời gian.

Một mô hình Transformer cho dữ liệu dạng video trong [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)
```

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

**Tham số:**

hidden_states (`torch.Tensor` có hình dạng `(batch_size, num_frames, channels, height, width)`) : `hidden_states` đầu vào.

encoder_hidden_states (`torch.Tensor` có shape `(batch_size, sequence_len, embed_dims)`) : Các embeddings điều kiện (embeddings được tính từ các điều kiện đầu vào như prompts) cần sử dụng.

timestep (`torch.LongTensor`) : Dùng để chỉ bước khử nhiễu.

timestep_cond (`torch.Tensor`, *tùy chọn*) : Các embedding điều kiện cho timestep. Nếu được cung cấp, các embedding này sẽ được cộng với các mẫu đi qua lớp `self.time_embedding` để thu được các embedding timestep cuối cùng.

ofs (`torch.Tensor`, *tùy chọn*) : Các embedding offset được sử dụng trong CogVideoX-5b-I2V.

image_rotary_emb (`tuple` của `torch.Tensor`, *tuỳ chọn*) : Các nhúng vị trí quay đã tính trước.

attention_kwargs (`dict`, *tùy chọn*) : Một từ điển kwargs mà nếu được chỉ định sẽ được truyền đến `AttentionProcessor` như đã định nghĩa dưới `self.processor` trong [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py).

return_dict (`bool`, *tùy chọn*, mặc định là `True`) : Có nên trả về một `~models.transformer_2d.Transformer2DModelOutput` thay vì một tuple thông thường hay không.

**Trả về:**

Nếu `return_dict` là True, một `~models.transformer_2d.Transformer2DModelOutput` sẽ được trả về, ngược lại một `tuple` trong đó phần tử đầu tiên là tensor mẫu.

Phương thức forward của [CogVideoXTransformer3DModel](/docs/diffusers/v0.43.0/vi/api/models/cogvideox_transformer3d#diffusers.CogVideoXTransformer3DModel).

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

```python
fuse_qkv_projections()
```

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

Bật các phép chiếu QKV đã hợp nhất. Đối với các module tự chú ý, tất cả các ma trận chiếu (tức là truy vấn, khóa, giá trị) đều được hợp nhất. Đối với các module chú ý chéo, các ma trận chiếu khóa và giá trị được hợp nhất.

> [!WARNING] > API này 🧪 đang ở giai đoạn thử nghiệm.

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

```python
unfuse_qkv_projections()
```

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

Tắt dự phóng QKV hợp nhất nếu đã được bật.

> [!WARNING] > API này 🧪 đang ở giai đoạn thử nghiệm.

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

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

**Tham số:**

sample (`torch.Tensor` có shape `(batch_size, num_channels, height, width)` hoặc `(batch size, num_vector_embeds - 1, num_latent_pixels)` nếu [Transformer2DModel](/docs/diffusers/v0.43.0/vi/api/models/transformer2d#diffusers.Transformer2DModel) là discrete) : Đầu ra của hidden states được điều kiện bởi đầu vào `encoder_hidden_states`. Nếu là discrete, trả về các phân phối xác suất cho các latent pixels chưa bị nhiễu.

Đầu ra của [Transformer2DModel](/docs/diffusers/v0.43.0/vi/api/models/transformer2d#diffusers.Transformer2DModel).