HeyGem.ai 数字人本地部署完全指南：10 秒素材克隆出会说话的口播视频-平芜编程栈

HeyGem.ai 数字人本地部署完全指南：10 秒素材克隆出会说话的口播视频

【免费下载链接】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 秒左右的出镜视频，它就能克隆你的形象和声音，之后只要输入文字或音频，就能驱动这个数字人口型对轨，产出口播视频。整个数字人本地部署流程不需要上传任何素材到云端，隐私和算力都留在自己的机器里。

动手前：确认你的电脑跑得动

在装任何东西之前，先对照这份清单，缺了硬件是省不掉的——本项目的全部推理算力都在本地 GPU 上跑。

项目	要求
显卡	英伟达 N 卡 + 正确安装的驱动（`nvidia-smi`能看到显卡信息才算数）
内存	32G 及以上，16G 机器连 ASR 服务都可能起不来
系统	Windows 10 19042+ 或 Ubuntu 22.04（其他 Linux 未验证）
磁盘	Docker 镜像约 100G 空闲，作品数据目录 30G+ 空闲
运行时	Docker（Windows 上走 WSL2 后端）+ Node.js 18（仅自己构建客户端时需要）

一个容易踩的坑：Windows 上 Docker Desktop 的镜像默认存在 C 盘，如果你 C 盘不够，安装 Docker 之后要提前把存储位置改到别的盘，否则拉镜像会直接把 C 盘撑爆。

跑通服务端：三步起三个 Docker 服务

服务端由三个容器组成：duix-avatar-tts（语音合成，端口 18180）、duix-avatar-asr（语音识别，端口 10095）、duix-avatar-gen-video（视频合成，端口 8383），定义都在 deploy/docker-compose.yml 里。

Windows 流程：先用wsl --install装好 WSL2，再装 Docker Desktop，然后在仓库目录下执行：

cd deploy docker-compose up -d

Ubuntu 22.04 流程：装好 Docker 和 NVIDIA Container Toolkit（让容器能用上显卡）后执行：

cd deploy docker-compose -f docker-compose-linux.yml up -d

配置文件对应 deploy/docker-compose-linux.yml。首次拉取镜像大约消耗 70G 流量，建议连 WiFi 等半小时左右。

怎么算成功了？Docker 里三个容器都变成 Running 状态，服务端就就绪了。接下来打开客户端（下载官方构建的安装包直接装，或在仓库里npm install后npm run dev跑开发版），能看到首页并成功创建第一个数字模特，说明端到端全通了。

打开客户端，产出第一条口播视频

客户端首页就两块区域，对应两条主线任务：

Create Video（制作视频）：选择已克隆的数字人 + 输入文案或上传音频 → 生成口播视频。
Create Avatar（定制模特）：上传一段出镜视频 → 克隆形象 + 声音，得到一个可重复使用的数字模特。

推荐先走第二条：准备 10 秒左右的视频，要求画面里的人在说话（声音会用于克隆音色），背景安静、人脸清晰。训练完成后，"My Avatars" 列表里就会出现你的数字模特，之后每次生成视频只需换文案，形象不用重新训。

它能替你干的活儿

把功能名词翻译成实际能交付的东西，大概是这四件事：

口播视频量产：写一段稿子，几十秒后得到一条人物口型对轨的播报视频，适合短视频、课程、产品介绍这类"真人出镜但懒得拍"的场景。
声音克隆：10 秒声音样本就能复刻音色，之后合成语音都带你的声线，脚本支持中、英、日、韩、法、德、阿、西 8 种语言。
多模特管理：客户端支持导入多个模型，不同栏目、不同出镜人分开管理，一键切换。
接口化集成：服务端 Docker 起来后在127.0.0.1上暴露了模特训练、音频合成、视频合成和进度查询四组接口，可以直接接进自己的业务系统。调用逻辑参考 src/main/service/model.js、src/main/service/video.js、src/main/service/voice.js。

让它跑得更快更稳：版本选择与调优

50 系显卡专用方案：RTX 5090 等新卡默认 compose 可能起不来，官方提供了基于 torch 预览版 CUDA 的 deploy/docker-compose-5090.yml，30/40 系使用 cuda12.8 的机器也可以借用这套：
```
cd deploy docker-compose -f docker-compose-5090.yml up -d
```
轻配机器用 Lite 版：显存吃紧时执行docker-compose -f docker-compose-lite.yml up -d，只启动视频合成一个服务（配置见 deploy/docker-compose-lite.yml）。
磁盘规划：Docker 镜像放 C 盘空间充足的位置，数字人和作品数据放独立盘（默认约定D:\duix_avatar_data）。需要搬家时，在 Docker Desktop 的 Settings → Resources → Advanced 里改 "Disk image location"：

拉镜像慢：给 Docker 配置 registry-mirrors 加速（Linux 改/etc/docker/daemon.json，Windows 在 Docker Engine JSON 里加同名字段），可用镜像源列表见 doc/常见问题.md。
视频质量：源素材决定上限——照片/视频越清晰、声音越干净，克隆效果越好；批量生成时按条排队提交，避免多条任务挤占同一块显存。

遇到报错怎么修

①docker-compose up -d拉镜像超时（Get "https://registry-1.docker.io/v2/": request canceled）

官方源连接不稳定。打开 Docker Desktop 的 Settings → Docker Engine，在 JSON 里加入registry-mirrors字段，Apply & restart 后重试：

② 新增模特时训练失败

上传的视频必须包含人声且人在说话——程序要从这段声音里做声音克隆，纯画面视频会直接失败。

③ 定制模特报Connection refused或 asr 相关错误

ASR 服务冷启动偏慢，服务端刚拉完容器别急着建模特，等几分钟再操作；内存只有 16G 的机器可能根本拉不起来，建议 32G 起步。

④ tts 容器日志刷File not exists

一般是数据卷挂载路径不对（比如非 Windows 环境照抄了d:/duix_avatar_data/...的卷映射），检查 compose 文件里的 volumes 是否指向了真实存在的数据目录：

⑤ 问题难定位时，先取日志

客户端日志在设置菜单 "打开日志" 里，文件位于Roaming\heygem.ai\logs\main.log；服务端日志直接在对应容器的 Logs 页签复制：

更多报错和解决方案，翻 doc/常见问题.md 基本都有覆盖。

下一步

部署跑通之后，值得花时间的方向有三个：用 API 把"文案进、视频出"接进自己的发布流程，实现无人值守的批量生产；针对常用出镜场景沉淀 2~3 个固定模特，减少重复训练；显存充裕的话，试试完整版与 Lite 版在生成速度上的差距，给自己的机器定一个最优配置。整套流程走完你会发现：一段 10 秒素材，换来了一个随时能开口说话的数字分身，而且全程数据不出本机。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考