HeyGem（Duix Avatar）保姆级部署教程：Windows / Ubuntu 全离线数字人克隆与视频合成从零搭建

HeyGem（官方现名 Duix Avatar，仓库地址 GuijiAI/HeyGem.ai）是硅基智能（Duix.com）开源的 AI 数字人工具包：只要提交一段 10 秒左右的真人视频，就能克隆出这个人的外貌与声音，之后用文字或语音驱动这个数字人自动合成说话视频，全程本地离线运行、不需要联网。截至本文写作时，该仓库在 GitHub 上已收获 16k+ Star，是目前开源数字人赛道里少有的"开箱即用、带桌面客户端"的项目——它不像 SadTalker、LivePortrait 那样只给一堆 Python 脚本，而是把"语音识别（ASR）+ 语音合成（TTS）+ 视频合成"三个服务打成了 Docker 镜像，再配一个桌面客户端，普通用户双击安装包就能用。

本文按照官方 README 的部署方式，完整带你在 Windows 10/11 和 Ubuntu 22.04 上从零把这套服务跑起来：包含 Docker 安装、NVIDIA 显卡容器工具、docker-compose 拉起三个服务、客户端安装、以及官方开放的语音合成 / 视频合成 API 调用示例。所有命令均逐条对照官方 README 原文给出。

一、项目介绍与适用场景

Duix.Avatar 定位是"面向 Windows 系统的完全离线视频合成工具"，核心能力是把一个人数字化：高精度克隆面部五官与轮廓建立虚拟形象模型，同时克隆声音特征，再通过唇形同步把数字人画面和语音对齐。它与同类项目的差异在于：

• 工程化程度高：官方直接提供三个 Docker 镜像（fun-asr 语音识别、fish-speech-ziming 语音克隆合成、duix.avatar 视频合成），不再让用户自己折腾 Python 环境；
• 带桌面客户端：官方 Release 提供 Windows 安装包和 Linux AppImage，非技术人员也能操作；
• 全离线：所有算力都在本地完成，不联网，适合对隐私敏感的企业内训、课程录制、口播视频生产场景。

典型适用场景：自媒体人批量生产口播视频、企业做数字人员工 / 客服形象、教育机构录制虚拟讲师课程、团队做需要人脸与声音本地化处理的隐私敏感项目。个人本地玩票用它，硬件门槛也比纯研究型仓库友好——官方推荐配置只是 RTX 4070 级别的消费级显卡。

二、核心功能逐条拆解

1. 外貌克隆：用真人视频训练数字人形象模型，面部特征、轮廓高精度还原（官方 README"Core Features"第一条）。
2. 声音克隆：基于 fish-speech-ziming 服务克隆音色，支持各种语音参数调节。
3. 文字 / 语音双驱动：输入文字自动转语音驱动数字人，或直接上传语音文件让数字人按节奏与语调表演。
4. 音画同步合成：视频合成服务把数字人画面与声音高度同步，自然流畅的唇形对齐。
5. 多语言脚本：支持英语、日语、韩语、中文、法语、德语、阿拉伯语、西班牙语共 8 种语言。
6. 多模型管理：客户端支持导入多个数字人模型，一键切换。
7. 开放 API：Docker 启动后本机暴露多个端口，可自行调用语音合成（18180）与视频合成（8383）接口，接入自己的业务流程。
8. Lite 轻量版：资源紧张时可用 docker-compose-lite.yml 只启动一个视频合成服务。

三、全套官方链接

四、硬件与环境前置要求

官方 README 给出的硬件要求（出处：README "Dependencies" 与 "Mode 1 / Mode 2" 两节）：

• 系统：Windows 10 19042.1526 或更高版本；或 Ubuntu 22.04（官方仅在该版本完整测试，理论上其他桌面版 Linux 也可）。
• 推荐配置：CPU 为 13 代 Intel Core i5-13400F；内存 32GB；显卡 RTX 4070（必须是 NVIDIA 显卡并正确安装驱动）。
• 磁盘（Windows）：必须有 D 盘存放数字人与项目数据，预留 30GB 以上；C 盘存 Docker 镜像文件，预留 100GB 以上。若 C 盘不足 100GB，安装 Docker 后可在 Docker 设置里把镜像存储目录改到其他大于 100GB 的磁盘。
• 磁盘（Ubuntu）：剩余空间大于 100GB。
• 依赖：Node.js 18；三个 Docker 镜像（guiji2025/fun-asr、guiji2025/fish-speech-ziming、guiji2025/duix.avatar，compose 会自动拉取）。
• NVIDIA 50 系显卡用户：官方 README 提供了基于 PyTorch 预览版的部署方案（"Server Deployment Solution for NVIDIA 50 Series Graphics Cards"一节），30/40 系在 CUDA 12.8 下同样适用。

注意：本项目所有计算都在本地进行，没有 NVIDIA 显卡或驱动装错，三个服务根本起不来——这是官方 FAQ 的明确说明。

