# SanaWMTransformer3DModel 一个 3D 扩散 Transformer（16 亿参数），用于相机控制下的图像到视频生成，作为 [SanaWMPipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/sana_wm#diffusers.SanaWMPipeline) 的第一阶段采样器。该 Transformer 结合了： * 一个双向 GDN-Triton 线性注意力主干分支（深度 20，隐藏维度 2240，20 个注意力头）， * 一个 UCPE（Unified Camera Pose Embedding，统一相机位姿嵌入）相机控制分支，它接收所请求轨迹的 raymap + Plücker 表示， * 一种 Wan 风格的 3D 旋转位置嵌入，外加每隔 `softmax_every_n` 层注入一次的周期性 softmax 注意力块。 该模型可通过以下方式加载： ```python import torch from diffusers import SanaWMTransformer3DModel transformer = SanaWMTransformer3DModel.from_pretrained( "Efficient-Large-Model/SANA-WM_bidirectional-diffusers", subfolder="transformer", torch_dtype=torch.bfloat16, ) ``` ## SanaWMTransformer3DModel[[diffusers.SanaWMTransformer3DModel]] #### diffusers.SanaWMTransformer3DModel[[diffusers.SanaWMTransformer3DModel]] ```python diffusers.SanaWMTransformer3DModel(in_channels: int = 128, num_layers: int = 20, hidden_size: int = 2240, num_attention_heads: int = 20, patch_size: tuple[int, int, int] = (1, 1, 1), softmax_every_n: int = 4, linear_head_dim: int = 112, ffn_type: str = 'GLUMBConvTemp', t_kernel_size: int = 3, conv_kernel_size: int = 4, k_conv_only: bool = True, pos_embed_type: str = 'wan_rope', qk_norm: bool = True, cross_norm: bool = True, y_norm: bool = True, cam_attn_compress: int = 1, init_cam_from_base: bool = True, use_chunk_plucker_post_attn: bool = True, chunk_plucker_channels: int = 48, chunk_plucker_post_attn_blocks: int = 20, fp32_attention: bool = True, image_size: int = 720, caption_channels: int = 2304, mlp_ratio: float = 3.0, mlp_acts: tuple = ('silu', 'silu', None), use_pe: bool = True, learn_sigma: bool = False, pred_sigma: bool = False, mixed_precision: str = 'bf16') ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_sana_wm.py#L2663) **参数：** in_channels (*int*，默认为 128)：VAE 潜在通道数（LTX-2）。 softmax_every_n (*int*，默认为 4)：每 N 个块使用一个 softmax 注意力块。 linear_head_dim (*int*，默认为 112)：GDN 头维度。 ffn_type (*str*，默认为 `"GLUMBConvTemp"`)：FFN。 t_kernel_size (*int*，默认为 3)：时间卷积核。 conv_kernel_size (*int*，默认为 4)：注意力机制中的空间卷积核。 k_conv_only (*bool*，默认为 True)：仅对 K 应用卷积。 pos_embed_type (*str*，默认为 `"wan_rope"`)：位置嵌入。 qk_norm (*bool*，默认为 True) : 对 Q/K 应用 RMSNorm。 cross_norm (*bool*，默认为 True) : 对交叉注意力中的 K 应用 RMSNorm。 y_norm (*bool*，默认为 True)：对文本嵌入应用 `attention_y_norm`。 init_cam_from_base (*bool*，默认为 True)：未使用；相机分支从检查点加载。保留此参数以便已发布的 *config.json* 文件能够正常加载。 use_chunk_plucker_post_attn (*bool*，默认为 True)。-- chunk_plucker_channels (*int*，默认为 48)：`6 dims * temporal_stride 8`。 chunk_plucker_post_attn_blocks (*int*，默认为 20)：所有块。 fp32_attention (*bool*，默认为 True)：未使用；注意力始终在 fp32 下运行。保留此参数以便加载已发布的 *config.json* 文件。 image_size (*int*，默认值为 720)：标称图像尺寸。 caption_channels (*int*，默认为 2304)：Gemma-2 的隐藏层大小。 SANA-WM 1600M 双向相机控制 DiT。 单类 DiT（depth=20，hidden_size=2240，patch_size=(1,1,1)，num_heads=20 —— 即公开的 `Efficient-Large-Model/SANA-WM_bidirectional` 版本）。`save_pretrained` / `from_pretrained` 通过 [ConfigMixin](/docs/diffusers/v0.43.0/zh/api/configuration#diffusers.ConfigMixin) 开箱即用。 每个块都会执行一个相机条件（UCPE）注意力机制：[*BidirectionalGDNUCPESinglePathLiteLA*]，但每隔 `softmax_every_n` 个块会执行其对应的 softmax 版本 [*_SoftmaxUCPESinglePathLiteLA*]。 state-dict 与公开的 sana 检查点完全相同，只是有意移除了 `pos_embed` 缓冲区。 #### forward[[diffusers.SanaWMTransformer3DModel.forward]] ```python forward(hidden_states: torch.Tensor, timestep: torch.Tensor, encoder_hidden_states: torch.Tensor, encoder_attention_mask: torch.Tensor | None = None, mask: torch.Tensor | None = None, return_dict: bool = True, data_info: Optional[dict] = None, camera_conditions: torch.Tensor | None = None, chunk_plucker: torch.Tensor | None = None, cam_pos_embeds: Optional[dict] = None, pos_embeds: torch.Tensor | None = None, raymats: torch.Tensor | None = None, frame_valid_mask: torch.Tensor | None = None, chunk_size: int | None = None) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_sana_wm.py#L2896) **参数：** hidden_states : `(B, C, T, H, W)` 潜在变量。 timestep : `(B, 1, T)` 逐帧扩散时间步（LTX 风格）。 encoder_hidden_states : `(B, 1, L, D_caption)` 文本嵌入。 encoder_attention_mask : `(B, L)` 文本注意力掩码（diffusers 约定）。 mask : `encoder_attention_mask` 的别名，用于匹配 sana DiT 的关键字参数名称。如果同时传入两者，`mask` 优先。 return_dict : 如果 `True`（默认值），则返回一个 `Transformer2DModelOutput`；否则返回一个单元素元组 `(sample,)`。 data_info : 额外的条件；当 `data_info["image_vae_embeds"]` 存在时，会沿通道轴与潜变量拼接。 camera_conditions : `(B, T, 20)` 原始相机条件，用于驱动相机控制（UCPE）分支。 chunk_plucker : Plucker 光线嵌入 `(B, C, T, H, W)`，在模型配置为 `use_chunk_plucker_input` / `use_chunk_plucker_post_attn` 时使用。 cam_pos_embeds : 可选的预计算相机位置嵌入（`"absmap"` / `"P"` 条目），用于复用而非重新计算。 pos_embeds : 可选的预计算旋转位置嵌入；当 `None` 时，它们将根据潜在形状构建。 raymats : 可选的预计算 UCPE 射线矩阵（仅在 `cam_pos_embeds` 不包含 `"P"` 时使用）。 frame_valid_mask : 可选的逐帧有效性掩码，形状为 `(B, 1, T, 1, 1)`、`(B, 1, T)` 或 `(B, T)`。 chunk_size : 转发给各块的块长度覆盖值；若未指定，则回退到每个块配置的 `chunk_size`。 **返回值：** `Transformer2DModelOutput`，其中 `sample` 的形状为 `(B, C, T, H, W)`。 运行 SANA-WM DiT。 #### unpatchify[[diffusers.SanaWMTransformer3DModel.unpatchify]] ```python unpatchify(x, post_patch_num_frames, post_patch_height, post_patch_width) ``` [源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/transformer_sana_wm.py#L3099) x: (N, T, patch_size**2 * C) imgs: (N, H, W, C) ## 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/v0.43.0/src/diffusers/models/modeling_outputs.py#L21) **参数：** sample (`torch.Tensor`，形状为 `(batch_size, num_channels, height, width)`；若 [Transformer2DModel](/docs/diffusers/v0.43.0/zh/api/models/transformer2d#diffusers.Transformer2DModel) 为离散模式，则为 `(batch size, num_vector_embeds - 1, num_latent_pixels)`)：以 `encoder_hidden_states` 输入为条件的隐藏状态输出。若为离散模式，则返回未加噪潜在像素的概率分布。 [Transformer2DModel](/docs/diffusers/v0.43.0/zh/api/models/transformer2d#diffusers.Transformer2DModel) 的输出。