Duix.Avatar 数字人本地部署指南：4 步跑通离线克隆与口播视频生成-育师

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 是一个面向本地部署的开源 AI 数字人工具包，全流程离线运行：提交约 10 秒视频即可完成形象与声音克隆，再用文本或音频驱动数字人生成口播视频。项目面向需要批量制作口播视频、且不希望素材离开本机环境的内容创作者与开发者。本文基于仓库文档与 deploy/ 目录下的部署文件，给出 Windows / Ubuntu 两套环境的最小部署路径、核心能力拆解和常见故障排查项。

跑通后的效果预览

部署成功后的交付物是一个桌面客户端，包含两个主入口：创建数字人模型、用已有模型生成口播视频。语音克隆、口型合成、视频渲染全部发生在本机，不依赖外网。

部署前检查清单：硬件与软件

项目	最低要求	推荐
操作系统	Windows 10 19042.1526 及以上 / Ubuntu 22.04	同左；NVIDIA 50 系显卡走专用 compose 文件
显卡	NVIDIA 显卡且驱动已安装（必需，3 个服务全部依赖 GPU）	RTX 4070
内存	16G 可能无法启动	32G 及以上
磁盘	Windows：C 盘 100G（镜像）+ D 盘 30G（数据）；Ubuntu：100G 空闲	SSD
软件	Docker；构建客户端源码才需要 Node.js 18，安装官方构建包则不需要	最新版

两点说明：Windows 下 C 盘不足 100G 时，可在 Docker 设置中把镜像目录改到空闲大于 100G 的磁盘；如果只需要视频合成能力，仓库提供 lite 配置，只启动一个服务。

最小路径：4 步跑通服务端与客户端

第 1 步：克隆仓库

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

部署配置在 deploy/ 目录，按系统选择：docker-compose.yml（Windows）、docker-compose-linux.yml（Ubuntu）、docker-compose-lite.yml（仅视频合成服务）。

第 2 步：准备 GPU 环境

服务端 3 个容器均声明runtime: nvidia，没有 NVIDIA 显卡或未装驱动时无法启动。先用nvidia-smi验证驱动；Ubuntu 还需安装 NVIDIA Container Toolkit 并配置 Docker runtime，完整命令见 README_zh.md「Ubuntu22.04 安装」一节。

第 3 步：启动服务

cd deploy docker-compose up -d

Ubuntu 执行docker-compose -f docker-compose-linux.yml up -d；NVIDIA 50 系显卡（30/40 系 CUDA 12.8 亦可）执行docker-compose -f docker-compose-5090.yml up -d。首次拉取约 70GB 镜像，耗时半小时左右，Docker 中出现duix-avatar-asr、duix-avatar-tts、duix-avatar-gen-video三个 Running 服务即成功。

第 4 步：安装客户端并访问

Windows 用户安装项目 Release 中的Duix.Avatar-x.x.x-setup.exe；Ubuntu 用户直接运行Duix.Avatar-x.x.x.AppImage，root 用户需加--no-sandbox参数。客户端启动后进入主界面，能创建模型、提交视频任务，即为跑通。服务端端口参考：TTS 18180、ASR 10095、视频合成 8383，均绑定本地回环。

核心能力拆解：克隆、驱动与多语言

按用户可感知的能力划分，而不是源码模块：

形象 + 声音双克隆：提交约 10 秒素材，系统自动分离静音视频与音频，音频侧走 fish-speech 做声音克隆，视觉侧建立 face2face 形象模型。素材必须包含人在说话的声音，否则无法完成声音克隆。
双驱动方式：文本驱动（TTS 合成语音后驱动口型）与音频驱动（直接上传已有音频）二选一。
8 种语言脚本：英语、日语、韩语、中文、法语、德语、阿拉伯语、西班牙语。
口型同步：音视频高度同步、口型自然，是duix.avatar服务（端口 8383）的核心产出。
多模型管理：支持创建多个模型并本地存储、按需切换。

客户端对应逻辑集中在模型服务、视频合成、语音处理三个文件；Docker 侧同时暴露本地 HTTP 接口，可绕过客户端直接调用做集成。

典型任务实操

任务 1：克隆自己的数字分身

输入：10 秒以上的正面视频，光线充足、有清晰人声说话内容。
操作：主界面点击创建模型，上传素材，等待训练完成（自动分离声音、做 ASR 与声音克隆）。
输出：模型列表中一个可驱动的数字人模型。

任务 2：用文本脚本生成口播视频

输入：任务 1 的模型 + 一段文本脚本（支持上述 8 种语言）。
操作：视频创作入口选择模型，粘贴文本，确认语音参数后提交。
输出：作品列表中可预览、导出的口播视频。

任务 3：用音频驱动生成口播视频

输入：已有音频文件（自录或他处合成）。
操作：驱动方式切换为音频，上传文件后提交。
输出：数字人按音频节奏与语调驱动口型的视频，适合需要保留固定录音语气的场景。

排查速查表：常见症状对照

症状	排查项
服务起不来、容器反复退出	①`nvidia-smi`确认显卡与驱动 ② 内存是否达到 32G ③`docker logs <容器名>`看具体报错
`docker-compose up -d`拉镜像超时	在 Docker 的`daemon.json`配置`registry-mirrors`镜像源后重启服务；确认网络连通
新增模特时报错（素材问题）	素材视频必须带人声说话内容，无声视频无法用于声音克隆
训练报 Connection refused	ASR 服务启动较慢，服务端启动后等几分钟再操作；确认`duix-avatar-asr`处于 Running
功能异常、怀疑版本落后	到`deploy/`重新执行`docker-compose up -d`更新服务端；客户端更新到最新构建