Awesome Digital Human (ADH3) 数字人教程
Awesome Digital Human (ADH3) 是一个开源的多模态数字人系统，采用先进的Live2D渲染技术，支持语音识别、智能对话、语音合成等多模态交互方式。系统旨在打造有温度、有灵魂的数字人，为用户提供沉浸式的交互体验。ADH集成了多种AI引擎，支持高度定制化，适用于客服、教育、娱乐等多种场景。
此项目已更新至ADH3版本，相较于之前的版本，特别对前端内容进行了重构。
本文介绍的内容新增实现了连续对话、语音唤醒、人物模型位置调整等功能，推荐前往网盘下载完整代码体验。
源码地址
前置教程
如想快速启动本ADH3数字人项目，你可能需要先完成以下前置教程：
1. 项目安装
1.1 项目部署与启动指南
环境准备
ADH数字人系统支持多种部署方式，满足不同用户的需求：
操作系统要求: Windows 10+, macOS 10.15+, Ubuntu 18.04+
运行环境: Python 3.10+ (后端服务), Node.js 20+ (前端开发)
容器环境: Docker 20.10+ & Docker Compose 2.0+ (推荐)
浏览器要求: Chrome 90+, Firefox 88+, Safari 14+
安装步骤
方式一：Docker容器快速部署（推荐新手）
这是最简单快捷的启动方式，无需配置本地环境：
# 1. 克隆项目到本地 建议通过网盘下载完整代码git clone https://github.com/wan-h/awesome-digital-human-live2d.gitcd awesome-digital-human-live2d# 2. 使用快速启动配置文件docker-compose -f docker-compose-quickStart.yaml up -d# 3. 等待服务启动完成（约2-3分钟）docker-compose ps启动成功后访问：http://localhost:8880
方式二：Docker开发环境部署
适合需要修改代码进行定制化开发的用户：
# 1. 克隆项目cd awesome-digital-human-live2d# 2. 构建并启动开发环境docker-compose up --build -d# 3. 查看服务状态docker-compose logs -f方式三：本地裸机部署
适合有经验的开发者，需要完整控制开发环境：
后端服务启动：
# 1. 创建Python虚拟环境conda create -n adh-env python=3.10conda activate adh-env# 2. 安装Python依赖pip install -r requirements.txt# 3. 安装FFmpeg音频处理工具# Windows: 下载FFmpeg并配置环境变量# Ubuntu: sudo apt install ffmpeg# macOS: brew install ffmpeg# 4. 启动后端服务python main.py前端服务启动：
# 1. 进入前端目录cd web# 2. 安装pnpm包管理器npm install -g pnpm# 3. 安装前端依赖pnpm install# 4. 开发模式启动pnpm run dev# 5. 生产模式启动（可选）pnpm run buildpnpm run start访问地址：
Docker部署：http://localhost:8880
1.2 核心配置
环境变量配置：
项目运行需要配置多个环境变量文件来连接各个服务模块。
后端配置 (.env)
在项目根目录创建或将env.example 重命名为 .env 文件：
# AI服务API密钥（根据使用情况配置）DIFY_TTS_API_KEY=your-dify-api-key # 语音合成服务密钥DIFY_ASR_API_KEY=your-dify-api-key # 语音识别服务密钥DIFY_AGENT_API_KEY=your-dify-api-key # 智能对话服务密钥前端配置 (web/.env)
创建前端环境配置文件：
# 后端服务连接配置NEXT_PUBLIC_SERVER_PROTOCOL="http" # 协议类型 (http/https)NEXT_PUBLIC_SERVER_IP="127.0.0.1" # 后端服务IP地址NEXT_PUBLIC_SERVER_PORT="8000" # 后端服务端口NEXT_PUBLIC_SERVER_VERSION="v0" # API版本号NEXT_PUBLIC_SERVER_MODE="prod" # 运行模式 (dev/prod)端口配置说明：
8880: Nginx反向代理端口（前端入口）
3000: Next.js前端服务端口（开发模式）
8000: FastAPI后端API服务端口
10095: FunASR语音识别服务端口
服务架构：
Docker部署架构：Internet → Nginx(8880) → [Web UI(3000) + API Server(8000) + FunASR(10095)]本地部署架构：Browser → Web UI(3000) → API Server(8000) → [ASR + TTS + Agent Services]2. 核心功能与使用
2.1 基础操作
多模态数字人交互流程
ADH系统实现了完整的多模态交互闭环：
用户语音输入 → ASR语音识别 → Agent智能处理 → TTS语音合成 → 数字人输出 ↓ ↓ ↓ ↓ ↓ 唤醒词检测 文本预处理 意图理解 语音生成 口型同步 录音质量检查 分词断句 知识检索 情感分析 表情匹配 噪声过滤 语言检测 上下文管理 韵律控制 动作触发核心功能特性：
Live2D数字人技术
流畅动画渲染: 基于Live2D Cubism引擎，提供高质量的2D角色动画
实时口型同步: 通过音素分析实现精确的口型同步效果
物理模拟: 内置物理引擎，实现自然的头发、衣物摆动效果
表情丰富: 支持多种表情文件，能够根据对话内容自动切换表情
多模态交互系统
语音识别(ASR): 支持中英文混合识别，实时语音转文本
语音合成(TTS): 多种语音合成引擎，支持情感化语音生成
智能对话(Agent): 集成多种AI框架，支持上下文理解和多轮对话
唤醒词功能: 支持自定义唤醒词，无需手动点击即可激活数字人
基础使用操作：
1. 首次启动配置
访问系统界面（http://localhost:8880）
允许浏览器麦克风权限
等待Live2D模型加载完成
测试麦克风录音功能
2. 唤醒数字人
说出任意唤醒词激活数字人：
“你好。”
“你好”
唤醒成功后，数字人会有相应的动画反馈。
3. 语音交互
唤醒数字人后，系统会自动开始录音
正常说话，系统会实时识别您的语音
识别完成后，数字人会进行智能回复
支持连续对话，无需重复唤醒
4. 文本输入
在设置面板中也可以使用文本输入方式与数字人交流：
点击文本输入框
输入您想说的话
点击发送或按回车键
数字人会进行语音和动作回应
2.2 高级配置
角色与背景定制
内置角色介绍
系统内置了多个高质量的Live2D角色模型：
Haru系列 - 经典Live2D角色
HaruGreeter: 礼仪版本，适合迎宾场景
Haru: 标准版本，表情丰富多样
其他角色：
Chitose: 日系风格，适合客服场景
Epsilon: 科技感强，适合产品展示
Kei, Hibiki, Hiyori等多种风格角色
角色切换方法
界面操作切换：
打开设置面板
在”角色选择”中选择心仪的角色
系统会自动加载新的角色模型
修改默认角色：
// 编辑 web/lib/constants.ts 文件export const SENTIO_CHARACTER_DEFAULT = "Haru" // 修改为其他角色名添加自定义角色：
将Live2D角色文件夹放入
web/public/sentio/characters/free/在角色列表常量中添加文件夹名
确保角色文件结构完整
背景定制配置
系统支持静态图片和动态视频两种背景类型：
静态背景设置：
将背景图片放入
web/public/sentio/backgrounds/static/目录在常量文件中添加背景配置：
export const SENTIO_BACKGROUND_STATIC_IMAGES = [ "back.jpg", "office.jpg", "nature.jpg", "custom_bg.jpg"]
动态背景设置：
将视频背景放入
web/public/sentio/backgrounds/dynamic/目录支持MP4格式的视频文件
视频会自动循环播放
技术参数调优
Live2D模型参数
// 模型缩放调整export const SENTIO_MODEL_SCALE_MIN: number = 0.5 // 最小缩放export const SENTIO_MODEL_SCALE_DEFAULT: number = 1.0 // 默认缩放export const SENTIO_MODEL_SCALE_MAX: number = 2.0 // 最大缩放// 模型Y轴位置调整export const SENTIO_MODEL_POSITION_Y_MIN: number = -1.0 // 最小Y坐标export const SENTIO_MODEL_POSITION_Y_DEFAULT: number = 0.0 // 默认Y坐标export const SENTIO_MODEL_POSITION_Y_MAX: number = 1.0 // 最大Y坐标// 口型同步系数调整export const SENTIO_LIPFACTOR_MIN: number = 0.0 // 最小口型系数export const SENTIO_LIPFACTOR_DEFAULT = 5.0 // 默认口型系数export const SENTIO_LIPFACTOR_MAX: number = 10.0 // 最大口型系数录音参数配置
// 录音时长限制export const SENTIO_RECODER_MIN_TIME: number = 1000 // 最小录音时长(1秒)export const SENTIO_RECODER_MAX_TIME: number = 30000 // 最大录音时长(30秒)// 唤醒超时设置export const SENTIO_WAKE_TIMEOUT_DURATION = 30000 // 唤醒后超时时间(30秒)TTS语音合成配置
// 语音合成停顿标点export const SENTIO_TTS_PUNC: string[] = ['；', '！', '？', '。', '?']export const SENTIO_TTS_SENTENCE_LENGTH_MIN = 6 // 最小句子长度AI引擎集成
ADH系统支持多种AI引擎的灵活配置：
ASR语音识别引擎
Dify: 基于Dify的语音识别模型
FunASR: 阿里巴巴开源语音识别框架，支持实时流式识别
Azure Speech: 微软语音服务，识别准确率高
OpenAI Whisper: OpenAI的语音识别模型
TTS语音合成引擎
Dify: 基于Dify的语音模型
Edge TTS: 微软Edge浏览器的语音合成服务
Azure Speech: 高质量语音合成，支持多种音色
Dify TTS: 可配置的语音合成服务
Agent对话引擎
OpenAI GPT: 强大的对话和推理能力
Dify Agent: 可定制的对话代理框架
本地模型: 支持部署本地大语言模型
3. 常见问题解决
3.1 浏览器权限与网络问题
问题1：Chrome浏览器无法访问麦克风
现象：在HTTP协议下Chrome浏览器拒绝麦克风访问权限
解决方案：
在Chrome地址栏输入：
chrome://flags/#unsafely-treat-insecure-origin-as-secure找到”Insecure origins treated as secure”选项
在输入框中添加前端服务地址：
http://localhost:3000或http://localhost:8880点击”Enabled”启用该功能
重启Chrome浏览器使设置生效
刷新页面并重新允许麦克风权限
问题2：Docker网络连接问题
现象：Windows环境下Docker容器无法正常访问或容器间通信失败
解决方案：
修改Docker Compose配置文件，移除复杂的网络配置：
# docker-compose.yaml 或 docker-compose-quickStart.yamlversion: '3.8'services: nginx: ports: - "8880:80" # 确保端口映射正确 # 移除networks配置 web: ports: - "3000:3000" api: ports: - "8000:8000"检查Windows防火墙设置，确保Docker端口未被阻止
重启Docker Desktop服务
清理Docker缓存：
docker system prune -adocker-compose down --volumesdocker-compose up -d
3.2 模型加载与渲染问题
问题3：Live2D模型加载失败
现象：页面显示空白或模型无法正常渲染，控制台出现404错误
解决方案：
检查文件路径：
确认模型文件存在于正确路径：
web/public/sentio/characters/free/[角色名]/验证主模型文件名：
[角色名].model3.json
验证文件完整性：
# 检查关键文件是否存在ls -la web/public/sentio/characters/free/[角色名]/# 应该包含：[角色名].model3.json, [角色名].physics3.json 等清除浏览器缓存：
按F12打开开发者工具
右键刷新按钮选择”清空缓存并硬性重新加载”
或在控制台运行：
location.reload(true)
检查网络请求：
在Network标签中查看模型文件请求状态
确保所有文件返回200状态码
问题4：模型显示异常或动画卡顿
现象：Live2D模型显示位置错误、尺寸异常或动画不流畅
解决方案：
调整显示参数：
// 修改 web/lib/constants.ts 中的参数export const SENTIO_MODEL_SCALE_DEFAULT = 0.8 // 调整默认缩放export const SENTIO_MODEL_POSITION_Y_DEFAULT = -0.2 // 调整Y轴位置优化渲染性能：
降低模型质量设置
关闭不必要的物理效果
减少同时加载的表情和动作数量
检查浏览器性能：
关闭其他占用GPU资源的标签页
确保显卡驱动程序为最新版本
尝试使用不同的浏览器测试
3.3 音频与通信问题
问题5：语音识别无响应或准确率低
现象：说话后无文字输出或识别结果错误
解决方案：
检查麦克风硬件：
确认麦克风已正确连接
测试系统录音功能
检查麦克风音量设置
优化录音环境：
减少背景噪音
保持适当的说话距离（20-30cm）
语速适中，发音清晰
调整录音参数：
// 在设置面板中调整以下参数录音增益: 适当增加噪声抑制: 开启回声消除: 开启
问题6：前后端连接失败
现象：页面显示”Soul is Death!”错误或WebSocket连接失败
解决方案：
检查服务状态：
# 确认后端服务正常运行curl http://localhost:8000/health# 检查Docker服务状态docker-compose ps验证网络配置：
检查
web/.env文件中的服务地址配置确认端口映射正确
测试后端API可访问性
检查防火墙设置：
# Windows防火墙设置# 1. 打开Windows Defender防火墙设置# 2. 添加端口8000、3000、8880的例外规则# 3. 重启相关服务
3.4 性能优化问题
问题7：系统响应速度慢
现象：数字人回复延迟高，交互体验不流畅
解决方案：
优化AI服务选择：
使用本地AI模型减少网络延迟
调整AI模型参数平衡速度和质量
启用响应缓存机制
优化音频处理：
# 调整音频流处理参数CHUNK_SIZE = 1024 # 减小音频块大小SAMPLE_RATE = 16000 # 降低采样率前端性能优化：
# 启用生产模式cd webpnpm run build # 构建优化版本pnpm run start # 启动生产服务器
4. 总结
Awesome Digital Human (ADH) 作为一个开源的多模态数字人系统，为开发者和用户提供了一个功能强大、高度可定制的数字人交互平台。通过本教程的学习，您应该掌握了：
核心技术特色
多模态交互体系：ADH系统成功整合了语音识别、智能对话、语音合成等核心技术，实现了自然流畅的人机交互体验。特别是基于Live2D技术的数字人渲染，能够提供高质量的视觉表现和情感表达能力。
灵活的架构设计：采用前后端分离架构，支持多种部署方式。Docker容器化部署大大简化了环境配置和运维工作，而本地裸机部署则为开发者提供了完整的定制空间。
丰富的定制选项：从角色模型、背景环境到技术参数，ADH提供了全方位的定制能力。用户可以根据具体应用场景，灵活调整数字人的外观、行为和交互方式。
应用场景展望
ADH数字人系统在多个领域都具有广阔的应用前景：
客户服务领域：可以作为智能客服助手，提供24小时不间断的服务，结合情感识别技术，提供更加人性化的服务体验。
教育培训领域：可作为虚拟教师或学习伙伴，通过生动的表情和动作，提升学习者的参与度和学习效果。
娱乐互动领域：在游戏、直播等娱乐场景中，数字人可以作为虚拟主播或游戏角色，与用户进行实时互动。
企业展示领域：可作为企业的数字代言人，用于产品介绍、品牌宣传等商业场景。
学习进阶建议
基础技能巩固：
深入学习Live2D技术原理和模型制作
掌握WebSocket实时通信技术
熟悉语音识别和合成的技术细节
高级功能开发：
集成更多AI引擎，如情感分析、知识图谱等
开发自定义的动作和表情系统
实现多数字人协同交互功能
系统优化提升：
优化系统性能，提升响应速度
增强安全性和稳定性
开发监控和运维工具
社区参与贡献：
参与开源社区，贡献代码和想法
分享使用经验和最佳实践
帮助完善文档和教程
ADH数字人系统代表了人机交互技术的一个重要发展方向。随着AI技术的不断进步，数字人将在更多场景中发挥重要作用，成为连接人与数字世界的桥梁。希望本教程能够帮助您更好地理解和使用ADH系统，创造出更多有价值的数字人应用。