Diffusers 中 WanAnimateTransformer3DModel 深度解析Wan2.2 面部动画驱动 Diffusion Transformer 的架构与使用【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers导读WanAnimateTransformer3DModel是 Diffusers 仓库中为 Wan Animate阿里 Wan 团队 Wan2.2 系列实现的面部动画驱动扩散 Transformer 模型它以 3D 视频潜变量为处理对象将参考人物图像、姿态视频、面部视频与文本提示统一融合实现高质量的角色动画生成。本文以 WanAnimateTransformer3DModel API 文档 为骨架结合 transformer_wan_animate.py 源码与 pipeline_wan_animate.py 调用链带你掌握模型的加载方式、完整架构、全部配置参数、前向输入输出约定以及它在 WanAnimatePipeline 中的实际工作方式。模型定位为面部驱动动画而生的扩散 TransformerWanAnimateTransformer3DModel 在 Wan Animate API 文档 中定位为用于类视频 3D 数据的 Diffusion Transformer 模型由阿里 Wan 团队在 Wan2.2 系列中提出。与普通文生视频 DiT 不同它的核心任务是以人物面部与姿态的运动信息作为条件信号驱动生成因此模型内部集成了两套为动画任务专门设计的编码器运动编码器Motion Encoder从面部视频的像素序列中提取紧凑的运动向量面部编码器Face Encoder把逐帧运动向量转化为可与 Transformer 主分支对齐的时间对齐特征并通过面部适配器注入到主干网络。从源码类定义transformer_wan_animate.py#L986-L988可以看到该类同时继承了ModelMixin、ConfigMixin、PeftAdapterMixin、FromOriginalModelMixin、CacheMixin与AttentionMixin这意味着它天然支持from_pretrained加载、LoRA/Peft 适配、原始权重转换、条件缓存与自定义注意力后端等 Diffusers 标准能力。快速加载一行代码加载 14B 动画 Transformer官方文档给出的加载方式如下from diffusers import WanAnimateTransformer3DModel transformer WanAnimateTransformer3DModel.from_pretrained( Wan-AI/Wan2.2-Animate-14B-Diffusers, subfoldertransformer, dtypetorch.bfloat16 )WanAnimateTransformer3DModel已通过 models/init.py#L153 注册进diffusers顶层命名空间因此可以直接from diffusers import。为了让上面的代码真正可运行需要补全torch导入并指定设备import torch from diffusers import WanAnimateTransformer3DModel transformer WanAnimateTransformer3DModel.from_pretrained( Wan-AI/Wan2.2-Animate-14B-Diffusers, subfoldertransformer, torch_dtypetorch.bfloat16, ) transformer.to(cuda)几个值得注意的加载细节subfoldertransformer仓库目录内模型权重存放于transformer子目录与 VAE、文本编码器umT5、CLIP等组件分开管理dtypetorch.bfloat1614B 级别参数在 FP32 下显存压力极大官方推荐以 bf16 加载推理从原始权重加载由于类实现了FromOriginalModelMixin也支持通过 single-file 方式从.gguf等单文件权重恢复详见下文量化与单文件加载一节。架构全景六段式前向流水线forward的实现transformer_wan_animate.py#L1155-L1306清晰地划分为六个阶段注释与官方实现一一对应旋转位置编码RoPEWanRotaryPosEmbed按 T/H/W 三个维度分别生成 1D 旋转位置频率并拼接输出形状为(1, ppf * pph * ppw, 1, head_dim)Patch 嵌入Patch Embeddingpatch_embedding与pose_patch_embedding是两个Conv3d前者把含参考帧的视频潜变量(B, 2C4, T1, H, W)打成 patch后者单独嵌入姿态潜变量随后姿态嵌入被加到主分支的后 T 帧上hidden_states[:, :, 1:] pose_hidden_states见 L1223再flatten(2).transpose(1, 2)变成序列形式条件嵌入时间/文本/图像WanTimeTextImageEmbedding基于 Wan2.1 的时间步逻辑输出temb、timestep_proj以及处理后的文本/图像嵌入图像嵌入CLIP 视觉特征会被concat到文本嵌入前方形成联合条件运动特征提取面部视频像素先经WanAnimateMotionEncoder得到逐帧运动向量再由WanAnimateFaceEncoder转成带时间因果性的面部特征Transformer 主干 面部适配器40 层WanTransformerBlock顺序执行每 5 层inject_face_latents_blocks插入一次WanAnimateFaceBlockCrossAttention的交叉注意力结果残差相加输出归一化与反 patchifynorm_outFP32 LayerNorm加 scale-shift 调制后经proj_out线性投影再reshape/permute/flatten还原为视频潜变量张量。关键子模块逐一拆解子模块类作用源码位置旋转位置编码WanRotaryPosEmbed对 T/H/W 三轴分别做 1D RoPE 并拼接L833Patch 嵌入nn.Conv3d× 2视频潜变量与姿态潜变量分别 patchify 后相加L1087-L1088条件嵌入WanTimeTextImageEmbedding时间步正弦嵌入 文本投影 图像嵌入L784运动编码器WanAnimateMotionEncoder外观卷积网络 运动线性网络 线性运动分解QR 正交化L282面部编码器WanAnimateFaceEncoder时间因果 Conv1d 多头含 padding token特征编码L356主干块WanTransformerBlock自注意力 交叉注意力 FFN带 scale-shift 调制L899面部适配器WanAnimateFaceBlockCrossAttention以运动特征为 KV 的临时对齐交叉注意力QK 带 RMSNormL493运动编码器内部L282-L353包含两条通路外观编码器由MotionConv2d卷积残差块逐级下采样最后接 4×4 卷积得到style_dim维外观特征运动网络则由多层MotionLinear构成源码注释特别提醒这些线性层之间没有激活函数这与官方实现保持一致。最终的线性运动分解操作把运动向量做成对角矩阵与motion_synthesis_weight的 QR 正交分解矩阵相乘再按行求和得到运动向量。源码中 QR 分解被刻意 upcast 到 FP32 以保证数值稳定性L340-L351。面部编码器L386-L419采用时间因果填充time_causal_padding (kernel_size - 1, 0)replicate模式的 Conv1d 串接 LayerNorm SiLU最后一维拼接一个可学习的 padding token把输出变成(B, T, N1, C_out)——多出的第N1个头用于吸收无运动帧。面部适配器注入逻辑在 L1273-L1279当block_idx % inject_face_latents_blocks 0时取对应的face_adapter[block_idx // inject_face_latents_blocks]执行交叉注意力并把输出与主干隐状态残差相加考虑到模型并行场景适配器输出会被显式搬到主干所在设备。配置参数全解以下参数均来自__init__的register_to_config签名transformer_wan_animate.py#L1040-L1069与类 docstringL992-L1023Wan2.2-Animate-14B 官方权重即使用这些默认值参数默认值含义patch_size(1, 2, 2)视频嵌入的 3D patch 尺寸(t_patch, h_patch, w_patch)num_attention_heads40注意力头数attention_head_dim128每个注意力头的通道数in_channels36输入通道数等于2 * latent_channels 4latent_channels16Wan VAE 的潜变量通道数out_channels16输出通道数缺省时回退为latent_channelstext_dim4096文本嵌入维度对应 umT5 输出freq_dim256正弦时间嵌入维度ffn_dim13824前馈网络中间维度num_layers40Transformer 块数量cross_attn_normTrue是否启用交叉注意力归一化qk_normrms_norm_across_headsQ/K 归一化方式eps1e-6归一化层 epsilonimage_dim1280图像嵌入通道数CLIP 视觉特征维度None表示不投影added_kv_proj_dimNone附加 KV 投影通道数None表示不启用rope_max_seq_len1024RoPE 最大序列长度pos_embed_seq_lenNone图像位置嵌入序列长度motion_encoder_channel_sizes默认字典运动编码器各分辨率通道数映射512→32 至 4→512motion_encoder_size512面部视频输入分辨率须为正方形motion_style_dim512外观特征维度motion_dim20运动向量维度motion_encoder_dim512运动编码器输出维度face_encoder_hidden_dim1024面部编码器隐藏维度face_encoder_num_heads4面部编码器头数inject_face_latents_blocks5每隔多少层注入一次面部特征motion_encoder_batch_size8面部视频按 batch 编码的批大小其中in_channels与latent_channels二选一即可——构造时若只给其一代码会自动按in_channels 2 * latent_channels 4推导L1074-L1082若两者都给则必须满足该恒等式否则直接断言报错。类级还声明了若干对下游生态至关重要的元属性L1025-L1038_supports_gradient_checkpointing True支持训练时梯度检查点blocks循环内会走_gradient_checkpointing_func分支_no_split_modules [WanTransformerBlock, MotionEncoderResBlock]accelerate 设备放置时按这些模块切分_keep_in_fp32_modulestime_embedder、scale_shift_table、各norm、motion_synthesis_weight、rope等数值敏感模块保持在 FP32_repeated_blocks [WanTransformerBlock]供循环权重共享与加载优化使用。前向输入输出约定forward的完整签名与形状约束L1155-L1166参数形状说明hidden_states(B, 2C4, T1, H, W)含参考帧的加噪视频潜变量C16 为 Wan VAE 潜变量通道timestep(B,)的torch.LongTensor去噪循环当前时间步encoder_hidden_states(B, seq, 4096)umT5 文本嵌入encoder_hidden_states_image(B, 257, 1280)参考人物图的 CLIP 视觉特征可选pose_hidden_states(B, C, T, H, W)姿态视频潜变量帧数须比hidden_states少 1否则抛 ValueErrorL1204-L1208face_pixel_values(B, 3, S, H, W)像素空间面部视频S 为推理段帧数官方为 77H/W 须与motion_encoder_size一致512×512motion_encode_batch_sizeint可选运动编码器的分批批大小缺省用配置值 8return_dictbool默认True返回字典还是元组attention_kwargsdict可选透传给 AttentionProcessor 的参数输出为Transformer2DModelOutputsample字段或纯元组sample为去噪后的视频潜变量。测试 test_models_transformer_wan_animate.py 中的真实尺寸 dummy 输入hidden_states(1,36,21,64,64)、pose_hidden_states(1,16,20,64,64)、face_pixel_values(1,3,77,512,512)完整印证了上述形状约定。在 WanAnimatePipeline 中的实际调用该模型通常不单独使用而是作为 WanAnimatePipeline 的transformer组件被驱动L28。管道内置的示例L50-L115展示了两种模式import torch from diffusers import WanAnimatePipeline from diffusers.utils import export_to_video, load_image, load_video model_id Wan-AI/Wan2.2-Animate-14B-Diffusers pipe WanAnimatePipeline.from_pretrained(model_id, torch_dtypetorch.bfloat16) pipe.vae.to(torch.float32) # 可选将 Wan VAE upcast 到 FP32 pipe.to(cuda) image load_image(path/to/reference_character.png) pose_video load_video(path/to/pose_video.mp4) face_video load_video(path/to/face_video.mp4) # 动画模式用姿态/面部视频驱动角色 output pipe( imageimage, pose_videopose_video, face_videoface_video, promptA woman speaking naturally, high quality, ultrarealistic detail., height720, width1280, segment_frame_length77, # 每个推理段的数据帧长度 guidance_scale1.0, # Wan Animate 一般不使用 CFG num_inference_steps20, modeanimate, ).frames[0] export_to_video(output, output_animation.mp4, fps30) # 替换模式在背景视频中替换角色需要额外提供背景与掩码视频 output pipe( imageimage, pose_videopose_video, face_videoface_video, background_videoload_video(path/to/background_video.mp4), mask_videoload_video(path/to/mask_video.mp4), # 黑色区域保留白色区域生成 promptA woman speaking naturally., height720, width1280, segment_frame_length77, guidance_scale1.0, num_inference_steps20, modereplace, ).frames[0]管道的去噪循环L1113-L1140揭示了模型的两个关键调用细节段式推理segment-wise长视频被切成segment_frame_length77帧的推理段逐段去噪段间通过前一帧潜变量做条件衔接prev_segment_conditioning_frames每一段都会调用一次self.transformer(...)并传入pose_hidden_states、face_pixel_values与motion_encode_batch_sizeCFG 的面部置空策略若启用 classifier-free guidance无条件分支会把面部视频像素整体置为-1face_pixel_values_uncond face_video_segment * 0 - 1其余输入保持不变——即抹掉面部信息而非抹掉文本这是面部驱动模型特有的 CFG 语义同时cache_context(cond)/cache_context(uncond)的缓存上下文说明该模型支持 Diffusers 的条件缓存机制。量化与单文件加载从测试矩阵可以确认该模型对多种量化与编译生态的支持见 test_models_transformer_wan_animate.pyBitsAndBytes 量化TestWanAnimateTransformer3DBitsAndBytes支持 int8 量化推理测试中真实维度输入为(1,36,5,16,16)等TorchAO 量化TestWanAnimateTransformer3DTorchAo支持 TorchAO 低比特量化使用 bf16 基座GGUF 量化TestWanAnimateTransformer3DGGUF/GGUFCompileTesterMixin可通过单文件 GGUF 权重如Wan2.2-Animate-14B-Q2_K.gguf加载并在 single_file_model.py#L172 中注册了WanAnimateTransformer3DModel的 single-file 映射torch.compileTorchCompileTesterMixin覆盖编译路径但测试特意跳过F.pad(modereplicate)WanAnimateFaceEncoder内的时间因果填充触发的 dynamo 图中断场景说明该模块在编译时存在已知限制内存与训练MemoryTesterMixin、TrainingTesterMixin含梯度检查点验证均有覆盖。测试验证与延伸阅读模型测试配置WanAnimateTransformer3DTesterConfigtest_models_transformer_wan_animate.py#L39-L143演示了如何用自定义小通道配置构建模型做快速验证其中特意缩小motion_encoder_channel_sizes否则运动编码器会占据测试模型绝大多数参数并断言输出通道数少于输入12→4这正对应主干只预测潜变量增量的设计。若需继续深入可顺藤摸瓜阅读Wan 管道 API 文档WanAnimatePipeline的完整参数说明与预处理要求姿态关键点、面部特征需预先从参考视频中提取WanAnimate2Transformer3DModel API 文档Wan2.2-Animate 的第二代变体其实现位于 transformer_wan_animate_2.py测试位于 test_models_transformer_wan_animate_2.pymodels/init.py 与 transformers/init.py查看该模型在diffusers中的导出与模块注册方式。总之WanAnimateTransformer3DModel把运动条件注入做到了模型内部运动编码器负责从人脸像素中提炼运动向量面部编码器负责时间对齐面部适配器负责把信号按固定间隔注入 40 层主干——理解这三者的协作方式是自定义训练或二次开发 Wan Animate 类应用的前提。【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考