视频合成预处理失败？HeyGem.ai项目全流程解决方案

视频合成预处理失败是HeyGem.ai用户最常遇到的问题之一，尤其在模型训练和视频生成阶段。本文将从服务状态检查、环境配置验证、资源要求匹配、错误日志分析四个维度，提供系统化的排查方案，并附具体操作步骤与案例解析，帮助用户快速定位问题根源。

服务状态诊断

所有预处理任务依赖Docker容器内的三个核心服务协同工作，任一服务异常都会导致处理失败。通过Docker Desktop检查服务状态是首要步骤：

检查要点：

• 确认Duix.Avatar-asr、Duix.Avatar-gen-video、Duix.Avatar-tts三个服务均显示"Running"状态
• 服务异常时会显示"Exited"或"Restarting"，需通过日志定位具体原因
• 服务重启命令：进入deploy/目录执行docker-compose up -d

环境配置验证

硬件加速和驱动配置是预处理成功的基础，项目所有算力均在本地GPU完成，环境缺失会直接导致任务失败。

显卡驱动检查

通过nvidia-smi命令验证驱动状态，需满足：

• 驱动版本≥525.00
• CUDA版本≥11.7
• 显卡显存≥8GB（推荐12GB以上）

Docker环境配置

国内用户需特别配置镜像源解决拉取超时问题，修改Docker配置文件添加：

{
  "registry-mirrors": [
    "https://docker.zhai.cm",
    "https://atomhub.openatom.cn",
    "https://docker.m.daocloud.io"
  ]
}

配置文件位置及修改方法参见doc/常见问题.md中的详细说明。

资源要求匹配

预处理失败常与硬件资源不足相关，特别是内存和磁盘空间不足会导致静默失败。

系统资源要求

组件	最低配置	推荐配置
CPU	8核Intel i5	12核Intel i7
内存	16GB DDR4	32GB DDR5
显卡	RTX 3060	RTX 4070
磁盘	100GB SSD	200GB NVMe

典型资源不足案例

当系统内存≤16GB时，可能出现Duix.Avatar-asr服务启动失败，日志会显示：

ConnectionRefusedError: [Errno 111] Connection refused

解决方案：关闭其他占用内存的应用，或增加物理内存至32GB。

错误日志分析

预处理失败的详细原因记录在两类日志中，通过分析日志可准确定位问题。

客户端日志获取

在应用设置中开启调试模式，日志文件保存路径：

• Windows: C:\Users\{用户名}\AppData\Roaming\HeyGem\logs
• Linux: ~/.config/HeyGem/logs

服务端日志查看

通过Docker Desktop界面查看具体服务日志：

• ASR服务超时：通常为模型加载慢，等待5-10分钟后重试
• TTS服务重启：检查src/main/service/voice.js中的参数配置
• 视频服务错误：验证FFmpeg是否正确安装，可执行src/main/util/ffmpeg.js进行测试

进阶解决方案

针对特定错误场景，提供经过社区验证的解决方案。

连接拒绝错误

当创建模型时出现"Connection refused"错误：

解决步骤：

1. 确认ASR服务已运行至少3分钟
2. 检查src/main/api/request.js中的超时设置
3. 执行docker-compose restart Duix.Avatar-asr重置服务

音频预处理失败

视频合成要求输入音频满足：

• 格式：WAV/MP3
• 时长：5-60秒
• 内容：清晰人声，无背景音乐
• 采样率：44.1kHz

不符合要求的音频会导致预处理失败，可通过src/main/dao/voice.js中的验证逻辑进行自查。

预防措施与最佳实践

定期维护可显著降低预处理失败概率，建议：

1. 每周执行docker system prune -a清理冗余镜像
2. 每月更新客户端至最新版本：src/main/interval/interval.js中实现了自动更新检查
3. 重大版本更新后执行docker-compose down && docker-compose up -d全量重建服务

通过遵循本文档的排查流程，90%以上的预处理失败问题可在30分钟内解决。如问题持续存在，可提供完整日志在项目Issues区提交，开发团队通常会在24小时内响应。

项目核心处理逻辑参见：

• 模型训练：src/main/service/model.js
• 视频合成：src/main/service/video.js
• 音频处理：src/main/service/voice.js