# HunyuanVideoTransformer3DModel

腾讯在 [HunyuanVideo: A Systematic Framework For Large Video Generative Models](https://huggingface.co/papers/2412.03603) 中介绍了一种用于 3D 类视频数据的 Diffusion Transformer 模型。

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

```python
from diffusers import HunyuanVideoTransformer3DModel

transformer = HunyuanVideoTransformer3DModel.from_pretrained("hunyuanvideo-community/HunyuanVideo", subfolder="transformer", dtype=torch.bfloat16)
```

## HunyuanVideoTransformer3DModel[[diffusers.HunyuanVideoTransformer3DModel]]

#### diffusers.HunyuanVideoTransformer3DModel[[diffusers.HunyuanVideoTransformer3DModel]]

```python
diffusers.HunyuanVideoTransformer3DModel(in_channels: int = 16, out_channels: int = 16, num_attention_heads: int = 24, attention_head_dim: int = 128, num_layers: int = 20, num_single_layers: int = 40, num_refiner_layers: int = 2, mlp_ratio: float = 4.0, patch_size: int = 2, patch_size_t: int = 1, qk_norm: str = 'rms_norm', guidance_embeds: bool = True, text_embed_dim: int = 4096, pooled_projection_dim: int = 768, rope_theta: float = 256.0, rope_axes_dim: tuple = (16, 56, 56), image_condition_type: str | None = None)
```

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

**参数：**

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

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

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

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

num_layers (`int`，默认为 `20`)：要使用的双流块层数。

num_single_layers (`int`，默认为 `40`)：要使用的单流块层数。

num_refiner_layers (`int`，默认为 `2`)：要使用的 refiner 块层数。

mlp_ratio (`float`，默认为 `4.0`)：前馈网络中隐藏层大小与输入大小的比率。

patch_size (`int`，默认为 `2`)：在 patch embedding 层中使用的空间 patch 的大小。

patch_size_t (`int`，默认为 `1`)：在 patch embedding 层中使用的时序 patch 的大小。

qk_norm (`str`，默认为 `rms_norm`)：注意力层中查询和键投影所使用的归一化方法。

guidance_embeds (`bool`，默认为 `True`)：是否在模型中使用引导嵌入。

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

pooled_projection_dim (`int`，默认为 `768`)：文本嵌入池化投影的维度。

rope_theta (`float`，默认值为 `256.0`)：RoPE 层中使用的 theta 值。

rope_axes_dim (`tuple[int]`，默认为 `(16, 56, 56)`)：RoPE 层中使用的轴维度。

image_condition_type (`str`，*可选*，默认为 `None`)：要使用的图像条件类型。如果为 `None`，则不使用图像条件。如果为 `latent_concat`，则将图像拼接到潜在流中。如果为 `token_replace`，则使用图像替换潜在流中的首帧 token 并应用条件。

用于 [HunyuanVideo](https://huggingface.co/tencent/HunyuanVideo) 的、处理类视频数据的 Transformer 模型。

#### forward[[diffusers.HunyuanVideoTransformer3DModel.forward]]

```python
forward(hidden_states: Tensor, timestep: LongTensor, encoder_hidden_states: Tensor, encoder_attention_mask: Tensor, pooled_projections: Tensor, guidance: Tensor = None, attention_kwargs: dict[str, typing.Any] | None = None, return_dict: bool = True)
```

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

**参数：**

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

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

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

encoder_attention_mask (`torch.Tensor`) : 在注意力机制中应用于 `encoder_hidden_states` 的掩码。

pooled_projections (`torch.Tensor`，形状为 `(batch_size, projection_dim)`)：由输入条件的嵌入投影得到的嵌入。

guidance (`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`，其中第一个元素是样本张量。

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

## 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) 的输出。