Dify.AI 语音助手：3步打通语音交互完整链路

Dify.AI 语音助手：3步打通语音交互完整链路

【免费下载链接】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.AI 语音助手解决的就是这个问题：录音转文字，LLM 生成回答，TTS 再把回答读出来。这条 Dify.AI 语音交互链路，跟着本文 3 步就能跑通。

能力全景：一张表看清语音链路

本节回答一个问题：Dify.AI 的语音功能到底覆盖哪些能力、边界在哪。

整条链路只有四个环节，声音进、文字出、文字出、声音出：

中间环节由应用本身完成：STT 把音频交给模型提供商转成文本，文本进入你配置的对话流或工作流，LLM 的输出再交给 TTS。整段逻辑集中在 api/services/audio_service.py，接口定义见 api/controllers/service_api/app/audio.py。

3步打通语音闭环：最小可行路径 🚀

本节给出跑通 Dify.AI STT 配置和 TTS 调用的最短路径。

第 1 步：添加语音模型提供商

• 做什么：在"模型提供商"里选择一个带语音能力的提供商（如 OpenAI），填入 API Key。
• 配什么：STT 用whisper-1，TTS 用tts-1之类的 TTS 模型。
• 注意什么：提供商若完全不支持语音模型，调用会直接报provider_not_support_speech_to_text，先确认模型列表。

第 2 步：打开应用功能开关

• 做什么：在应用的"功能"面板打开 speech_to_text 和 text_to_speech。
• 配什么：TTS 在这里选音色，比如alloy（中性）或nova（女性、更亲和）。
• 注意什么：开关没打开时，接口返回speech_to_text_disabled，这是新手最常见的报错。

第 3 步：两个接口验证闭环

# STT：上传录音，返回文本 curl -X POST "{base_url}/v1/apps/{app_id}/audio-to-text" \ -H "Authorization: Bearer {api_key}" -F "file=@demo.mp3" # TTS：提交文本，返回音频二进制 curl -X POST "{base_url}/v1/apps/{app_id}/text-to-audio" \ -H "Authorization: Bearer {api_key}" \ -H "Content-Type: application/json" \ -d '{"text":"你好，我是Dify语音助手","voice":"nova"}'

一个返回 JSON 文本，一个直接回音频字节流，Content-Type会标明具体容器格式。到这里，录音进、声音出的最小闭环已经成立。

场景实战一：语音客服——通话录音变工单

要解决什么：客服每天花大量时间人工听录音、手敲工单，既慢又容易漏信息。

怎么配：只开 STT 开关。把通话录音传给 audio-to-text，拿回文本后拼进你的 LLM 提示词，让它输出"问题摘要 + 处理建议"两个字段。需要回放某条历史语音回复时，不用重发文本，传消息 ID 即可：

# 回放某条消息的语音：传 message_id，无需重发 text curl -X POST "{base_url}/v1/apps/{app_id}/text-to-audio" \ -H "Authorization: Bearer {api_key}" \ -d '{"message_id":"<message_id>"}'

效果如何：3 分钟录音 10 秒变文字，客服只需核对字段，转写工作从人工变成接口调用。

场景实战二：内容创作——一句话出有声稿

要解决什么：做有声读物、视频口播时，配音是最耗时的环节。

怎么配：只开 TTS。Dify.AI TTS 音色选择的诀窍是：先查看当前提供商返回的音色列表，按性别和风格挑——中性通用选alloy，讲故事选fable，客服类选亲和感更强的nova；中文内容建议换用对中文优化的提供商，自然度差异明显。

效果如何：脚本交给 LLM 生成或人工写好，调 text-to-audio 拿到可播放的 MP3/AAC 流，直接进剪辑工具，单人一天能产出数小时配音量。

避坑清单：6个高频报错对照表 ⚠️

本节把真实接口会抛出的错误集中列出，报错时直接查表。

进阶与趋势

跑通最小闭环后，你可以往三个方向走：一是实时双向语音，把"上传整段文件"换成流式输入输出，做准实时的语音对话；二是音色个性化，用提供商的音色克隆能力让助手拥有专属声音；三是多语言实时转译，STT 识别一种语言、LLM 转译、TTS 用另一种语言读出来。

语音能力的源码入口（api/）、前端录音与播放组件（web/app/components/base/audio-btn/）和官方文档（docs/）都已就位。现在就拉下项目，按上面 3 步把你的第一个 Dify.AI 语音助手跑起来吧。

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