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

Duix.Avatar 是一款开源的数字人（AI Avatar）工具包，支持全离线运行：提交一段 10 秒左右的真人视频，即可克隆形象和声音，之后输入文案或上传音频，就能自动生成口型同步的播报视频。对需要制作口播内容、又不想把素材上传到第三方平台的开发者来说，这是一条可以在自己电脑上完整跑通的路径。

部署前需要检查什么

Duix.Avatar 的架构是「桌面客户端 + Docker 服务端」，所有算力都在本地，没有 NVIDIA 显卡就启动不了核心服务。开始前先对照硬件与软件要求：

系统：Windows 10 19042.1526 及以上，或 Ubuntu 22.04 Desktop
显卡：必须为 NVIDIA 显卡并正确安装驱动（官方已验证 RTX 40 系，50 系有专用方案）
内存：32GB 及以上（必要，16GB 可能无法启动 ASR 服务）
磁盘：数据盘 30GB+，Docker 镜像存储盘 100GB+（首次拉取镜像约消耗 70GB 流量）
软件：Node.js 18、Docker（Windows 需先安装 WSL）

如何完成首次运行

以最常用的 Windows 环境为例，最短路径分三步。

第一步：获取项目源码

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

第二步：启动服务端。项目依赖三个 Docker 镜像（guiji2025/fun-asr、guiji2025/fish-speech-ziming、guiji2025/duix.avatar），在仓库的/deploy目录执行：

docker-compose up -d

耐心等待半小时左右（取决于网速），Docker 中出现三个 Running 状态的服务即表示服务端就绪。显存较小的机器可改用docker-compose-lite.yml精简配置；50 系显卡（含已装 CUDA 12.8 的 30/40 系）使用docker-compose-5090.yml。Linux 用户则对应使用docker-compose-linux.yml。

💡 如果 C 盘空间不足 100GB，安装 Docker 后可在设置中把镜像存储改到其他磁盘。

第三步：运行客户端。从官方 Releases 下载对应平台的安装包（Windows 为Duix.Avatar-x.x.x-setup.exe，Linux 为 AppImage，无需安装），双击启动后连接本机127.0.0.1的服务端即可。

功能验证：三个典型场景确认效果

服务端就绪后，建议按以下顺序验证，每步都对应一个可感知的结果：

克隆形象与声音：在客户端新建模特，上传一段10 秒左右、本人正对镜头说话的视频。注意：素材必须有声音且是人在说话，程序会用这段声音做克隆，静音视频会直接报错。
文字驱动：输入一段文案，系统先用克隆的声音合成音频，再生成口型匹配的视频。重点听音色相似度、看口型是否自然。
音频驱动：上传一段现成音频文件，跳过文字转语音环节直接合成。适合对发音有严格要求的场景。

生成的视频支持中文、英语、日语、韩语、法语、德语、阿拉伯语、西班牙语共八种语言脚本。如果口型效果不理想，优先换用更清晰、光照均匀、语速平稳的原片重新训练。

生成失败或服务不稳定时如何排查

按出现频率从高到低，先自查以下四点：

拉镜像失败（request canceled / context canceled）：Docker Hub 官方源不稳定，在/etc/docker/daemon.json中配置registry-mirrors国内镜像源后重试，Windows 用户可在 Docker Desktop 设置中完成同样配置。

新增模特报 Connection refused：ASR 服务（fun-asr）冷启动较慢，服务端刚启动后请等待几分钟再克隆形象；内存过小（如 16GB）也会导致该服务起不来。
服务状态异常：确认 Docker 中三个服务全部为 Running；确认nvidia-smi能正常输出显卡信息。
升级到最新版本：服务端在/deploy重新执行docker-compose up -d，客户端拉取代码后重新构建，社区迭代很快，很多已知问题新版已修复。

排查时记得保留日志：客户端可在日志入口导出日志文件；服务端直接点击对应 Docker 容器复制日志，附上完整日志能显著加快社区定位问题的速度。

进阶：开放 API 与后续使用

Duix.Avatar 的服务端在本地暴露了模特训练和视频合成两组 API（基于127.0.0.1调用），覆盖形象训练、音频合成、视频提交与进度查询等接口，适合把数字人能力嵌入自己的业务系统。接口定义可直接参考仓库中的 src/main/service/ 下的model.js、voice.js、video.js，具体参数以仓库内 README 的最新说明为准。

几点使用边界提醒：