Diffusers 中的 UNetMotionModel为视频扩散构建时空 UNet 的完整指南【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers导读本文围绕 Diffusers 仓库中的UNetMotionModel展开它是为视频生成以 AnimateDiff 为代表设计的二维空间 UNet 时间注意力混合架构在经典 2D UNet 之上插入运动模块Motion Module从而在保持图像空间建模能力的同时学习帧间时间依赖。读完本文你将掌握UNet 在扩散系统中的角色、UNetMotionModel的构造参数与内部模块划分、如何通过from_unet2d把UNet2DConditionModel升级为运动版 UNet、如何借助MotionAdapter冻结/保存/加载运动模块进行微调以及它在 AnimateDiff 系列 pipeline 中的实际调用方式。UNet 的起源与在扩散系统中的地位UNetMotionModel所属的 UNet 家族最初由 Ronneberger 等人在论文 U-Net: Convolutional Networks for Biomedical Image Segmentation 中提出用于生物医学图像分割。它之所以在 Diffusers 中被广泛使用是因为它输出的图像与输入尺寸相同是扩散系统中最重要的组件之一——它实际承载了去噪denoising这一核心过程。根据维度的不同以及是否为条件模型 Diffusers 中存在多种 UNet 变体而本文的主角UNetMotionModel是一个面向视频数据的 2D UNet 变体。原论文摘要如下可以帮助你理解 UNet 的对称编码器-解码器设计动机业界普遍认为深度网络的成功训练需要成千上万张带标注的训练样本。本文提出了一种网络与训练策略依靠数据增强的强有力使用来更高效地利用可用标注样本。该架构包含一条用于捕捉上下文的收缩路径contracting path和一条实现精确定位的对称扩展路径expanding path。我们证明了这种网络可以仅凭极少量图像进行端到端训练并在电子显微镜堆栈神经元结构分割的 ISBI 挑战中显著优于此前最佳方法滑动窗口卷积网络。使用在同一网络上训练的透射光显微图像相衬和 DIC分割结果我们以较大优势赢得了 ISBI 2015 细胞追踪挑战赛的多个类别。此外该网络速度很快在现代 GPU 上分割一张 512x512 图像耗时不到一秒。完整实现基于 Caffe和训练好的网络可在 http://lmb.informatik.uni-freiburg.de/people/ronneber/u-net 获取。一句话概括UNet 的收缩路径捕捉上下文 对称扩展路径实现精确定位的对称结构恰好适配扩散模型输入与输出同尺寸的需求因此成为扩散去噪网络的主流骨架。UNetMotionModel 概览空间卷积 时间注意力的混合体UNetMotionModel定义在 src/diffusers/models/unets/unet_motion_model.py其类文档描述为A modified conditional 2D UNet model that takes a noisy sample, conditional state, and a timestep and returns a sample shaped output.一个经过改造的条件 2D UNet 模型接收带噪样本、条件状态与时间步返回与样本同形状的输出。它继承自ModelMixin、AttentionMixin、ConfigMixin、UNet2DConditionLoadersMixin与PeftAdapterMixin因此天然具备模型保存/加载、注意力处理器管理与 LoRA/PEFT 适配能力。类上还声明了_supports_gradient_checkpointing True支持梯度检查点以节省显存。从架构上看它与标准UNet2DConditionModel的空间骨干完全一致Conv2d 输入输出、ResNet block、下/上采样、跨注意力区别在于在每个 down/up block 和 mid block 中额外插入了时间维度的运动模块motion module这些模块使用AnimateDiffTransformer3D对帧维做注意力建模。因此它处理的是形状为(batch, num_frames, channel, height, width)的 5D 视频潜变量。对应地它的内部 block 类型也分为四类全部定义在同一文件中Block 类位置功能DownBlockMotion下采样路径空间 ResNet 运动模块无跨注意力CrossAttnDownBlockMotion下采样路径空间 ResNet 跨注意力 运动模块UpBlockMotion上采样路径空间 ResNet 运动模块无跨注意力CrossAttnUpBlockMotion上采样路径空间 ResNet 跨注意力 运动模块UNetMidBlockCrossAttnMotion中间层最低分辨率处的跨注意力 运动模块运动模块本身由MotionModulesunet_motion_model.py容器承载其内部核心是AnimateDiffTransformer3Dunet_motion_model.py这是一个面向视频类数据的 Transformer在前向时把(batch_frames, channel, height, width)重排为(batch_size * height * width, num_frames, channel)从而让注意力在帧维上运行捕捉运动信息其默认配置为num_attention_heads16、attention_head_dim88、激活函数geglu、double_self_attentionTrue。构造参数详解UNetMotionModel.__init__通过register_to_config把全部参数写入模型配置核心参数如下均为默认值参数默认值说明sample_sizeNone训练时固定的潜变量宽度离散输入用于学习位置嵌入in_channels/out_channels4/4输入/输出通道数使用 PIA 类 adapter 时输入通道可扩展为 9down_block_types三个CrossAttnDownBlockMotionDownBlockMotion下采样路径 block 类型up_block_typesUpBlockMotion 三个CrossAttnUpBlockMotion上采样路径 block 类型与 down 对称block_out_channels(320, 640, 1280, 1280)各分辨率层级输出通道数与 down block 数一致layers_per_block2每个 block 内 ResNet/注意力层数downsample_padding1下采样卷积 paddingmid_block_scale_factor1mid block 输出缩放因子act_fnsilu激活函数norm_num_groups32GroupNorm 分组数置None可跳过输出归一化norm_eps1e-5GroupNorm epsiloncross_attention_dim1280文本/条件编码器隐藏维度transformer_layers_per_block1每个空间 transformer block 的层数reverse_transformer_layers_per_blockNone非对称 UNet 上采样侧空间 transformer 层数temporal_transformer_layers_per_block1每个运动模块内的 Transformer 层数reverse_temporal_transformer_layers_per_blockNone非对称运动模块的上采样侧层数transformer_layers_per_mid_blockNonemid block 空间 transformer 层数默认取最后一个 down block 的值temporal_transformer_layers_per_mid_block1mid block 运动模块 Transformer 层数use_linear_projectionFalse是否使用线性投影替代卷积投影num_attention_heads8空间注意力头数可逐 block 指定motion_max_seq_length32运动模块最大序列长度即最大帧数motion_num_attention_heads8运动模块注意力头数可逐 block 指定reverse_motion_num_attention_headsNone上采样侧运动注意力头数use_motion_mid_blockTrue是否在 mid block 使用运动模块mid_block_layers1mid block 层数encoder_hid_dim/encoder_hid_dim_typeNone图像/其他编码器投影配置如ip_image_proj用于 IP-Adapteraddition_embed_typeNone附加条件嵌入类型如text_timeaddition_time_embed_dim/projection_class_embeddings_input_dimNonetext_time条件的时间嵌入维度与投影输入维度time_cond_proj_dimNone时间步条件投影维度构造时源码会执行若干一致性校验unet_motion_model.pydown_block_types与up_block_types数量必须一致、block_out_channels必须与 down block 数一致、num_attention_heads/layers_per_block/cross_attention_dim若以列表形式给出则长度必须匹配 block 数若使用非对称 UNet列表内嵌列表则必须显式提供对应的reverse_*参数否则抛出ValueError。forward 的输入与输出forward方法unet_motion_model.py接收的关键参数sample带噪输入形状(batch, num_frames, channel, height, width)timestep去噪时间步张量/浮点/整数均可会自动转换并广播到 batch 维encoder_hidden_states条件编码器隐藏状态形状(batch, seq_len, feature_dim)用于跨注意力timestep_cond可选的时间步条件嵌入会与time_embedding输出相加attention_mask形状(batch, key_tokens)1 保留、0 丢弃内部转为大负数 biascross_attention_kwargs透传给AttentionProcessor的参数字典用于 LoRA/IP-Adapter 等added_cond_kwargs附加条件如text_embeds、time_ids、image_embedsdown_block_additional_residuals/mid_block_additional_residual可选的额外残差用于 ControlNet 类结构return_dict为True时返回UNetMotionOutput否则返回仅含 sample 的 tuple。前向流程与标准 UNet 一致时间步嵌入 →conv_in预处理把 5D 输入展平为 4D 逐帧卷积→ down blocks → mid block → up blocks通过跳跃连接融合下采样残差→conv_norm_outconv_actconv_out后处理最终把输出重新 reshape 回(batch, channel, num_frames, height, width)返回。输出封装为UNetMotionOutputunet_motion_model.py其sample字段形状为(batch_size, num_channels, num_frames, height, width)。另外当输入的空间尺寸不是总上采样因子2 ** num_upsamplers的整数倍时代码会自动转发upsample_size强制插值输出尺寸保证任意输入尺寸可运行unet_motion_model.py。从 UNet2DConditionModel 一键升级from_unet2dUNetMotionModel不需要从零训练空间部分而是通过类方法from_unet2dunet_motion_model.py把已有的UNet2DConditionModel权重迁移过来unet UNetMotionModel.from_unet2d(unet, motion_adapter)其内部逻辑为若传入motion_adapter先做兼容性校验down_block_types数量必须等于 adapter 的block_out_channels数量展开后的layers_per_block必须等于 adapter 的motion_layers_per_block否则抛出ValueError基于unet.config生成新配置把down_block_types中含CrossAttn的替换为CrossAttnDownBlockMotion、其余替换为DownBlockMotion上采样侧同理并把 adapter 的motion_num_attention_heads、motion_max_seq_length、use_motion_mid_block、motion_layers_per_block等参数合并进新配置unet_motion_model.py迁移权重conv_in、time_proj、time_embedding、各 down/up block 的resnets、attentions、采样器、mid block、conv_norm_out/conv_act/conv_out全部从原 UNet 的 state_dict 加载若 adapter 配置了conv_in_channelsPIA 场景输入通道为 9会把 adapter 的conv_in与 UNet 的conv_in权重沿通道维拼接前 4 通道来自原 UNet后 5 通道来自 PIA实现图文对齐的输入扩展unet_motion_model.py若原 UNet 使用了 IP-Adapter 注意力处理器会保留并重建对应的IPAdapterAttnProcessor/IPAdapterAttnProcessor2_0同时把encoder_hid_dim_type设为ip_image_projunet_motion_model.py最后调用load_motion_modules(motion_adapter)载入运动模块权重并把整个模型 dtype 对齐到原 UNet。load_motion_modulesunet_motion_model.py遍历 adapter 的 down/up/mid blocks把其中motion_modules的 state_dict 复制到新模型对应位置同时兼容旧版运动模块没有 mid_block的情况。MotionAdapter可插拔的运动模块容器MotionAdapterunet_motion_model.py是 AnimateDiff 运动模块的容器继承ModelMixin、ConfigMixin、FromOriginalModelMixin可独立save_pretrained/from_pretrained也支持从原始 AnimateDiff checkpoint 转换。其关键配置参数参数默认值说明block_out_channels(320, 640, 1280, 1280)各 block 输出通道决定运动模块插入位置motion_layers_per_block2每个 block 的运动层数可为逐 block 元组motion_transformer_layers_per_block1每个运动层内的 Transformer 层数motion_mid_block_layers_per_block1mid block 运动层数motion_transformer_layers_per_mid_block1mid block 运动 Transformer 层数motion_num_attention_heads8运动注意力头数motion_norm_num_groups32运动模块 GroupNorm 分组数motion_max_seq_length32运动模块最大序列长度帧数上限use_motion_mid_blockTrue是否在 mid block 放置运动模块conv_in_channelsNone非 None 时如 9为 PIA 模式额外构造输入卷积adapter 的forward为空实现占位它只负责存储结构实际计算发生在其内部MotionModules被合并进UNetMotionModel之后。使用时直接加载预训练权重即可from diffusers import MotionAdapter adapter MotionAdapter.from_pretrained(guoyww/animatediff-motion-adapter-v1-5-2)训练与微调只训练运动模块UNetMotionModel为视频生成微调提供了专门方法freeze_unet2d_paramsunet_motion_model.py冻结全部参数后仅解冻各 down/up block 及 mid block 中的motion_modules。这正是 AnimateDiff 训练范式的关键——空间 UNet 权重保持不动只优化新增的运动模块从而用较少数据和显存学会时间一致性save_motion_modulesunet_motion_model.py从模型 state_dict 中筛选所有含motion_modules的键重新包装为MotionAdapter并调用save_pretrained保存支持safe_serialization、variant与push_to_hub参数。这样微调产物是一个轻量的 motion adapter可独立分享模型同时支持enable_gradient_checkpointing继承自ModelMixin进一步降低视频训练/推理显存占用。推理期的内存与速度优化除了训练推理侧也提供了一系列与UNet2DConditionModel对齐的优化 APIenable_forward_chunking(chunk_sizeNone, dim0)/disable_forward_chunking()unet_motion_model.py对 Transformer 的前馈层做分块计算Reformer 风格dim0按 batch 分块、dim1按序列长度分块换取更低显存enable_freeu(s1, s2, b1, b2)/disable_freeu()unet_motion_model.py启用 FreeU论文 2309.11497机制通过衰减跳跃特征s1/s2与放大骨干特征b1/b2缓解过度平滑提升生成质量fuse_qkv_projections()/unfuse_qkv_projections()unet_motion_model.py把自注意力中的 Q/K/V 投影矩阵融合为单个算子、跨注意力融合 K/V配合FusedAttnProcessor2_0提升推理速度标记为实验性 APIset_default_attn_processor()按当前处理器类型AddedKV 或普通跨注意力恢复默认注意力实现。在 AnimateDiff pipeline 中的实际调用UNetMotionModel的实际应用场景是视频生成。在 src/diffusers/pipelines/animatediff/pipeline_animatediff.py 中AnimateDiffPipeline接收一个UNet2DConditionModel | UNetMotionModel若传入的是 2D UNet则 pipeline 内部自动执行unet UNetMotionModel.from_unet2d(unet, motion_adapter)完成升级from diffusers import AnimateDiffPipeline, MotionAdapter, DiffusionPipeline, DPMSolverMultistepScheduler adapter MotionAdapter.from_pretrained(guoyww/animatediff-motion-adapter-v1-5-2) pipe DiffusionPipeline.from_pretrained( stable-diffusion-v1-5/stable-diffusion-v1-5, motion_adapteradapter )同样的模式还出现在pipeline_animatediff_controlnet.py、pipeline_animatediff_sdxl.py、pipeline_animatediff_sparsectrl.py等 pipeline 中它们均以UNetMotionModel.from_unet2d(unet, motion_adapter)为桥梁在既有 Stable Diffusion 空间模型之上叠加运动建模能力。测试与验证仓库为UNetMotionModel提供了完整测试tests/models/unets/test_models_unet_motion.py其中UNetMotionModelTesterConfig使用block_out_channels(16, 32)、down_block_types(CrossAttnDownBlockMotion, DownBlockMotion)、up_block_types(UpBlockMotion, CrossAttnUpBlockMotion)的迷你配置验证模型前向输出形状(4, 4, 16, 16)并组合了ModelTesterMixin、AttentionTesterMixin、MemoryTesterMixin、TrainingTesterMixin等通用测试套件覆盖前向/反向、注意力处理器、显存峰值与训练稳定性。此外 tests/single_file/test_model_motion_adapter_single_file.py 验证MotionAdapter从原始单文件 checkpoint 的转换加载tests/pipelines/animatediff/ 下的测试则端到端验证 AnimateDiff 系列 pipeline 的推理行为。关于文档中引用的 UNet3DConditionOutputUNetMotionModel的 API 文档还交叉引用了UNet3DConditionOutputdiffusers.models.unets.unet_3d_condition.UNet3DConditionOutput它是三维条件 UNetUNet3DConditionModel另一种真正在三维空间卷积的视频 UNet 变体的输出封装。需要区分的是UNetMotionModel的空间骨干仍是 2D 卷积时间维度交给注意力运动模块处理而UNet3DConditionModel则直接使用 3D 卷积与时空注意力。两者都面向视频但实现范式不同使用时根据目标模型如 AnimateDiff 风格 vs. 原生 3D 视频 UNet选择即可。小结UNetMotionModel是 Diffusers 中图像扩散模型升级为视频扩散模型的关键组件它复用了成熟 2D UNet 的空间权重通过MotionAdapter注入时间注意力运动模块并以from_unet2d实现平滑迁移配合freeze_unet2d_params/save_motion_modules可以低成本微调出可分享的轻量运动适配器enable_forward_chunking/enable_freeu/fuse_qkv_projections等 API 则覆盖了推理期的显存与速度优化。想深入源码可重点关注 unet_motion_model.py 中的UNetMotionModel、MotionAdapter、AnimateDiffTransformer3D三个类以及 tests/models/unets/test_models_unet_motion.py 的迷你配置测试。【免费下载链接】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），仅供参考 Diffusers 中的 UNetMotionModel：为视频扩散构建时空 UNet 的完整指南
Diffusers 中的 UNetMotionModel为视频扩散构建时空 UNet 的完整指南【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers导读本文围绕 Diffusers 仓库中的UNetMotionModel展开它是为视频生成以 AnimateDiff 为代表设计的二维空间 UNet 时间注意力混合架构在经典 2D UNet 之上插入运动模块Motion Module从而在保持图像空间建模能力的同时学习帧间时间依赖。读完本文你将掌握UNet 在扩散系统中的角色、UNetMotionModel的构造参数与内部模块划分、如何通过from_unet2d把UNet2DConditionModel升级为运动版 UNet、如何借助MotionAdapter冻结/保存/加载运动模块进行微调以及它在 AnimateDiff 系列 pipeline 中的实际调用方式。UNet 的起源与在扩散系统中的地位UNetMotionModel所属的 UNet 家族最初由 Ronneberger 等人在论文 U-Net: Convolutional Networks for Biomedical Image Segmentation 中提出用于生物医学图像分割。它之所以在 Diffusers 中被广泛使用是因为它输出的图像与输入尺寸相同是扩散系统中最重要的组件之一——它实际承载了去噪denoising这一核心过程。根据维度的不同以及是否为条件模型 Diffusers 中存在多种 UNet 变体而本文的主角UNetMotionModel是一个面向视频数据的 2D UNet 变体。原论文摘要如下可以帮助你理解 UNet 的对称编码器-解码器设计动机业界普遍认为深度网络的成功训练需要成千上万张带标注的训练样本。本文提出了一种网络与训练策略依靠数据增强的强有力使用来更高效地利用可用标注样本。该架构包含一条用于捕捉上下文的收缩路径contracting path和一条实现精确定位的对称扩展路径expanding path。我们证明了这种网络可以仅凭极少量图像进行端到端训练并在电子显微镜堆栈神经元结构分割的 ISBI 挑战中显著优于此前最佳方法滑动窗口卷积网络。使用在同一网络上训练的透射光显微图像相衬和 DIC分割结果我们以较大优势赢得了 ISBI 2015 细胞追踪挑战赛的多个类别。此外该网络速度很快在现代 GPU 上分割一张 512x512 图像耗时不到一秒。完整实现基于 Caffe和训练好的网络可在 http://lmb.informatik.uni-freiburg.de/people/ronneber/u-net 获取。一句话概括UNet 的收缩路径捕捉上下文 对称扩展路径实现精确定位的对称结构恰好适配扩散模型输入与输出同尺寸的需求因此成为扩散去噪网络的主流骨架。UNetMotionModel 概览空间卷积 时间注意力的混合体UNetMotionModel定义在 src/diffusers/models/unets/unet_motion_model.py其类文档描述为A modified conditional 2D UNet model that takes a noisy sample, conditional state, and a timestep and returns a sample shaped output.一个经过改造的条件 2D UNet 模型接收带噪样本、条件状态与时间步返回与样本同形状的输出。它继承自ModelMixin、AttentionMixin、ConfigMixin、UNet2DConditionLoadersMixin与PeftAdapterMixin因此天然具备模型保存/加载、注意力处理器管理与 LoRA/PEFT 适配能力。类上还声明了_supports_gradient_checkpointing True支持梯度检查点以节省显存。从架构上看它与标准UNet2DConditionModel的空间骨干完全一致Conv2d 输入输出、ResNet block、下/上采样、跨注意力区别在于在每个 down/up block 和 mid block 中额外插入了时间维度的运动模块motion module这些模块使用AnimateDiffTransformer3D对帧维做注意力建模。因此它处理的是形状为(batch, num_frames, channel, height, width)的 5D 视频潜变量。对应地它的内部 block 类型也分为四类全部定义在同一文件中Block 类位置功能DownBlockMotion下采样路径空间 ResNet 运动模块无跨注意力CrossAttnDownBlockMotion下采样路径空间 ResNet 跨注意力 运动模块UpBlockMotion上采样路径空间 ResNet 运动模块无跨注意力CrossAttnUpBlockMotion上采样路径空间 ResNet 跨注意力 运动模块UNetMidBlockCrossAttnMotion中间层最低分辨率处的跨注意力 运动模块运动模块本身由MotionModulesunet_motion_model.py容器承载其内部核心是AnimateDiffTransformer3Dunet_motion_model.py这是一个面向视频类数据的 Transformer在前向时把(batch_frames, channel, height, width)重排为(batch_size * height * width, num_frames, channel)从而让注意力在帧维上运行捕捉运动信息其默认配置为num_attention_heads16、attention_head_dim88、激活函数geglu、double_self_attentionTrue。构造参数详解UNetMotionModel.__init__通过register_to_config把全部参数写入模型配置核心参数如下均为默认值参数默认值说明sample_sizeNone训练时固定的潜变量宽度离散输入用于学习位置嵌入in_channels/out_channels4/4输入/输出通道数使用 PIA 类 adapter 时输入通道可扩展为 9down_block_types三个CrossAttnDownBlockMotionDownBlockMotion下采样路径 block 类型up_block_typesUpBlockMotion 三个CrossAttnUpBlockMotion上采样路径 block 类型与 down 对称block_out_channels(320, 640, 1280, 1280)各分辨率层级输出通道数与 down block 数一致layers_per_block2每个 block 内 ResNet/注意力层数downsample_padding1下采样卷积 paddingmid_block_scale_factor1mid block 输出缩放因子act_fnsilu激活函数norm_num_groups32GroupNorm 分组数置None可跳过输出归一化norm_eps1e-5GroupNorm epsiloncross_attention_dim1280文本/条件编码器隐藏维度transformer_layers_per_block1每个空间 transformer block 的层数reverse_transformer_layers_per_blockNone非对称 UNet 上采样侧空间 transformer 层数temporal_transformer_layers_per_block1每个运动模块内的 Transformer 层数reverse_temporal_transformer_layers_per_blockNone非对称运动模块的上采样侧层数transformer_layers_per_mid_blockNonemid block 空间 transformer 层数默认取最后一个 down block 的值temporal_transformer_layers_per_mid_block1mid block 运动模块 Transformer 层数use_linear_projectionFalse是否使用线性投影替代卷积投影num_attention_heads8空间注意力头数可逐 block 指定motion_max_seq_length32运动模块最大序列长度即最大帧数motion_num_attention_heads8运动模块注意力头数可逐 block 指定reverse_motion_num_attention_headsNone上采样侧运动注意力头数use_motion_mid_blockTrue是否在 mid block 使用运动模块mid_block_layers1mid block 层数encoder_hid_dim/encoder_hid_dim_typeNone图像/其他编码器投影配置如ip_image_proj用于 IP-Adapteraddition_embed_typeNone附加条件嵌入类型如text_timeaddition_time_embed_dim/projection_class_embeddings_input_dimNonetext_time条件的时间嵌入维度与投影输入维度time_cond_proj_dimNone时间步条件投影维度构造时源码会执行若干一致性校验unet_motion_model.pydown_block_types与up_block_types数量必须一致、block_out_channels必须与 down block 数一致、num_attention_heads/layers_per_block/cross_attention_dim若以列表形式给出则长度必须匹配 block 数若使用非对称 UNet列表内嵌列表则必须显式提供对应的reverse_*参数否则抛出ValueError。forward 的输入与输出forward方法unet_motion_model.py接收的关键参数sample带噪输入形状(batch, num_frames, channel, height, width)timestep去噪时间步张量/浮点/整数均可会自动转换并广播到 batch 维encoder_hidden_states条件编码器隐藏状态形状(batch, seq_len, feature_dim)用于跨注意力timestep_cond可选的时间步条件嵌入会与time_embedding输出相加attention_mask形状(batch, key_tokens)1 保留、0 丢弃内部转为大负数 biascross_attention_kwargs透传给AttentionProcessor的参数字典用于 LoRA/IP-Adapter 等added_cond_kwargs附加条件如text_embeds、time_ids、image_embedsdown_block_additional_residuals/mid_block_additional_residual可选的额外残差用于 ControlNet 类结构return_dict为True时返回UNetMotionOutput否则返回仅含 sample 的 tuple。前向流程与标准 UNet 一致时间步嵌入 →conv_in预处理把 5D 输入展平为 4D 逐帧卷积→ down blocks → mid block → up blocks通过跳跃连接融合下采样残差→conv_norm_outconv_actconv_out后处理最终把输出重新 reshape 回(batch, channel, num_frames, height, width)返回。输出封装为UNetMotionOutputunet_motion_model.py其sample字段形状为(batch_size, num_channels, num_frames, height, width)。另外当输入的空间尺寸不是总上采样因子2 ** num_upsamplers的整数倍时代码会自动转发upsample_size强制插值输出尺寸保证任意输入尺寸可运行unet_motion_model.py。从 UNet2DConditionModel 一键升级from_unet2dUNetMotionModel不需要从零训练空间部分而是通过类方法from_unet2dunet_motion_model.py把已有的UNet2DConditionModel权重迁移过来unet UNetMotionModel.from_unet2d(unet, motion_adapter)其内部逻辑为若传入motion_adapter先做兼容性校验down_block_types数量必须等于 adapter 的block_out_channels数量展开后的layers_per_block必须等于 adapter 的motion_layers_per_block否则抛出ValueError基于unet.config生成新配置把down_block_types中含CrossAttn的替换为CrossAttnDownBlockMotion、其余替换为DownBlockMotion上采样侧同理并把 adapter 的motion_num_attention_heads、motion_max_seq_length、use_motion_mid_block、motion_layers_per_block等参数合并进新配置unet_motion_model.py迁移权重conv_in、time_proj、time_embedding、各 down/up block 的resnets、attentions、采样器、mid block、conv_norm_out/conv_act/conv_out全部从原 UNet 的 state_dict 加载若 adapter 配置了conv_in_channelsPIA 场景输入通道为 9会把 adapter 的conv_in与 UNet 的conv_in权重沿通道维拼接前 4 通道来自原 UNet后 5 通道来自 PIA实现图文对齐的输入扩展unet_motion_model.py若原 UNet 使用了 IP-Adapter 注意力处理器会保留并重建对应的IPAdapterAttnProcessor/IPAdapterAttnProcessor2_0同时把encoder_hid_dim_type设为ip_image_projunet_motion_model.py最后调用load_motion_modules(motion_adapter)载入运动模块权重并把整个模型 dtype 对齐到原 UNet。load_motion_modulesunet_motion_model.py遍历 adapter 的 down/up/mid blocks把其中motion_modules的 state_dict 复制到新模型对应位置同时兼容旧版运动模块没有 mid_block的情况。MotionAdapter可插拔的运动模块容器MotionAdapterunet_motion_model.py是 AnimateDiff 运动模块的容器继承ModelMixin、ConfigMixin、FromOriginalModelMixin可独立save_pretrained/from_pretrained也支持从原始 AnimateDiff checkpoint 转换。其关键配置参数参数默认值说明block_out_channels(320, 640, 1280, 1280)各 block 输出通道决定运动模块插入位置motion_layers_per_block2每个 block 的运动层数可为逐 block 元组motion_transformer_layers_per_block1每个运动层内的 Transformer 层数motion_mid_block_layers_per_block1mid block 运动层数motion_transformer_layers_per_mid_block1mid block 运动 Transformer 层数motion_num_attention_heads8运动注意力头数motion_norm_num_groups32运动模块 GroupNorm 分组数motion_max_seq_length32运动模块最大序列长度帧数上限use_motion_mid_blockTrue是否在 mid block 放置运动模块conv_in_channelsNone非 None 时如 9为 PIA 模式额外构造输入卷积adapter 的forward为空实现占位它只负责存储结构实际计算发生在其内部MotionModules被合并进UNetMotionModel之后。使用时直接加载预训练权重即可from diffusers import MotionAdapter adapter MotionAdapter.from_pretrained(guoyww/animatediff-motion-adapter-v1-5-2)训练与微调只训练运动模块UNetMotionModel为视频生成微调提供了专门方法freeze_unet2d_paramsunet_motion_model.py冻结全部参数后仅解冻各 down/up block 及 mid block 中的motion_modules。这正是 AnimateDiff 训练范式的关键——空间 UNet 权重保持不动只优化新增的运动模块从而用较少数据和显存学会时间一致性save_motion_modulesunet_motion_model.py从模型 state_dict 中筛选所有含motion_modules的键重新包装为MotionAdapter并调用save_pretrained保存支持safe_serialization、variant与push_to_hub参数。这样微调产物是一个轻量的 motion adapter可独立分享模型同时支持enable_gradient_checkpointing继承自ModelMixin进一步降低视频训练/推理显存占用。推理期的内存与速度优化除了训练推理侧也提供了一系列与UNet2DConditionModel对齐的优化 APIenable_forward_chunking(chunk_sizeNone, dim0)/disable_forward_chunking()unet_motion_model.py对 Transformer 的前馈层做分块计算Reformer 风格dim0按 batch 分块、dim1按序列长度分块换取更低显存enable_freeu(s1, s2, b1, b2)/disable_freeu()unet_motion_model.py启用 FreeU论文 2309.11497机制通过衰减跳跃特征s1/s2与放大骨干特征b1/b2缓解过度平滑提升生成质量fuse_qkv_projections()/unfuse_qkv_projections()unet_motion_model.py把自注意力中的 Q/K/V 投影矩阵融合为单个算子、跨注意力融合 K/V配合FusedAttnProcessor2_0提升推理速度标记为实验性 APIset_default_attn_processor()按当前处理器类型AddedKV 或普通跨注意力恢复默认注意力实现。在 AnimateDiff pipeline 中的实际调用UNetMotionModel的实际应用场景是视频生成。在 src/diffusers/pipelines/animatediff/pipeline_animatediff.py 中AnimateDiffPipeline接收一个UNet2DConditionModel | UNetMotionModel若传入的是 2D UNet则 pipeline 内部自动执行unet UNetMotionModel.from_unet2d(unet, motion_adapter)完成升级from diffusers import AnimateDiffPipeline, MotionAdapter, DiffusionPipeline, DPMSolverMultistepScheduler adapter MotionAdapter.from_pretrained(guoyww/animatediff-motion-adapter-v1-5-2) pipe DiffusionPipeline.from_pretrained( stable-diffusion-v1-5/stable-diffusion-v1-5, motion_adapteradapter )同样的模式还出现在pipeline_animatediff_controlnet.py、pipeline_animatediff_sdxl.py、pipeline_animatediff_sparsectrl.py等 pipeline 中它们均以UNetMotionModel.from_unet2d(unet, motion_adapter)为桥梁在既有 Stable Diffusion 空间模型之上叠加运动建模能力。测试与验证仓库为UNetMotionModel提供了完整测试tests/models/unets/test_models_unet_motion.py其中UNetMotionModelTesterConfig使用block_out_channels(16, 32)、down_block_types(CrossAttnDownBlockMotion, DownBlockMotion)、up_block_types(UpBlockMotion, CrossAttnUpBlockMotion)的迷你配置验证模型前向输出形状(4, 4, 16, 16)并组合了ModelTesterMixin、AttentionTesterMixin、MemoryTesterMixin、TrainingTesterMixin等通用测试套件覆盖前向/反向、注意力处理器、显存峰值与训练稳定性。此外 tests/single_file/test_model_motion_adapter_single_file.py 验证MotionAdapter从原始单文件 checkpoint 的转换加载tests/pipelines/animatediff/ 下的测试则端到端验证 AnimateDiff 系列 pipeline 的推理行为。关于文档中引用的 UNet3DConditionOutputUNetMotionModel的 API 文档还交叉引用了UNet3DConditionOutputdiffusers.models.unets.unet_3d_condition.UNet3DConditionOutput它是三维条件 UNetUNet3DConditionModel另一种真正在三维空间卷积的视频 UNet 变体的输出封装。需要区分的是UNetMotionModel的空间骨干仍是 2D 卷积时间维度交给注意力运动模块处理而UNet3DConditionModel则直接使用 3D 卷积与时空注意力。两者都面向视频但实现范式不同使用时根据目标模型如 AnimateDiff 风格 vs. 原生 3D 视频 UNet选择即可。小结UNetMotionModel是 Diffusers 中图像扩散模型升级为视频扩散模型的关键组件它复用了成熟 2D UNet 的空间权重通过MotionAdapter注入时间注意力运动模块并以from_unet2d实现平滑迁移配合freeze_unet2d_params/save_motion_modules可以低成本微调出可分享的轻量运动适配器enable_forward_chunking/enable_freeu/fuse_qkv_projections等 API 则覆盖了推理期的显存与速度优化。想深入源码可重点关注 unet_motion_model.py 中的UNetMotionModel、MotionAdapter、AnimateDiffTransformer3D三个类以及 tests/models/unets/test_models_unet_motion.py 的迷你配置测试。【免费下载链接】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），仅供参考