如何本地部署Duix-Avatar，30分钟创建AI数字人：完整Docker实战指南

如何本地部署Duix-Avatar，30分钟创建AI数字人：完整Docker实战指南

【免费下载链接】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 秒左右的视频，就能完成人物形象和声音的克隆；之后输入文案或上传音频，即可自动驱动口型，生成口播视频，脚本支持中文、英语、日语、韩语等八种语言。

整个方案分成两部分：Docker 服务端负责计算（形象训练、声音克隆、视频合成），桌面客户端提供图形化界面。视频和音频始终不离开你的电脑，这也是它适合隐私敏感场景的原因。本文按"查硬件 → 配 Docker → 起服务 → 装客户端"的顺序带你走完部署，最后用一段 10 秒视频验证效果。

以 Windows 环境为主线介绍，Ubuntu 22.04 用户原理相同，只是换用deploy/docker-compose-linux.yml启动。

动手前准备：系统与硬件清单

装任何东西之前，先核对这张表，有一项不满足，后面的步骤大概率会卡住：

⚠️ 所有算力都跑在本地英伟达显卡上。没有显卡或驱动没装好，三个服务是无论如何起不来的，所以这一项要先确认。

部署实操

第一步：环境检查，确认 GPU 与磁盘空间

做什么：先确认显卡对系统可见，再看两个盘的剩余空间。

nvidia-smi

成功后应看到：命令输出显卡型号、驱动版本和显存信息。如果显示找不到显卡，先装最新的 NVIDIA 驱动。Windows 用户同时在"此电脑"里确认 D 盘和 C 盘的剩余空间达标。

第二步：WSL 与 Docker Desktop 配置

做什么：检查并安装 WSL，然后安装 Docker Desktop（按 CPU 架构选对应安装包）。

wsl --list --verbose wsl --install wsl --update

成功后应看到：Docker Desktop 启动后，底部状态栏显示 Engine running。安装 WSL 时会要求设置用户名和密码，记一下，后面会用到。

Docker 装好后还有一件事：如果 C 盘空闲不足 100G，打开 Settings → Resources → Advanced，在 Disk image location 处点 Browse，把镜像文件位置改到空间充足的磁盘。

💡wsl --install受网络影响可能失败，多试几次即可。完整的前置条件说明见 README_zh.md 的"Windows 安装"一节。

第三步：拉取镜像与启动服务

做什么：克隆项目，进入deploy目录，执行 docker-compose。

git clone https://gitcode.com/GitHub_Trending/he/Duix-Avatar cd Duix-Avatar/deploy docker-compose up -d

成功后应看到：Docker Desktop 的容器列表里出现三个服务且均为 Running：duix-avatar-tts（语音合成）、duix-avatar-asr（语音识别）、duix-avatar-gen-video（视频合成）。首次拉镜像约 70GB，耗时取决于网速，建议连 WiFi 或有线网络等待。

根据硬件情况可以选用不同的 compose 文件：

• 标准版：docker-compose.yml，三个服务齐全
• 轻量版：docker-compose -f docker-compose-lite.yml up -d，只起duix-avatar-gen-video一个服务
• 英伟达 50 系列显卡（5090 已测试通过）：docker-compose -f docker-compose-5090.yml up -d

⚠️ 三个服务都依赖 GPU 运行时，如果容器反复重启而不是 Running，优先回到第一步检查显卡驱动，再看 常见问题文档。

第四步：安装客户端

做什么：从项目发布页下载官方构建的安装包，Windows 双击Duix.Avatar-x.x.x-setup.exe按向导安装；Ubuntu 用户直接运行.AppImage文件即可，无需安装（root 用户需加--no-sandbox参数）。

成功后应看到：客户端启动后，本地服务状态显示绿色对勾，说明已成功连上本地服务，界面可以正常操作。

验证服务，并用一段10秒视频创建第一个数字人

服务是否真的跑起来了，用两种方式确认：

1. Docker Desktop 容器列表里，三个服务（轻量版为一个）全部是 Running；
2. 点开容器查看 Logs 页签，日志持续输出正常的启动信息，右侧状态为 Running，即为健康。

服务端接口都暴露在本地127.0.0.1：8383 端口对应视频合成，18180 对应语音合成，10095 对应语音识别。如果你想用代码对接而不是走客户端，接口的请求参数示例见 README_zh.md 的"开放 API"部分，对应实现代码在 src/main/service/ 目录下。

然后创建第一个数字人：

1. 在客户端首页点"快速定制 / Create Avatar"；
2. 上传一段 10 秒左右的视频；
3. 等训练完成，新的数字人出现在"My Avatars"列表里。

⚠️ 上传的视频里必须有人声且是人在说话——程序要用这段声音做声音克隆，无声视频会直接失败。

接着点"Create Video"，输入口播文案或上传音频文件，系统会自动完成口型匹配并导出视频。首次生成需要几分钟，结束后可以对照原视频看看口型和声音相似度。

原理速览

说人话，这个项目做三件事：

• 面部重建：用 3D 形变模型从单目视频里逐帧拟合面部特征，重建出面部网格，原视频轻微晃动也不影响模型稳定。这就是为什么只需要 10 秒视频，而不是摄影棚级别的采集。
• 声音克隆：从视频里那几秒人声样本中提取音色、语调和节奏，之后输入文字就能合出音色相近的语音。
• 视频合成：把语音和数字人画面按帧对齐口型，音画同步后导出成口播视频。

三个环节各对应一个 Docker 服务，模块划分也直接体现在源码里，想深入看 src/main/service/ 下 model、voice、video 三个文件即可。

还能做什么

• 在线教育：把课程讲义转成数字人课程视频，不同知识点换不同文案各出一版，省去反复拍摄。
• 电商营销：数字人主播，商品卖点直接填成文案转成口播视频，适合批量生成商品介绍和促销短视频。
• 企业培训：入职材料、制度宣导这类固定格式内容用文字驱动，内容更新时随时重出，不用重新找人录。

这三类的共同点是"文案 → 语音 → 口型"这条链路，本地服务部署一次后可以反复复用。

常见坑速查

1.docker-compose up -d连接失败，报 registry-1.docker.io 超时

网络访问不到 Docker Hub 官方源。最常见的解法是配置国内镜像加速器：Docker Desktop → Docker Engine，在配置里加上registry-mirrors，点 Apply & restart 后重新拉取。

2. 新增模特报错 "file not exists"

先查文件路径里有没有中文或特殊字符，路径尽量保持纯英文数字；再确认上传的视频确实带人声。定位不了就打开客户端"设置 → 打开日志"，看具体报错位置。

服务端这边也能直接看容器日志，下面是典型的 file not exists 报错现场：

3. 定制模特时报 Connection refused

ASR 服务启动比其他服务慢，服务刚起来就克隆会连不上。等服务启动几分钟后重试；另外如果机器内存低于 32GB，服务本身可能就没起来，这属于硬件不满足，不是配置问题。

4. 磁盘空间不足，拉镜像或生成视频中断

首次镜像下载约 70GB，之后模型和作品数据落在 D 盘。C 盘保留 100GB 以上、D 盘保留 30GB 以上，C 盘快满了就按第二步的方法把 Docker 镜像存储位置迁到别的盘。

结尾

下一步就一件事：录一段 10 秒的口播视频，传到客户端里，等第一个数字人生成出来。遇到问题先对照上面"常见坑速查"的四条自查，大多数情况已经覆盖。后续版本还会持续改善多语言效果和 GPU 兼容性，记得把服务端和客户端都更新到最新版，能少踩很多坑。

【免费下载链接】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