5 步搭出语音助手：Dify 语音交互（STT / TTS）从 0 到 1 完整教程

5 步搭出语音助手：Dify 语音交互（STT / TTS）从 0 到 1 完整教程

【免费下载链接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.项目地址: https://gitcode.com/GitHub_Trending/di/dify

Dify 内置语音转文字（STT）和文字转语音（TTS）两条链路，配好语音模型后，你的应用就能听用户说话、也能开口回答。这篇 Dify 语音教程带你走通一条完整链路：从开启功能到接口调通，新手也能照着跑起来。

一、语音助手能帮你干什么

先说结果，这四类应用现在就能搭：

1. 🎙️ 语音客服：用户打电话或发语音，机器人听懂后直接语音答复。
2. 📝 口述转文字：开会、通勤时说话，自动落成可编辑的文字。
3. 🎧 有声化输出：把文章、问答内容自动念出来，做成播客式应用。
4. 🗣️ 无障碍交互：面向不擅长打字的用户，全语音完成一轮问答。

二、一次对话背后的语音链路

下面这张图就是一次完整语音对话的路径：用户在调试窗或 Web 页面点录音，音频上传后先交给识别（STT）模型转成文字，文字再进入你搭好的 LLM 应用生成回复，最后由合成（TTS）模型把回复变成音频流播回去。

整条链路上你只需要操心两处配置：识别模型和合成模型；中间的 LLM 应用本身，就是你平时搭的 Chat 或工作流应用。

三、五步搭出你的语音助手

1. 开启应用里的语音功能

• Chat 应用：应用编辑页 →「模型设置」→ 打开「语音转文字」开关，选供应商和识别模型；同一区域还有「文字转语音」开关。
• Chatflow / 工作流应用：画布 → 右上角「设置」→「特性」，同时配置语音转文字和文字转语音两项。

没打开开关，后面所有语音请求都会被直接拒绝，这是新手最常踩的第一坑。

2. 接入语音模型

「设置 → 模型供应商」里分别加两类模型：识别（语音转文字）和合成（文字转语音），填好对应供应商的 API Key 并保存。两类模型都要设为可用，缺哪个哪个环节就断。

3. 配置识别：格式与大小

识别请求只收音频类型，代码里实际接受 mp3、m4a、wav、amr、mpga 这几类容器，单个文件上限 30MB。录音前端时直接输出 MP3 或 WAV 最省事。

4. 配置合成：选音色

打开「文字转语音」开关后选择音色，不同供应商音色列表不一样。不指定音色时，系统默认取该模型音色列表里的第一个。建议先在调试窗逐个试听再定。

5. 两个接口联调跑通

用调试窗先点一遍录音和播放，再走 Web API 验证两条链路。两段调用分别对应识别与合成：

# 识别：上传录音拿文字 r = requests.post(f"{base}/audio-to-text", headers={"Authorization": f"Bearer {token}"}, files={"file": open("a.mp3", "rb")}) print(r.json()["text"]) # 合成：文字变音频，直接落盘播放 r = requests.post(f"{base}/text-to-audio", headers={"Authorization": f"Bearer {token}"}, json={"text": "你好，我是你的语音助手"}) open("out.mp3", "wb").write(r.content)

调试窗能录、能播，接口两条都返回 200，就算跑通了。

四、识别不准、发音机械、响应慢

识别不准

• 现象：关键词经常听错 → 原因：环境噪音大、语速过快 → 动作：录音端做降噪，或换一款口碑更好的识别模型对比同一录音。
• 现象：上传 OGG、FLAC 等文件直接被拒 → 原因：不在支持的容器列表里 → 动作：转成 MP3 或 WAV 再传。
• 现象：长录音末尾识别缺失 → 原因：采样率偏低或文件接近 30MB 上限 → 动作：压缩或截取后分次上传。

发音机械

• 现象：音色平淡、像机器朗读 → 原因：用了默认音色或该模型表现力有限 → 动作：换音色，或换一家 TTS 供应商试听对比。
• 现象：长段文字读起来气口不对 → 原因：一次性合成整段长文 → 动作：按句分片合成再拼接。

响应慢

• 现象：按完录音要等很久才有文字 → 原因：文件上传占大头 → 动作：前端先提示「正在听」，改善体感。
• 现象：合成音频迟迟不出 → 原因：供应商合成耗时 + 文本太长 → 动作：识别、合成各自选响应快的模型，把重的留给离线场景。

五、常见报错速查

以下错误码来自源码，出现时对照处理：

六、下一步

调试窗跑通后，把录音和播放组件搬进你自己的前端，就是一个完整的 Dify 语音助手。接下来可以去 Dify 官方文档的模型供应商章节，看看还能接哪些识别与合成模型。

【免费下载链接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.项目地址: https://gitcode.com/GitHub_Trending/di/dify