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 是一个可以完全离线运行的数字人视频合成工具：提交一段 10 秒左右的说话视频，即可克隆你的形象和声音；之后输入文案或上传音频，就能驱动这个数字人自动对口型、生成口播视频。整个过程都在你自己的电脑上完成，视频不上传云端，也不限生成次数。本文带你走通从环境准备到产出第一条视频的全流程，以 Windows 为主线，Ubuntu 22.04 的步骤放在文末。
先看成果：装完你会得到什么
安装完成后你手里会有两样东西：
- 一套本地 AI 服务：视频合成、声音克隆（TTS）、语音识别（ASR）三个服务，全部跑在 Docker 容器里，由你的 NVIDIA 显卡提供算力；
- 一个桌面客户端：图形化界面，用来上传视频创建数字人模型、输入文字生成视频、管理已生成的作品。
客户端主界面如下：顶部是"Create Video（创建视频）"和"Create Avatar（创建数字人）"两个入口，下方列表管理你的作品和数字人。
开工前自查：系统与硬件要求
本项目所有算力都在本地，NVIDIA 显卡是硬性要求，集显无法运行。对照下表检查你的机器：
| 项目 | 要求 | 说明 |
|---|---|---|
| 系统 | Windows 10（19042.1526 及以上）或 Ubuntu 22.04 桌面版 | 其他系统未验证 |
| 显卡 | NVIDIA 显卡 + 已装驱动 | 推荐 RTX 4070 级别，8G 显存可用 |
| 内存 | 32GB 推荐 | 16GB 可能有个别服务起不来 |
| 磁盘（Windows） | D 盘 30G 以上 + Docker 镜像目录所在盘 100G 以上 | 首次拉取镜像约 70GB |
⚠️ 如果你的 C 盘剩余空间不足 100G，安装 Docker 后可以在 Docker Desktop 的资源设置里把 "Disk image location" 改到别的盘，如下图所示：
开工前还需要准备好两个软件：Git（拉取项目代码用）和Docker Desktop（运行 AI 服务用），去各自官网下载安装即可。
确认 NVIDIA 驱动已安装
去 NVIDIA 官网下载并安装显卡驱动，装完后在终端执行nvidia-smi，能显示显卡信息就说明驱动正常，这是三个服务能启动的前提。
安装 WSL 与 Docker Desktop（Windows 用户）
Docker Desktop 在 Windows 上依赖 WSL（Windows 子系统 Linux，可以简单理解为在 Windows 里跑的一个轻量 Linux）来运行容器，所以要先把 WSL 装好。
- 打开终端，执行检查命令，看 WSL 是否已安装：
wsl --list --verbose报错或没有任何发行版输出，说明还没装，执行下面的命令安装（网络不好时可能失败，多试几次即可）：
wsl --install安装过程中会让你设置用户名和密码，记好它们。装完后再执行一次wsl --update把 WSL 更新到最新版本。
- 到 Docker 官网下载 Windows 版 Docker Desktop，按 CPU 架构选对应安装包，安装完成看到主界面即成功。
- 首次启动时接受协议、跳过登录，不需要注册账号。
一条命令启动服务端
先拉取项目代码并进入目录：
git clone https://gitcode.com/GitHub_Trending/he/Duix-Avatar cd Duix-Avatardeploy/目录下放的是开箱即用的 compose 配置文件：默认完整版包含 asr / tts / gen-video 三个服务，docker-compose-lite.yml精简版只启动视频合成一个服务，占用更少资源。
进入 deploy 目录启动服务：
cd deploy docker-compose up -d这条命令会先从镜像仓库拉取三个镜像（合计约 70GB，耗时从半小时到几小时不等，取决于网速，建议用有线网络），拉完自动启动容器。完成后打开 Docker Desktop 的 Containers 页面，看到三个服务全部处于 Running 状态即成功：
两种特殊情况的启动命令：
# 只需要"已有音频 + 已有数字人 → 出片"的场景，用精简版 docker-compose -f docker-compose-lite.yml up -d# RTX 50 系显卡（5090/5080 等）用专属配置 docker-compose -f docker-compose-5090.yml up -d安装客户端，产出第一条口播视频
客户端使用官方构建好的安装包，不需要自己编译：Windows 双击Duix.Avatar-x.x.x-setup.exe安装；Ubuntu 用户下载 AppImage 版本，双击Duix.Avatar-x.x.x.AppImage即可运行（root 用户下需要用命令行加--no-sandbox参数启动）。
打开客户端就能看到开头那张主界面，第一次使用的完整流程是：
- 创建数字人：点 "Create Avatar"，上传一段 10 秒左右的视频。注意素材必须有清晰的人声——程序会用它做声音克隆，无声视频会直接报错；
- 生成视频：点 "Create Video"，选中刚创建的数字人，输入口播文案并选择音色，提交合成；
- 查看作品：成片出现在 "My Works" 列表里，可以直接播放和保存到本地。
💡 服务端刚启动后，ASR（语音识别）服务就绪最慢，建议等几分钟再操作客户端；如果日志里看到 Connection refused，等一会儿重试即可。
卡住了怎么办：常见问题与解法
| 问题 | 可能原因 | 解法 |
|---|---|---|
docker-compose up -d报 context canceled / 连接超时 | Docker Hub 官方源连接不稳定 | 配置国内镜像加速器，见下文 |
| 服务起不来或起来后立刻退出 | 没有 NVIDIA 显卡或驱动没装好 | 重装驱动，用nvidia-smi验证 |
| 新增模特时报错 | 素材视频没声音，或不是人在说话 | 换一段 10 秒左右、语音清晰的人像视频 |
| 定制模特报 Connection refused | ASR 服务还没就绪，或内存不足 | 服务端启动后等几分钟再操作；16GB 内存可能起不来，建议 32GB |
排查镜像下载慢
打开 Docker Desktop → Settings → Docker Engine，在 JSON 配置里加入registry-mirrors字段（镜像源清单，可用哪个选哪个，失效了自行搜索最新的），点 "Apply & restart" 生效：
学会看日志
排障基本靠两份日志：
- 客户端日志：客户端右上角齿轮菜单 → Open Log，日志文件
main.log在 AppData 的 logs 目录里； - 服务端日志：在 Docker Desktop 里点开对应容器的 Logs 页签，点右侧复制按钮即可带走整段日志。
提问前建议先翻一遍仓库里的 常见问题 文档，里面有更多报错样例和对应解法。
玩得更深：精简版、开放 API 与多系统
- 精简版（lite）：如果你已有数字人模型和音频、只需要出片，用精简版命令（见第四章）只跑一个容器，省资源也省流量。
- 开放 API：Docker 启动后，各服务会在本地暴露端口（如 18180 语音合成、8383 视频合成，通过
http://127.0.0.1调用），可以接进自己的程序；接口调用示例可参考src/main/service/下的 model.js、voice.js、video.js。 - 多模型管理：客户端支持保存多个数字人模型，创建视频时按需切换，互不干扰。
- Ubuntu 22.04 部署：先用
sudo apt install docker.io docker-compose装 Docker，再装 NVIDIA 驱动和 nvidia-container-toolkit（关键一步是sudo nvidia-ctk runtime configure --runtime=docker后重启 Docker），最后在 deploy 目录执行docker-compose -f docker-compose-linux.yml up -d，思路与 Windows 一致。
到这里，你的本地数字人合成环境就齐了——回到客户端主界面，创建第一条口播视频试试吧。
【免费下载链接】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），仅供参考
