企业官网建设流程全解析

Duix.Avatar 开源数字人本地部署完整教程：用 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

想做口播视频却不想真人出镜，也不想把人脸、声音素材传到任何云平台？Duix.Avatar 是一款开源的 AI 数字人（数字分身）工具包：你只需提交一段 10 秒左右的视频，就能在本地完成数字人形象和声音克隆，输入文案即可自动生成口型匹配的口播视频。整个流程完全离线，数据不出你的电脑。这篇教程会陪你从环境自检一路走到第一条视频产出，并附上避坑对照表。

要点速览

• 核心关键词：AI 数字人、本地部署、离线视频生成、数字人克隆、口播视频
• 长尾关键词：10 秒视频克隆、Docker 部署数字人、数字人避坑、数字人 API 二次开发
• 你将学到：
  1. Windows / Ubuntu 两套环境的环境自检清单
  2. 镜像加速到一键启动的完整部署命令
  3. 界面导览与"定制模特 → 合成视频"的完整操作路径
  4. 三个本地服务的分工原理（含术语解释）
  5. 常见报错的排查顺序与硬件档位参考

动手前：环境自检与硬件要求

部署前先花两分钟核对下面两张清单，任何一项不满足都会让后续服务起不来。

Windows 平台清单

Ubuntu 平台清单

为什么显卡是硬性要求：这个项目的所有算力都在本地，三个 Docker 服务都依赖 NVIDIA GPU，没有 NVIDIA 显卡或驱动，服务直接启动不了。驱动请到 NVIDIA 官网查找并下载对应型号的版本，装完执行nvidia-smi看到显卡信息即算通过。

快速部署：从环境准备到客户端连接

第一步：装好 Docker 运行环境

Windows：Docker Desktop 依赖 WSL 运行，所以先装 WSL 再装 Docker。

wsl --list --verbose # 查看是否已装过 WSL，没有再执行 wsl --install wsl --update # 安装成功后更新 WSL

网络原因可能导致wsl --install失败，多试几次即可；安装过程中会要求设置新的用户名和密码，请设置并记住。

之后下载 Docker Windows 版安装包（按 CPU 架构选择），安装后启动 Docker Desktop，首次运行接受协议并跳过登录。

Ubuntu：先执行docker --version检查是否已装 Docker，没有的话执行：

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

Docker 要能调用显卡，还需安装 NVIDIA Container Toolkit，并配置 Docker 使用 NVIDIA 运行时：

sudo apt-get install -y nvidia-container-toolkit sudo nvidia-ctk runtime configure --runtime=docker sudo systemctl restart docker

为什么要装 Toolkit：它是 Docker 使用 NVIDIA GPU 的必要组件，缺了它容器内的模型服务拿不到显卡算力。

第二步：镜像加速与存储优化

拉镜像会消耗约70GB 流量，国内网络直接连官方源经常超时。这一步的目的是让下载不卡死、存得下：

• Ubuntu：编辑/etc/docker/daemon.json，添加registry-mirrors字段填入可用的国内镜像源（镜像源会随时间失效，建议自行搜索最新可用的），保存后重启 Docker 服务。
• Windows：如果 C 盘不足 100GB，安装完 Docker 后可以在 Docker Desktop 的资源设置里，把镜像存储位置改到剩余空间大于 100GB 的其他磁盘目录。

第三步：一键启动服务端

先克隆仓库，再进入deploy目录启动。deploy目录下有四个 compose 文件，按需求选一个：

git clone https://gitcode.com/GitHub_Trending/he/Duix-Avatar cd Duix-Avatar/deploy # Windows 完整版 docker-compose up -d # Windows 轻量版 docker-compose -f docker-compose-lite.yml up -d # Ubuntu 完整版 docker-compose -f docker-compose-linux.yml up -d # 50 系显卡方案 docker-compose -f docker-compose-5090.yml up -d

预期结果：等待约半小时（取决于网速），打开 Docker 看到三个服务均为 Running 状态即成功；轻量版只有Duix.Avatar-gen-video一个服务。

三个服务会占用这些本地端口，后面调用 API 会用到：

第四步：安装客户端并连接

