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

如果你想让某个固定形象出镜说口播视频，又不想每次实拍，可以考虑本地开源数字人方案。Duix.Avatar 是一个完全开源的数字人项目，仅需一段 10 秒视频即可完成形象与声音克隆，全流程支持本地部署离线运行，适合内容创作者与想尝试数字人技术的开发者。

读完本文你能拿到：

从零部署到第一支成片，约需 30~40 分钟
3 个 Docker 服务构成服务端，全部离线本地运行
10 秒视频同时完成形象与声音克隆
脚本支持中、英、日、韩等 8 种语言
模型训练、语音合成、视频合成 3 组本地 API 可供二次开发

核心能力速览

能力项	一句话说明	典型使用场景
形象与声音克隆	10 秒视频同时提取面部特征与声音音色	创建自己的数字人模型
文字驱动口播	输入文本自动合成语音并驱动口型视频	制作口播播报视频
音频驱动视频合成	上传录音直接驱动数字人口型	用现成配音音频出片
全离线本地运行	计算全部在本地完成，素材不上传	处理敏感素材
本地 API 调用	启动后暴露训练、语音、视频合成 3 组接口	批量生成视频、二次开发

接下来完成环境与部署，即可逐项用上这些能力。

本地部署与环境配置

部署分服务端、客户端两部分，数据目录由容器自动创建。先对照检查机器配置。

配置要求检查

项目	最低要求	推荐配置
系统	Windows 10 19042.1526 及以上，或 Ubuntu 22.04	与左列相同
显卡	NVIDIA 显卡且已安装驱动	RTX 4070（50 系列走专属方案）
内存	16GB（过小可能导致服务启动失败）	32GB 及以上
磁盘	C 盘 100GB 以上存镜像，D 盘 30GB 以上存数据	Ubuntu 空闲 100GB 以上

分系统部署步骤

Windows 系统

检查并更新 WSL：

wsl --list --verbose wsl --update

安装 Docker Desktop，首次启动接受协议并跳过登录。
在项目 /deploy 目录启动服务端：

cd /deploy docker-compose up -d

镜像下载约 70GB，建议连 Wi-Fi 后台拉取。显存或内存紧张可改用 lite 版本，把命令换成docker-compose -f docker-compose-lite.yml up -d；50 系列显卡换成docker-compose -f docker-compose-5090.yml up -d。
从项目 Releases 页下载 Windows 安装包，双击 exe 安装客户端。

Linux 系统（Ubuntu 22.04）

安装 Docker：

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

安装 NVIDIA 显卡驱动，加装 NVIDIA Container Toolkit 并配置 Docker 运行时，详细命令见 README_zh.md。
启动服务端：

cd /deploy docker-compose -f docker-compose-linux.yml up -d

客户端运行 AppImage 文件即可启动；root 用户需在终端加--no-sandbox参数运行。

部署验证

标准版会启动 3 个容器：duix-avatar-tts负责文本转语音（本地 18180 端口），duix-avatar-asr负责音频转写（10095 端口），duix-avatar-gen-video负责口型视频合成（8383 端口）。lite 版本只有最后 1 个容器。

执行docker ps查看容器状态，再打开客户端首页确认不再提示连接错误。完成标志是 3 个服务均为 running 状态，且客户端首页正常加载出作品与模型两个列表。

从克隆到口播视频的核心流程实操

此时客户端已连上本地服务端，进入主界面会看到 Create Video 与 Create Avatar 两个功能区。

数字人客户端设置与语言切换

上传素材并启动形象克隆

点击主界面右上方的 Create Avatar，上传一段 10 秒左右的视频素材。系统会基于这段视频同时完成形象与声音克隆，它是后续口型与音色效果的关键输入。

素材时长建议 10~20 秒
必须包含人物连续说话的声音
人物清晰可见，正面无遮挡
上传后自动开始训练任务

训练完成后，My Avatars 列表会出现一个新的数字人模型。

核对刚克隆出来的模型是否可用。

核对克隆完成的数字人模型

进入 My Avatars 页签，找到刚生成的模型卡片，核对缩略图与创建时间。

数字人模型管理界面

支持按名称搜索定位模型
素材不合适可删除后重新上传
多个模型可并存，按选择使用

预期结果是模型出现在列表中且状态可直接选用。

模型就绪，下面进入成片生成阶段。

输入文案生成成片

选中模型进入 Create Video，在编辑页输入口播文案，或上传音频文件后点击生成。系统先合成语音，再合成口型匹配的成片视频。

文案较长时建议分段生成
有录音文件时优先上传音频
生成进度可在作品列表查看

生成完成后，My Works 列表中会出现对应的成片。

预览与导出成片

在 My Works 中打开成片播放，检查口型同步与音色相似度。

确认口型与语音节奏一致
效果不满意可重新生成对比
以标准视频文件导出保存

预期结果是一支可直接使用的口播成片。

排错与调优

部署与生成环节的大部分问题，都能归入下面 5 类。

高频故障速查

症状	可能原因	解决操作
up -d 报请求超时	Docker Hub 连接不稳定	在 Docker 设置中配置国内镜像源，重启 Docker
3 个服务起不来	无 NVIDIA 显卡或未装驱动	用 nvidia-smi 验证，安装驱动后重启服务
定制模型报 Connection refused	asr 服务未就绪或内存不足	服务端启动后等几分钟再克隆，内存保证 32GB
新增模特失败	视频无声音或无人说话	换有清晰人声的视频重新上传
生成卡在 20%	tts 服务报文件路径错误	查看 Duix.Avatar-tts 日志，重启相关服务

镜像源在 Docker 设置中配置：

Docker镜像源配置位置

tts 服务异常时，在 Docker 中打开对应容器查看日志：

数字人TTS服务日志排查

客户端侧的问题，可通过设置菜单里的 Open Log 定位日志文件：

客户端日志文件定位位置

服务端问题排除后客户端仍失败时，把两边日志对照着看。

生成质量调优

光线充足，面部布光均匀
正面拍摄，避免侧脸遮挡
发音清晰，避免背景噪音
素材控制在 10~20 秒
按输出需求选择分辨率
批量生成，避免系统过载

进阶调用入口

模型训练与语音合成接口：参考 src/main/service/model.js、src/main/service/voice.js
视频合成与进度查询接口：参考 src/main/service/video.js
更多故障案例：查看仓库 doc/常见问题.md

如果你的需求偏向程序化调用而非使用界面，优先看上一节的接口说明。

适用人群与落地建议

同一套部署可以服务不同业务，按你的主要用途对号入座。

自媒体周更口播：一个模型多次复用，不用每次实拍，保持更新频率
企业展会门店循环播放：品牌代言模型产出演示视频，全天候循环
课程系列批量生产：同一数字人驱动多科目课程口播，视觉风格统一
多语言内容制作：TTS 脚本支持 8 种语言，同一模型产出不同语言口播

Duix.Avatar 目前处于 1.0.x 版本，社区活跃、更新频繁，近期完成了 Ubuntu 22.04 版本适配与 5090 显卡专属部署方案。使用中遇到问题，先查阅 doc/常见问题.md 里的自查步骤与常见解决方案；仍无法解决时，可在项目仓库提交 Issue，并附上对应的客户端或服务端日志。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析