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 是硅基智能开源的 AI 数字人（digital human）工具，支持本地部署与 API 调用：上传一段 10 秒左右的视频即可克隆形象与声音，输入文案或音频后生成口型同步的口播视频。全链路离线运行，适合想低成本做数字人视频的内容创作者，以及想集成数字人能力的开发者。

🚀 部署前的环境核对

先确认机器满足以下条件，否则后三个 Docker 服务起不来：

项目	要求
系统	Windows 10（19042.1526 及以上）或 Ubuntu 22.04 Desktop
显卡	NVIDIA 显卡且已装驱动，硬性要求
内存	32GB 及以上
磁盘	Windows：C 盘空闲大于 100G（镜像）、D 盘大于 30G（数据）；Ubuntu：空闲大于 100G

C 盘空间不足时，可以在 Docker Desktop 的 Settings → Resources → Advanced 里，把 Disk image location 改到空间更大的磁盘。

Windows 部署步骤

确认 WSL 可用并更新：

wsl --list --verbose wsl --update

安装 Docker Desktop，首次启动时接受协议、跳过登录。
克隆仓库并进入项目：

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

进入/deploy目录启动服务端，compose 文件就放在这个目录里：

cd deploy docker-compose up -d

这一步会拉取并启动 duix-avatar-tts、duix-avatar-asr、duix-avatar-gen-video 三个服务，镜像约 70G，首次启动请预留半小时左右。想省资源可以改用轻量版，只起一个 gen-video 服务：

cd deploy docker-compose -f docker-compose-lite.yml up -d

执行docker ps，看到三个容器均为 Running 即部署成功。
从项目 Release 页下载对应系统的预构建安装包，Windows 双击.exe完成客户端安装。

Ubuntu 22.04 部署步骤

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

按 NVIDIA 官方文档安装显卡驱动，nvidia-smi能显示显卡信息即成功。接着安装 nvidia-container-toolkit 并配置 Docker 运行时：

sudo nvidia-ctk runtime configure --runtime=docker sudo systemctl restart docker

启动服务端：

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

客户端下载 AppImage 版本直接双击运行；root 用户桌面环境下需在终端执行并追加--no-sandbox参数。

🎬 部署成功后的使用流程

创建数字人。主界面右侧点 Create Avatar，上传一段 10 秒左右的视频。注意视频里必须有人清晰说话，系统要同时提取面部特征和声音特征，无语音的视频会直接报错。你会看到：成功后"我的数字人"列表里多出一张带头像的卡片，可以重命名。

生成口播视频。点 Create Video 选中刚创建的数字人，输入文案或上传音频文件，提交生成。你会看到：作品出现在 My Works 列表并带进度，完成后直接播放、保存成片，口型与语音自动对齐。

管理与调试。My Works 支持关键词搜索和分页浏览，历史作品随时可找。右上角 Setting 菜单可以打开客户端日志、切换界面语言（支持中、英、日、韩、法、德、阿、西 8 种）、查看用户协议。排查问题前先开日志，效率最高。

🔧 生成卡住或服务起不来时看这里

按"现象 → 原因 → 动作"逐条对照：

docker-compose up -d失败，报 request canceled / 连接超时→ Docker Hub 源不稳定 → 在 Docker 配置的registry-mirrors里加国内镜像源后重试，或换可直连源的网络。
三个服务起不来，容器反复退出→ 没有 NVIDIA 显卡或驱动没装好 → 用nvidia-smi验证，本项目全部算力在本地，无 GPU 时服务必然启动失败。
创建数字人失败，提示与声音相关→ 上传的视频里没有人在说话 → 重新拍摄 10-20 秒的说话视频再上传。
创建时报 Connection refused→ asr 服务启动慢或内存不足（16G 可能带不动）→ 等服务全部 Running 后再等几分钟重试，必要时加大内存。
生成卡住或 heygen-tts 容器反复重启→ 音频处理环节出错 → 点开对应容器查看日志定位报错，重启该服务再试。

以上都解决不了时，对照仓库里的常见问题，里面覆盖了镜像源、无声视频、asr 连接失败等高频问题。

⚙️ 服务端结构与本地 API

部署完的/deploy实际是三个独立服务，全部通过http://127.0.0.1本地调用，不依赖外网：

duix-avatar-tts：基于 fish-speech 的声音克隆与文本转语音，本地端口 18180；
duix-avatar-asr：基于 fun-asr 的音频识别，端口 10095；
duix-avatar-gen-video：数字人视频合成，端口 8383。

对开发者，完整链路是三段式 API：先调 18180 端口的模特训练接口/v1/preprocess_and_tran提取声音参考，再调/v1/invoke合成音频，最后调 8383 端口的/easy/submit提交视频合成、/easy/query查进度。客户端里这些调用的组织逻辑可以读视频生成服务和声音服务两个文件，参数示例在 README 的"开放 API"一节。