本文记录了我在部署和开发开源项目 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 以写入完整文件） |
📝 结语
这个项目虽然基于开源代码，但真正跑通后你会发现，工程化比模型本身更重要。环境配置、路径映射、权限控制、数据同步、日志调试，每一步都不能掉以轻心。
希望这份文档能帮你少踩一些坑，也欢迎关注更多关于 AI + 工程实践的内容！
