20分钟把开源数字人跑起来：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 是一个开源 AI 数字人项目，支持开源数字人本地部署：上传一段 10 秒左右的视频，就能完成数字人形象和声音的克隆，离线驱动口播视频生成。这份文档写给会敲docker-compose up、但没接触过这类项目的你。跟着做，半小时左右出第一条口播视频。
先对号入座：这份教程适合谁
| 人群 | 典型场景 | 预计投入时间 |
|---|---|---|
| 个人内容创作者 | 用真人形象做短视频口播 | 1 个下午（含首次约 70G 镜像下载） |
| 小团队运营 | 批量生成商品介绍、课程口播 | 1 天，之后反复复用 |
| 企业 IT 管理员 | 在带 GPU 的办公机上部署给团队用 | 1 天，另加日常维护 |
不在以上三类里？先往下看硬件要求，不够就省得折腾。
动手前自检：Docker部署AI数字人前查三件事
| 平台 | 最低配置 | 推荐配置 | 最容易踩的坑 |
|---|---|---|---|
| Windows 10（19042.1526 及以上） | 英伟达显卡 + 16G 内存 | i5-13400F / 32G / RTX 4070 | C 盘不足 100G 且没改镜像存放位置 |
| Ubuntu 22.04 桌面版 | 英伟达显卡 + 32G 内存 | 同上 | 没装 NVIDIA Container Toolkit，Docker 用不上 GPU |
官方验证过的推荐配置是 i5-13400F + 32G 内存 + RTX 4070，磁盘空闲 100G 以上。三个高频坑提前说：
- 本项目所有算力都在本地 GPU，没有英伟达显卡或驱动没装好，三个服务一个都起不来。
- 首次拉镜像约 70G 流量，建议连 WiFi 再启动。
- Windows 的 C 盘要放 Docker 镜像（需 100G），D 盘放数字人数据（需 30G）。C 盘不够也没事，装完 Docker 可以改镜像存放的盘。
图 1：Docker Desktop 的 Settings → Resources → Advanced，可把镜像换到空间更大的磁盘
三十分钟完成数字人服务本地部署：三步
第 1 步：拿到项目代码
这一步只做一件事：把仓库拉到本地。
git clone https://gitcode.com/GitHub_Trending/he/Duix-Avatar成功信号：本地出现Duix-Avatar目录，里面有deploy/子目录。预计耗时 1-2 分钟。
第 2 步：Windows 一键启动
先确认 WSL 正常（wsl --list --verbose有输出即可，没装就wsl --install），装好 Docker Desktop。然后进 deploy 目录启动服务：
cd Duix-Avatar\deploy docker-compose up -d这一步会拉镜像并启动三个服务。只想要视频生成能力，可改用轻量版：docker-compose -f docker-compose-lite.yml up -d，只起一个服务。
成功信号：Docker 里看到duix-avatar-tts、duix-avatar-asr、duix-avatar-gen-video三个服务都是 Running。 首次预计半小时，速度取决于网速。
第 3 步：Ubuntu 22.04 部署
这一步装 Docker、配好 GPU 运行时，再起 Linux 专用配置：
sudo apt update sudo apt install docker.io docker-compose然后按仓库 README_zh.md 的步骤安装英伟达驱动和 NVIDIA Container Toolkit，装完用nvidia-smi能打出显卡信息就算成功。再回到 deploy 目录执行docker-compose -f docker-compose-linux.yml up -d。成功信号同第 2 步。
用 50 系显卡（如 5090）的话，改用docker-compose-5090.yml；30/40 系配 CUDA 12.8 也可以用这份。客户端从项目 Release 下载即可：Windows 双击Duix.Avatar-x.x.x-setup.exe安装，Ubuntu 双击 AppImage 就能跑，root 用户启动失败就加--no-sandbox在终端运行。
第一次打开它：10秒视频克隆数字人的两条路径
图 2：主界面，上方两个大按钮，下方是作品与数字人列表
客户端连上服务后，你看到的是两张卡片。操作动线只有两条：
创建数字人：你点右上角 Create Avatar → 上传一段 10 秒视频 → 系统用视频里的脸和声音克隆形象 → 训练完成后回首页，My Avatars 列表里多了一个模型。注意：视频里必须有人在说话，声音是克隆用的，纯画面会报错。
创建口播视频：你点左上角 Create Video → 选刚才的模型 → 输入文案或上传音频 → 点生成 → 到 My Works 列表里看结果。右上角 Setting 菜单里有查看日志和切换语言，排障时会用到。
再进一步：视频合成 API 与数据去向
想跳过客户端直接集成，最常用的就是视频合成接口。服务起来后，把音频和模特视频发给本机 8383 端口：
curl -X POST http://127.0.0.1:8383/easy/submit \ -H "Content-Type: application/json" \ -d '{"audio_url":"a.wav","video_url":"b.mp4","code":"my-task-001","chaofen":0,"watermark_switch":0,"pn":1}'提交后GET http://127.0.0.1:8383/easy/query?code=my-task-001轮询进度。声音克隆和文本转语音在 18180 端口，完整参数见 src/main/service/。
数据去哪了：Windows 固定在D:\duix_avatar_data，Linux 在~/duix_avatar_data。挂载目录和端口映射都在 deploy/ 目录的 compose 文件里，按需调整对应参数即可；客户端侧服务地址和数据路径配置在src/main/config/config.js。
卡住了？对照这张排查表
| 你看到的错误 | 大概率原因 | 一行修复 |
|---|---|---|
docker-compose up -d报 registry-1.docker.io 超时 | Docker Hub 连接不稳 | 在 Docker 的 daemon.json 里加 registry-mirrors 配镜像源，重启 Docker |
| 三个服务起不来、反复重启 | 英伟达驱动缺失或损坏 | nvidia-smi验证驱动，报错就重装 |
| 新增模特报错，提示文件不存在 | 上传的视频没有声音或没人说话 | 换一段人在说话的视频重新上传 |
| 定制模特 Connection refused | asr 服务启动慢，或内存不足 16G | 服务起来后等几分钟再克隆 |
图 2：客户端报错时，点开对应 Docker 服务的 Logs 看红字，报错内容基本都能对上表
性能方面，官方没有给出"显卡档位 → 速度"的精确对照，实测以你机器为准。能给的事实是：内存低于 16G 大概率起不来；显存紧张时先用 lite 版只跑视频生成；50 系显卡记得换 5090 配置。更多问题见 doc/常见问题.md。
先跑通，再调参
数据不出本机，一次部署反复用。建议先用默认配置出第一条口播视频，再考虑接 API 或调参数。
【免费下载链接】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），仅供参考
