开源数字人工具 Duix.Avatar 本地部署完整实战教程-平芜编程栈

开源数字人工具 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

这份指南写给想在自己电脑上完成数字人平台本地部署的开发者、内容创作者和企业培训团队。装完之后，你的机器就是一套数字人生产线：上传约 10 秒视频即可克隆形象与声音，输入文案后自动生成口播视频。这套能力由开源项目 Duix.Avatar 提供，支持文字或语音两种驱动方式。

部署前：环境与配置要求

选择本地部署，是因为人脸和声音素材属于敏感数据，留在自己的机器上最稳妥，长期使用也没有额外费用。

系统要求

Windows：10 系统 19042.1526 及以上版本，NVIDIA 显卡且装好最新驱动；必须有 D 盘（存数字人数据，空闲大于 30G），C 盘空闲大于 100G（存 Docker 镜像）
Ubuntu：22.04 Desktop，磁盘空闲大于 100G

硬件对比（三档）

项目	最低档	推荐档	高端档
CPU	第 10 代酷睿 i5 或同级 AMD	第 13 代 i7-13700F	第 14 代 i9-14900K
内存	16GB	32GB	64GB
显卡	RTX 3060（6GB）	RTX 4070（12GB）	RTX 4090（24GB）
存储	256GB SSD + 1TB HDD	512GB SSD + 2TB SSD	1TB SSD + 4TB SSD
大致性能	720p 合成，训练约 30 分钟/模型	1080p 合成，训练约 15 分钟/模型	4K 合成，训练约 8 分钟/模型

💡 选型建议：显卡优先，12GB 显存的卡加 32GB 内存能覆盖绝大多数场景。

部署实操：6 步装好数字人服务端

① 系统检查

先确认系统版本达标，用下面对应系统的命令验证：

winver lsb_release -a

第一条在 Windows 执行，第二条在 Ubuntu 执行。看到 19042 以上版本或 22.04，即通过。

② 安装 Docker 与 GPU 依赖

Docker 是把服务打包成即用镜像的容器运行环境，本项目完全依赖它跑服务端。

Windows 用户先装并更新 WSL，即 Windows 自带的 Linux 子系统：

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

⚠️ WSL 更新可能要重启电脑，动手前保存好手头工作。装完后从 Docker 官网下载 Docker Desktop 安装，首次启动接受协议并跳过登录。

Ubuntu 用户先按 NVIDIA 官方文档装好显卡驱动，再执行以下命令安装 Docker 和 GPU 容器工具（首次需先添加 NVIDIA Container Toolkit 软件源，仓库 README 中有现成命令）：

sudo apt update sudo apt install docker.io docker-compose sudo apt-get update sudo apt-get install -y nvidia-container-toolkit sudo nvidia-ctk runtime configure --runtime=docker sudo systemctl restart docker

验证方式：

docker --version nvidia-smi

前者输出 Docker 版本号，后者显示显卡型号和驱动信息，两项都正常即通过。

③ 克隆项目仓库

拿到 deploy/ 目录下的部署脚本和客户端源码：

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

进入Duix-Avatar目录能看到deploy/文件夹即通过。

④ 拉取镜像并启动服务

在 deploy/ 目录启动三个服务：fun-asr（语音识别）、fish-speech-ziming（语音合成）、duix.avatar（视频合成）：

cd deploy docker-compose up -d

首次运行会下载大量镜像，耗时取决于网速，请耐心等待。按需替换命令：

Ubuntu：docker-compose -f docker-compose-linux.yml up -d
50 系显卡（如 5090）：docker-compose -f docker-compose-5090.yml up -d
显存较小的轻量版：docker-compose -f docker-compose-lite.yml up -d（只启动 1 个服务）

💡 镜像拉取慢时，给 Docker 配置国内镜像源再重启服务，能明显提速。

⑤ 核对服务状态

查看容器运行情况：

docker ps

看到duix-avatar-tts、duix-avatar-asr、duix-avatar-gen-video三个容器均为 "Up" 状态即通过（lite 版只有duix-avatar-gen-video一个）。

⑥ 安装客户端

从项目 release 页面下载最新版安装包：

Windows：双击Duix.Avatar-x.x.x-setup.exe按向导安装
Ubuntu：双击.AppImage文件直接运行（root 用户需在终端加--no-sandbox参数）

✅ 主界面加载出来、能看到 "Create Video" 和 "Create Avatar" 两个入口，即安装成功。

跑通你的第一条数字人视频

客户端主界面顶部有两个入口：紫色的 "Create Video" 和蓝色的 "Create Avatar"。

第一步：建数字人形象

点 "Create Avatar"，上传约 10 秒的正面人像视频，要求光线充足、镜头稳定。训练完成后，"My Avatars" 列表里会出现你的新形象。

第二步：生成视频

点 "Create Video"，选中刚建的数字人，输入文案。系统自动合成口型对齐的口播视频，无需逐句剪辑。

第三步：检查产物

到 "My Works" 列表点开作品预览，确认画面、口型和声音都正常，再导出成片。

场景速览：三类常见用法

教育：虚拟教师

素材：10~15 秒正面讲课视频，背景简洁、光线均匀
参数：语速 120~150 字/分钟，文案中用逗号句号控制停顿
产出：课程导入、单词领读、知识点讲解片段

企业：数字代言人

素材：正面与 45 度角视频各一段，包含问候等标准动作
声音：安静环境录制，覆盖正式、亲切两种语气
产出：设置品牌背景和标题后，保存为可复用模板

个人自媒体

素材：任意 10 秒正面口播片段即可
参数：先用 50 字以内短文案跑通流程，再逐步加长
产出：日常口播、观点点评、带货介绍

常见问题速查

遇到问题先别慌，打开 Docker Desktop 里对应容器的日志面板，找带 ERROR 或 Traceback 的行定位：

问题现象	可能原因	处理方式
容器起不来，反复 Restarting	端口 18180/8383 被占用；显卡驱动缺失；磁盘不足	用`netstat -tuln \\| grep -E "18180\\|8383"`查端口；更新 NVIDIA 驱动；清理出 30G 以上空间
训练卡在某个百分比	素材光线差、分辨率低；显存不够	重录 720p 以上、H.264 编码的 MP4；或降低精度、升级显卡
镜像拉取超时或极慢	未配置镜像源	在`/etc/docker/daemon.json`添加国内镜像源后重启 Docker
客户端连不上服务	三个容器未全部 Up	在 deploy/ 目录重跑`docker-compose up -d`，等约 10 分钟再试
视频合成速度慢	内存吃紧、任务排队	关闭其他大型程序；清理 duix_avatar_data 下的缓存文件