企业官网建设流程全解析

Duix-Avatar 本地部署完整指南：克隆专属 AI 数字人并生成口播视频

【免费下载链接】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 数字人视频生成工具，支持在 Windows 和 Ubuntu 上本地部署：用一段十几秒的真人视频克隆出你的形象和声音，之后输入一段文字或上传一段音频，就能驱动这个数字人开口说话、对口型，产出口播视频。整个过程素材不离开你的电脑。本文按"先把环境跑通 → 再用功能 → 最后接 API"的顺序，带你从零搭起一套可用的本地数字人生产线。

先检查机器：这套方案对硬件有什么要求

在动手装任何东西之前，先确认两个硬性条件，否则后面的服务容器会起不来：

• 必须有 NVIDIA 显卡，且驱动已正确安装。所有推理算力都在本地 GPU 上跑，项目文档中明确说明没有英伟达显卡或驱动，三个服务容器无法启动。装完驱动后执行nvidia-smi，能看到显卡信息才算通过。
• 磁盘空间要留足：Windows 下约定用 D 盘存放数字人数据（空闲 ≥30GB），C 盘存放 Docker 镜像（空闲 ≥100GB）。

推荐配置参考：

第一步：获取代码

只需一个仓库，代码即客户端与部署配置的来源：

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

如果你不想装 Docker 全套环境，只想体验最核心的视频生成能力，仓库里也保留了 lite 版本方案（见下文）。

第二步：安装 Docker

Windows：先备好消息

Windows 上 Docker Desktop 依赖 WSL，按以下顺序操作：

1. wsl --list --verbose查看是否已装 WSL，未装则执行wsl --install（网络不稳定时多试几次）；
2. wsl --update更新 WSL；
3. 从 Docker 官网下载 Windows 版安装包，按 CPU 架构选对应版本，安装后首次启动接受协议、跳过登录即可。

如果 C 盘剩余空间不足 100GB，可以在 Docker Desktop 的Settings → Resources → Advanced里，把 Disk image location 改到空间更大的磁盘分区：

Ubuntu 22.04：三条命令装 Docker，再配好 GPU 直通

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

Docker 要用到 GPU，还差一步：安装NVIDIA Container Toolkit（添加 NVIDIA 仓库 →sudo apt-get install -y nvidia-container-toolkit→sudo nvidia-ctk runtime configure --runtime=docker→sudo systemctl restart docker），完整步骤见 README_zh.md 的 Ubuntu 安装章节。

第三步：一键启动三个服务

服务端由 deploy/ 目录下的 docker-compose 编排，共三个容器，各司其职：

进入deploy目录启动：

cd deploy docker-compose up -d

几点说明：

• 首次拉镜像耗时约半小时，流量约 70GB，耐心等；
• 磁盘紧张时可用精简版：docker-compose -f docker-compose-lite.yml up -d，只起视频合成一个容器；
• RTX 50 系显卡（30/40 系 CUDA 12.8 也可）用专用编排：docker-compose -f docker-compose-5090.yml up -d。

启动后在 Docker Desktop 里看到三个服务均为 Running 状态即成功，点开容器日志能持续刷出运行记录：

拉镜像超时怎么办？国内网络下 Docker Hub 官方源经常连不上（报错Client.Timeout exceeded），到 Docker Desktop 的Settings → Docker Engine里给守护进程配置registry-mirrors镜像源，保存后 Apply & restart：

更多报错与解法收录在 常见问题。

第四步：安装客户端，跑通第一条视频

客户端是 Electron 桌面程序，负责管理模特、声音和作品：

• Windows：下载官方构建的Duix.Avatar-x.x.x-setup.exe安装包双击安装；
• Ubuntu：下载Duix.Avatar-x.x.x.AppImage直接运行；若以 root 用户登录桌面，需在终端加--no-sandbox参数执行。

打开客户端，界面非常克制：上方两个入口Create Video（创建视频）和Create Avatar（创建数字人），下方是My Works（我的作品）和My Avatars（我的数字模特）两个列表：

跑通一条完整视频的操作路径是：

1. 创建模特：上传一段 10 秒左右的视频。注意——视频里必须有人、且人在说话，程序要分离出画面用于形象克隆、分离出人声用于声音克隆，静音视频会直接报错；
2. 创建视频：选择一个模特，输入文案（支持中、英、日、韩、法、德、阿拉伯、西 8 种语言）或直接上传音频；
3. 提交后任务进入队列轮询，完成后作品出现在 My Works 列表，可播放、导出。

背后发生的事（源码在 src/main/service/）：文字先由 TTS 服务合成音频（voice.js），再与模特的无声素材视频一起提交给 face2face 服务做口型驱动（video.js），客户端每 2 秒轮询一次进度并更新状态。

进阶：不走客户端，直接调本地 API

服务端启动后会在本机暴露三个接口，适合写脚本批量生产数字人视频。参数细节可对照 model.js、voice.js、video.js 里的实际调用代码：

1. 声音克隆预处理（把模特视频的音轨交给 TTS 服务，返回后续合成所需的引用信息）

POST http://127.0.0.1:18180/v1/preprocess_and_tran {"format": ".wav", "reference_audio": "xxxx.wav", "lang": "zh"}

返回值中的asr_format_audio_url和reference_audio_text要记下来，下一步要用。

2. 文本转语音

POST http://127.0.0.1:18180/v1/invoke {"speaker": "{uuid}", "text": "要合成的文案", "format": "wav", "reference_audio": "{上一步返回值}", "reference_text": "{上一步返回值}"}

（完整固定传参见 README_zh.md 的开放 API 章节）

3. 视频合成 + 进度查询

POST http://127.0.0.1:8383/easy/submit {"audio_url": "{音频路径}", "video_url": "{模特无声视频路径}", "code": "{uuid}", "chaofen": 0, "watermark_switch": 0, "pn": 1} GET http://127.0.0.1:8383/easy/query?code={taskCode}

拿这三个接口串一个循环，就是一个最简单的批量数字人视频生成流水线。

常见问题 FAQ

Q1：三个容器起不来 / 反复重启？先跑nvidia-smi确认 GPU 驱动正常；再确认内存 ≥32GB——16GB 内存下 ASR 等容器可能直接起不来。

Q2：创建模特时报错？99% 是上传的视频没有声音、或不是真人在说话（见 常见问题 第 2 条）。形象克隆和声音克隆都依赖这段视频，素材不达标流程走不下去。

Q3：克隆形象时提示Connection refused？ASR 容器（duix-avatar-asr）冷启动较慢，服务端拉起来之后等几分钟再操作即可。

Q4：出错了，日志去哪看？客户端：右上角设置菜单 → "打开日志"，在 Roaming 目录的 logs 下查看main.log：

服务端：点开对应的 Docker 容器，在 Logs 页复制关键报错：

Q5：端口被占用或客户端连不上服务？确认 TTS（18180）、ASR（10095）、视频合成（8383）端口未被其他程序占用；客户端默认连http://127.0.0.1，配置位置见 config.js。

写在最后

到这里，一台带 N 卡的工作机上已经跑起了一条完整的本地数字人生产线：形象克隆、声音克隆、口播合成全部离线完成。先从一段 10 秒的自拍视频开始，跑通第一条口播，剩下的批量生成、API 集成都是顺手的事了。

【免费下载链接】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