本教程面向想在本地搭建一个可语音交互的 Live2D 数字人、并让对话、语音识别、语音合成全链路统一使用 DeepSeek APP API 的读者。教程以 Awesome Digital Human(ADH)v3 开源项目为基础,完成本地部署、新增 DeepSeek ASR/TTS 引擎、接入 DeepSeek APP API(全家桶应用 API)、使用官方默认人物与背景,并验证唤醒词等定制功能。
前置教程
如想快速开始学习本教程,你可能需要先完成以下前置教程:
- 大语言模型LLM服务商Api服务调用教程,本教程通过 OpenAI 兼容协议调用 DeepSeek APP API,前置教程介绍 API 调用的通用方法。
- OpenAI兼容API的概念与用法详解,ADH 的 OpenAI Agent 依赖 OpenAI 兼容接口,前置教程解释 base_url、model、api_key 三个参数的含义。
资源下载
- ADH v3 + DeepSeek 定制版示例代码与运行素材包,包含后端、前端源码、官方 Live2D 角色/背景/VAD 素材、关闭思考开关与 inert 警告修复脚本,解压后按本教程安装依赖并配置密钥即可运行。
1. 认识 ADH 与 DeepSeek APP API
1.1 ADH v3 的组成
Awesome Digital Human(ADH)是一个开源的 Live2D 数字人项目,v3 版本由三部分构成:FastAPI 后端负责语音识别(ASR)、语音合成(TTS)与对话 Agent 的调度;Next.js 前端负责 Live2D 模型渲染与交互;Live2D 角色素材提供人物形象与口型动作。后端默认端口 8880,前端开发模式端口 3000。
Live2D 渲染] FE --> BE[FastAPI 后端
8880] BE --> ASR[DeepSeek ASR
/tools/asr] BE --> TTS[DeepSeek TTS
/tools/tts] BE --> Agent[OpenAI Agent] Agent --> DS[DeepSeek APP API
deepseek-flash] ASR --> DS TTS --> DS style User fill:#e8f4f8,stroke:#1a6b8a style FE fill:#d6eaf8,stroke:#2980b9 style BE fill:#ffecd6,stroke:#b7950b style ASR fill:#d5f5e3,stroke:#27ae60 style TTS fill:#d5f5e3,stroke:#27ae60 style Agent fill:#fadbd8,stroke:#c0392b style DS fill:#ebdef0,stroke:#8e44ad
1.2 DeepSeek APP API(全家桶应用 API)
2026 年 11 月 13 日 DeepSeek 宣布开放 DeepSeek APP API("全家桶应用 API"),把 App 与网页端的完整对话体验通过 API 全量开放,V4.1-Flash 模型(调用名 deepseek-flash)在 Chat Completions 等接口下支持联网搜索、深度思考、文件输入等能力,Search、Fetch、OCR、ASR、TTS 五项底层能力各自提供独立接口(详见行业资讯)。
ADH 的 OpenAI Agent 使用标准 Chat Completions 协议,与 DeepSeek 的 OpenAI 兼容接口直接对接,只需三个参数:base_url 填 https://api.deepseek.com/v1,model 填 deepseek-flash,api_key 填你的 DeepSeek Key。deepseek-flash 默认带深度思考,ADH 会把思考过程以 THINK 事件流式展示,回复正文以 TEXT 事件下发;思考可通过 enable_thinking 开关关闭(见 4.6)。
2. 环境准备
2.1 Python 后端环境
# 创建虚拟环境
conda create -n adh python=3.10
# 激活虚拟环境
conda activate adh
# 安装依赖
pip install -r requirements.txt
依赖中 fastapi、uvicorn 提供后端服务,openai 用于调用 DeepSeek 兼容接口,pydub 用于 ASR 的 mp3→WAV 转换,edge-tts 提供免费的 TTS 备选引擎,python-dotenv 读取 .env 配置。
2.2 前端环境
前端使用 Next.js 15 + HeroUI,包管理器用 pnpm,建议安装 9.x 以避免锁文件兼容问题:
npm install -g pnpm@9
node --version
3. 本地部署 ADH
ADH 本质是 FastAPI 后端加 Next.js 前端两个服务。
3.1 启动后端
python main.py
main.py 自动读取根目录 .env,加载 configs/config.yaml(不存在时回退 config_template.yaml),在 8880 端口启动。看到 Uvicorn running on http://0.0.0.0:8880 即启动成功。
3.2 启动前端
cd web
pnpm install
pnpm run dev
浏览器访问 http://localhost:3000,自动跳转到 /sentio 数字人页面。前端通过 web/.env 的 NEXT_PUBLIC_SERVER_PORT="8880" 连接后端。
4. 接入 DeepSeek APP API
4.1 统一默认引擎为 DeepSeek
ADH 通过 configs/config.yaml 覆盖模板配置。把对话 Agent、ASR、TTS 三个默认引擎统一指向 DeepSeek:
# configs/config.yaml
SERVER:
IP: "0.0.0.0"
PORT: 8880
ENGINES:
ASR:
SUPPORT_LIST: [ "deepseekAPI.yaml", "cozeAPI.yaml", "tencentAPI.yaml"]
DEFAULT: "deepseekAPI.yaml"
TTS:
SUPPORT_LIST: [ "deepseekAPI.yaml", "edgeAPI.yaml", "tencentAPI.yaml", "cozeAPI.yaml" ]
DEFAULT: "deepseekAPI.yaml"
AGENTS:
SUPPORT_LIST: [ "repeaterAgent.yaml", "openaiAPI.yaml", "difyAgent.yaml", "fastgptAgent.yaml", "cozeAgent.yaml" ]
DEFAULT: "openaiAPI.yaml"
4.2 配置 DeepSeek 参数
configs/agents/openaiAPI.yaml 的 PARAMETERS 默认值会暴露给前端作为初始配置。把三个参数默认值改为 DeepSeek:
# configs/agents/openaiAPI.yaml(PARAMETERS 节选)
- name: "model"
default: "deepseek-flash"
- name: "base_url"
default: "https://api.deepseek.com/v1"
- name: "api_key"
default: "你的DeepSeek-API-Key"
将 你的DeepSeek-API-Key 替换为你在 DeepSeek 开放平台申请的 Key。示例代码中该处为占位符,不含真实密钥。
4.3 验证 API 连通
先用 curl 直接验证 Key 与模型可用(请求体保存为 UTF-8 文件 ds-test.json):
curl -s https://api.deepseek.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 你的DeepSeek-API-Key" \
--data-binary @ds-test.json
返回 choices[0].message.content 即连通。再验证 ADH 后端推理接口(SSE 流式):
curl -s -N -X POST http://127.0.0.1:8880/adh/agent/v0/engine \
-H "Content-Type: application/json" -H "user-id: tester" \
--data-binary @infer-test.json
依次收到 CONVERSATION_ID、THINK(思考流)、TEXT(回复流)事件,说明 ADH 已成功经 OpenAI Agent 调用 DeepSeek。完整请求体见 adh/test 目录与示例配置。
4.4 新增 DeepSeek ASR/TTS 引擎
官方 ADH 自带 Dify/Coze/腾讯等 ASR/TTS 引擎,但没有 DeepSeek 的。本示例新增两个引擎,对接全家桶独立接口:
| 引擎 | 文件 | 接口 | 说明 |
|---|---|---|---|
| DeepSeek ASR | digitalHuman/engine/asr/deepseekASR.py |
POST /v1/tools/asr |
multipart file 字段,仅收 16 位 PCM WAV/Ogg Opus,返回 text |
| DeepSeek TTS | digitalHuman/engine/tts/deepseekTTS.py |
POST /v1/tools/tts |
JSON {text, voice_id, format},整段返回 WAV,音色 stella(女)/tide(男) |
两个引擎在各自 __init__.py 注册,配置见 configs/engines/asr/deepseekAPI.yaml 与 configs/engines/tts/deepseekAPI.yaml(base_url、api_key,TTS 另有 voice)。
ASR 有一个格式适配点:前端录音上传的是 mp3,而 DeepSeek ASR 只收 WAV/Ogg Opus,引擎内先用 mp3ToWav 转换再上传。TTS 返回 WAV,前端播放通过 decodeAudioData 按内容解码,可直接播放。
4.5 验证 ASR/TTS 闭环
先调 TTS 合成一段语音,再把得到的 WAV 交给 ASR 识别,验证全链路:
# TTS:返回 base64 WAV(data 字段),解码保存为 speech.wav
curl -s -X POST http://127.0.0.1:8880/adh/tts/v0/engine \
-H "Content-Type: application/json" --data-binary @tts-req.json
# ASR:把 speech.wav 以 base64 传入,返回识别文本
curl -s -X POST http://127.0.0.1:8880/adh/asr/v0/engine \
-H "Content-Type: application/json" --data-binary @asr-req.json
实测 TTS 合成"你好,我是希怡数字人,今天天气不错。"后,ASR 识别回"你好,我是西仪数字人,今天天气不错。";单独说"你好希怡"时则可能识别为"你好,西姨"。"希怡"被识别为同音的"西仪""西姨",这正是唤醒词需要同音容错的原因——wakeWord.ts 的同音归一(见 5.2)会把它们折叠回"希怡"再匹配。
4.6 关闭模型思考过程
deepseek-flash 默认开启思考,先输出思维链(THINK 事件)再给回答,会增加时延。数字人闲聊场景若只需快速回答,可以关闭思考。本示例在三个层面支持该开关:
- 配置:
configs/agents/openaiAPI.yaml新增布尔参数enable_thinking,默认true。 - 后端:
openaiAgent.py读取该参数,按 DeepSeek OpenAI 格式思考开关传入extra_body={"thinking": {"type": "enabled" 或 "disabled"}}。 - 前端:
params.tsx实现了布尔类型渲染,"AI智能体"页签出现enable_thinking开关,关闭即不输出思维链。
# configs/agents/openaiAPI.yaml(PARAMETERS 节选)
- name: "enable_thinking"
type: "bool"
default: true

