Mora视频生成错误排查手册：常见问题诊断与解决方案

你是否曾遇到视频生成到一半突然中断？或者输出画面出现花屏、卡顿等问题？本手册将帮助你快速定位Mora视频生成过程中的常见错误，并提供 step-by-step 解决方案，让你的创作流程更加顺畅。

一、环境配置类错误

1.1 CUDA设备初始化失败

症状：启动时报错 CUDA out of memory 或 device not found
可能原因：显卡内存不足、驱动版本不匹配或未正确安装CUDA
解决方案：

• 检查显卡内存使用情况，关闭其他占用GPU的程序
• 降低视频分辨率（默认1024x576），修改 mora/actions/generate_video_with_image.py 中的尺寸参数
• 确认CUDA版本与PyTorch兼容，推荐配置：CUDA 11.7+ + PyTorch 1.13+

1.2 API密钥配置错误

症状：调用LLM接口时返回 401 Unauthorized
解决方案：

1. 检查 mora/configs/llm_config.py 中的 api_key 是否正确设置
2. 确认API密钥格式，OpenAI密钥通常以 sk- 开头
3. 对于Azure用户，需同时配置 azure_endpoint 和 api_version

# 正确配置示例
api_key: str = "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
base_url: str = "https://api.openai.com/v1"

二、视频生成核心错误

2.1 模型加载超时

症状：程序卡在 SVD model loaded 之前无响应
可能原因：Stable Video Diffusion模型下载失败或网络超时
解决方案：

• 手动下载模型文件并放置到本地缓存目录：~/.cache/huggingface/hub
• 使用国内镜像源加速下载：

  export HF_ENDPOINT=https://hf-mirror.com
  

• 检查 mora/actions/generate_video_with_image.py 中的模型名称是否正确

2.2 帧序列处理异常

症状：生成视频只有前几秒正常，后续画面冻结或黑屏
问题定位：查看帧迭代逻辑 [mora/actions/generate_video_with_image.py#L30-L37] 修复方案：

# 修改前
for iteration in range(3):
    frames = self.model(...)
    generate_message += frames
    current_image = frames[-1]  # 可能导致最后一帧格式异常

# 修改后
for iteration in range(3):
    frames = self.model(...)
    generate_message.extend(frames[:-1])  # 排除可能异常的最后一帧
    current_image = frames[-2].copy()  # 使用倒数第二帧作为下一迭代输入

三、输出文件异常

3.1 视频无法保存

症状：报 AttributeError: 'list' object has no attribute 'write_videofile'
原因分析：测试代码中 tests/test_video_producer.py 错误地将帧列表直接调用视频写入方法
正确做法：使用OpenCV或MoviePy处理帧序列

# 正确保存示例
import cv2
from PIL import Image

fourcc = cv2.VideoWriter_fourcc(*'mp4v')
out = cv2.VideoWriter('output.mp4', fourcc, 7.0, (1024, 576))

for frame in video_frames:
    cv_img = cv2.cvtColor(np.array(frame), cv2.COLOR_RGB2BGR)
    out.write(cv_img)
out.release()

3.2 生成视频卡顿严重

症状：视频播放时帧率低于预期（目标7fps）
优化方案：

• 减少 motion_bucket_id 值（默认180），降低运动幅度
• 增加 decode_chunk_size 参数（默认12），提升解码效率
• 示例配置：[mora/actions/generate_video_with_image.py#L31]

  frames = self.model(..., motion_bucket_id=120, decode_chunk_size=16)
  

四、网络与资源问题

4.1 模型下载速度慢

解决方案：配置国内代理，修改 mora/configs/llm_config.py

proxy: str = "http://127.0.0.1:7890"  # 根据实际代理地址修改

4.2 长时间无响应

症状：生成单段视频超过5分钟无结果
排查步骤：

1. 检查网络连接，确认能正常访问HuggingFace和LLM API
2. 查看GPU利用率，若持续低于30%可能是数据预处理 bottleneck
3. 启用详细日志，修改 mora/llm/general_api_requestor.py 中的超时参数

五、预防措施与最佳实践

5.1 系统资源监控

在生成视频前运行以下命令检查系统状态：

nvidia-smi  # 查看GPU状态
free -m     # 检查内存使用

5.2 测试工作流

推荐先运行测试脚本验证基础功能：

python tests/test_video_producer.py

成功生成 h.mp4 文件表示基础环境配置正确

5.3 版本控制

• 定期同步最新代码：git pull origin main
• 关键配置文件备份：llm_config.py、generate_video_with_image.py

六、进阶调试技巧

如果以上方案仍未解决问题，可以：

1. 查看详细错误日志：tail -f logs/mora.log
2. 在 mora/agent/video_producer.py 中添加调试打印
3. 提交issue到GitHub仓库，附上：错误截图、系统配置和日志片段

---

通过本手册解决了你的问题吗？欢迎点赞收藏，关注项目获取更多实用教程。下期预告：《Mora高级视频特效制作指南》