Duix.Avatar 数字人克隆部署教程：从一段10秒视频到第一条口播成片-育师

Duix.Avatar 数字人克隆部署教程：从一段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

上传一段 10 秒左右的说话视频，几分钟之后，你就能得到一条长相相同、声音相同、口型对得上的口播视频——这是 Duix.Avatar 能做的事。它是一款开源的全离线 AI 数字人克隆与视频合成工具：用真人视频克隆形象和声音，再用文本或音频驱动这个数字人，产出成片。全程在本地显卡上运行，不需要联网，适合想自己搭建数字人工作流的内容创作者、教师和企业用户。

📦 项目速览：Duix.Avatar 是什么

克隆加驱动，一步到位

Duix.Avatar 由两部分组成：Docker 部署的推理服务端，和一个桌面客户端（Windows 安装程序 / Ubuntu AppImage）。客户端负责界面交互，所有计算都走本地服务，素材不经过公网传输。它同时支持形象克隆和声音克隆——上传的视频里既提取外貌特征，也提取人声特征。

与商业服务的差异

商业数字人平台通常按条数或时长计费，且数据要上传到云端；Duix.Avatar 把克隆与合成链路整体开源，可以免费使用并修改代码（企业用户量超 10 万或年营收超 1000 万美元需签署商业许可协议，仓库内有中英文协议 PDF）。代价是：你需要自己准备一张 NVIDIA 显卡并承担维护工作。

📋 跑前检查清单：硬件与环境要求

系统与硬件

项目	要求
系统	Windows 10（19042.1526 及以上）或 Ubuntu 22.04 Desktop（内核 6.8.0-52-generic 已验证，其他 Linux 版本未测试）
显卡	NVIDIA 显卡且驱动装好，30/40/50 系列均可（50 系列用专门方案，见下文）
内存	建议 32GB 及以上，16GB 可能起不来全部服务
CPU	参考配置 i5-13400F 级别
开发环境	Node.js 18（源码开发客户端时需要）

磁盘空间规划

Windows：C 盘留给 Docker 镜像，空闲要大于 100G；必须有 D 盘存数据（数字人、作品），空闲大于 30G。C 盘不够的话，装完 Docker 后可以把它的数据目录改到别的盘。
Ubuntu：空闲空间大于 100G 即可。
首次拉镜像大约消耗 70G 流量，注意带宽。

🔧 部署全流程：从克隆到三个服务跑起来

第一步：拿到代码并确认 GPU

git clone https://gitcode.com/GitHub_Trending/he/Duix-Avatar

执行nvidia-smi，能显示显卡信息说明驱动没问题。没有 NVIDIA 显卡或没装驱动，三个服务都起不来，这是最常见的"部署失败"。

第二步：装 Docker（分平台）

Windows：先执行wsl --list --verbose看 WSL 是否已装，没有就wsl --install；再用wsl --update更新。然后从 Docker 官网下载 Docker Desktop 安装，首次启动接受协议、跳过登录即可。

Ubuntu：docker --version检查是否已装，没有则：

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

接着安装 NVIDIA Container Toolkit（Docker 调用 GPU 的必需组件）：添加 NVIDIA 包仓库 →sudo apt-get install -y nvidia-container-toolkit→sudo nvidia-ctk runtime configure --runtime=docker→sudo systemctl restart docker。仓库 README_zh.md 里给出了完整命令。

第三步：启动服务端

进入仓库的 deploy/ 目录，按显卡情况三选一：

# 常规（30/40 系列） docker-compose up -d # 50 系列显卡（30/40 系列 CUDA 12.8 用户也可用） docker-compose -f docker-compose-5090.yml up -d # 只要视频合成、不要声音克隆的轻量版（仅 1 个服务） docker-compose -f docker-compose-lite.yml up -d # Ubuntu 专用（数据目录改为 ~/duix_avatar_data） docker-compose -f docker-compose-linux.yml up -d

耐心等待大约半小时，镜像下载完成后，Docker 里出现三个容器即为成功：duix-avatar-tts（语音合成，端口 18180）、duix-avatar-asr（语音识别，端口 10095）、duix-avatar-gen-video（视频合成，端口 8383）。

第四步：安装客户端

到项目 Releases 页下载官方构建包：Windows 双击Duix.Avatar-x.x.x-setup.exe安装；Ubuntu 直接运行Duix.Avatar-x.x.x.AppImage，root 用户下需加参数--no-sandbox。客户端启动后会自动连接本机 8383 / 18180 端口，无需额外配置。

🎬 产出你的第一个数字人作品

建模特：上传素材并等待克隆

