# ConsisIDTransformer3DModel

A Diffusion Transformer model for 3D data from [ConsisID](https://github.com/PKU-YuanGroup/ConsisID) was introduced in [Identity-Preserving Text-to-Video Generation by Frequency Decomposition](https://huggingface.co/papers/2411.17440) by Peking University & University of Rochester & etc.

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

```python
from diffusers import ConsisIDTransformer3DModel

transformer = ConsisIDTransformer3DModel.from_pretrained("BestWishYsh/ConsisID-preview", subfolder="transformer", dtype=torch.bfloat16).to("cuda")  # or "mps", "xpu", "cpu"
```

## ConsisIDTransformer3DModel[[diffusers.ConsisIDTransformer3DModel]]

#### diffusers.ConsisIDTransformer3DModel[[diffusers.ConsisIDTransformer3DModel]]

```python
diffusers.ConsisIDTransformer3DModel(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, 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, 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, is_train_face: bool = False, is_kps: bool = False, cross_attn_interval: int = 2, cross_attn_dim_head: int = 128, cross_attn_num_heads: int = 16, LFE_id_dim: int = 1280, LFE_vit_dim: int = 1024, LFE_depth: int = 10, LFE_dim_head: int = 64, LFE_num_heads: int = 16, LFE_num_id_token: int = 5, LFE_num_querie: int = 32, LFE_output_dim: int = 2048, LFE_ff_mult: int = 4, LFE_num_scale: int = 5, local_face_scale: float = 1.0)
```

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

**参数：**

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`)：时间步嵌入的输出维度。

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`)：输入潜变量中的帧数。请注意，由于 ConsisID 在其默认和推荐设置中一次处理 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 位置嵌入的缩放因子。

is_train_face (`bool`，默认为 `False`)：是否在训练过程中启用身份保持模块。当设置为 `True` 时，模型将专注于身份保持任务。

is_kps (`bool`，默认为 `False`)：是否启用全局面部提取器的关键点功能。如果为 `True`，模型中将包含关键点。

cross_attn_interval (`int`，默认为 `2`)：Transformer 架构中交叉注意力层之间的间隔。较大的值可能会降低交叉注意力计算的频率，从而有助于减少计算开销。

cross_attn_dim_head (`int`，可选，默认值为 `128`)：Transformer 架构中交叉注意力层里每个注意力头的维度。较大的值会提升关注更复杂模式的能力，但也会增加内存和计算开销。

cross_attn_num_heads (`int`，可选，默认为 `16`)：交叉注意力层中的注意力头数量。更多的注意力头允许采用更多并行的注意力机制，从而捕捉输入不同组成部分之间的多样化关系，但同时也可能增加计算需求。

LFE_id_dim (`int`，可选，默认值为 `1280`)：本地面部提取器（LFE）中使用的身份向量的维度。该向量表示面部的身份特征，对于人脸识别以及在不同帧之间保持身份一致性等任务至关重要。

LFE_vit_dim (`int`，可选，默认值为 `1024`)：在局部面部提取器（LFE）中使用的视觉 Transformer（ViT）输出的维度。该值决定了用于面部特征处理的 Transformer 生成特征向量的大小。

LFE_depth (`int`，可选，默认为 `10`)：本地面部提取器（LFE）的层数。增加深度可使模型捕获更复杂的面部特征表示，但也会增加计算负载。

LFE_dim_head (`int`，可选，默认值为 `64`)：Local Facial Extractor (LFE) 中每个注意力头的维度。该参数影响模型在提取过程中对面部特征不同部分进行处理和聚焦的精细程度。

LFE_num_heads (`int`，可选，默认为 `16`)：本地面部提取器（LFE）中的注意力头数量。增加注意力头数量可以提升模型捕捉多样化面部特征的能力，但会增加计算复杂度。

LFE_num_id_token (`int`，可选，默认为 `5`)：本地面部提取器（LFE）中使用的身份令牌数量。这定义了模型在处理面部特征提取时，为确保面部身份一致性而处理的身份相关令牌数量。

LFE_num_querie (`int`，可选，默认为 `32`)：本地面部提取器（LFE）中使用的查询 token 数量。这些 token 用于捕获有助于准确提取面部特征的高频面部相关信息。

LFE_output_dim (`int`，可选，默认值为 `2048`)：本地面部提取器（LFE）的输出维度。该维度决定了 LFE 模块生成的特征向量的大小，这些特征向量将用于后续任务，例如人脸识别或跟踪。

LFE_ff_mult (`int`，可选，默认为 `4`)：应用于本地面部提取器（LFE）中前馈网络隐藏层大小的乘数因子。较高的值会增加模型学习更复杂的面部特征变换的能力，但也会增加计算和内存需求。

LFE_num_scale (`int`，可选，默认为 `5`)：视觉特征的不同尺度数量。较高的值会增加模型学习更复杂的面部特征变换的能力，但也会增加计算和内存需求。

local_face_scale (`float`，默认为 `1.0`)：用于调整模型中局部面部特征重要性的缩放因子。这会影响模型对高频面部相关内容的关注程度。

用于 [ConsisID](https://github.com/PKU-YuanGroup/ConsisID) 中类视频数据的 Transformer 模型。

#### forward[[diffusers.ConsisIDTransformer3DModel.forward]]

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

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

**参数：**

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` 层传入的样本相加，以得到最终的时间步嵌入。

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

id_cond (`torch.Tensor`, *可选*) : 由本地面部提取器提取的面部嵌入，用于身份条件控制。

id_vit_hidden (`torch.Tensor`, *可选*) : 从人脸图像中提取的 ViT 隐藏状态，用于身份条件控制。

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

**返回值：**

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

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

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