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

本文记录了我在部署和开发开源项目 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() 中自动下载合成后视频。

---

🧠 项目原理与数据库设计

数据流：

1. 训练音色（/v1/preprocess_and_tran）：

   • 上传原始 .wav 音频

   • 返回：标准化音频路径 + 转录文本

2. 合成语音（/v1/invoke）：

   • 传入文字 + reference 音频路径

   • 返回生成 .wav 语音文件

3. 视频合成（/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 以写入完整文件）

---

📝 结语

这个项目虽然基于开源代码，但真正跑通后你会发现，工程化比模型本身更重要。环境配置、路径映射、权限控制、数据同步、日志调试，每一步都不能掉以轻心。

希望这份文档能帮你少踩一些坑，也欢迎关注更多关于 AI + 工程实践的内容！