30 分钟本地跑通开源数字人口播：Duix-Avatar 部署避坑清单-育师

30 分钟本地跑通开源数字人口播：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 秒左右的说话视频，本地克隆你的形象和声音；之后输入文案或音频，自动产出口型同步的口播视频。全程不联网，素材和数据都留在自己机器上。

一句话说清它能干嘛

输入是一段 10 秒左右的说话视频（用于 10 秒视频克隆）+ 文案或音频；输出是一个可循环使用的数字人模型和一条 mp4 口播视频。中间环节——语音合成、口型驱动——全部由本地 NVIDIA 显卡完成，属于典型的离线数字人生成链路。

项目	说明
输入	10 秒左右说话视频；文案文本或音频文件
输出	口型同步的口播视频（mp4）
支持平台	Windows 10 19042.1526+ / Ubuntu 22.04
硬件门槛	英伟达显卡 + 32G 内存（推荐 RTX 4070）
许可证	免费商用（用户量超 10 万或年营收超 1000 万美元的企业需另签协议）

图 1：主界面左侧 Create Video 生成口播视频，右侧 Create Avatar 上传 10 秒视频克隆数字人

跑起来：从零到出片

先确认机器过不过关

系统：Windows 10 19042.1526 以上（C 盘 100G 放镜像、D 盘 30G 放数据），或 Ubuntu 22.04（100G 可用空间）
硬件：英伟达显卡且驱动装好，内存 32G 起，低于这个数 ASR 服务可能起不来
终端跑nvidia-smi能看到显卡信息，再往下走

Windows 上如果 C 盘不够 100G，别急着重装系统，在 Docker Desktop 的 Resources → Advanced 里把 Disk image location 指到别的盘即可。

图 2：C 盘空间不足时，把 Docker 镜像存储位置改到其他磁盘

用 Docker 拉齐三个数字人服务

克隆仓库并在 deploy 目录起服务，这一步会拉约 70GB 镜像，首次大概半小时，注意连 WiFi：

git clone https://gitcode.com/GitHub_Trending/he/Duix-Avatar cd Duix-Avatar/deploy docker-compose up -d # 只要视频合成单服务就改用 -f docker-compose-lite.yml

这条命令会拉三个容器：TTS 语音合成（端口 18180）、ASR 语音识别（10095）、视频合成（8383），全部挂 nvidia runtime 跑在本地显卡上。Ubuntu 上把命令换成docker-compose -f docker-compose-linux.yml up -d。看到三个容器都是 Running，服务端就算就绪了。

装客户端，生成第一条视频

Windows 直接双击 Release 里的Duix.Avatar-x.x.x-setup.exe安装；Ubuntu 下载 AppImage，root 用户桌面运行时要在终端执行./Duix.Avatar-x.x.x.AppImage --no-sandbox。

启动后走一遍完整链路：上传一段 10 秒的说话视频创建数字人（程序会用 ffmpeg 分离出 H.264 视频和 WAV 音频，音频送去做声音克隆）；然后选这个模型输入文案，提交合成。作品列表里状态从 waiting 变成 success、能直接播放和导出，说明整条链路跑通了。

玩出花样：3 个可以直接抄的场景

1. 存量口播视频批量换讲述人手里已有一批讲品视频的 mp4，不想重拍？8383 的/easy/submit接口本身就支持"新音频 + 旧视频"组合，audio_url和video_url分别指向文件路径，code填个唯一 uuid 就能提交，随后用GET /easy/query?code=xxx轮询进度。一段 10 秒的素材视频可以反复复用，换文案、换声音就是新视频，零重拍成本。

2. 线下展厅无人讲解屏一次性生成 3 分钟左右的讲解视频，在展厅屏幕循环播放，讲解员可以撤。客户端内置任务队列（每 2 秒轮询一次进度），长文案直接一条生成，也可以 API 批量提交排队。同一份素材可以产出中、英、日、韩等 8 种语言版本，多语言展会各放一版。

图 3：中文界面下从右上角设置可切换语言、查看用户协议和客户端日志

3. 播客音频动态化成视频做播客或电台的团队，把单集音频直接上传（编辑页的 EditUpload 支持音频上传）驱动数字人，口型按音频节奏自动对。一集音频同时产出声音和画面两条内容，竖屏平台直接发，不用进棚重录。

深入一层：架构与接口

架构就三层，每层一句话：

客户端层：Electron + Vue 3 桌面应用（src/main），负责模型管理、文案录入、任务轮询，本地 SQLite 存元数据
推理层：3 个 Docker 容器，TTS 基于 fish-speech（18180）、ASR 基于 FunASR（10095）、视频合成即 face2face 口型驱动（8383）
数据层：模型、音频、产物统一落在D:\duix_avatar_data（Linux 为~/duix_avatar_data），与容器通过 volume 共享

想绕过 GUI 直接集成，两个关键端点：

# 声音预处理：返回 reference 音频和参考文本，TTS 合成要用 curl -X POST http://127.0.0.1:18180/v1/preprocess_and_tran -H 'Content-Type: application/json' \ -d '{"format":".wav","reference_audio":"origin_audio/a.wav","lang":"zh"}' # 视频合成：提交任务，拿到 code 后轮询进度 curl -X POST http://127.0.0.1:8383/easy/submit \ -d '{"audio_url":"/path/a.wav","video_url":"/path/b.mp4","code":"uuid","pn":1}'

要改行为，认准三个入口：src/main/config/config.js里是服务地址和数据目录，deploy/docker-compose.yml控制端口映射和卷挂载，src/main/service/下的model.js、video.js、voice.js是完整业务逻辑参考。

踩坑清单：90% 的人卡在这几步

1. 拉镜像超时现象：docker-compose up -d报request canceled/context canceled。原因：Docker Hub 官方源不稳定。解决：Docker Desktop 进 Docker Engine 配置，加registry-mirrors镜像源列表后重启，重新拉取。

图 4：在 Docker Engine JSON 配置里添加 registry-mirrors 解决拉取超时

2. 新增模特报错"视频必须有声音"现象：创建模型直接失败。原因：上传的 10 秒视频里没有人说话，声音克隆没素材。解决：重新录一段人声清晰、持续说话的视频，别用风景空镜。

3. 克隆时 Connection refused现象：日志里 funasrConnection refused。原因：ASR 容器启动慢，服务刚拉起来就去操作了；16G 内存的机器可能根本起不来。解决：服务端启动后等 3–5 分钟再创建模特，内存低于 32G 先升级。

4. 容器日志报 file not exists现象：TTS 容器反复刷File not exists。原因：volume 挂载路径对不上，Windows 默认约定挂 D 盘的duix_avatar_data，目录不存在或写错了位置。解决：先建好对应目录，再核对docker-compose.yml里的 volumes 映射。

图 5：duix-avatar-tts 容器日志，红框处为音频文件路径不存在的报错

5. 三个服务没全 Running现象：容器反复重启或直接起不来。原因：没有英伟达显卡，或驱动没加载进容器。解决：先跑nvidia-smi确认宿主机正常，再docker-compose ps看状态；客户端侧的问题就从右上角设置里"打开日志"看main.log。

图 6：从客户端设置菜单可直达日志目录，main.log 是排障第一现场