HeyGem.ai 本地部署：3 条命令跑通离线数字人

HeyGem.ai 本地部署：3 条命令跑通离线数字人

【免费下载链接】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 秒左右的自拍视频，它能克隆出你的形象和声音，之后输入一段文字或传一个音频文件，它就吐出一段口型同步的口播视频。适合内容团队做批量口播、个人把素材留在本地不想上传到云端、以及想直接调它的合成接口嵌入自己产品的开发者。

三条上手路径

容器路：一条 compose 命令拉起三个服务

服务端就是三个 Docker 容器：语音合成（fish-speech）、语音识别（fun-asr）、视频合成（face2face），定义都在 deploy 目录 里。在deploy目录执行：

cd deploy docker-compose up -d # 标准版，拉取约 70G 镜像

命令执行后耐心等待（半小时起步，取决于网速），直到docker ps里duix-avatar-tts、duix-avatar-asr、duix-avatar-gen-video三个容器全部变成 Running：

拉取前确认 D 盘（或 Linux 的挂载目录）空闲大于 30G、Docker 数据目录所在盘大于 100G，否则挂载的duix_avatar_data会直接写满。

50 系显卡路：换一个 compose 文件就行

RTX 50 系列（以及 CUDA 12.8 的 30/40 系）需要换一套基于 torch 预览版的镜像，把命令里的文件换掉即可：

cd deploy docker-compose -f docker-compose-5090.yml up -d # 5090 镜像，只起 2 个容器

你会看到duix-avatar-tts和duix-avatar-gen-video两个容器起起来，这个方案里没有独立的 asr 容器，语音识别合并进了合成服务。

源码路：装依赖后本地起客户端

客户端是一个 Electron 应用，服务端跑好后，克隆仓库并启动界面：

git clone https://gitcode.com/GitHub_Trending/he/HeyGem.ai cd HeyGem.ai npm install # 需要 Node.js 18 npm run dev # electron-vite 开发模式启动

界面起来后先做两件事：确认能连上127.0.0.1的三个端口，再把客户端指向服务端的地址确认无误。这些连接信息集中在 src/main/config/config.js，开发模式下走的是局域网 IP，生产构建默认走本机回环，指向别的机器改这里就行。

能力拆解：克隆、合成、出片三步

整个链路就三步：克隆模特 → 文字变语音 → 语音驱动视频。界面里对应「Create Avatar」和「Create Video」两个入口，每一步都有对应的本地 API 可以单独调。

克隆模特

• 能做什么：从一段约 10 秒的真人说话视频里，同时提取外貌和声音，生成一个可反复使用的数字人
• 怎么触发：界面点「Create Avatar」上传视频；或直接 POST127.0.0.1:18180/v1/preprocess_and_tran
• 关键参数：reference_audio（提取出的音频相对路径）、lang（zh/en 等）；返回值里的asr_format_audio_url和reference_audio_text要记下来，后面合成语音时还要用

文字转语音

• 能做什么：用克隆出来的声音朗读任意文本，产出一段 wav
• 怎么触发：POST127.0.0.1:18180/v1/invoke；或者界面里直接输入文案
• 关键参数：text（要朗读的内容）、speaker（一个保持唯一的 UUID）、reference_audio/reference_text（上一步克隆的返回值）

语音驱动视频

• 能做什么：把合成好的音频和模特参考视频对齐，输出口型同步的口播视频
• 怎么触发：POST127.0.0.1:8383/easy/submit，再用127.0.0.1:8383/easy/query?code=xxx轮询进度
• 关键参数：audio_url、video_url、code（任务唯一标识，查询时回传）

三个服务各占一个端口，职责如下：

想跳过界面直接集成到自己的产品，服务端的调用示例代码就在 src/main/service/video.js 和 src/main/service/voice.js 里，照着改即可。

调优与排障

拉镜像卡在 Docker Hub 超时

• 现象：docker-compose up -d报Client.Timeout exceeded while awaiting headers
• 原因：官方源连接不稳定，70G 的镜像基本拉不完
• 修复：给 Docker 配置国内镜像源

// Docker Engine 配置中添加 registry-mirrors { "registry-mirrors": [ "https://docker.m.daocloud.io", "https://docker.1ms.run" // 源会失效，用哪个先 curl 测一下连通性 ] }

克隆模特时 asr 报 Connection refused

• 现象：新增模特报错，服务端日志里建立funasr连接异常：[Errno 111] Connection refused
• 原因：fun-asr 容器启动慢，刚起服务就提交任务，16G 内存的机器甚至起不来
• 修复：

# 等服务完全就绪再克隆，观察 asr 容器状态 docker ps docker logs duix-avatar-asr --tail 50 # 出现监听日志再操作

克隆报"file not exists"或提示视频不合规

• 现象：提交模特视频后克隆失败，日志提示文件不存在或素材无效
• 原因：上传的视频没有声音，或画面里的人没有说话——声音克隆素材被静默丢弃了
• 修复：换一段约 10 秒、单人正面、持续说话的录像重新上传；确认duix_avatar_data目录（Windows 在 D 盘）剩余空间充足

更多报错对照可以查 常见问题文档，客户端日志在界面右上角 Setting 菜单里打开：

下一步

• 你可以试试用curl直接打127.0.0.1:8383/easy/query?code=你的任务code，对比界面轮询和接口轮询拿到的进度差异
• 把 compose 文件从标准版换成 docker-compose-lite.yml，只留视频合成服务，对比一下磁盘占用和启动耗时
• 拿 30 秒和 3 分钟两段文案各跑一次合成，记录 8383 接口的返回耗时，感受长文案对显存和时长的影响

【免费下载链接】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