Duix.Avatar 本地部署教程：4 步完成数字人克隆与离线口播视频生成
【免费下载链接】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 秒视频克隆你的形象和声音，再用文字或音频离线生成口播视频。这是一套基于 Docker 的私有化部署方案，照着做就能端到端跑通。
一、部署前准备：硬件与环境自检
硬件档位怎么选
官方只给出了一档推荐配置，且对内存和显卡有硬性要求，先对照下表自检：
| 项目 | 要求 | 说明 |
|---|---|---|
| CPU | 第 13 代英特尔酷睿 i5-13400F 或更高 | 同档 AMD 可替代 |
| 内存 | 32GB 及以上（必要） | 常见问题文档提示 16G 可能启动不了服务 |
| 显卡 | 英伟达显卡（推荐 RTX 4070），必须装好驱动 | 30/40 系列用默认方案；50 系列（或 CUDA 12.8 的 30/40 系）用docker-compose-5090.yml |
| 存储 | Windows：D 盘空闲30GB以上、C 盘空闲100GB以上；Ubuntu：空闲100GB以上 | C 盘存 Docker 镜像文件，D 盘存数字人与作品数据 |
| 性能预期 | 首次拉镜像约70GB流量、30 分钟左右（取决于网速） | 克隆一个形象只需 10 秒视频，训练与合成速度以实测为准 |
一条命令检查系统和依赖
每项依赖对应一条单行验证命令，全部通过再往下走：
- Windows 10 19042.1526 或更高版本
winver- Ubuntu 22.04 Desktop（其他 Linux 版本官方暂未做兼容测试）
lsb_release -a- WSL（仅 Windows 需要）
wsl --list --verbose- Docker（含 Docker Compose）
docker --version- 英伟达显卡驱动（必要）
nvidia-smi- Node.js 18（构建客户端时需要）
node -v⚠️ 避坑提醒：本项目全部算力都在本地，没有英伟达显卡或驱动没装对，三个服务端容器根本起不来；Linux 上还需额外安装 NVIDIA Container Toolkit 并重启 Docker。另外 Windows 的 C 盘若不足 100GB，安装 Docker 后可在 Docker Desktop 的 Settings → Resources 里把镜像存储位置换到别的盘：
图1：Docker Desktop 的 Disk image location 设置项，可把镜像存储改到剩余空间大于 100GB 的磁盘
二、5 分钟看懂：它能帮你做什么
能力清单
| 能力 | 能做什么 | 上手难度 |
|---|---|---|
| 形象克隆 | 上传一段10 秒左右的视频，克隆出数字人形象 | 低 |
| 声音克隆 | 从视频里的人声克隆音色、语调，支持多种声音参数设置 | 低 |
| 文字驱动视频 | 文字转语音并自动匹配口型，生成口播视频，全离线完成 | 低 |
| 音频驱动视频 | 直接上传现成音频，驱动数字人对口型 | 低 |
| 多语言脚本 | 支持中、英、日、韩、法、德、阿、西8 种语言 | 低 |
| 本地开放 API | 模特训练、音频合成、视频合成接口经http://127.0.0.1的18180/8383端口调用 | 高 |
每项需要准备什么
- 形象克隆：录一段正面、光线均匀、必须有人在说话的短视频，声音克隆就来自这段音频。
- 声音克隆：环境安静、无背景音乐和杂音，克隆效果更干净。
- 文字/音频驱动：准备好脚本文本或 WAV 音频，客户端界面内直接输入即可。
- 本地 API：需要能读懂 deploy/ 里 compose 文件的端口映射，参考 README_zh.md 的"开放 API"一节。
三、部署主流程：手把手走一遍
以 Windows 为主线，Ubuntu 22.04 的差异在各步骤中单独标出。
第 1 步：克隆项目
git clone https://gitcode.com/GitHub_Trending/he/Duix-Avatar cd Duix-Avatar预期结果：出现Duix-Avatar目录，里面有deploy/、src/、README_zh.md等文件。
注意：建议先建一个专门的工作目录再克隆，避免文件分散。
第 2 步：装好 Docker 与 GPU 环境
Windows：先执行wsl --update更新 WSL（更新过程可能需要重启电脑），再从 Docker 官网下载 Docker Desktop 安装，首次运行接受协议、跳过登录。
Ubuntu：
sudo apt update && sudo apt install -y docker.io docker-compose sudo apt-get install -y nvidia-container-toolkit sudo nvidia-ctk runtime configure --runtime=docker && sudo systemctl restart docker预期结果：docker --version输出版本号，nvidia-smi能显示显卡信息。
注意：NVIDIA Container Toolkit 需先按 README_zh.md 的 Ubuntu 章节添加软件源；配置完成后必须重启 Docker 服务。
第 3 步：一键启动服务端（Docker 部署）
cd deploy docker-compose up -d- 只需要视频合成能力时，改用 lite 版：
docker-compose -f docker-compose-lite.yml up -d（仅启动一个服务） - 50 系显卡：
docker-compose -f docker-compose-5090.yml up -d - Ubuntu 22.04：
docker-compose -f docker-compose-linux.yml up -d
预期结果：约30 分钟后，Docker 中出现 3 个 Running 状态的容器（lite 版只有Duix.Avatar-gen-video一个）。
注意：首次拉取约70GB镜像，务必连 WiFi 或有线网络，期间不要关终端。
💡 小贴士：如果这一步报request canceled/ 连接超时，是 Docker Hub 官方源连不上的问题，在 Docker 的daemon.json里配置国内registry-mirrors镜像源后重新执行即可，详见 doc/常见问题.md。
第 4 步：安装客户端
Windows：到项目 release 页面下载Duix.Avatar-x.x.x-setup.exe，双击安装。
Ubuntu：下载Duix.Avatar-x.x.x.AppImage双击启动；若用 root 用户，在终端执行./Duix.Avatar-x.x.x.AppImage --no-sandbox。
预期结果：客户端安装完成、可正常打开。
注意：客户端依赖本地服务端，保持 3 个容器运行即可。
第 5 步：验证服务状态
docker ps预期结果：3 个容器均为 Running，端口10095（ASR）、18180（TTS）、8383（视频合成）正常映射。
注意：ASR 服务启动较慢，服务端起来后等几分钟再去做克隆形象操作。
四、首次运行验收：跑通最小闭环
图2：客户端主界面，含 Create Video、Create Avatar 与 My Works / My Avatars 列表
按下面顺序操作一遍，就是最短的端到端链路：
- 启动客户端，确认主界面 "My Works" 和 "My Avatars" 两个区域正常加载。
- 点击Create Avatar。
- 上传一段 10 秒左右的正面视频，画面里的人必须在说话。
- 等待模型训练完成，"My Avatars" 中出现新模型。
- 点击Create Video，选择刚创建的模型。
- 输入一段短文本（先试 1~2 句），提交生成。
- 在 "My Works" 里查看、播放生成的视频。
验收清单
docker ps中 3 个服务均为 Running（lite 版为 1 个）- 上传视频后，"My Avatars" 中出现新克隆的模型
- 文本生成任务跑完且无报错
- 生成视频里的声音是克隆音色、口型与语音基本同步
- 断开外网后客户端仍可正常生成（全离线）
五、场景化玩法：挑 2 个典型场景写透
场景 1：个人口播视频（文字驱动）
- 素材/输入要求：10 秒左右正面视频，光线均匀、背景简洁，音频必须是人声（程序用这段声音做声音克隆）。
- 关键参数建议值：脚本语言从8 种语言里选对应项；测试期文本控制在 1~2 句，确认口型效果后再加长。
- 产出物："My Works" 中一条可离线播放的口播视频，数据落在
D:\duix_avatar_data（Windows）。
场景 2：同一形象的批量口播（企业培训/产品宣讲）
- 素材/输入要求：用一段正式感强的形象视频完成一次性克隆，之后所有脚本复用这一个模型。
- 关键参数建议值：一个形象配多段文案，逐条提交生成；合成服务端口8383支持通过本地 API 循环调用，适合脚本化批量产出。
- 产出物：同一数字人形象、统一音色的一批口播视频。
- 💡 若你已有形象数据、只需要视频合成，可改用 deploy/ 下的
docker-compose-lite.yml，只启动一个服务，资源占用更低。
六、排障速查表：一分钟定位故障
| 症状 | 最可能原因 | 一步修复 |
|---|---|---|
docker-compose up -d报request canceled/ 超时 | Docker Hub 官方源连接不稳定 | 在daemon.json添加国内registry-mirrors后重新执行 |
| 新增模特时报错（音频文件不存在等） | 上传的视频没有声音、或没人说话 | 重新录制一段有人清晰说话的视频再上传 |
定制模特报Connection refused | ASR 服务启动慢，或内存不足（16G 可能启动不了） | 服务端启动后等几分钟再操作；内存升到32GB |
图3：duix-avatar-tts容器日志，红框处为报错行
图4：Docker Desktop 的 Docker Engine 设置页，在 registry-mirrors 中填入国内镜像源
深度排查时，分别盯三个容器的日志：
docker logs -f duix-avatar-tts # 语音合成 docker logs -f duix-avatar-asr # 语音识别 docker logs -f duix-avatar-gen-video # 视频合成客户端侧的报错可在客户端右上角 Setting → Open Log 里查看。
七、资源与后续
- 仓库关键路径：deploy/（4 份 docker-compose 配置，一键启动服务端）、doc/常见问题.md（自查步骤与高频报错）。
- 社区交流：项目 README 中的技术交流群二维码，以及仓库 Issues 区，问题单每天在更新。
- 获取更新：服务端到
deploy/重新执行docker-compose up -d拉取最新镜像；客户端换用最新官方构建安装包。
到这里，你已经把 Duix.Avatar 的本地部署、三个服务端和最小闭环验收全部跑通，数字人克隆与口播视频生成都可以离线使用了。下一步建议：按第五节挑一个场景，用你自己的 10 秒视频做出第一条口播视频，并留意口型同步效果。
【免费下载链接】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），仅供参考
