# SD3 Transformer 模型

在 [Stable Diffusion 3](https://hf.co/papers/2403.03206) 中引入的 Transformer 模型。其创新之处在于 MMDiT transformer 块。

## SD3Transformer2DModel[[diffusers.SD3Transformer2DModel]]

#### diffusers.SD3Transformer2DModel[[diffusers.SD3Transformer2DModel]]

```python
diffusers.SD3Transformer2DModel(sample_size: int = 128, patch_size: int = 2, in_channels: int = 16, num_layers: int = 18, attention_head_dim: int = 64, num_attention_heads: int = 18, joint_attention_dim: int = 4096, caption_projection_dim: int = 1152, pooled_projection_dim: int = 2048, out_channels: int = 16, pos_embed_max_size: int = 96, dual_attention_layers: tuple[int, ...] = (), qk_norm: str | None = None)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_sd3.py#L79)

**参数：**

sample_size (`int`，默认为 `128`)：潜在表示的宽度/高度。由于该值用于学习一定数量的位置嵌入，因此在训练过程中是固定的。

patch_size (`int`，默认为 `2`)：用于将输入数据划分为小块的补丁大小。

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

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

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

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

joint_attention_dim (`int`，默认为 `4096`)：用于联合文本-图像注意力的嵌入维度。

caption_projection_dim (`int`，默认为 `1152`)：标题嵌入的嵌入维度。

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

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

pos_embed_max_size (`int`，默认为 `96`)：位置嵌入的最大潜在高度/宽度。

dual_attention_layers (`tuple[int, ...]`，默认为 `()`)：要使用的双流 Transformer 块的数量。

qk_norm (`str`，*可选*，默认为 `None`)：注意力层中用于查询和键的归一化方式。如果为 `None`，则不使用归一化。

在 [Stable Diffusion 3](https://huggingface.co/papers/2403.03206) 中引入的 Transformer 模型。

#### enable_forward_chunking[[diffusers.SD3Transformer2DModel.enable_forward_chunking]]

```python
enable_forward_chunking(chunk_size: int | None = None, dim: int = 0)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_sd3.py#L175)

**参数：**

chunk_size (`int`, *可选*) : 前馈层的块大小。如果未指定，则对每个 dim=`dim` 的张量单独运行前馈层。

dim (`int`，*可选*，默认为 `0`)：前馈计算应进行分块的维度。在 dim=0（批次）或 dim=1（序列长度）之间选择。

将注意力处理器设置为使用 [前馈分块](https://huggingface.co/blog/reformer#2-chunked-feed-forward-layers)。

#### forward[[diffusers.SD3Transformer2DModel.forward]]

```python
forward(hidden_states: Tensor, encoder_hidden_states: Tensor = None, pooled_projections: Tensor = None, timestep: LongTensor = None, block_controlnet_hidden_states: list = None, joint_attention_kwargs: dict[str, typing.Any] | None = None, return_dict: bool = True, skip_layers: list[int] | None = None)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_sd3.py#L248)

**参数：**

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

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

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

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

block_controlnet_hidden_states (`list` of `torch.Tensor`) : 张量列表，如果指定，将添加到 Transformer 块的残差中。

joint_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` 而不是普通元组。

skip_layers (`list` of `int`, *可选*) : 前向传播过程中需要跳过的层索引列表。

**返回值：**

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

[SD3Transformer2DModel](/docs/diffusers/v0.43.0/zh/api/models/sd3_transformer2d#diffusers.SD3Transformer2DModel) 的前向方法。

#### fuse_qkv_projections[[diffusers.SD3Transformer2DModel.fuse_qkv_projections]]

```python
fuse_qkv_projections()
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_sd3.py#L217)

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

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

#### unfuse_qkv_projections[[diffusers.SD3Transformer2DModel.unfuse_qkv_projections]]

```python
unfuse_qkv_projections()
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_sd3.py#L239)

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

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