30分钟跑通 Duix.Avatar：免费开源的本地AI数字人克隆实操指南-迪斯科星球

30分钟跑通 Duix.Avatar：免费开源的本地AI数字人克隆实操指南

【免费下载链接】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 数字人工具包：上传一段约10秒的视频，就能完成形象与声音的双重克隆，之后输入文案或音频即可驱动数字人自动生成口播视频，全程无需联网，数据不出本机。下面按"查机器 → 起服务 → 客户端上手 → 踩坑排错"的顺序，带你从零把整套环境跑通。

先弄懂它：这个工具到底能做什么

Duix.Avatar 的用法可以概括为"录一段视频，之后随便说"。上传的源视频会被拆解为静音视频加音轨两部分，分别用于克隆形象和克隆声音。之后的每一次生成，只需要给脚本或给音频。

能力	具体表现	底层技术
外貌与声音克隆	高精度捕捉五官、面部轮廓，还原语调、语速等声音细节，支持多种声音参数	AI 人脸分析 + 声音克隆
文字/语音双驱动	文字经自然语言处理转为流畅语音；也可直接上传音频，让口型跟随语音的节奏与语调变化	NLP + 自动语音合成（TTS）
视频合成	画面与声音高度同步，口型匹配自然	计算机视觉（面部识别、口型分析）
八种语言脚本	英语、日语、韩语、中文、法语、德语、阿拉伯语、西班牙语	—

除功能外，它还有三个值得一提的特点：全离线（不联网、隐私安全）、上手门槛低（界面简洁，无技术背景也能操作）、多模型管理（可导入多个模型，用一键启动包统一管理）。

第一步：硬件与环境自查清单

部署前先把机器对着这张表过一遍，尤其是显卡——本项目所有算力都在本地，没有 NVIDIA 显卡或未装好驱动，三个服务端容器根本起不来，这是最高频的失败原因。

平台	系统	磁盘	推荐配置（硬性要求加粗）
Windows	Windows 10 19042.1526 或更高	D 盘 ≥30GB（存数字人与作品）；C 盘 ≥100GB（存 Docker 镜像，装完后可改位置）	13代 i5-13400F、内存 32GB 及以上、RTX 4070 等 NVIDIA 显卡 + 正确驱动
Ubuntu	22.04 Desktop（内核 6.8.0-52-generic 已验证，其他 Linux 未做兼容性测试）	空闲空间 ≥100GB	同上

另外服务端依赖 Nodejs 18。C 盘空间不足 100GB 时不必焦虑，装完 Docker 后可在设置里把镜像目录指到空间充足的磁盘。

第二步：Windows 一条龙启动

2.1 检查并更新 WSL

wsl --list --verbose # 查看是否已装 WSL wsl --update # 更新 WSL

未安装则执行wsl --install，过程中需要设置并记住用户名和密码；因网络原因可能失败，多试几次即可。

2.2 安装 Docker Desktop 并规划磁盘

按机器 CPU 架构下载对应的 Docker Windows 安装包，出现主界面即安装成功。首次运行需接受协议并跳过登录。

进入 Settings → Resources → Advanced，可以在此修改磁盘镜像位置。若 C 盘紧张，把 Disk image location 指到剩余空间大于 100GB 的磁盘分区，再点 Apply & restart。

2.3 拉取镜像并启动服务端

docker pull guiji2025/fun-asr docker pull guiji2025/fish-speech-ziming docker pull guiji2025/duix.avatar

然后进入deploy目录启动容器：

cd deploy docker-compose up -d

想省资源可换用轻量版（只启动视频合成一个服务）：

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

首次下载约70GB数据、耗时半小时左右，网速决定进度，建议连 Wi-Fi。成功后 Docker 中应出现三个服务；lite 版则只有一个Duix.Avatar-gen-video服务。

2.4 安装客户端

下载官方构建的安装包，双击Duix.Avatar-x.x.x-setup.exe完成安装，打开即可开始创建数字人。

第三步：Ubuntu 22.04 路线

先执行docker --version，已装 Docker 可跳过本节开头部分。

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

