Duix.Avatar 部署指南：数字人离线克隆到出片最短路径
【免费下载链接】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
你有一份写好的口播稿，但没有摄影棚，也不想反复对着镜头重录。Duix.Avatar 就是干这件事的开源数字人工具：提交一段约 10 秒的真人视频，完成形象和声音克隆；之后输入文案或上传音频，即可离线合成口型同步的口播视频，全程不依赖云端。
📌 项目速览：它能做什么
Duix.Avatar 由 Duix.com 开源，定位是"全离线数字人视频合成工具"：一个 Electron 客户端 + 三个 Docker 服务端容器，模特训练和视频合成能力全部跑在你自己的机器上。核心能力如下：
- 克隆形象与声音：上传一段带人声的约 10 秒视频，自动完成人脸建模和声音克隆
- 驱动虚拟形象出片：支持文字转语音、直接上传音频两种驱动方式
- 合成口型同步视频：画面与声音对齐，输出可直接使用的口播视频
- 管理多个数字人模型：客户端里一键导入、切换不同模特
- 开放本地 API：模特训练、音频合成、视频合成接口均可通过
http://127.0.0.1调用，方便接入自己的流水线
⚙️ 跑起来之前：硬件与软件要求
结论先说：NVIDIA 独立显卡 + 32G 内存是硬门槛，缺了任何一项服务都起不来。完整要求如下：
| 属性 | 要求 / 值 |
|---|---|
| 操作系统 | Windows 10 19042.1526 或更高版本，或 Ubuntu 22.04 |
| 显卡 | NVIDIA 显卡且驱动正确安装（必需，无 GPU 三个服务无法启动） |
| 推荐配置 | i5-13400F / 32G 内存（必需）/ RTX 4070 |
| 磁盘空间 | 服务镜像约需 100G 空闲；Windows 另建议 D 盘留 30G+ 存数字人与作品数据 |
| 软件依赖 | Docker + docker-compose；从源码构建客户端需 Node.js 18 |
| 服务端组成 | 三个 Docker 镜像：fun-asr（语音识别）、fish-speech-ziming（语音合成）、duix.avatar（视频合成） |
| 首次拉取 | 约 70G 流量、半小时左右，建议 Wi-Fi 环境 |
🚀 从零到跑通：6 步最小部署路径
按顺序执行，Windows 和 Ubuntu 通用（差异处已标注）。
- 拉取代码。仓库地址：
git clone https://gitcode.com/GitHub_Trending/he/HeyGem.ai- 确认显卡就绪。终端执行
nvidia-smi，能正常显示显卡信息即可，否则先去装好 NVIDIA 驱动。 - 安装 Docker。Windows 先执行
wsl --install、再wsl --update，然后安装 Docker Desktop；若 C 盘空闲不足 100G，在 Docker Desktop 的 Settings → Resources → Advanced 中把 Disk image location 改到空间充足的盘再 Apply & restart。
- 启动服务端。完整配置跑 deploy/ 目录下的默认编排；50 系显卡（或 30/40 系 + CUDA 12.8）改用
docker-compose-5090.yml。Ubuntu 用docker-compose-linux.yml：
cd deploy && docker-compose up -d- 安装客户端。从官方 Release 下载安装包：Windows 双击
Duix.Avatar-x.x.x-setup.exe安装；Ubuntu 下载 AppImage 双击启动（root 用户需加--no-sandbox参数）。 - 验证并出片。看到 asr / tts / gen-video 三个容器均为 Running 即部署成功，然后打开客户端：上传带人声的约 10 秒视频克隆模特 → 输入文案或上传音频 → 生成口播视频。
🎬 适用场景：假如你是……
- 假如你是课程讲师：先录一段 10 秒左右的样片完成克隆，之后每节课只写文案就能出片，换主题、换章节都不用再进"影棚"，录制环节被整体跳过。
- 假如你是自媒体作者：把一批口播稿批量转成数字人视频；项目支持导入多个模型，不同栏目可以切换不同的"出镜人"，文案还支持中、英、日、韩等 8 种语言。
- 假如你是开发者：可以跳过图形界面，直接调用本地 API——音频合成走
http://127.0.0.1:18180/v1/invoke，视频合成走http://127.0.0.1:8383/easy/submit（进度用/easy/query查询），把克隆和合成接进自动化流水线，参考代码在src/main/service/下的 model.js、video.js、voice.js。
🩹 常见卡点排查
Q1：拉镜像报超时 / Connection 错误？
Docker Hub 官方源不稳定。打开 Docker Engine 的 daemon 配置（Windows 在 Docker Desktop → Settings → Docker Engine；Linux 编辑/etc/docker/daemon.json），加入registry-mirrors国内镜像源后 Apply & restart，再重新执行docker-compose up -d。
Q2：服务起不来，或客户端连不上服务端？
按两步排查：先执行nvidia-smi确认显卡和驱动正常（本项目全部算力在本地，没有 N 卡驱动三个服务必然起不来）；再看容器状态，docker ps里应有三个 Running 的服务，缺哪个补哪个。另外客户端和服务端都要保持最新版，很多已知问题已在新版修复。
Q3：定制模特时报 Connection refused？
这是 ASR 服务启动慢导致的：Docker 起来后等几分钟再执行克隆操作。若等了很久仍失败，大概率是内存不足——16G 内存机器可能根本拉不起服务，建议 32G。
Q4：出现报错，日志去哪找？
客户端：右上角菜单 → Open Log，打开 logs 目录里的main.log。
获取Duix.Avatar客户端日志：菜单Open Log打开main.log
服务端：在 Docker 里点开对应容器的 Logs 页签，选中报错段复制出来。
更多问题可先查 doc/常见问题.md。
🧭 收尾：适合谁，不适合谁
一句话结论：有 NVIDIA 显卡、想做离线数字人口播视频的人适合；没有独立显卡、或需要实时互动数字人的不适合（开源版做的是离线视频合成，实时交互能力在官方平台上提供）。资源入口：仓库克隆地址见上文第 1 步，中文部署文档在 README_zh.md，服务端编排文件在 deploy/。
【免费下载链接】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），仅供参考
