# PixArtTransformer2DModel

用于类图像数据的 Transformer 模型，源自 [PixArt-Alpha](https://huggingface.co/papers/2310.00426) 和 [PixArt-Sigma](https://huggingface.co/papers/2403.04692)。

## PixArtTransformer2DModel[[diffusers.PixArtTransformer2DModel]]

#### diffusers.PixArtTransformer2DModel[[diffusers.PixArtTransformer2DModel]]

```python
diffusers.PixArtTransformer2DModel(num_attention_heads: int = 16, attention_head_dim: int = 72, in_channels: int = 4, out_channels: int | None = 8, num_layers: int = 28, dropout: float = 0.0, norm_num_groups: int = 32, cross_attention_dim: int | None = 1152, attention_bias: bool = True, sample_size: int = 128, patch_size: int = 2, activation_fn: str = 'gelu-approximate', num_embeds_ada_norm: int | None = 1000, upcast_attention: bool = False, norm_type: str = 'ada_norm_single', norm_elementwise_affine: bool = False, norm_eps: float = 1e-06, interpolation_scale: int | None = None, use_additional_conditions: bool | None = None, caption_channels: int | None = None, attention_type: str | None = 'default')
```

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

**参数：**

num_attention_heads (int, 可选, 默认为 16) : 用于多头注意力的头数。

attention_head_dim (int, 可选, 默认值为 72) : 每个头中的通道数。

in_channels (int, 默认为 4)：输入中的通道数。

out_channels (int, 可选) : 输出中的通道数。如果输出通道数与输入不同，请指定此参数。

num_layers (int, 可选, 默认为 28) : 要使用的 Transformer 块层数。

dropout (float, 可选，默认值为 0.0) : 在 Transformer 块中使用的 dropout 概率。

norm_num_groups (int, 可选, 默认值为 32) : Transformer 块内组归一化的组数。

cross_attention_dim (int, 可选)：交叉注意力层的维度，通常与编码器的隐藏维度相匹配。

attention_bias (bool, 可选, 默认为 True) : 配置 Transformer 块中的注意力机制是否应包含偏置参数。

sample_size (int, 默认为 128)：潜在图像的宽度。此参数在训练过程中是固定的。

patch_size (int, 默认为 2) : 模型处理的块大小，适用于处理非顺序数据的架构。

activation_fn (str，可选，默认为 "gelu-approximate")：在 Transformer 块中的前馈网络中使用的激活函数。

num_embeds_ada_norm (int, 可选，默认值为 1000) : AdaLayerNorm 的嵌入数量，在训练期间固定，并影响推理时的最大去噪步数。

upcast_attention (bool, 可选, 默认为 False) : 如果为 true，则向上转换注意力机制的维度，以可能提升性能。

norm_type (str, 可选，默认为 "ada_norm_zero")：指定所使用的归一化类型，可以是 'ada_norm_zero'。

norm_elementwise_affine (bool, 可选, 默认为 False) : 如果为 true，则在归一化层中启用逐元素仿射参数。

norm_eps (float, 可选，默认为 1e-6)：在归一化层中添加到分母的一个小常数，用于防止除以零。

interpolation_scale (int, 可选) : 在插值位置嵌入时使用的缩放因子。

use_additional_conditions (bool, optional) : 是否使用附加条件作为输入。

attention_type (str，可选，默认为 "default")：要使用的注意力机制类型。

caption_channels (int, 可选, 默认为 None) : 用于投影字幕嵌入的通道数。

use_linear_projection (bool, 可选，默认为 False) : 已弃用的参数。将在未来版本中移除。

num_vector_embeds (bool, 可选，默认为 False) : 已弃用的参数。将在未来版本中移除。

如 PixArt 系列模型（https://huggingface.co/papers/2310.00426, https://huggingface.co/papers/2403.04692）中介绍的 2D Transformer 模型。

#### forward[[diffusers.PixArtTransformer2DModel.forward]]

```python
forward(hidden_states: Tensor, encoder_hidden_states: typing.Optional[torch.Tensor] = None, timestep: typing.Optional[torch.LongTensor] = None, added_cond_kwargs: dict[str, torch.Tensor] = None, cross_attention_kwargs: dict[str, typing.Any] = None, attention_mask: typing.Optional[torch.Tensor] = None, encoder_attention_mask: typing.Optional[torch.Tensor] = None, return_dict: bool = True)
```

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

**参数：**

hidden_states (`torch.FloatTensor`，形状为 `(batch size, channel, height, width)`)：输入 `hidden_states`。

encoder_hidden_states (`torch.FloatTensor`，形状为 `(batch size, sequence len, embed dims)`，*可选*)：用于交叉注意力层的条件嵌入。如果未提供，交叉注意力将默认为自注意力。

timestep (`torch.LongTensor`, *可选*) : 用于指示去噪步骤。作为嵌入应用于 `AdaLayerNorm` 的可选时间步。

added_cond_kwargs : (`dict[str, Any]`，*可选*)：用作输入的附加条件。

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

attention_mask ( `torch.Tensor`, *可选*) : 形状为 `(batch, key_tokens)` 的注意力掩码将应用于 `encoder_hidden_states`。如果值为 `1`，则保留该掩码；如果值为 `0`，则丢弃该掩码。掩码将被转换为偏置，向对应于“丢弃”标记的注意力分数添加较大的负值。

encoder_attention_mask ( `torch.Tensor`, *可选*) : 应用于 `encoder_hidden_states` 的交叉注意力掩码。支持两种格式：  * 掩码 `(batch, sequence_length)`，True = 保留，False = 丢弃。 * 偏置 `(batch, 1, sequence_length)`，0 = 保留，-10000 = 丢弃。  如果 `ndim == 2`：将被解释为掩码，然后转换为与上述格式一致的偏置。该偏置将被加到交叉注意力分数上。

return_dict (`bool`，*可选*，默认为 `True`)：是否返回 [UNet2DConditionOutput](/docs/diffusers/main/zh/api/models/unet2d-cond#diffusers.models.unets.unet_2d_condition.UNet2DConditionOutput) 而不是普通元组。

**返回值：**

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

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

#### fuse_qkv_projections[[diffusers.PixArtTransformer2DModel.fuse_qkv_projections]]

```python
fuse_qkv_projections()
```

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

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

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

#### set_default_attn_processor[[diffusers.PixArtTransformer2DModel.set_default_attn_processor]]

```python
set_default_attn_processor()
```

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

禁用自定义注意力处理器并设置默认的注意力实现。

由于 PixArt 的默认模型没有使用任何特殊的注意力处理器，因此可以直接使用 `AttnProcessor()`。

#### unfuse_qkv_projections[[diffusers.PixArtTransformer2DModel.unfuse_qkv_projections]]

```python
unfuse_qkv_projections()
```

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

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

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