安装 NVIDIA 显卡驱动后，执行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

启动服务端：

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

镜像下载太慢时，在/etc/docker/daemon.json中加入registry-mirrors配置国内镜像源（镜像源时效性较强，请自行搜索最新的）。

客户端使用Duix.Avatar-x.x.x.AppImage，双击即可启动，无需安装。注意：以 root 用户进入桌面时双击可能无效，需在终端执行./Duix.Avatar-x.x.x.AppImage --no-sandbox并附加--no-sandbox参数。

NVIDIA 50 系列显卡专项方案

如果你用的是 50 系显卡（经 5090 实测通过；30、40 系且 CUDA 12.8 的用户也可采用此方案），需要走基于 PyTorch 官方预览版的独立配置：

cd deploy docker-compose -f docker-compose-5090.yml up -d

踩坑实录：从拉镜像失败到日志排查

容器启动失败：Docker Hub 连接超时

docker-compose up -d报net/http: request canceled一类错误，本质是官方源连接不稳定。两条路：开全局网络代理，或配置国内镜像源。Windows 下在 Docker Desktop 的 Settings → Docker Engine 的 JSON 配置中加入registry-mirrors字段：

{ "registry-mirrors": [ "https://hub.fast360.xyz", "https://hub.littlediary.cn", "https://docker.kejilion.pro", "https://docker.1panelproxy.com" ] }

Ubuntu 同理，写入/etc/docker/daemon.json后重启 Docker。

三个服务没有全部 Running

提问前先自查四件事：

三个服务（asr / tts / gen-video）是否均为 Running 状态；
机器是否确为 NVIDIA 显卡且驱动正常（本项目无 GPU 跑不起来）；
服务端与客户端是否都更新到最新版——服务端到deploy目录重跑docker-compose up -d，客户端 pull 代码后重新 build；
项目更新频繁，先看看社区已知问题是否已解决。

定制模特报 Connection refused

日志出现[Errno 111] Connection refused时，多半是Duix.Avatar-asr启动较慢：服务端启动后等几分钟再做克隆操作即可。另外若内存只有 16GB，可能直接启动不了，建议 32GB。

新增模特时直接报错

用于创建模特的视频必须带声音且是人在说话，程序要靠这段声音做声音克隆。无声视频是无效的。

服务端日志报 "file not exists"

这类错误指向音频存储路径问题。音频默认放在D:\duix_avatar_data\voice\data（该路径是与guiji2025/fish-speech-ziming服务约定的，可在 docker-compose 文件中修改），确认文件真实存在且路径拼写一致。

日志去哪里找

客户端日志：点右上角设置菜单中的 "Open Log" 打开：

服务端日志：点开三个 Docker 服务，在 Logs 页定位关键报错后直接复制：

进阶：本地开放 API 二次集成

Docker 启动后会在本地暴露端口，通过http://127.0.0.1即可调用，方便把数字人能力嵌入自己的应用：

能力	端点
音频预处理（模特训练第一步）	`POST http://127.0.0.1:18180/v1/preprocess_and_tran`
音频合成	`POST http://127.0.0.1:18180/v1/invoke`
视频合成提交	`POST http://127.0.0.1:8383/easy/submit`
合成进度查询	`GET http://127.0.0.1:8383/easy/query?code=${taskCode}`

完整调用示例（含固定传参说明）参考客户端主进程中的三份服务代码：model.js、video.js、voice.js。

三步开始 + 学习资源

三步起步：

克隆仓库并进入目录：

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

在deploy目录执行docker-compose up -d，等待镜像下载与服务 Ready；
安装客户端，上传一段 10 秒左右的说话视频，完成你的第一个数字人。

学习资源：

部署配置：deploy/docker-compose.yml（含 5090、lite、linux 三个变体）
官方 FAQ：doc/常见问题.md
客户端主进程入口：src/main/index.js
协议说明：LICENSE

数字人创作不必再依赖云端。把环境跑通之后，从"克隆自己"到"批量出片"，剩下的只是时间问题。

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

企业官网建设流程全解析