企业官网建设流程全解析

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 把离线数字人拆成三个本地容器，其中 duix-avatar-gen-video 是真正出片的视频合成智能体：给它一段克隆形象加一条音频，它就回传一条口型对齐的口播视频。本文围绕任务队列、状态轮询、报错自查讲清它怎么用、边界在哪，帮第一次本地部署的人少走弯路。

架构定位：谁把视频合成任务派给 gen-video 容器

项目在 deploy/docker-compose.yml 里定义了三个容器：tts 管声音合成、asr 管语音转写、gen-video 管视频合成。本文主角只负责最后一步——输入音频加模特视频，输出 mp4。任务全部由 Electron 客户端发起：你在界面点"合成"，主进程通过video/makeIPC 把记录写成 waiting 状态存进本地 SQLite，后台定时任务再串行取队，调用 8383 端口的easy/submit接口，合成智能体在容器内跑 face2face 推理。

它的职责边界可以压缩成四句话：

• 任务来源只有客户端，没有外部入口
• 上游依赖两样东西：模特视频（克隆形象时产出）和音频（TTS 生成或用户上传）
• 队列先进先出、一次只合成一条，waiting 状态会显示排队位置
• 下游产物是作品目录里的 mp4，客户端可直接播放和导出

报错排查：Connection refused、进度不动与 API 直连

下面三种问法覆盖最常见的卡点，每种按"你的提问 → 它给出的结果 → 为什么可信"展开。

问法一：服务刚起来就克隆，报 Connection refused

服务启动几分钟就去克隆模特，日志里刷屏 Connection refused

答案不是端口配错：fun-asr 冷启动慢，服务端启动后等几分钟再做克隆形象操作；机器内存只有 16G 时可能直接起不来。这一点在 doc/常见问题.md 的自查步骤里有明确记录。

为什么可信：文档里的报错原文正对应 asr_fun.py 的 init_conn 连接异常，且提问模板要求先贴服务端日志再描述现象，说明官方排查顺序就是"先认容器状态，再看日志"。

问法二：提交后一直显示"正在提交任务"，进度不动

视频提交后卡在"正在提交任务"，刷新也不变

它会把状态链拆开给你看：waiting → pending → success / failed。客户端每 2 秒轮询一次easy/query，code 为 10000 表示任务有效（status=1 合成中、status=2 完成、status=3 失败），而 9999、10002、10003 一律标记失败并把原因写进作品列表的 message 字段。卡在提交阶段时，优先确认 gen-video 容器还活着、显卡驱动正常。

easy/submit 提交任务（code=uuid） └─ 每 2 秒轮询 easy/query ├─ code 10000 & status=1：合成中 └─ code 9999 / 10002 / 10003：标记失败

为什么可信：这套轮询与错误码处理在 src/main/service/video.js 的 loopPending 里逐行可见，合成成功后还会用 ffmpeg 读出视频时长写回记录，不存在"假成功"。

问法三：想在业务系统里直接调用合成，不走客户端界面

我不想用客户端界面，怎么在自己的服务里直接合成？

它给出三个本地接口：18180/v1/preprocess_and_tran做模特音频预处理，返回 reference_audio 和 reference_text 两个值；18180/v1/invoke把这两个返回值连同目标文本传入，合成出音频；最后8383/easy/submit加easy/query完成视频合成与进度查询。请求参数示例在 README_zh.md 的"开放 API"章节，逐字段标注了哪些是固定传参。

为什么可信：调用样例代码就在 src/main/service/ 目录下与 video.js 同层，接口参数和文档示例一一对应，照抄即可跑通。

红线与分工：它必须做到的事和转交对象

所有算力在本地：没有英伟达显卡和驱动，三个服务都起不来，这是硬前提。

任何任务必须落在 success 或 failed 之一，失败原因必须写入 message 字段，作品列表永远能看到失败理由。

• 任务队列串行执行，不并行合成，避免显存互相挤占
• 它不做的四类事，各自有明确去处：
  • 文字转克隆语音 → duix-avatar-tts 容器（fish-speech，端口 18180）
  • 音频转写与模特音频预处理 → duix-avatar-asr 容器（fun-asr，端口 10095）
  • 界面、模特管理与作品播放 → Electron 客户端（src/renderer 目录）
  • 镜像拉取与 GPU 运行时 → Docker 加 NVIDIA Container Toolkit

资料与验证：排查报错时翻哪几个文件

• README_zh.md：硬件前置条件、部署步骤、三个开放接口的完整请求参数示例
• doc/常见问题.md：提问前自查步骤、提问模板，以及 Connection refused 等真实报错日志对照
• deploy/docker-compose.yml：三个容器的定义、端口映射、GPU 预留与 shm_size 配置
• src/main/service/video.js：任务状态机、2 秒轮询循环、失败码处理逻辑
• src/main/api/f2f.js：视频合成提交与进度查询的 HTTP 调用封装

快速上手：三步从仓库到第一条口播视频

1. 克隆代码：git clone https://gitcode.com/GitHub_Trending/he/Duix-Avatar
2. 在 /deploy 目录执行docker-compose up -d，镜像下载约 70G 流量、耗时半小时左右，确认三个服务全部 Running
3. 安装客户端，上传一段 10 秒左右的说话视频创建模特，再输入文案合成第一条视频

从一条 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