Duix.Avatar 虚拟形象视频合成安装指南：从 0 到 1 生成第一条数字人视频

Duix.Avatar 虚拟形象视频合成安装指南：从 0 到 1 生成第一条数字人视频

【免费下载链接】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 是一款免费开源的虚拟形象视频合成工具。用一段 10 秒左右的真人视频克隆你的外貌和声音，再通过文字或音频驱动形象，生成口播视频。全程本地离线运行，数据不出本机，无需联网。

📋 装前自检

先确认你的机器满足条件，这是 Duix.Avatar 安装教程里最省时间的一步。

💡 本项目所有算力都在本地：没有 NVIDIA 显卡或没装好驱动，三个后端服务直接起不来，装其他的东西都白搭。

预装工具清单：

• Git —— 拉取项目源代码
• Docker —— Windows 用 Docker Desktop，Ubuntu 用 docker.io + docker-compose，承载语音识别、语音合成、视频合成三个服务
• NVIDIA 驱动 —— 装完用nvidia-smi能显示显卡信息才算正常
• Node.js 18 —— 仅从源码构建客户端时需要，用官方安装包可跳过

Windows 上 Docker 镜像默认放在 C 盘，空间要求大于 100G。如果 C 盘不够，在 Docker 设置的 Resources 里把 Disk image location 改到剩余空间大于 100G 的磁盘：

🛠️ 安装主线

第 1 步｜拉取项目源码

目的：把源代码和部署文件下载到本地，后面所有命令都在这个目录里执行。

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

把项目克隆到本地，然后进入项目目录。

判断点：当前目录出现Duix-Avatar文件夹，里面有deploy、src、README.md等内容，即表示本步完成。

项目到手后，接着配置运行环境。

第 2 步｜装好 Docker 与显卡驱动

目的：Docker 承载三个 AI 服务，驱动让服务能调用显卡，两者缺一不可。

Windows：

wsl --list --verbose

检查 WSL 是否已安装，没有就先用wsl --install安装，再执行wsl --update更新。

然后安装 Docker Desktop（按 CPU 架构选安装包），首次启动接受协议并跳过登录；再从 NVIDIA 官网装好显卡驱动，用nvidia-smi验证，能看到显卡信息就说明驱动正常。

Ubuntu 22.04：

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

安装 Docker 和 docker-compose。接着安装 NVIDIA 驱动与 NVIDIA Container Toolkit，执行sudo nvidia-ctk runtime configure --runtime=docker配置 Docker 的 GPU 运行时而后重启 Docker，完整命令序列见 README_zh.md 的 Ubuntu 安装一节。

拉取官方镜像源不稳定时，在 Docker Desktop 里打开 设置 → Docker Engine，在 JSON 里加一段"registry-mirrors": [...]再"应用并重启"：

判断点：docker --version和docker compose version都能正常返回版本号，本步完成。

环境就绪后，启动后端服务。

第 3 步｜启动后端三个服务

目的：把 ASR（语音识别）、TTS（语音合成）、视频合成三个服务跑起来，这是数字人怎么部署的核心一步，后面客户端全靠它们。

cd deploy docker-compose up -d

拉取三个镜像并后台启动服务。Ubuntu 用户改用docker-compose -f docker-compose-linux.yml up -d；显卡是 50 系列的改用docker-compose-5090.yml。

⚠️ 首次启动要下载约 70G 镜像，耗时半小时左右。建议连上 Wi-Fi 耐心等待，期间不要关机。

判断点：Docker 里（或执行docker-compose ps）看到duix-avatar-tts、duix-avatar-asr、duix-avatar-gen-video三个服务全部 Running，即表示本步完成。

后端跑起来后，最后一步装操作界面。

第 4 步｜安装客户端

目的：客户端是操作界面，负责调用上一步启动的本地服务。

方式一，官方安装包：从项目 releases 页下载Duix.Avatar-x.x.x-setup.exe（Windows）或Duix.Avatar-x.x.x.AppImage（Ubuntu），双击安装或启动。

方式二，源码构建（需要 Node.js 18）：

npm install npm run build:win

安装依赖并构建 Windows 安装包，产物在dist目录；Ubuntu 把命令换成npm run build:linux。

判断点：dist目录生成安装包（或 exe 已安装到桌面），双击能正常打开客户端，即表示本步完成。

✅ 跑通验证

1. 到deploy目录执行docker-compose ps，确认三个服务都是 Running。
2. 打开客户端。首屏应该是主界面：上方有"Create Video"和"Create Avatar"两张卡片，下方是"My Works"和"My Avatars"两个页签：

3. 用最小输入做一次端到端测试：
   • 输入：点击"Create Avatar"，上传一段 10 秒左右、人物在说话的真人视频（必须有声音）；
   • 输出：训练成功后形象出现在"My Avatars"列表；再到"Create Video"选中这个形象，输入一句简短文字并生成；
   • 结论："My Works"里出现一条带你自己形象和声音的口播视频，音画同步，就说明整条链路跑通了。

⚠️ ASR 服务启动较慢，服务起来后请等几分钟再创建形象；训练视频没有声音必然失败。

🧭 上手速览

3 分钟会用

• Create Avatar（创建形象）—— 上传 10 秒真人视频克隆外貌与声音 —— 首次制作数字人模型
• Create Video（创建视频）—— 选形象、输入文字或上传音频，一键生成口播视频 —— 产品介绍、知识讲解等固定文案
• My Works / My Avatars（作品与形象管理）—— 查看、搜索、删除已生成内容 —— 日常内容管理
• 设置菜单—— 用户协议、打开日志、中英文界面切换 —— 自查环境与切换语言

进阶可玩

• 本地开放 API—— 模型训练、语音合成（127.0.0.1:18180）、视频合成（127.0.0.1:8383）均有本地接口，参数结构参考 src/main/service/ —— 程序化接入自己的系统
• Lite 版部署—— 用docker-compose-lite.yml单镜像运行 —— 显存有限时先体验视频合成
• 50 系显卡部署方案——docker-compose-5090.yml，CUDA 12.8 的 30/40 系显卡也能用 —— 新显卡用户
• 多形象管理—— 导入多个数字模特，不同场景换用不同形象 —— 多角色内容制作

🔍 排障速查

最常用的查状态与查日志命令：

docker-compose ps docker-compose logs duix-avatar-tts

前者看三个服务是否都 Running；后者查看指定服务的日志（把服务名换成 asr / gen-video 同理）。客户端日志在右上角"设置 → Open Log"：

服务端日志在 Docker 里点进对应服务，打开 Logs 页签直接看：

三个服务 Running、第一条口播视频到手，这次数字人新手入门就算跑通了。接下来可以接本地 API 做程序化接入，或先看看常见问题文档：更多部署细节与解决办法见 doc/常见问题.md。

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