MOFA-Video 安装与运行避坑指南：解决常见问题，快速上手图像动画生成

MOFA-Video 是一个基于生成式扩散模型的开源项目，用于图像动画生成。本文将总结从安装到运行过程中遇到的坑点以及解决方案，帮助大家顺利上手。

---

1. 环境配置

项目要求的基础环境包括：

• Python 版本：3.10
• CUDA 版本：11.7（推荐）
• 依赖库：通过 requirements.txt 安装

安装步骤

1. 克隆项目代码：

   git clone https://github.com/MyNiuuu/MOFA-Video.git
   cd MOFA-Video/MOFA-Video-Hybrid
   

2. 创建并激活 Conda 环境：

   conda create -n mofa python=3.10
   conda activate mofa
   

3. 安装依赖：

   pip install -r requirements.txt
   pip install opencv-python-headless
   pip install "git+https://github.com/facebookresearch/pytorch3d.git"
   

4. 下载模型文件并放置到指定路径：
   • HuggingFace 模型地址
   • 将 ckpts 文件夹放到 MOFA-Video-Hybrid 目录下。

---

2. 常见问题与解决方案

问题 1：pytorch3d 安装失败

错误信息：

ERROR: Failed building wheel for pytorch3d

原因：

• pytorch3d 需要与 PyTorch 和 CUDA 版本匹配。大部分情况是本地的 CUDA 或 PyTorch 不支持当前安装的版本。

解决方案：

1. 检查当前 PyTorch 和 CUDA 版本：

   python -c "import torch; print(torch.__version__, torch.cuda.is_available())"
   

   确保 PyTorch 版本和 CUDA 配置正确。

2. 手动安装适配版本的 pytorch3d：

   • 查阅 官方安装指南，根据你的 CUDA 和 PyTorch 版本获取对应命令。
   • 例如，对于 CUDA 11.7 和 PyTorch 1.12：

     pip install pytorch3d -f https://dl.fbaipublicfiles.com/pytorch3d/packaging/wheels/py3.10_cu117_pyt1120/download.html
     

---

问题 2：torchvision 警告

错误信息：

UserWarning: Failed to load image Python extension...

原因：

• torchvision 在安装时可能缺少系统依赖（如 libjpeg 或 libpng），导致部分图像功能不可用。

解决方案：

1. 安装缺失的系统依赖：
   • 对于 Ubuntu：

     sudo apt-get update
     sudo apt-get install libjpeg-dev libpng-dev
     

2. 重新安装 torchvision：

   pip uninstall torchvision
   pip install torchvision
   

3. 如果警告仍然存在但不影响使用，可以忽略。

---

问题 3：diffusers 模块找不到

错误信息：

ModuleNotFoundError: No module named 'diffusers.models.unet_3d_blocks'

原因：

• 当前安装的 diffusers 版本不包含所需模块，可能版本过低或不兼容。

解决方案：

1. 升级 diffusers 到指定版本：

   pip install diffusers==0.18.0
   

2. 如果升级失败，尝试先卸载旧版本：

   pip uninstall diffusers
   pip install diffusers==0.18.0
   

---

问题 4：huggingface_hub 导入错误

错误信息：

ImportError: cannot import name 'cached_download' from 'huggingface_hub'

原因：

• 当前 huggingface_hub 的版本与脚本不兼容。

解决方案：

1. 安装兼容版本：

   pip install huggingface_hub==0.25
   

2. 检查安装版本是否正确：

   pip show huggingface_hub
   

---

问题 5：Gradio 界面加载失败

原因：

• gradio 版本可能与脚本要求不一致。

解决方案：

1. 安装指定版本的 gradio：

   pip install gradio==4.5.0
   

2. 遇到不兼容问题时，先卸载后重新安装：

   pip uninstall gradio
   pip install gradio==4.5.0
   

---

3. 验证运行

成功配置环境后，可运行以下命令测试 Gradio 界面：

1. 音频驱动动画：

   python run_gradio_audio_driven.py
   

2. 视频驱动动画：

   python run_gradio_video_driven.py
   

遇到问题时，检查对应的模型路径和日志输出，逐一解决。

---

4. 总结

MOFA-Video 的安装过程虽然可能会遇到一些环境问题，但通过以下几点可以有效避免踩坑：

• 明确依赖版本：严格按照项目的依赖安装说明操作。
• 解决系统依赖问题：确保 libjpeg、libpng 等基础库已安装。
• 管理好 Python 环境：使用独立的 Conda 环境隔离依赖。
• 记录日志：运行过程中保存报错信息，便于逐一排查。