• Windows：从项目 Release 页下载官方安装包，双击Duix.Avatar-x.x.x-setup.exe安装，启动后自动检测本地服务状态。
• Ubuntu：下载 Linux 版 AppImage，双击Duix.Avatar-x.x.x.AppImage即可运行，无需安装。注意：root 用户下双击可能无法运行，需要在终端执行./Duix.Avatar-x.x.x.AppImage --no-sandbox。

上手体验：界面导览与第一条视频

打开客户端后，首页分两个主要功能区：

• 短视频制作（Create Video）：入口"创建视频"，用文字或音频驱动数字人说话，产出口播视频
• 快速定制模特（Create Avatar）：入口"快速定制"，上传一段视频，克隆出你的专属数字模特

页面下方是两个管理区：我的作品（已生成的视频列表，可预览、下载）和我的数字模特（已克隆的模特库，可预览、直接"做视频"）。

完成一次完整生成的操作路径

第 1 步：定制模特。点击"快速定制"，上传拍摄好的原始视频。上传前按界面里的"标准示例"自查，五条规则缺一不可：

1. 视频时长最少 8 秒，说话吐字清晰
2. 视频前后有且只有同一个人
3. 五官清晰不遮挡，头部不倾斜或侧向，手不挡脸
4. 分辨率最低 720P
5. 格式为 MP4 / MOV

提交后模特进入"训练中"状态，等训练完成即可出现在"我的数字模特"列表里。

第 2 步：创建视频。在"创建视频"流程里选择刚定制的模特，然后二选一：

• 文本合成：直接输入文案（支持中英文），系统自动转成克隆的语音
• 音频合成：上传自己的录音，单次最多 1 个文件，支持 mp3、wav、flac、m4a，单个录音时长小于 30 分钟，请传纯干音（背景音、噪音会影响合成效果）

给视频起个名字，点击"合成视频"提交。

第 3 步：查看结果。去"首页 → 我的作品"查看进度，状态从"排队中"变成可预览后，即可在线预览或下载到本地。

设置菜单里可以查看用户协议、打开客户端日志（排障必备）、在中英文之间切换界面语言。

它是怎么实现的：三个本地服务的分工

你现在已经跑通了完整流程，回头看一下背后发生了什么。克隆不是"存一个头像"，而是三条本地服务流水线协作的结果：

1. 拆解素材：你上传的 10 秒视频被分离为"静音视频 + 音频"，音频会按约定路径放入D:\duix_avatar_data\voice\data（Windows）或~/duix_avatar_data/voice/data（Linux）
2. ASR 服务（端口 10095）：把视频里的语音转写成文本。ASR 即 Automatic Speech Recognition（自动语音识别），基于开源的 FunASR
3. TTS 服务（端口 18180）：用你的声音样本克隆音色，把新文案合成成"你说话"的音频。TTS 即 Text-to-Speech（文本转语音），基于 fish-speech
4. 视频合成服务（端口 8383）：接收音频 + 原始视频，做口型驱动，让数字人按新音频的发音动嘴，输出最终口播视频

另外，客户端文案合成支持 8 种语言：中、英、日、韩、法、德、阿拉伯语、西班牙语。如果你关心数据落盘位置，可以查 src/main/config/config.js，里面定义了 Windows 与 Linux 下的数据目录约定。

场景落地：三类典型用法

教育培训：批量课程口播视频

• 痛点：真人录制讲解视频，一位讲师反复录、多语言版本成本更高，且课程改版后要全部重录
• 落地方式：为讲师定制一个数字模特，把课程讲义按章节拆成文本模板，每章提交一次"文本合成"；需要英文版时直接换语言输入，无需重新录制
• 效果：同一位"讲师"可无限量次生成新视频，改版只需改文案，不再依赖真人档期

电商与营销：口播带货视频量产

• 痛点：促销、新品、多平台分发需要大量口播素材，真人出镜拍摄排期紧、场地成本高
• 落地方式：用 10 秒视频克隆品牌数字人，把商品卖点文案直接输入合成；已有主播录音的，走"音频合成"路径保留原声
• 效果：视频产出与拍摄档期解耦，批量生成时数据全程留在本地，素材不外传

企业内部：标准化培训与通知

