# Kandinsky 6 Transformers

Kandinsky 6 使用多模态扩散 Transformer，对视频和音频潜变量进行联合去噪，以实现文本/图像到视频和音频的生成，并使用无文本扩散 Transformer 进行视频超分辨率。

## Kandinsky6Transformer3DModel[[diffusers.Kandinsky6Transformer3DModel]]

[Kandinsky6TI2VAPipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/kandinsky6#diffusers.Kandinsky6TI2VAPipeline) 所使用的多模态 transformer。

```python
import torch
from diffusers import Kandinsky6Transformer3DModel

transformer = Kandinsky6Transformer3DModel.from_pretrained(
    "kandinskylab/Kandinsky-6.0-Pro-distill-5s-Diffusers", subfolder="transformer", torch_dtype=torch.bfloat16
)
```

#### diffusers.Kandinsky6Transformer3DModel[[diffusers.Kandinsky6Transformer3DModel]]

```python
diffusers.Kandinsky6Transformer3DModel(in_visual_dim: int = 16, out_visual_dim: int = 16, in_text_dim: int = 3584, in_text_dim2: int = 768, time_dim: int = 1024, patch_size: tuple = (1, 2, 2), model_dim: int = 4096, ff_dim: int = 16384, num_text_blocks: int = 4, num_visual_blocks: int = 60, axes_dims: tuple = (32, 48, 48), visual_cond: bool = True, in_audio_dim: int = 20, out_audio_dim: int = 20, model_dim_a: int | None = None, time_dim_a: int | None = None, ff_dim_a: int | None = None, axes_dims_a: tuple | None = None, audio_freqs_scaling: float = 1.0, scale_factor: tuple | list[float] = (1.0, 2.0, 2.0), text_token_padding: bool = False, ca_rope: bool = False, cross_gates: bool = False, fix_modulation: bool = False, visual_token_type_num_embeddings: int = 0)
```

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

**参数：**

in_visual_dim (*int*，*optional*，默认为 16)：输入视频潜在通道的数量。

out_visual_dim (*int*，*optional*，默认为 16)：输出视频潜在通道的数量。

in_text_dim (*int*，*optional*，默认为 3584)：文本 token 嵌入维度。

in_text_dim2 (*int*，*optional*，默认值为 768)：池化文本嵌入的维度。

time_dim (*int*，*optional*，默认为 1024)：时间嵌入维度。

patch_size (*tuple[int, int, int]*，*optional*，默认为 `(1, 2, 2)`)：视频 patch 大小。

model_dim (*int*，*optional*，默认为 4096)：视频 Transformer 的隐藏维度。

ff_dim (*int*，*optional*，默认为 16384)：视频前馈隐藏维度。

num_text_blocks (*int*，*optional*，默认为 4)：每个模态的文本块数量。

num_visual_blocks (*int*，*optional*，默认为 60)：融合的视频/音频块数量。

axes_dims (*tuple[int, int, int]*，*optional*，默认为 `(32, 48, 48)`)：视频的 RoPE 维度。

visual_cond (*bool*，*optional*，默认为 True)：是否存在视频条件通道。

in_audio_dim (*int*，*optional*，默认为 20)：输入音频潜在通道的数量。

out_audio_dim (*int*，*optional*，默认为 20)：输出音频潜在通道的数量。

model_dim_a (*int*, *optional*) : 音频 Transformer 的隐藏维度。默认值为 *model_dim*。

time_dim_a (*int*, *optional*) : 音频时间嵌入维度。默认为 *time_dim*。

ff_dim_a (*int*, *optional*) : 音频前馈隐藏维度。默认为 *ff_dim*。

axes_dims_a (*tuple[int, int, int]*，*optional*)：音频 RoPE 维度。默认值为 *axes_dims*。

audio_freqs_scaling (*float*，*optional*，默认为 1.0)：音频 RoPE 频率缩放。

scale_factor (*tuple[float, float, float]*，*optional*，默认为 *(1.0, 2.0, 2.0)*)：应用于视频位置的按轴 *(t, h, w)* RoPE 频率缩放。

text_token_padding (*bool*，*可选*，默认为 False)：记录参考模型的文本序列是否经过填充的 Checkpoint 元数据。无论此标志如何，*forward* 始终接受一个可选的 *encoder_attention_mask*；是否实际传入该参数完全由调用方决定。

ca_rope (*bool*，*optional*，默认为 False)：是否使用跨模态音频 RoPE。

cross_gates (*bool*，*optional*，默认为 False)：是否使用跨模态残差门控。

fix_modulation (*bool*，*optional*，默认为 False)：是否使用固定调制变体。

visual_token_type_num_embeddings (*int*，*optional*，默认为 0)：视觉 token 类型嵌入的数量。

Kandinsky 6 多模态 Transformer，用于文本/图像到视频和音频的生成。

视频和音频通过融合的跨模态 Transformer 块共同进行去噪，每个块都以其自身的文本分支（Qwen2.5-VL 标记 + CLIP 池化嵌入）作为条件。如果不传入 *audio_hidden_states*，则仅对视频进行去噪，但仍会执行融合块中的视频自注意力、交叉注意力和前馈阶段。旋转位置嵌入在 *forward* 内部根据标记网格计算得出。

发布的检查点将 *text_token_padding*、*ca_rope*、*cross_gates* 和 *fix_modulation* 设置为 *True*（参见各检查点的 *transformer/config.json*）；*False* 的默认值仅描述了一种本仓库未提供权重的架构变体。

#### forward[[diffusers.Kandinsky6Transformer3DModel.forward]]

```python
forward(hidden_states: Tensor, encoder_hidden_states: Tensor, pooled_projections: Tensor, timestep: Tensor, audio_hidden_states: Tensor | None = None, visual_rope_pos: tuple[Tensor, Tensor, Tensor] | None = None, encoder_attention_mask: Tensor | None = None, visual_token_type_ids: Tensor | None = None, return_dict: bool = True)
```

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

**参数：**

hidden_states （形状为 `(batch_size, num_frames, height, width, in_channels)` 的 `torch.Tensor`）：采用 `(B, T, H, W, C)` 布局的视频潜在表示。当 `visual_cond=True` 时，`in_channels` 为 `2 * in_visual_dim + 1`：包含带噪潜在表示、条件潜在表示以及条件掩码。

encoder_hidden_states (`torch.Tensor`，形状为 `(batch_size, sequence_length, in_text_dim)`)：文本 token 嵌入，由视频和音频的文本分支共享。

pooled_projections (`torch.Tensor`，形状为 `(batch_size, in_text_dim2)`)：添加到两个分支的时间步嵌入中的池化文本嵌入。

timestep (`torch.Tensor`，形状为 `(batch_size,)`)：在 `[0, num_train_timesteps]` 尺度上的扩散时间步，两种模态共用。

audio_hidden_states (`torch.Tensor`，形状为 `(batch_size, audio_length, in_audio_dim)`，*可选*)：音频潜变量。如果省略，融合块将仅执行其视频路径。

visual_rope_pos (`tuple[torch.Tensor, torch.Tensor, torch.Tensor]`, *可选*) : 分块视频 token 的逐轴 `(t, h, w)` 旋转位置索引。默认情况下，对每个轴使用 `arange`。当流水线添加一个复用位置 `0` 的参考帧时，会传入显式的时间索引。

encoder_attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：`encoder_hidden_states` 的布尔填充掩码。当提示词未进行填充时，请传入 `None`。

visual_token_type_ids (`torch.Tensor`，形状为 `(batch_size, num_frames)`，*可选*)：逐帧的 token 类型 ID，通过 `visual_token_type_embeddings` 进行嵌入。要求 `visual_token_type_num_embeddings > 0`。

return_dict (`bool`，默认为 `True`)：是否返回 `Kandinsky6TransformerOutput` 而不是普通元组。

**返回：** `Kandinsky6TransformerOutput` 或 `tuple`

在 `(B, T, H, W, out_visual_dim)` 布局下的预测视频速度，以及当提供了 `audio_hidden_states` 时，形状为 `(B, audio_length, out_audio_dim)` 的预测音频速度。

## Kandinsky6SRTransformer3DModel[[diffusers.Kandinsky6SRTransformer3DModel]]

[Kandinsky6SRPipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/kandinsky6#diffusers.Kandinsky6SRPipeline) 用于逐块精修放大后视频的无文本 Transformer。

```python
import torch
from diffusers import Kandinsky6SRTransformer3DModel

transformer = Kandinsky6SRTransformer3DModel.from_pretrained(
    "kandinskylab/Kandinsky-6.0-VSR-distilled2steps-5s-Diffusers", subfolder="transformer", torch_dtype=torch.bfloat16
)
# The transformer always runs NABLA sparse attention (`nabla_threshold`, 0.8 by default) on the `flex` backend.
# Compile it, otherwise flex falls back to an eager implementation that needs far more memory at video resolutions.
transformer.compile_repeated_blocks(fullgraph=True)
```

#### diffusers.Kandinsky6SRTransformer3DModel[[diffusers.Kandinsky6SRTransformer3DModel]]

```python
diffusers.Kandinsky6SRTransformer3DModel(in_visual_dim: int = 64, out_visual_dim: int = 640, time_dim: int = 512, patch_size: tuple[int, int, int] = (1, 1, 1), model_dim: int = 1792, ff_dim: int = 7168, num_visual_blocks: int = 32, axes_dims: tuple[int, int, int] = (16, 24, 24), scale_factor: tuple[float, float, float] = (1.0, 2.0, 2.0), nabla_threshold: float = 0.8, nabla_window: tuple[int, int, int] = (11, 7, 7), tile_sizes: tuple[tuple[int, int], ...] = ((512, 512), (512, 768), (768, 512)))
```

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

**参数：**

in_visual_dim (`int`，默认为 `64`)：K-VAE 的潜在通道数。

out_visual_dim (`int`，默认为 `640`)：输出通道数。

time_dim (`int`，默认为 `512`)：时间步嵌入的维度。

patch_size (`tuple[int, int, int]`，默认为 `(1, 1, 1)`)：以 `(temporal, height, width)` 形式表示的 Patch 大小。

model_dim (`int`，默认为 `1792`)：transformer 的隐藏维度。

ff_dim (`int`，默认为 `7168`)：前馈网络的内部维度。

num_visual_blocks (`int`，默认为 `32`)：Transformer 块的数量。

axes_dims (`tuple[int, int, int]`，默认为 `(16, 24, 24)`)：RoPE 在 `(t, h, w)` 各轴上的维度；它们的总和即为注意力头维度。

scale_factor (`tuple[float, float, float]`，默认为 `(1.0, 2.0, 2.0)`)：应用于 token 位置的各轴 RoPE 频率缩放。

nabla_threshold (`float`，默认为 `0.8`)：NABLA 块选择的累积注意力阈值。

nabla_window (`tuple[int, int, int]`，默认值为 `(11, 7, 7)`)：滑动块先验的奇数 `(t, h, w)` 范围，每个 8x8 token 块始终会关注该范围。

tile_sizes (`tuple[tuple[int, int], ...]`，默认为 `((512, 512), (512, 768), (768, 512))`)：模型训练时使用的视频分块的像素 `(height, width)` 尺寸。[Kandinsky6SRPipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/kandinsky6#diffusers.Kandinsky6SRPipeline) 会以与输入视频宽高比最接近的尺寸来细化每个分块。

用于 Kandinsky 6 视频超分辨率的无文本扩散 Transformer。

该模型对 K-VAE 潜在视频的图块进行去噪。其输入将含噪潜在表示与用于条件化超分辨率的锚点潜在表示及锚点掩码进行拼接（`2 * in_visual_dim + 1` 个通道），其输出包含 `out_visual_dim` 个通道：对于普通速度检查点为 `in_visual_dim`，对于 [PiflowScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/piflow#diffusers.PiflowScheduler) 蒸馏检查点则为扩展后的 `n_grid * in_visual_dim`。视频自注意力通过 `flex` 注意力后端上的 NABLA 稀疏块模式运行，这要求令牌网格（`patch_size` 之后的 `height` 和 `width`）能被 8 整除。

#### forward[[diffusers.Kandinsky6SRTransformer3DModel.forward]]

```python
forward(hidden_states: Tensor, timestep: Tensor, return_dict: bool = True)
```

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

**参数：**

hidden_states (`torch.Tensor`，形状为 `(batch_size, num_frames, height, width, 2 * in_visual_dim + 1)`)：采用 `(B, T, H, W, C)` 布局的潜在瓦片：沿通道轴拼接的含噪潜在变量、锚点潜在变量和锚点掩码。

timestep (`torch.Tensor`，形状为 `(batch_size,)`)：在 `[0, num_train_timesteps]` 尺度上的扩散时间步。

return_dict (`bool`，默认为 `True`)：是否返回 [Transformer2DModelOutput](/docs/diffusers/v0.43.0/zh/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput) 而不是普通元组。

**返回：** [Transformer2DModelOutput](/docs/diffusers/v0.43.0/zh/api/models/cogview3plus_transformer2d#diffusers.models.modeling_outputs.Transformer2DModelOutput) 或 `tuple`

形状为 `(batch_size, num_frames, height, width, out_visual_dim)` 的预测结果。