本教程面向想在本地搭建一个可语音交互的 Live2D 数字人、并让对话、语音识别、语音合成全链路统一使用 DeepSeek APP API 的读者。教程以 Awesome Digital Human(ADH)v3 开源项目为基础,完成本地部署、新增 DeepSeek ASR/TTS 引擎、接入 DeepSeek APP API(全家桶应用 API)、使用官方默认人物与背景,并验证唤醒词等定制功能。

前置教程

如想快速开始学习本教程,你可能需要先完成以下前置教程:

资源下载

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。

graph LR User[用户语音/文本] --> FE[Next.js 前端
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

设置-AI智能体页签的 enable_thinking 开关,红框为该开关,Key 已遮罩

实测同一问题"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):

设置-AI智能体页签,红框为 model/base_url/api_key 配置项,Key 已遮罩

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

画廊-角色页签,红框为角色/背景切换,当前选中 HaruGreeter

前端界面的修改保存在浏览器 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 缓存后重启。该警告不影响功能,生产构建不显示。