• 痛点：内部培训、安全提示、制度宣导反复口口相传，质量不统一，员工离职后资料断档
• 落地方式：克隆一位内部讲师形象做固定"数字导师"，把培训材料转成文本批量合成，按部门批量产出
• 效果：培训视频风格统一、可随时更新，且全程离线生成，符合内部资料不外发的合规要求

进阶：API 接口与二次开发

本节面向有 HTTP 调用基础的读者，接口都在服务端启动后通过http://127.0.0.1本地调用。完整调用逻辑可参考 src/main/service/ 下的model.js、video.js、voice.js。

① 模特训练（音频预处理）：先把音频放到D:\duix_avatar_data\voice\data，然后调用：

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

返回asr_format_audio_url和reference_audio_text两个字段，记下来，下一步要用。

② 音频合成（用克隆的声音读文案）：

POST http://127.0.0.1:18180/v1/invoke { "speaker": "{uuid}", "text": "需要合成的文本内容", "format": "wav", "reference_audio": "{上一步返回的 asr_format_audio_url}", "reference_text": "{上一步返回的 reference_audio_text}", "topP": 0.7, "max_new_tokens": 1024, "chunk_length": 100, "repetition_penalty": 1.2, "temperature": 0.7, "need_asr": false, "streaming": false, "is_fixed_seed": 0, "is_norm": 0 }

speaker传一个唯一 UUID 即可，其余为固定参数，照抄即可。

③ 视频合成（驱动数字人）：

POST http://127.0.0.1:8383/easy/submit { "audio_url": "{音频路径}", "video_url": "{视频路径}", "code": "{uuid}", "chaofen": 0, "watermark_switch": 0, "pn": 1 }

④ 进度查询（code用提交时的值）：

GET http://127.0.0.1:8383/easy/query?code={code}

避坑手册：常见问题排查

按下面顺序自查，能覆盖大部分卡点：

1. 三个服务不是 Running 状态？先执行nvidia-smi确认显卡和驱动正常——没有 NVIDIA 显卡或驱动，服务一定起不来。其次确认服务端、客户端都是最新版本（服务端到deploy目录重新执行docker-compose up -d，客户端拉取最新代码重新构建）。

2.docker-compose up -d拉镜像超时（Client.Timeout exceeded）？这是连不上 Docker Hub 官方源，配置国内镜像源即可，方法见上文"镜像加速"一节；Windows 下也可在 Docker Desktop 里配置。

3. 新增模特报错，检查视频是否"有声音且在说话"。克隆需要用到视频里的声音，无声视频或背景音乐主导的视频都会失败，请重拍一段本人在自然说话的清晰视频。

4. 定制模特报Connection refused？ASR 服务启动较慢，服务端刚启动完请稍等几分钟再做克隆操作；另外机器内存太小（如 16GB）可能导致 ASR 起不来，建议 32GB 起步。

5. 生成结果或报错看不懂？客户端日志在"设置 → 打开日志"里查看；服务端日志在 Docker 服务列表里点开对应容器复制，参考下图操作：

更多问题可以先翻 doc/常见问题.md，项目更新频繁，你的问题很可能已经在新版里解决了。

硬件档位参考对照表

显存吃紧时可关注deploy配置中的PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:512等参数，按社区讨论按需调整，不要盲目照搬。

收尾：值不值得投入？

• 隐私：人脸、声音、文案全程不出本机，适合内部资料与合规敏感场景
• 成本：一次性硬件投入，之后不限次数生成，无按量订阅费
• 门槛低：10 秒视频即可完成克隆，客户端图形界面操作，非技术用户也能走完流程
• 可扩展：源码开放 + 本地 API，可接进自己的业务系统
• 局限要心里有数：依赖 NVIDIA 显卡和 32GB 起步内存，镜像下载约 70GB 流量，首次部署需要耐心

建议的行动步骤：先按上文清单自检环境 → 用轻量版（lite）先跑通视频生成，熟悉流程后再上完整版做克隆 → 第一次定制模特严格按"标准示例"拍素材，能少踩一半坑。社区更新活跃，遇到报错先查文档和最新版本，也欢迎把部署经验与优化方案回馈给开源社区，一起把这个数字人工具箱用得更好。

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