客户端首页点击"Create Avatar"，上传一段视频。素材要求：约 10 秒、画面里人脸清晰、视频中必须有真人说话的声音——系统会用这段声音做声音克隆，纯静音视频会直接报错。提交后进入"模特训练"流程，视硬件不同需要几分钟，完成后"My Avatars"里会出现新模特卡片。

生成视频：文本驱动成片

点击"Create Video"，在左侧选中刚建好的模特，中间输入文案（或直接上传音频），点击生成。预期结果：几分钟后"My Works"里出现一条口型与语音同步的视频，可在线播放或导出。文案支持中文、英语、日语、韩语、法语、德语、阿拉伯语、西班牙语共 8 种语言。

🚀 进阶玩法：API 调用与批量生成

三个本地 API

Docker 启动后全部走http://127.0.0.1即可调用，客户端源码 src/main/service/ 下的 model.js、voice.js、video.js 就是现成的调用示例：

能力	接口
声音训练预处理	`127.0.0.1:18180/v1/preprocess_and_tran`，返回`reference_audio`与`reference_text`，后续合成要用到
文本转语音	`127.0.0.1:18180/v1/invoke`，传入文本和上一步的返回字段
视频合成与查进度	`127.0.0.1:8383/easy/submit`提交（音频+静音视频路径），`8383/easy/query?code=xxx`轮询进度

批量与集成

合成接口是异步任务模型，自己写脚本循环提交 + 轮询，就能搭一条批量生产线：文案列表 → 逐条 TTS → 逐条视频合成。多模特场景可以维护多份 reference 信息切换说话人。

⚙️ 原理速览：三个服务与数据流

组件分工

整条链路由三个容器化模型服务加一个 Electron 客户端构成：guiji2025/fun-asr做语音识别（把素材里的话转成文字）、guiji2025/fish-speech-ziming做声音克隆与文本转语音、guiji2025/duix.avatar做核心视频合成。三个容器共享同一张 GPU，数据目录约定为D:\duix_avatar_data（Linux 为~/duix_avatar_data），可在 docker-compose 中修改。

数据流

上传的视频先被拆成"静音视频 + 音频"两条线：音频送进 ASR 得到参考文本，再经 TTS 训练得到参考音频，之后任意文本都能用你的声音念出来；念出的音频与静音视频一起送进 8383 合成服务，对齐口型后输出成片。理解这条流之后，任何环节失败（比如音频训练报错）都能定位到对应服务。

🩺 避坑手册：按故障现象排查

服务起不来：拉镜像失败

报错含Get "https://registry-1.docker.io/v2/": ... timeout时，是 Docker Hub 连不上。解法：在/etc/docker/daemon.json的registry-mirrors里配置国内镜像源（源会失效，自行搜索当前可用的），重启 Docker 后重跑docker-compose up -d。

新建模特失败：素材不合规

客户端提示创建模特失败时，九成是素材问题：视频必须包含真人清晰说话的声音。换一段带声音、人脸居中的视频重试。

Connection refused：ASR 还没就绪

日志里出现建立funasr连接异常：[Errno 111] Connection refused，通常是duix-avatar-asr启动较慢，服务端刚起来就操作了。等几分钟再试；若内存只有 16G，该服务可能根本起不来，按检查清单升配。

读日志：客户端与服务端

客户端：主界面右上角 Setting → Open Log。服务端：Docker 容器逐个点 Logs，把关键报错带出来。

🎯 适合谁用：场景推荐

内容创作

自媒体做口播、资讯播报时，不需要真人反复出镜重录，一条脚本进去就是一条成片；8 种语言也方便做多语种版本。

教育培训

把课程文稿交给固定形象的数字人讲师，统一风格、批量产出系列课视频，改文案就能重生成。

企业宣传

产品介绍、客服话术演示等标准化内容可以用同一数字人形象持续产出；开源版支持免费商用，注意核对仓库内商业许可协议的适用条件。

🏁 下一步与求助渠道

一条上手路径

按本文顺序执行即可：备机检查 → Docker 部署三服务 → 装客户端 → 上传 10 秒视频建模特 → 生成第一条成片。跑通后，再看 deploy/ 下的四个 compose 文件做定制（改端口、改数据目录、换 5090 镜像）。

遇到问题去哪问

先翻仓库内的 doc/常见问题.md，里面有镜像拉取、模特报错、ASR 连接等已验证的解法；再查项目 Issues 看是否已有人解决并关闭。提问时按"复现步骤 + 截图 + 报错日志"三件套组织，处理会快很多。

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

Duix.Avatar 数字人克隆部署教程：从一段10秒视频到第一条口播成片