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

用户说完话，几秒后就能听到 AI 用自然语调回答，这是你在 Dify 上可以跑通的效果。Dify 是一个开源的 Agentic 工作流开发平台，语音转文字（STT）与文字转语音（TTS）能力已内置于应用体系中。按本文操作，约 30 分钟可从克隆仓库走到听到第一句语音回复。

📋 能力边界速览

先对齐预期，避免配置到一半发现能力不在：

功能项	开箱即用？	需手动配置	备注
语音转文字（STT）	部分	配置语音识别模型 + 应用内开启功能开关	仅接受 mp3、m4a、wav、amr、mpga 五种格式，单文件上限 30MB
文字转语音（TTS）	部分	配置 TTS 模型 + 选择音色	返回音频流，具体音频格式取决于所选模型
控制台语音输入	是（配置好模型后）	无	应用对话页自动出现语音入口
Service API 调用	是	创建应用 API 密钥	走`/v1/apps/{app_id}/audio-to-text`与`/text-to-audio`
实时流式对话	否	—	当前为文件上传方案，不支持边说边传
多模型切换	是	在模型管理页改默认模型	更换提供商不改代码，即时生效

⏱ 最短可用路径

以下是从克隆仓库到听到第一句语音回复的最短步骤，共 5 步：

克隆仓库并启动全部服务（docker/docker-compose.yaml 定义了整个部署栈）：

git clone https://gitcode.com/GitHub_Trending/di/dify cd dify/docker docker compose up -d

浏览器打开http://localhost/install，完成初始化并创建管理员账号。
在「模型管理」页添加一个支持语音的提供商（如 OpenAI）的 API 密钥，并将其设为语音转文字、文字转语音两类的默认模型。
新建一个 Chatbot 或 Workflow 应用，在「功能设置」中开启语音转文字与文字转语音，并为 TTS 选一个音色。
用 curl 调用下面两个接口各验证一次，听到语音回复即打通全链路。

Dify 可视化编辑器中配置语音功能

🔍 核心机制拆解

语音转文字

输入：客户端上传的音频文件，格式限 mp3、m4a、wav、amr、mpga，大小不超过 30MB。
处理：服务端读取音频字节流，交给当前工作空间的默认语音识别模型执行识别。
输出：语音对应的纯文本，随后进入 LLM 或工作流节点。

主要提供商与模型对照：

提供商	模型	延迟特征	适用语言
OpenAI	whisper-1	中等	90 种以上
Azure	Speech 服务（whisper 系列）	较低，企业级稳定	多语言
Google	Speech-to-Text	较低，支持流式输入	多语言
Groq	whisper-large-v3-turbo	低，推理快	多语言
阿里云	Paraformer	较低，中文优化	中文为主

服务端核心逻辑在 api/services/audio_service.py，格式校验、大小限制与模型调用都在这里。

避坑提醒

⚠️ 音频超过 30MB 或格式不在白名单 → 上传前先压缩或转成 mp3 / wav ⚠️ 调接口报「语音转文字未启用」 → 回应用「功能设置」把 speech to text 开关打开，不启用该功能接口直接报错 ⚠️ 中文识别准确率偏低 → 把默认 STT 模型换为 Paraformer 等中文优化模型

文字转语音

输入：待合成的文本（通常就是 LLM 生成的回答），以及可选的音色参数。
处理：服务端调用默认 TTS 模型；未显式指定音色时，自动取该模型音色列表的第一个。
输出：音频流响应，Content-Type 由服务端根据音频内容自动判定，客户端按流播放即可。

提供商	模型	延迟特征	适用语言
OpenAI	tts-1（alloy / echo / nova / shimmer 四种音色）	中等	多语言
Azure	Neural TTS（数百种音色）	较低	多语言
Google	Cloud TTS	较低	多语言
国内提供商（硅基流动、火山等）	各自 TTS 模型	较低	中文为主

避坑提醒

⚠️ 音色不符合预期 → 在功能设置里显式指定 voice，不要依赖「取第一个音色」的默认行为 ⚠️ 拿到的音频文件无法播放 → 先查响应 Content-Type，容器格式（mp3 / ogg 等）随模型变化，别写死扩展名

🎧 一个完整案例走通

以电商售后客服机器人为例，按时间线走一遍。用户说：「我的订单到哪了？」

0–1s：客户端把这段录音 POST 到/v1/apps/{app_id}/audio-to-text（Service API 需携带应用 API 密钥）。
1–3s：默认 STT 模型把语音转成文本，工作流进入后续节点。
3–5s：LLM 节点结合知识库（RAG，基于文档检索增强生成）检索订单物流信息并生成回答。
5–7s：回答文本送入 text-to-audio 接口，TTS 模型合成语音，客户端播放。

用户听到「您的订单预计明天送达」。注意这是文件上传方案：整段录音传完才识别，不是实时链路。

两个关键接口的最小调用（密钥换成自己的）：

curl -X POST "http://localhost/v1/apps/your-app-id/audio-to-text" \ -H "Authorization: Bearer app-xxxxxx" \ -F "file=@question.wav"

curl -X POST "http://localhost/v1/apps/your-app-id/text-to-audio" \ -H "Authorization: Bearer app-xxxxxx" \ -H "Content-Type: application/json" \ -d '{"text": "您的订单预计明天送达。"}' \ --output reply.mp3

接口定义见 api/controllers/service_api/app/audio.py。

📊 性能与稳定性

指标	健康范围	触发动作
STT 往返耗时	< 3s	检查提供商延迟与音频文件大小
TTS 出声耗时	< 2s	精简文本或换低延迟模型
音频接口错误率	< 1%	核查提供商密钥配额与网络
超 30MB 音频占比	< 5%	前端加压缩，避免打满上限