实测同一问题"1+1等于几":开启思考时返回 23 个 THINK 事件加 TEXT 回答;关闭后 THINK 事件为 0,仅返回 TEXT,响应更快。前端"基础设置"里的"展示思考内容"只控制是否显示思维链,enable_thinking 才控制模型是否思考,二者独立。
5. 默认人物、背景与定制功能
5.1 官方默认人物与背景
前端默认人物与背景在 web/lib/constants.ts 中定义。官方默认人物为 HaruGreeter,官方默认不铺自定义背景图。本示例与官方一致:
// web/lib/constants.ts
export const SENTIO_CHARACTER_DEFAULT = "HaruGreeter"
export const SENTIO_BACKGROUND_DEFAULT = "" // 与官方一致:不铺自定义图
SENTIO_BACKGROUND_DEFAULT 置空时,appConfig.ts 通过 setBackground(null) 不铺背景图。
5.2 定制功能说明
本示例在官方 v3 基础上保留了以下定制,均已在浏览器实测:
| 定制 | 位置 | 说明 |
|---|---|---|
| 语音唤醒词 | web/lib/utils/wakeWord.ts、constants.ts |
沉浸模式下检测唤醒词,唤醒后 30 秒超时自动退出 |
| 隐藏头部组件 | web/app/(products)/sentio/components/header.tsx |
沉浸界面只保留右上角模式开关 |
| 模型 Y 轴调整 | web/lib/live2d/、constants.ts |
支持模型缩放与 Y 轴位置调节 |
唤醒词在 constants.ts 的 SENTIO_WAKE_WORDS 集中配置,本示例使用"希怡"及变体:
// web/lib/constants.ts
export const SENTIO_WAKE_WORDS: string[] = [
'希怡',
'熙怡',
'希仪',
'你好希怡',
'希怡你好',
'你好熙怡',
'你好希仪',
];
export const SENTIO_WAKE_TIMEOUT_DURATION = 30000; // 30秒
匹配前会去掉标点与空格,并做同音字归一:wakeWord.ts 把"西/熙/夕/曦/溪"折叠为"希"、"姨/仪/宜/谊/夷"折叠为"怡",因此 DeepSeek ASR 把"希怡"识别成"西姨""西仪""熙怡"等同音词时也能命中。唤醒仅在沉浸模式(右上角开关打开)下生效,默认对话模式不启用;唤醒后 30 秒无新语音自动退出。
5.3 前端配置入口与修改
前端自带完整配置界面,入口在右上角菜单按钮(沉浸开关旁),点击展开"设置"和"画廊"两项:

