AnimateDiff作为Stable Diffusion WebUI中生成动态视频的重要扩展，其加载稳定性高度依赖两个因素：模型文件是否放在正确路径，以及权重版本是否和主程序兼容。当控制台抛出FileNotFoundError或者shape mismatch类的异常时，往往不是环境崩坏，而是配置细节出了偏差。理解它的检索逻辑与版本约束，是快速恢复生成能力的前提。
模型路径的检索机制与正确摆放方式
AnimateDiff插件在初始化阶段会依据自身配置中定义的model_path变量去磁盘读取运动模块。默认情况下，这个路径指向WebUI根目录下的models/animatediff_model文件夹。很多用户在GitHub下载完mm_sd_v15.ckpt或v2_lora_alpha.pt之后，习惯顺手丢进extensions/AnimateDiff目录，结果插件根本不会去那里扫描，自然报出加载失败。理清插件实际的遍历逻辑，可以避免绝大多数路径类故障。
从源码角度看，插件通常使用os.listdir枚举目标文件夹，并将后缀为ckpt、pt、safetensors的文件名缓存到下拉框。如果文件夹不存在，它会尝试自动创建，但并不会回溯到其他目录寻找。因此正确的做法是在WebUI根目录手动建立models/animatediff_model，再把权重复制进去。重启UI后，日志里会出现Loaded motion module from ...才算成功。
下面是一段用于自查路径是否合法的Python脚本，可以放在插件目录外独立运行：
import os
base_dir = "./models/animatediff_model"
if not os.path.exists(base_dir):
print("目录不存在，请创建: " + base_dir)
else:
files = [f for f in os.listdir(base_dir) if f.endswith(('.ckpt', '.pt', '.safetensors'))]
if len(files) == 0:
print("目录为空，未检测到任何运动模型")
else:
print("发现模型文件: ")
for f in files:
print(" - " + f)
有时用户使用了自定义启动参数--animatediff-model-path，却忘了参数值应是绝对路径。在Windows上若写成C:modelsani而未转义反斜杠，命令行解析会出错，应写为C:\models\ani或改用正斜杠C:/models/ani。保持路径配置透明，是排除加载失败的第一步。
版本匹配的核心约束与混淆点
AnimateDiff的v1系列运动模块（如mm_sd_v14、mm_sd_v15）设计用于原始SD1.5基底，而v2系列引入了新的时空注意力结构，需要配合特定版本的插件（通常为v1.4.0以上）以及支持lora注入的WebUI。若把v2的v2_lora_alpha.pt强行塞进旧版插件，就会在build pipeline时提示KeyError: 'motion_modules'。这种版本错配比路径错误更隐蔽，因为文件能被读取，却在张量映射阶段崩溃。
另一个常见误区是认为任意SDXL基底都能直接用SD1.5的motion module。实际上AnimateDiff官方明确区分了SD1.5与SDXL分支，混用会导致通道数不一致。用户在下载页面应优先查看release note里的Compatible base字段。下表列出了典型组合：
| 运动模块 | 适配基底 | 插件最低版本 |
|---|---|---|
| mm_sd_v15.ckpt | SD1.5 | v1.0.0 |
| v2_lora_alpha.pt | SD1.5 + LoRA | v1.4.0 |
| mm_sdxl_v10.ckpt | SDXL | v1.5.0 |
当怀疑版本问题时，最可靠的办法是打开WebUI启动时的终端输出，搜索AnimateDiff version与loading motion module两段日志。如果插件版本过早，即使模型路径完全正确也无法解析新权重。此时应升级插件而非反复重下模型。版本匹配的本质是权重内部键值结构与代码反序列化逻辑的对齐，理解这一点能减少大量无效操作。
综合排查流程与错误日志解读
遇到加载失败，建议按照先路径后版本的顺序排查。首先在文件系统确认models/animatediff_model内有对应文件，再通过UI下拉框看是否列出名称。若下拉框空白，九成是路径问题；若选中有名称却报错，则转向版本与兼容性。这种分层定位法比盲目重装更高效。
错误日志中RuntimeError: Error(s) in loading state_dict基本指向版本错配，而FileNotFoundError: [Errno 2] No such file显然指向路径。还可以临时在插件加载函数插入print(os.getcwd())确认当前工作目录，避免相对路径计算偏差。以下代码片段展示如何捕获加载异常并输出友好信息：
try:
from animatediff import get_motion_module
mod = get_motion_module("mm_sd_v15.ckpt")
except FileNotFoundError as e:
print("模型文件未找到，请检查models/animatediff_model目录: " + str(e))
except RuntimeError as e:
print("模型与当前版本不兼容，请核对AnimateDiff release说明: " + str(e))
实际处理中，不少人忽略了WebUI本身的torch版本。较老的torch 1.13在加载safetensors时可能抛出无关错误，让人误判为路径或版本问题。保持torch 2.x与xformers匹配，也是间接保障AnimateDiff加载顺利的基础。把路径、版本、运行库三者结合起来审视，才能彻底解决加载失败而不只是临时绕过。
AnimateDiff模型路径版本匹配修改时间：2026-08-17 00:52:34