# CogVideoXTransformer3DModel

A Diffusion Transformer model for 3D data from [CogVideoX](https://github.com/THUDM/CogVideo) was introduced in [CogVideoX: Text-to-Video Diffusion Models with An Expert Transformer](https://huggingface.co/papers/2408.06072) by Tsinghua University & ZhipuAI.

可以使用以下代码片段加载该模型。

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

[源代码](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/cogvideox_transformer_3d.py#L160)

**参数：**

num_attention_heads (`int`，默认为 `30`)：用于多头注意力的头数。

attention_head_dim (`int`，默认为 `64`)：每个头中的通道数。

in_channels (`int`，默认为 `16`)：输入中的通道数。

out_channels (`int`，*可选*，默认为 `16`)：输出的通道数。

flip_sin_to_cos (`bool`，默认为 `True`)：是否将时间嵌入中的 sin 翻转为 cos。

time_embed_dim (`int`，默认为 `512`)：时间步嵌入的输出维度。

ofs_embed_dim (`int`，默认值为 `512`)：CogVideoX-5b-I2B 1.5 版本中用于 "ofs" 嵌入的输出维度

text_embed_dim (`int`，默认为 `4096`)：文本编码器输出的文本嵌入的输入维度。

num_layers (`int`，默认为 `30`)：要使用的 Transformer 块层数。

dropout (`float`，默认为 `0.0`)：要使用的 dropout 概率。

attention_bias (`bool`，默认为 `True`)：是否在注意力投影层中使用偏置。

sample_width (`int`，默认值为 `90`)：输入潜变量的宽度。

sample_height (`int`，默认为 `60`)：输入潜变量的高度。

sample_frames (`int`，默认值为 `49`)：输入潜变量中的帧数。请注意，由于 CogVideoX 在其默认和推荐设置中一次处理 13 个潜变量帧，因此该参数被错误地初始化为 49 而非 13，但为了保持向后兼容性，无法将其更改为正确的值。若要创建一个具有 K 个潜变量帧的 transformer，此处应传入的正确值为：((K - 1) * temporal_compression_ratio + 1)。

patch_size (`int`，默认为 `2`)：用于 patch 嵌入层的 patch 大小。

temporal_compression_ratio (`int`，默认为 `4`)：时间维度上的压缩比。请参阅 `sample_frames` 的文档。

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-5`)：归一化层中使用的 epsilon 值。

spatial_interpolation_scale (`float`，默认为 `1.875`)：应用于 3D 位置嵌入中空间维度的缩放因子。

temporal_interpolation_scale (`float`，默认为 `1.0`)：在时间维度上应用于 3D 位置嵌入的缩放因子。

用于 [CogVideoX](https://github.com/THUDM/CogVideo) 中类视频数据的 Transformer 模型。

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

[源代码](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/cogvideox_transformer_3d.py#L366)

**参数：**

hidden_states (`torch.Tensor`，形状为 `(batch_size, num_frames, channels, height, width)`)：输入 `hidden_states`。

encoder_hidden_states (`torch.Tensor`，形状为 `(batch_size, sequence_len, embed_dims)`)：要使用的条件嵌入（从输入条件（例如提示词）计算得出的嵌入）。

timestep (`torch.LongTensor`)：用于指示去噪步骤。

timestep_cond (`torch.Tensor`, *可选*) : 用于时间步的条件嵌入。如果提供，这些嵌入将与通过 `self.time_embedding` 层传入的样本相加，以得到最终的时间步嵌入。

ofs (`torch.Tensor`, *可选*) : 在 CogVideoX-5b-I2V 中使用的偏移嵌入。

image_rotary_emb (`tuple` of `torch.Tensor`, *可选*) : 预计算的旋转位置嵌入。

attention_kwargs (`dict`, *可选*) : 一个 kwargs 字典，如果指定，将作为参数传递给 [diffusers.models.attention_processor](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/attention_processor.py) 中 `self.processor` 下定义的 `AttentionProcessor`。

return_dict (`bool`，*可选*，默认为 `True`)：是否返回 `~models.transformer_2d.Transformer2DModelOutput` 而不是普通元组。

**返回值：**

如果 `return_dict` 为 True，则返回 `~models.transformer_2d.Transformer2DModelOutput`，否则返回一个 `tuple`，其中第一个元素是样本张量。

[CogVideoXTransformer3DModel](/docs/diffusers/main/zh/api/models/cogvideox_transformer3d#diffusers.CogVideoXTransformer3DModel) 的前向方法。

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

```python
fuse_qkv_projections()
```

[源代码](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/cogvideox_transformer_3d.py#L335)

启用融合的 QKV 投影。对于自注意力模块，所有投影矩阵（即 query、key、value）均会被融合。对于交叉注意力模块，key 和 value 投影矩阵会被融合。

> [!WARNING] > 此 API 处于 🧪 实验阶段。

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

```python
unfuse_qkv_projections()
```

[源代码](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/transformers/cogvideox_transformer_3d.py#L357)

如果已启用，则禁用融合的 QKV 投影。

> [!WARNING] > 此 API 处于 🧪 实验阶段。

## 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`，形状为 `(batch_size, num_channels, height, width)`；若 [Transformer2DModel](/docs/diffusers/main/zh/api/models/transformer2d#diffusers.Transformer2DModel) 为离散模式，则为 `(batch size, num_vector_embeds - 1, num_latent_pixels)`)：以 `encoder_hidden_states` 输入为条件的隐藏状态输出。若为离散模式，则返回未加噪潜在像素的概率分布。

[Transformer2DModel](/docs/diffusers/main/zh/api/models/transformer2d#diffusers.Transformer2DModel) 的输出。