零基础跑通 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 是一个全离线的开源数字人创作工具：录一段自己的视频，克隆出形象和声音后，输入文字就能自动合成口型对齐的成片，且素材全程不出你的电脑。这篇教程带你从装环境到生成第一条数字人视频，全程约 40 分钟。

01 项目概览：Duix.Avatar 本地部署到底能做什么

做完本章你能得到一张清晰的"能力地图"，知道哪些环节它能替你完成、哪些素材必须自己准备。

Duix.Avatar 解决的问题很直接：把你本人的形象和声音变成可复用的数字分身，之后"念稿"只花打字的时间。它基于真人视频训练（而非传统 3D 建模），把制作成本和硬件门槛都拉低到了消费级。核心能力一览：

功能模块	它替你做的事
形象克隆	从一段真人视频里重建面部特征和轮廓，生成可长期复用的虚拟模特
声音克隆	从同一段视频提取音色，支持语速等语音参数调节
文本 / 语音驱动	输入文字（或直接传语音）即可驱动数字人表演，无需真人出镜
口型同步	自动对齐音视频节奏，让嘴唇开合贴合发音
全离线运行	训练与合成全部在本地完成，断网也能用，素材不上传云端
多语言脚本	台词支持中、英、日、韩、法、德、阿、西八种语言

02 安装与首次运行：本地部署步骤

做完本章你会得到三样东西：运行中的服务容器、能打开的客户端主界面，以及一张硬件核对清单。预计耗时约 40 分钟（其中约一半是等镜像下载）。

先看硬件门槛，它比软件更"硬"——所有算力都消耗在本地，NVIDIA 显卡和驱动缺一不可：

项目	官方推荐配置	说明
操作系统	Windows 10 19042.1526+ / Ubuntu 22.04	Windows 版要求存在 D 盘
CPU	13 代 Intel Core i5-13400F	AMD 同级处理器可替代
内存	32GB	低于此值 asr 服务可能起不来
显卡	NVIDIA RTX 4070，驱动装好	非 NVIDIA 显卡无法启动任何服务
磁盘（Windows）	C 盘 100GB+，D 盘 30GB+	前者放服务镜像，后者放项目数据
磁盘（Ubuntu）	100GB 空闲	镜像与数据共用

第 1 步 · 按系统装好 Docker 环境（约 10 分钟）

Windows：先检查 WSL 状态，再更新它，然后安装 Docker Desktop 并首次启动（同意协议、跳过登录）：

wsl --list --verbose # 查看 WSL 是否已安装 wsl --update # 更新 WSL 到最新版本

若失败：C 盘不足 100GB 时，在 Docker Desktop 的 Settings → Resources → Advanced 里点 Browse，把磁盘镜像位置改到空间充足的盘。

图：Docker Desktop 资源设置界面，可将 Disk image location 改到空闲空间更大的磁盘

Ubuntu 22.04：安装 Docker、docker-compose 与 NVIDIA Container Toolkit（Docker 调用 GPU 的必备件），装完配置运行时并重启 Docker 服务：

sudo apt update && sudo apt install -y docker.io docker-compose nvidia-container-toolkit sudo nvidia-ctk runtime configure --runtime=docker && sudo systemctl restart docker

若失败：执行nvidia-smi应能打印显卡信息，打印不出来说明 NVIDIA 驱动本身没装好，先去解决驱动。

第 2 步 · 启动服务容器（下载约 30 分钟）

进入deploy/目录执行启动命令。首次运行要拉取三个镜像（fun-asr、fish-speech-ziming、duix.avatar），消耗约 70GB 流量：

cd deploy docker-compose up -d # Windows docker-compose -f docker-compose-linux.yml up -d # Ubuntu 22.04

若失败：报registry-1.docker.io ... request canceled是 Docker Hub 连接超时，按 doc/常见问题.md 的配置方法给 Docker 添加国内镜像源后重试。

第 3 步 · 安装客户端（约 10 分钟）

下载官方构建的安装包：Windows 双击Duix.Avatar-x.x.x-setup.exe安装；Ubuntu 直接双击Duix.Avatar-x.x.x.AppImage运行，root 用户启动需在终端追加--no-sandbox参数。

✅ 通过标志：Docker 里duix-avatar-asr、duix-avatar-tts、duix-avatar-gen-video三个容器全部 Running，客户端通过协议页后进入主界面。注意 asr 服务预热较慢，容器转 Running 后请先等几分钟再开始克隆。

图：Docker Desktop 容器日志页，STATUS 显示 Running 即代表该服务已就绪

03 创建第一个作品：第一次生成数字人视频

做完本章你会得到一个真实产出：一段由"文字 + 你的数字分身"合成的口播视频。

录素材：拍一段 10 秒左右的正面视频——光线充足、背景干净、表情自然，且必须有清晰的说话声（声音克隆直接取自这段音频，静音视频无法创建模特）。
训练形象：客户端首页点 Create Avatar，上传视频并填写模型名称，提交后等待训练完成。
确认形象：形象出现在 My Avatars 列表中即训练成功。完成信号：列表里能看到你的新模特卡片。
写台词：点 Create Video 进入创作页，选择刚建的形象，输入台词（新手建议 50 字以内），按需调整语速等语音参数。
生成视频：提交合成任务，数分钟内完成，期间保持三个服务容器在线。
验收成片：到 My Works 列表打开新视频。

图：客户端主界面——顶部两个入口分别负责视频合成与形象创建，下方管理你的作品和数字人模型

可感知的成功标志：视频能完整播放、口型与发音逐句对齐、声音是克隆出的你的音色。到这里，部署与创作两条线都跑通了。

04 效率与进阶：从单条成片到批量生成

批量生产走 Open API：服务端启动后在本地127.0.0.1暴露了 HTTP 接口——语音合成走127.0.0.1:18180/v1/invoke，视频合成走127.0.0.1:8383/easy/submit，进度查询走8383/easy/query?code=${taskCode}。写个脚本循环调用即可批量出片，接口字段与调用流程可直接参考 src/main/service/ 下 video.js、voice.js 的源码。
只想合成、不想训练？用轻量版部署：在deploy/目录执行docker-compose -f docker-compose-lite.yml up -d，只起一个Duix.Avatar-gen-video容器，省硬件资源，代价是没有本地 ASR/TTS 服务。
一形象多语言：台词换语言重新生成即可复用同一个形象，无需重训——八种语言脚本在同一个模型下都能跑。

05 排障速查：卡住时先查这张表

现象	原因	解决
拉镜像报`request canceled`	Docker Hub 官方源连接不稳定	给 Docker 配置国内镜像源（见 doc/常见问题.md）
容器起不来、反复退出	无 NVIDIA 显卡或驱动未装好	执行`nvidia-smi`验证驱动，装好后重启 Docker 再拉服务
创建形象报`file not exists`	asr 服务尚未就绪 / 上传视频无说话声	容器 Running 后等几分钟再试；确认视频里有人在说话
定制模特报`Connection refused`	fun-asr 启动慢或内存不足	等待 asr 就绪后重试；内存低于 32GB 时考虑扩容

完整故障排查与提问模板：doc/常见问题.md
客户端与服务端源码入口：src/main/（问题定位时可对照src/main/config/检查本地配置）
问题反馈：项目 Issues 页面每天都在处理新提交，提问前先搜一遍，很多坑已有解法

环境装好后先按 03 章跑通第一条视频，比研究更多功能更有价值。卡住的地方对照上面这张表处理，十分钟内大概率能自助解决。

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

企业官网建设流程全解析