五、多平台部署步骤

官方仅提供 Windows 安装 与 Ubuntu 22.04 安装 两种方式，且均为 Docker Compose 部署服务端 + 桌面客户端。官方未提供纯 macOS 的部署方式，本文不展开。

5.1 Windows 部署

第 1 步：检查并安装 WSL。

wsl --list --verbose

解释：这条命令列出本机已安装的 WSL 发行版。如果有输出说明已装好；报错或无发行版则说明没装。随后执行：

wsl --update

解释：把 WSL 内核更新到最新，Docker Desktop 依赖它。

第 2 步：安装 Docker Desktop。

从 https://www.docker.com/ 下载对应 CPU 架构的 Windows 安装包，一路安装。出现 Docker Desktop 成功界面后启动 Docker，首次运行同意协议、跳过登录（官方 README 第 5、6 步明确要求 skip login）。

第 3 步：拉起服务端。

cd 你的克隆目录\deploy
docker-compose up -d

解释：docker-compose.yml 就在仓库的 /deploy 目录下，在该目录执行 compose 会自动拉取上面三个镜像并后台启动。如果你要用 Lite 版（只起 Duix.Avatar-gen-video 一个服务），执行：

docker-compose -f docker-compose-lite.yml up -d

下载过程约半小时、约消耗 70GB 流量，官方建议用 WiFi。看到 Docker 里出现三个服务均为 Running 即成功（Lite 版只有一个服务）。

（上图为官方 README 中的服务状态截图，出处：README.assets/6.png）

第 4 步：安装客户端。

直接到官方 Release 页 https://github.com/duixcom/Duix.Avatar/releases 下载 Windows 安装包，双击 Duix.Avatar-x.x.x-setup.exe 安装即可。

5.2 Ubuntu 22.04 部署

第 1 步：装 Docker。先用 docker --version 检查是否已装，已装可跳过：

sudo apt update
sudo apt install docker.io
sudo apt install docker-compose

第 2 步：装 NVIDIA 驱动与容器工具。显卡驱动按 https://www.nvidia.cn/drivers/lookup/ 安装，装完执行 nvidia-smi 能看到显卡信息即为成功。然后安装 NVIDIA Container Toolkit（Docker 调用 NVIDIA GPU 的必要组件）：

distribution=$(. /etc/os-release;echo $ID$VERSION_ID) \
  && curl -s -L https://nvidia.github.io/libnvidia-container/gpgkey | sudo apt-key add - \
  && curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

逐段解释：前一段添加 NVIDIA 官方 apt 源；第二段更新索引并安装工具包；nvidia-ctk runtime configure 把 NVIDIA runtime 写进 Docker 配置；最后重启 Docker 生效。

第 3 步：拉起服务端。

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

