# HeliosTransformer3DModel

由北京大学、字节跳动等机构在 [Helios: Real Real-Time Long Video Generation Model](https://huggingface.co/papers/2603.04379) 中介绍了 [Helios](https://github.com/PKU-YuanGroup/Helios) 的 14B 实时自回归扩散 Transformer 模型（支持 T2V、I2V 和 V2V），用于处理 3D 类视频数据。

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

```python
from diffusers import HeliosTransformer3DModel

# Best Quality
transformer = HeliosTransformer3DModel.from_pretrained("BestWishYsh/Helios-Base", subfolder="transformer", dtype=torch.bfloat16)
# Intermediate Weight
transformer = HeliosTransformer3DModel.from_pretrained("BestWishYsh/Helios-Mid", subfolder="transformer", dtype=torch.bfloat16)
# Best Efficiency
transformer = HeliosTransformer3DModel.from_pretrained("BestWishYsh/Helios-Distilled", subfolder="transformer", dtype=torch.bfloat16)
```

## HeliosTransformer3DModel[[diffusers.HeliosTransformer3DModel]]

#### diffusers.HeliosTransformer3DModel[[diffusers.HeliosTransformer3DModel]]

```python
diffusers.HeliosTransformer3DModel(patch_size: tuple = (1, 2, 2), num_attention_heads: int = 40, attention_head_dim: int = 128, in_channels: int = 16, out_channels: int = 16, text_dim: int = 4096, freq_dim: int = 256, ffn_dim: int = 13824, num_layers: int = 40, cross_attn_norm: bool = True, qk_norm: str | None = 'rms_norm_across_heads', eps: float = 1e-06, added_kv_proj_dim: int | None = None, rope_dim: tuple = (44, 42, 42), rope_theta: float = 10000.0, guidance_cross_attn: bool = True, zero_history_timestep: bool = True, has_multi_term_memory_patch: bool = True, is_amplify_history: bool = False, history_scale_mode: str = 'per_head')
```

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

**参数：**

patch_size (`tuple[int]`，默认为 `(1, 2, 2)`)：用于视频嵌入的 3D 补丁维度 (t_patch, h_patch, w_patch)。

num_attention_heads (`int`，默认值为 `40`)：文本嵌入的固定长度。

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

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

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

text_dim (`int`，默认为 `512`)：文本嵌入的输入维度。

freq_dim (`int`，默认为 `256`)：正弦时间嵌入的维度。

ffn_dim (`int`，默认为 `13824`)：前馈网络中的中间维度。

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

window_size (`tuple[int]`，默认为 `(-1, -1)`)：局部注意力的窗口大小（-1 表示全局注意力）。

cross_attn_norm (`bool`，默认为 `True`)：启用交叉注意力归一化。

qk_norm (`bool`，默认为 `True`)：启用查询/键归一化。

eps (`float`，默认值为 `1e-6`)：归一化层的 epsilon 值。

add_img_emb (`bool`，默认为 `False`)：是否使用 img_emb。

added_kv_proj_dim (`int`，*可选*，默认为 `None`)：用于新增的键（key）和值（value）投影的通道数。如果为 `None`，则不使用投影。

用于 Helios 模型中类视频数据的 Transformer 模型。

#### forward[[diffusers.HeliosTransformer3DModel.forward]]

```python
forward(hidden_states: Tensor, timestep: LongTensor, encoder_hidden_states: Tensor, indices_hidden_states = None, indices_latents_history_short = None, indices_latents_history_mid = None, indices_latents_history_long = None, latents_history_short = None, latents_history_mid = None, latents_history_long = None, return_dict: bool = True, attention_kwargs: dict[str, typing.Any] | None = None)
```

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

**参数：**

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)`)：要使用的条件嵌入（从输入条件（例如提示词）计算得出的嵌入）。

indices_hidden_states (`torch.Tensor`, *可选*) : 用于计算旋转位置嵌入的 `hidden_states` 的帧索引。

indices_latents_history_short (`torch.Tensor`, *可选*) : 短历史潜变量的帧索引。

indices_latents_history_mid (`torch.Tensor`, *可选*) : 中间历史潜变量的帧索引。

indices_latents_history_long (`torch.Tensor`, *可选*) : 长历史潜变量的帧索引。

latents_history_short (`torch.Tensor`，*可选*)：短历史潜在变量条件。

latents_history_mid (`torch.Tensor`，*可选*)：中间历史潜在变量条件。

latents_history_long (`torch.Tensor`, *可选*) : 长历史潜在变量条件。

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

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` 为 True，则返回 `~models.transformer_2d.Transformer2DModelOutput`，否则返回一个 `tuple`，其中第一个元素是样本张量。

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

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