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

如果你想在本地跑一个数字人克隆 + 口播视频合成的方案，又不想把形象和声音交给任何云端 API，Duix.Avatar 就是为你准备的：提交一段 10 秒左右的说话视频，它就能克隆你的形象和声音，之后输入文案即可自动生成口型对齐的播报视频，全程离线、不限次数。这篇文章不讲功能清单，而是带你把一个视频任务从头走到尾，再把部署和合成中最常见的"卡住"按症状逐个拆掉。

📦 先拆清楚：三个服务各管哪一段

Duix.Avatar 的服务端是三个跑在 GPU 上的 Docker 容器，定义在 deploy/docker-compose.yml。它们职责边界非常清晰，理解这个分工，后面排障就不会晕：

服务	干的事	开放端口
`duix-avatar-asr`（fun-asr）	语音识别，把说话转成文本	10095
`duix-avatar-tts`（fish-speech）	声音克隆 + 把文案变成克隆人声的音频	18180
`duix-avatar-gen-video`（face2face）	音频 + 模特视频驱动口型，产出成片	8383

客户端是一个 Electron 壳，它不碰模型，只干四件事：用内置 ffmpeg 把视频转 H.264、分离音频轨（见 util/ffmpeg.js）、轮询任务进度、用本地 SQLite 记录模特和作品。每个接口在 src/main/api/ 里都只有一两行，你完全可以照着它自己拼批量调用。

🎬 走一个完整任务：从一段视频到成片

假设你上传了一段 10 秒的说话视频，整条链路是这样的：

上传视频 → 转 H.264 + 分离音频 → 声音克隆 → 存入模特库

具体发生了什么：视频先被转成标准 H.264，再抽出音频轨；然后客户端调 TTS 服务的克隆接口18180/v1/preprocess_and_tran，它返回两个关键值——参考音频路径和参考文本，必须记下来，后面每次合成都要带。最后模特信息连同声音 ID 一起写进本地库（见 service/model.js）。到这一步，"克隆"就完成了，后面换多少文案都不用再动它。

接着你填一段文案点合成，链路变成：

选模特和文案 → TTS 生成音频 → 提交合成任务 → 每 2 秒轮询进度 → 成片入库

客户端先调 TTS 的18180/v1/invoke，把文案变成克隆人声的 WAV，参数里就是克隆时存下的那两个值；
再调 face2face 的8383/easy/submit，拿到一个唯一任务码；
之后任务进入等待队列，客户端的轮询器每 2 秒查一次状态，成功就用 ffprobe 读出时长写进作品列表，失败则把错误信息落到记录里——所以你永远能在界面上看到"卡在哪一步"（完整逻辑见 service/video.js）。

📌关键规则：合成任务是异步的，"点了没反应"不等于失败，先确认三个服务都 Running，再给合成几分钟时间。

🔍 卡住了？按症状排障

部署和合成阶段最容易出现"服务起不来""克隆报错""合成卡住"三类故障，先看症状，再按顺序检查：

症状	病灶	检查顺序
`docker-compose up -d`拉镜像超时	Docker Hub 官方源连不通	给 Docker 配置国内镜像源，见常见问题
克隆报`Connection refused`	ASR 服务启动慢，或内存不足	服务端起来后等几分钟再克隆；16G 内存可能根本拉不起 ASR
新增模特报错	视频里没有声音	克隆素材必须是"人在说话"的视频，程序要拿这段声音做声音克隆
合成一直不完成	任务其实还在队列/计算中	查三个容器状态；打开容器 Logs 看服务端日志