注意：Linux 用的是专门的 `docker-compose-linux.yml，与 Windows 版不是同一个文件（官方 README 明确区分）。

第 4 步：装客户端。

到 https://github.com/duixcom/Duix.Avatar/releases 下载 Linux 版 Duix.Avatar-x.x.x.AppImage，双击即可运行、无需安装。提醒：如果以 root 用户登录桌面，直接双击 AppImage 可能打不开，需要在终端执行：

./Duix.Avatar-x.x.x.AppImage --no-sandbox

5.3 源码编译部署

官方未提供脱离 Docker 的纯源码编译运行方式（ASR/TTS/合成三服务均以镜像形式分发），本文不展开。

六、配置文件全部参数解释

官方提供的核心编排文件是 deploy/ 目录下的三个 compose 文件（docker-compose.yml、docker-compose-lite.yml、docker-compose-linux.yml）。官方 README 中明确的可调点如下：

其余容器内环境变量官方未在 README 中逐一列明，此处不臆造。

七、启动、后台常驻与开机自启

7.1 启动

cd /deploy && docker-compose up -d

预期：三个容器进入 Running 状态；docker ps 能看到 fun-asr、fish-speech-ziming、duix.avatar 三个容器。

7.2 后台常驻

Docker 本身就是后台常驻服务，docker-compose up -d 启动的容器默认随 Docker 守护进程驻留。查看日志：

docker-compose logs -f

7.3 开机自启

Docker Desktop（Windows）与 Docker 服务（Ubuntu systemctl enable docker）默认开机自启后，容器只要不手动删除就会随 Docker 自动拉起。可对单个容器设置重启策略：

docker update --restart=always <容器名>

7.4 修改端口

服务启动后本机通过 http://127.0.0.1 访问，语音合成接口固定 18180、视频合成 8383。如需改端口，编辑 docker-compose.yml 中对应服务的 ports 映射后执行 docker-compose up -d 重建。

八、功能实操教程

第 1 步：确认三服务 Running。 打开 Docker Desktop 或执行 docker ps，三个服务均为 Up（官方 FAQ 自检第 1 条）。

第 2 步：启动客户端。 Windows 双击桌面图标；Linux 执行 AppImage。首次启动客户端会自动连接本机 127.0.0.1 的服务端口。

第 3 步：克隆数字人。 在客户端中上传一段 10 秒左右的本人正面视频，系统会同时训练形象模型与声音模型（音频需放到 D:\duix_avatar_data\voice\data 目录，与 fish-speech-ziming 服务约定）。

第 4 步：文字驱动生成视频。 在客户端输入脚本文字，选择刚克隆的数字人，点击生成。客户端会先调 ASR/TTS 出音频，再调视频合成服务出片。

第 5 步：用 API 自己跑通一条链路。

音频合成接口 http://127.0.0.1:18180/v1/invoke，POST 示例（官方原文）：

{
  "speaker": "{uuid}",
  "text": "xxxxxxxxxx",
  "format": "wav",
  "topP": 0.7,
  "max_new_tokens": 1024,
  "chunk_length": 100,
  "repetition_penalty": 1.2,
  "temperature": 0.7,
  "need_asr": false,
  "streaming": false,
  "is_fixed_seed": 0,
  "is_norm": 0,
  "reference_audio": "{voice.asr_format_audio_url}",
  "reference_text": "{voice.reference_audio_text}"
}

视频合成接口 http://127.0.0.1:8383/easy/submit：

{
  "audio_url": "{audioPath}",
  "video_url": "{videoPath}",
  "code": "{uuid}",
  "chaofen": 0,
  "watermark_switch": 0,
  "pn": 1
}

提交后用进度查询接口轮询：http://127.0.0.1:8383/easy/query?code=${taskCode}，taskCode 就是上面提交时的 code。

九、全套报错故障排查

1. 三个服务起不来 / 服务一直 Restarting 原因：本机没有 NVIDIA 显卡或驱动未正确安装（官方 FAQ 第 2 条：本项目所有算力都在本地，无 GPU 不启动）。 解决：执行 nvidia-smi 确认能看到显卡信息；Linux 下确认已装好 NVIDIA Container Toolkit 并 systemctl restart docker；Windows 下确认 Docker Desktop 设置里已启用 GPU 支持。

2. 客户端连不上服务 / 生成一直转圈 原因：服务端或客户端不是最新版。官方 FAQ 第 3 条要求两端都更新。 解决：服务端进入 /deploy 重新执行 docker-compose up -d 拉最新镜像；客户端重新 pull 代码后 build 或下载最新 Release 安装包。

3. docker-compose 下载镜像卡住 / 70GB 下载中断 原因：镜像体积大、依赖网络。官方提示约半小时、70GB 流量。 解决：挂可靠网络源后重试；docker-compose pull 单独拉镜像再 up -d。

4. AppImage 在 root 桌面上双击打不开 原因：Electron sandbox 在 root 下的限制。 解决：终端执行 ./Duix.Avatar-x.x.x.AppImage --no-sandbox。

5. C 盘不足 100GB 导致 Docker 安装失败 原因：Docker 默认把镜像存 C 盘。 解决：在 Docker Desktop 设置中把磁盘镜像位置改到其他剩余空间 >100GB 的目录（官方 README 硬件要求一节配图说明）。

十、升级、回滚与卸载

• 升级：服务端进入 /deploy 重新执行 docker-compose up -d 拉取最新镜像（官方 FAQ 第 3 条）；客户端到 Release 页下载最新安装包覆盖安装。
• 回滚：Docker 镜像用 docker images 找到旧版本 tag 重新 docker-compose up -d 指定旧 tag；官方未提供版本快照机制，重要数据目录 D:\duix_avatar_data 建议备份。
• 卸载：docker-compose down 停止并删除容器；docker rmi 删除三个镜像；删除 duix_avatar_data 数据目录；Windows 控制面板卸载客户端。

十一、商用许可与合规风险提示

本项目采用 DUIX.COM Community License（自定义社区许可），不是 MIT/Apache：

• 允许全球免费使用，但产品月活用户（MAU）超过 1000（或官方 README 业务对照表写的企业级阈值为 10 万用户 / 年营收超 1000 万美元）时，必须向 DUIX.COM 申请商业授权，官方可自行决定是否授予。
• 再分发时必须附带本协议、显著标注 "Built with DUIX.COM"，并在用户协议中声明产品基于 DUIX.COM 技术；用其训练/分发 AI 模型时模型名前需带 "DUIX.COM"。
• 官方明确免责：生成内容由使用者负责，不得用于违法、伤害他人、传播个人信息或针对弱势群体等用途。
• 数字人克隆涉及真人肖像与声音权，克隆他人形象前必须取得本人书面授权，这是使用层面的红线，与代码许可无关。

参考链接

• 官方 README：https://github.com/GuijiAI/HeyGem.ai/blob/main/README.md
• 官方 LICENSE：https://github.com/duixcom/Duix.Avatar/blob/main/LICENSE
• 客户端 Release：https://github.com/duixcom/Duix.Avatar/releases
• 官网：https://duix.com