HeyGem.ai（Duix.Avatar）本地部署实战：5 步跑通离线数字人口播视频生成
【免费下载链接】Duix-Avatar🚀 Truly open-source AI avatar(digital human) toolkit for offline video generation and digital human cloning.项目地址: https://gitcode.com/GitHub_Trending/he/Duix-Avatar
想做一个会说话的数字人，却要忍受上传隐私、排队等待、按条收费？HeyGem.ai（Duix.Avatar）把数字人克隆和离线视频生成整套搬到了你自己的电脑上：提交一段 10 秒左右的视频，就能克隆你的形象和声音；之后输入文案或上传音频，自动生成口型匹配的播报视频。下面按"准备 → 拉起服务 → 客户端出片 → 调优 → 排障 → 落地"这条路线走一遍，每一步都能独立跑通。
一分钟认识它：Duix.Avatar 是什么、适合谁
HeyGem.ai（Duix.Avatar）是一款可本地部署、支持 API 调用的开源数字人工具箱。它的核心价值是全离线：外貌克隆 + 声音克隆 + 文字/语音驱动 + 视频合成，全部跑在本机，数据不出电脑。适合三类人——
- 内容创作者：反复出片、批量口播，不想为每一条付费；
- 技术型用户：想拿到代码做二次开发，或直接调开放 API；
- 注重隐私的团队：内部资料、客户数据不想上传到云端。
它的"身体"由三个 Docker 服务组成：声音合成（TTS，基于 fish-speech）、语音识别（ASR，基于 fun-asr）、视频合成（数字人驱动）。你只需把它们拉起来，客户端就能"指挥"它们干活。
第一关：把机器和依赖准备好
部署前先把这台机器"体检"一遍，缺一样后面都会卡住。
| 项目 | 推荐配置 | 说明 |
|---|---|---|
| CPU | i5-13400F 或同档 | 影响预处理与合成速度 |
| 内存 | 32G 及以上 | 官方标注为必要项 |
| 显卡 | RTX-4070（NVIDIA 独显） | 必须有 N 卡且装好驱动，所有算力在本地 |
| 磁盘 | D 盘 > 30G、C 盘 > 100G | D 盘存模特和作品，C 盘存 Docker 镜像 |
| 系统 | Windows 10（19042.1526+）或 Ubuntu 22.04 | Ubuntu 已验证内核 6.8.0-52-generic |
| 运行时 | Node.js 18 | 客户端与构建依赖 |
⚠️风险提示：没有 NVIDIA 显卡或没装驱动，三个服务是起不来的，这是本地部署最常见的"零号杀手"。
Windows 上先确认 WSL（Windows 子系统，Docker 的底层运行环境）是否就绪：
wsl --list --verbose预期效果：能列出已安装的发行版说明装过了；没有则执行wsl --install，再执行wsl --update更新一次。网络不稳时多试几次即可。
第二关：一条命令拉起服务端
项目已经自带了deploy/目录下的编排文件，里面预定义了三个服务。你只需进入该目录，然后：
git clone https://gitcode.com/GitHub_Trending/he/HeyGem.ai cd HeyGem.ai/deploy docker-compose up -d预期效果：开始拉取镜像，大约消耗 70G 流量（建议连 WiFi），约半小时后 Docker 里出现 3 个 Running 状态的容器，分别对应：
duix-avatar-tts→ 端口 18180（声音合成）duix-avatar-asr→ 端口 10095（语音识别）duix-avatar-gen-video→ 端口 8383（视频合成）
💡小贴士：不同硬件/系统有对应变体，直接换一条命令即可。
- 低配想先跑通（只启动视频合成）：
docker-compose -f docker-compose-lite.yml up -d - NVIDIA 50 系显卡（已测 5090，30/40 系 CUDA 12.8 也可用）：
docker-compose -f docker-compose-5090.yml up -d - Ubuntu 22.04：先装好 Docker 与 NVIDIA Container Toolkit，再
docker-compose -f docker-compose-linux.yml up -d
三个服务都 Running，这一关就通了。
第三关：装上客户端，生成第一条视频
服务端只是"后厨"，客户端才是你操作的"前台"。直接下载官方构建的安装包（Windows 是setup.exe，Ubuntu 是AppImage，后者可直接运行、无需安装），双击安装即可。
打开后就是熟悉的两大入口：左侧"我的作品 / 我的数字模特"，顶部"创建视频"和"快速定制"。
出片只需三步：
- 克隆模特：上传一段约 10 秒、有人在对镜头说话的视频，程序用它同时克隆外貌与声音；
- 写文案 / 传音频：输入播报文字，或直接上传一段语音；
- 合成视频：客户端把音频发给 TTS 服务、把模特和音频发给视频合成服务，自动对齐口型，产出口播视频。
💡 如果你是开发者，想直接接开放 API，三个端点分别是：模特训练http://127.0.0.1:18180/v1/preprocess_and_tran、音频合成http://127.0.0.1:18180/v1/invoke、视频合成http://127.0.0.1:8383/easy/submit（用/easy/query?code=...轮询进度）。客户端源码可参考 src/main/service/ 下的model.js、video.js、voice.js。
配置与调优：让磁盘和镜像都不拖后腿
默认能跑，但下面几处调一下，体验会顺很多。
1. 把 Docker 镜像盘挪到空间够的大盘。进入 Docker Desktop → Settings → Resources → Advanced，在Disk image location处把镜像位置改到剩余空间 > 100G 的磁盘：
预期效果：镜像不再写爆 C 盘，拉取和启动更稳。
2. 拉镜像慢 / 失败，配一个国内镜像源。编辑 Docker 的daemon.json，加入registry-mirrors（镜像源会随时间变动，以官方文档为准）：
{ "registry-mirrors": [ "https://hub.fast360.xyz", "https://docker.m.daocloud.io", "https://docker.1ms.run" ] }预期效果：重启 Docker 后，三个镜像的下载速度明显提升。
3. 显存吃紧时的取舍。生成时优先保证视频合成服务的shm_size与显存余量，降低导出分辨率比硬堆参数更有效；高配机可放心开 1080p。
避坑与排障：三个最常卡住的地方
坑一：docker-compose up -d报Connection refused或拉镜像超时。多为 Docker Hub 官方源连不上。打开daemon.json配好上面的registry-mirrors再重启即可。
坑二：新增模特时报错。九成是上传的视频没有声音、或人没在说话——克隆声音必须有可识别的语音样本，重拍一段"对着镜头念 10 秒文案"的片段即可。
坑三：合成时日志反复出现file not exists/ 连接失败。这通常是三个服务没全 Running，或客户端与服务端版本不一致。先按官方"提问前自查"过一遍：
取日志的姿势（报障时基本都要附）：
- 客户端日志：点右上角"设置 → 打开日志"，文件一般在
%AppData%\Roaming\heygem.ai\logs下； - 服务端日志：在 Docker 里点开对应容器看日志并"复制"。
⚠️ 排障顺序建议：先看服务是否都 Running → 再确认 N 卡与驱动 → 最后核对版本（服务端在/deploy重跑docker-compose up -d，客户端pull后重新build）。社区更新频繁，很多问题在新版里已经修了。
能落地到哪些场景
- 教育培训：克隆一位"虚拟讲师"，文案一换就出新课程口播，24 小时在线；
- 数字营销：批量产出不同卖点的带货/品牌口播，省去反复棚拍；
- 内容创作：把一篇稿子直接变成数字人出镜视频，产能拉满；
- 远程沟通：用数字形象代替真人出镜，保护隐私的同时保持一致人设。
配合开放 API，还能把它接进你自己的业务流程，实现"文案进、成片出"的自动化流水线。
一句话收尾
HeyGem.ai（Duix.Avatar）把"克隆形象 + 声音 + 口型合成"这一整套数字人能力做到了全离线、可自建、可二次开发，只要一台带 N 卡的机器，就能稳定产出口播视频。现在可以动手了：你准备用第一个数字人形象，讲一段什么内容呢？
【免费下载链接】Duix-Avatar🚀 Truly open-source AI avatar(digital human) toolkit for offline video generation and digital human cloning.项目地址: https://gitcode.com/GitHub_Trending/he/Duix-Avatar
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
