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

Duix.Avatar 让你在自己的电脑上离线生成数字人口播视频：上传一段 10 秒左右的视频，克隆出形象与声音，之后输入文案或音频即可产出成片。适合内容创作者、企业培训团队，以及希望数据不出本地的开发者。

📋 值得上手：本地跑数字人的 3 个理由

免费商用：仓库授权支持全球免费商用，不按计划或按条视频收费
数据不出本机：ASR、TTS、视频合成三个服务全部跑在本地 Docker，视频与声音内容不经过第三方
启动链路短：5 条命令拉起整套环境，10 秒视频即可完成一次形象克隆

🖥️ 环境检查清单、安装与首次出结果

结论先行：有 NVIDIA 显卡和 Docker，按下面 4 步就能把界面跑起来。

环境检查清单：

系统：Windows 10（19042.1526 及以上）或 Ubuntu 22.04 Desktop（内核 6.8.0-52-generic）
显卡：英伟达显卡且驱动正常，nvidia-smi能看到显卡信息即通过（必要项）
内存：32G 及以上；官方推荐配置为 i5-13400F + RTX 4070
磁盘：Windows 的 D 盘空闲 >30G 存数据、C 盘空闲 >100G 存镜像；Ubuntu 需空闲 >100G
依赖：Node.js 18、Docker（Windows 需先装 WSL2）

启动步骤，每条命令后附一行说明：

git clone https://gitcode.com/GitHub_Trending/he/HeyGem.ai— 拉取客户端源码
在deploy/目录执行docker-compose up -d— 拉取 ASR、TTS、视频合成 3 个服务镜像，约 70G 流量，耐心等半小时左右；显存紧张可改用 lite 配置，只启动视频合成 1 个服务
npm install— 安装客户端依赖
npm run dev— 以开发模式启动客户端，打开主界面

首次成功的判断标准：Docker 中 duix-avatar-tts、duix-avatar-asr、duix-avatar-gen-video 三个容器都是 Running，客户端能加载作品列表页。

🎬 两条常用路径：定制模特与口播成片

场景一：克隆一个可复用的数字人形象

要做什么：把 10 秒左右的视频变成一个模型，之后的视频都不用再训练。

怎么做：

客户端点"快速定制"，上传一段本人说话的 10 秒视频。视频必须带声音、且是人在说话，声音会用于克隆
服务端自动把视频分离为画面加音频，调用 TTS 服务（端口 18180）完成形象与声音训练
训练完成后，在"我的数字模特"里确认新模型出现

预期结果：得到一个可驱动口型的模型。注意：服务端刚启动时 ASR（端口 10095）预热较慢，等几分钟再提交克隆，否则容易报 Connection refused。

场景二：输入文案直接产出成片

要做什么：选中模型，输入口播文案，输出口型对齐的视频。

怎么做：

在"短视频制作"入口选择刚建好的模型，输入文案或上传音频文件
客户端调用http://127.0.0.1:8383/easy/submit合成接口，凭返回的 code 在/easy/query查询进度，接口示例见 README_zh.md 开放 API 一节
生成完成后在"我的作品"里查看并下载

预期结果：音画同步的口播视频，文案支持中、英、日、韩、法、德、阿、西 8 种语言。

🔧 4 个高频配置项，什么时候改、怎么改

Docker 镜像存放位置（Windows）：C 盘空闲不足 100G 时需要改。在 Docker Desktop 的资源设置里，把镜像目录指到剩余空间 >100G 的磁盘文件夹
数据挂载目录：数据盘盘符不是 D 时需要改。在 deploy/docker-compose.yml 的 volumes 中改d:/duix_avatar_data左侧的宿主机路径，容器内路径保持/code/data不动
服务端地址：客户端和服务端不在同一台机器时需要改。src/main/config/config.js 里 serviceUrl 默认是 127.0.0.1（8383 与 18180 两个端口），改成服务端局域网 IP
50 系列显卡：50 系显卡服务起不来时需要换启动文件。用 deploy/ 目录下经过 5090 测试的docker-compose-5090.yml拉起

🩺 排错速查：4 个高频错误与修复

症状：执行 docker-compose up -d 时三个服务报 net/http request canceled 或 context canceled → 可能原因：Docker Hub 官方源连接不稳定 → 修复：在 Docker 守护进程配置里加国内镜像源 registry-mirrors，重启 Docker 后重新拉取
症状：新增模特时报错，任务直接失败 → 可能原因：上传的视频没有声音，或不是人在说话 → 修复：重录一段 10 秒、清晰人声的视频再提交训练
症状：定制模特报 Connection refused → 可能原因：ASR 服务预热慢，刚启动就提交；或机器内存不足 16G，服务起不齐 → 修复：服务启动后等几分钟再克隆形象；内存建议升到 32G
症状：客户端行为异常，需要定位问题出在哪一端 → 可能原因：客户端与服务端问题需要分开看日志 → 修复：客户端日志在界面右上角设置菜单的"打开日志"入口，文件位于 heygem.ai 的 logs 目录下的 main.log；服务端日志直接在 Docker 对应容器里复制

以上都排查完仍无进展，就把"复现步骤 + 客户端日志 + 容器日志"打包，对照 doc/常见问题.md 的自查清单再查一遍，或按 README_zh.md 的提问模板去 issue 区搜索同类问题。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析