HeyGem跨平台音视频 AI数字人/声音克隆/视频合成部署与开发避坑全纪录

最新推荐文章于 2025-04-30 22:57:57 发布

wumule

最新推荐文章于 2025-04-30 22:57:57 发布

阅读量2.2k

点赞数 40

文章标签：音视频人工智能 AIGC python

本文链接：https://blog.csdn.net/wumule/article/details/146845742

版权

本文记录了我在部署和开发开源项目 HeyGem.ai 过程中遇到的各种问题与解决方案，涵盖了 NVIDIA 驱动、Docker 配置、GPU 加速、音视频同步、数据库设计、API 交互及前后端联调等完整流程，适合有一定基础的 AI 开发者或项目集成者参考。

🚀 项目背景与目标

HeyGem.ai 是一个基于 Electron + Vue + Python 的开源 AI 视频生成工具，支持从文本或音频生成带口型同步的视频。它集成了 TTS（文本转语音）、F2F（Face2Face 视频驱动）等模型，适用于虚拟数字人、AI 视频剪辑等场景。

我的目标是：

✅ 实现在 Windows 上开发调试前端（Electron）；
✅ 后端部署在 Linux，通过 Docker 支持 GPU 推理；
✅ 支持音频/视频跨平台传输与自动同步；
✅ 使用 SQLite 管理数据，开发自定义音色训练/视频生成功能；
✅ 支持私有化部署，整理一套小白友好的交付文档与避坑指南。

🧱 系统环境与架构

前端运行环境（Windows）：
- WebStorm / VSCode
- Electron + Vue 前端
- PowerShell / Git Bash + SFTP 工具
后端部署环境（Linux）：
- Ubuntu 20.04
- NVIDIA GPU + 驱动 + CUDA 11.8
- Docker + NVIDIA Container Toolkit
容器结构：
- heygem-tts：文本转语音服务
- heygem-f2f：视频合成服务
- heygem-asr：语音识别服务

共享目录（宿主机）：

 ~/heygem_data/
   ├── face2face/temp/         # 视频模板与合成结果
   └── voice/data/
       ├── origin_audio/       # 训练用原始音频
       └── temp/               # 合成用临时音频

🔧 环境部署流程（Linux 端）

安装 NVIDIA 驱动和 CUDA

 # 驱动安装（根据显卡型号选）
 sudo apt install nvidia-driver-525
 
 # 验证 GPU 是否可用
 nvidia-smi

安装 Docker 和 NVIDIA Toolkit

 sudo apt install docker.io docker-compose
 distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
 curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
 curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | \
   sudo tee /etc/apt/sources.list.d/nvidia-docker.list
 
 sudo apt update && sudo apt install -y nvidia-container-toolkit
 sudo systemctl restart docker

配置容器运行时支持 GPU

 sudo tee /etc/docker/daemon.json <<EOF
 {
   "default-runtime": "nvidia",
   "runtimes": {
     "nvidia": {
       "path": "nvidia-container-runtime",
       "runtimeArgs": []
     }
   }
 }
 EOF
 
 sudo systemctl restart docker

clone项目

进入想要存放项目的目录

 git clone https://github.com/GuijiAI/HeyGem.ai.git

然后进入deploy目录

 cd ~/你存放项目路径/HeyGem.ai/deploy

执行下面步骤。

拉取镜像并运行容器

 docker pull guiji2025/fun-asr
 docker pull guiji2025/fish-speech-ziming
 docker pull guiji2025/heygem.ai
 
 docker-compose up -d #最新版deploy下已经有供Linux环境使用的docker-compose文件：docker-compose-linux.yml，可使用以下命令启动：docker-compose -f docker-compose-linux.yml up -d

⚙️ Windows + Electron 前端开发配置

拉取项目文件，打开你想要存放项目的目录，在路径中输入CMD，运行下面clone项目的命令

 git clone https://github.com/GuijiAI/HeyGem.ai.git

项目clone完成后在你的开发IDE中打开项目直接运行npm intall，没有抱错后，在启动项目npm run dev，然后就能看到Electron UI，可以进行创作了！下面是一些配置项，以供参考：

本地音视频存放路径：

 D:\heygem_data\
   ├── voice\data\origin_audio\
   └── face2face\temp\

config.js 配置：

 remoteSync: {
   enabled: true,
   serverIp: '10.147.20.33',
   username: 'your-username',
   password: 'your-password',
   voiceRemoteDir: '/home/your-username/heygem_data/voice/data',
   audioRemoteDir: '/home/your-username/heygem_data/voice/data/temp',
   videoRemoteDir: '/home/your-username/heygem_data/face2face/temp'
 }

自动上传/下载实现：
- 使用 ssh2-sftp-client 实现 SFTP 同步；
- makeAudio() 中上传音频；
- loopPending() 中自动下载合成后视频。

🧠 项目原理与数据库设计

数据流：

训练音色（/v1/preprocess_and_tran）：
- 上传原始 .wav 音频
- 返回：标准化音频路径 + 转录文本
合成语音（/v1/invoke）：
- 传入文字 + reference 音频路径
- 返回生成 .wav 语音文件
视频合成（/easy/submit）：
- 传入音频 + 视频模板
- 生成完整口型同步视频

SQLite 表结构（简化）：

voice：音色训练记录
f2f_model：视频模板模型（含语音 ID 与视频文件）
video：生成的视频任务状态与结果

🐞 踩坑合集与解决方案

问题	解决方式
Docker 拉取镜像失败	配置国内镜像源或使用 VPN
GPU 容器不识别显卡	重装 `nvidia-container-toolkit` 并验证 `--gpus all`
音频合成失败	确认 `reference_audio` 路径正确，文件已通过 SFTP 上传
视频合成失败 `format video error`	检查视频模板 `.mp4` 是否上传到容器共享目录
Electron 控制台中文乱码	配置 `$PROFILE` 添加 `$OutputEncoding = [console]::OutputEncoding = [Text.UTF8Encoding]::UTF8`
Windows 路径同步失败	注意路径分隔符，使用 `.replace(/\\/g, '/')`，以及Linux路径的权限问题

🧩 调整声音参数（语速/情绪等参数还未知）

目前 /v1/invoke 接口支持以下参数影响合成效果：

参数名	作用
`temperature`	控制生成的多样性，默认 0.7
`top_p`	控制采样概率阈值，默认 0.7
`chunk_length`	每段语音最大长度
`repetition_penalty`	重复惩罚系数
`need_asr`	是否做自动语音识别（通常设为 false）
`streaming`	是否启用流式返回（设为 false 以写入完整文件）