设置含四个页签:基础设置(声音开关、展示思考、唇形系数、模型缩放、Y 轴位置)、语音识别、语音合成、AI智能体。更换 API 服务商、模型、base_url、API Key 在"AI智能体"(对话)与"语音识别/语音合成"页签的引擎配置中修改;"AI智能体"页签还提供 enable_thinking 思考开关(见 4.6):

画廊含"角色/背景"两个页签,点击卡片即可切换人物模型与背景:

前端界面的修改保存在浏览器 localStorage,只对该浏览器生效;要改变所有用户的默认值,需修改后端
configs/与前端constants.ts(见 5.1)。
6. 运行验证
6.1 默认数字人页面
启动前后端后访问 http://localhost:3000/sentio,默认加载官方人物 HaruGreeter,底部为语音输入按钮,右上角为沉浸模式开关:

6.2 沉浸模式与唤醒词
打开右上角开关进入沉浸模式,底部出现唤醒状态指示器,未唤醒时显示"等待唤醒词"。说出唤醒词后指示器变绿进入唤醒状态,后续语音直接提交给 DeepSeek 对话:

7. 总结
7.1 核心内容回顾
- ADH v3 由 FastAPI 后端、Next.js 前端与 Live2D 素材组成,本地分别启动两个服务即可运行。
- 对话、ASR、TTS 全链路统一 DeepSeek:对话使用 OpenAI 兼容
deepseek-flash,ASR/TTS 使用全家桶独立接口/tools/asr、/tools/tts,不依赖 Dify。 - 新增 DeepSeek ASR/TTS 引擎需做格式适配:ASR 把前端 mp3 转 WAV,TTS 返回 WAV 供前端解码播放。
- 默认人物与背景在
constants.ts配置,官方默认为 HaruGreeter 与不铺背景图。 - 唤醒词、隐藏头部、Y 轴调整等定制功能集中在前端
lib与constants.ts;唤醒词含同音容错变体。
7.2 常见问题与解答
问:前端启动报 next 不是内部或外部命令?
答:node_modules 可能在其他平台安装、缺少 Windows 的 .cmd shim。删除 web/node_modules 后以 CI=true pnpm install 重装即可。
问:pnpm 安装提示 Aborted removal of modules directory due to no TTY?
答:设置环境变量 CI=true 再执行 pnpm install,允许其重建 node_modules。
问:调用 DeepSeek 返回 invalid unicode code point?
答:curl 直接传中文请求体时 shell 编码非 UTF-8。把请求体保存为 UTF-8 文件后用 --data-binary @文件 发送。
问:DeepSeek APP API 支持实时交互吗?
答:支持"准实时"的回合制交互。对话接口支持 SSE 流式输出,TTS 提供 WebSocket 流式合成(wss://api.deepseek.com/v1/tools/tts,可边生成边朗读),ASR 为整段识别(一次上传完整音频、返回完整文本)。ADH 沉浸模式用 VAD 断句后整段送 ASR,属于"说完一句即答即读"的准实时,本教程不引入流式 ASR 引擎。
问:说"你好希怡"数字人没反应?
答:先确认右上角开关已打开(唤醒仅沉浸模式生效)。其次 DeepSeek ASR 常把"希怡"识别为同音词(如"西姨"),本示例已在 wakeWord.ts 做同音字归一解决;若仍无反应,检查麦克风权限与 ASR 引擎是否返回文本。
问:开发模式左下角出现 inert 红色报错?
答:这是 HeroUI 内联的 getInertValue 走 react18 分支、在 React 19 下给 inert 传空字符串导致的开发警告。本示例通过 web/scripts/fix-inert.mjs 在 pnpm install 后(postinstall)自动将其改写为返回布尔值,警告即消除;若仍出现,删除 web/.next 缓存后重启。该警告不影响功能,生产构建不显示。
评论