如何搭建 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/difyDify 语音助手能力的本质是把大模型应用的耳朵和嘴巴补齐用户上传一段录音Dify 先通过语音转文字STT模型识别成文本再交给 LLM 处理模型回复后再通过文字转语音TTS模型转成可播放的音频流返回。整个过程由两个核心 HTTP 接口支撑——POST /audio-to-text和POST /text-to-audio服务层统一收口在 api/services/audio_service.py。本文从一次真实请求的数据流讲起带你 3 步完成语音功能配置、用两个最小接口调通链路并附上硬限制与常见报错速查表。一次语音请求在 Dify 内部经历了什么先建立一个整体印象语音并不是独立系统而是挂在模型提供方体系上的两个外设。方向作用接口Web 应用侧依赖的模型类型语音 → 文字STT/ASR把用户上传的录音识别为文本POST /apps/{app_id}/audio-to-textspeech2text文字 → 语音TTS把文本合成音频流返回POST /apps/{app_id}/text-to-audiotts请求链路可以拆成 5 步前端把录音以multipart/form-data形式 POST 到audio-to-text字段名为file服务端校验 MIME 类型与 30MB 体积上限不合规直接抛错api/controllers/web/audio.pyAudioService._invoke_speech_to_text通过ModelManager.get_default_model_instance(model_typeSPEECH2TEXT)拿到租户配置的默认 ASR 模型并调用识别出的文本进入正常的 LLM 对话流程生成回复前端带着text或历史message_id调text-to-audioDify 用默认 TTS 模型合成音频Content-Type由返回字节自动嗅探api/core/base/tts/audio_mime.py。三步完成语音功能配置第 1 步在模型提供方中配置 STT 与 TTS 模型Dify 的语音能力不绑定某一家厂商而是在设置 → 模型提供方里选择任意支持speech2text/tts模型类型的供应商OpenAI、Azure、阿里云等填入 API Key 后该供应商下对应类型的模型即可被应用引用。代码里所有语音调用最终都走ModelManager.for_tenant(...).get_default_model_instance(...)也就是说——用哪个供应商、哪个模型完全由你在模型提供方里的默认配置决定供应商可用列表可在 api/core/model_manager.py 中找到。第 2 步在应用功能设置中打开开关并选声音基础对话/Agent 应用在功能设置里勾选语音转文字和文字转语音。开关状态实际存储在app_model_config的speech_to_text.enabled/text_to_speech.enabled字段中服务层每次调用前都会强制校验没开就抛SpeechToTextDisabledServiceError。Chatflow / 工作流应用同样在 features 面板启用配置存于workflow.features_dict并且可以额外指定text_to_speech.voice固定音色。Agent 应用发布后的 Agent 会以Agent Soul配置优先再与旧版AppModelConfig合并生效见 api/core/app/apps/agent_app/app_feature_projection.py。第 3 步选择音色可选调用 TTS 时若未显式传voiceDify 会向供应商查询get_tts_voices()并取列表第一个作为默认音色——所以不同供应商的默认声音不一样生产环境建议显式指定。两个最小可运行的接口示例STT上传录音拿文本import requests resp requests.post( https://your-dify/apps/app_id/audio-to-text, files{file: open(recording.mp3, rb)}, headers{Authorization: Bearer api_key}, ) print(resp.json()[text]) # 识别出的文字一句话解释把录音文件以file字段 POST 上去返回体里只关心text这一个字段。TTS文本变音频流import requests resp requests.post( https://your-dify/apps/app_id/text-to-audio, json{text: 你好我是语音助手, voice: nova}, headers{Authorization: Bearer api_key}, ) open(reply.mp3, wb).write(resp.content) # 直接落盘即可播放两个实用细节TTS 请求体支持传message_id代替textDify 会取出该条历史回复的内容来合成适合给任意历史消息配音的场景响应是二进制音频流前端可直接URL.createObjectURL(blob)交给audio播放。硬限制与报错速查表踩坑前先看这张表能省一半调试时间。项目限制/行为出处音频大小单文件30MB超出返回 413api/services/audio_service.py 中FILE_SIZE 30音频格式仅接受mp3 / m4a / wav / amr / mpga大小写不敏感MIME 需为audio/*api/constants/init.pyTTS 输出二进制音频流常见 MP3MIME 由内容自动嗅探audio_mime.py未传音频文件NoAudioUploadedError服务层校验功能未开启SpeechToTextDisabledErrorfeatures 开关校验没配 ASR/TTS 模型ProviderNotSupportSpeechToTextError/...TextToSpeech...ModelManager 找不到默认模型供应商 Key 未配置ProviderNotInitializeError凭证缺失额度用尽ProviderQuotaExceededError计费配额格式/体积不合规UnsupportedAudioTypeError/AudioTooLargeError入参校验把语音接进工作流ASR 工具节点除了应用级开关Dify 还提供内置 ASR 工具api/core/tools/builtin_tool/providers/audio/可以把语音转文字作为工作流里的一个独立节点使用输入一个audio_file参数下拉框列出租户全部可用 ASR 模型provider#model格式支持按节点选模型而不是全局默认输出识别文本供后续 LLM 节点消费。这意味着你可以在 Chatflow 里编排用户上传语音 → ASR 节点识别 → LLM 处理 → 回复的自定义管线灵活度高于纯应用级开关。实战搭一个会听会说的客服机器人目标场景用户对着浏览器说话机器人听懂、回答并开口复述。整体只有四件事建应用创建 Chat 应用功能设置里同时开启 STT 与 TTSTTS 选一个偏友好的音色前端录音用浏览器MediaRecorder录一段产出Blob两段式调用先audio-to-text拿文本再走正常聊天流程得到回复最后把回复文本 POST 给text-to-audio播放失败兜底按前面速查表映射错误——413 提示用户压缩录音、格式错提示换 mp3、ProviderQuotaExceeded提示额度不足。前端最小闭环伪代码核心就三次请求// 1) 录音上传识别 const text await (await fetch(/apps/${appId}/audio-to-text, { method: POST, body: formData, headers: authHeaders, })).json().then(r r.text); // 2) 正常对话拿回复 answer省略 // 3) 回复配音并播放 const blob await fetch(/apps/${appId}/text-to-audio, { method: POST, body: JSON.stringify({ text: answer }), headers: { ...authHeaders, Content-Type: application/json }, }).then(r r.blob()); new Audio(URL.createObjectURL(blob)).play();性能上两个小建议长录音先在前端压缩到 30MB 以内再上传TTS 对历史消息按需配音传message_id而不是每次全量合成能明显省供应商额度。常见问题排查Q1识别结果和录音对不上先确认录音格式在支持列表内ogg、flac 这类并不在audio/*校验白名单里、采样率正常再检查你配置的是不是默认 ASR 模型——工作流 ASR 节点里可以显式换模型对比。Q2调 TTS 报 TTS is not enabled说明该应用的text_to_speech.enabled没开。Chatflow 应用要改工作流 features基础应用要改功能设置两者存的地方不一样。Q3换语言后声音不对或识别差音色与语言支持取决于具体供应商模型建议按目标语言选择对应模型并显式指定voice避免落到供应商默认值。Q4想做成实时语音对话怎么办Dify 当前接口是上传文件 → 返回文本/音频的请求-响应模式不是双向实时流。实时对话可以前端做 VAD 断句 高频短请求或基于 SSE/WebSocket 自行封装长连接属于应用层方案。写在最后Dify 语音交互的设计思路很克制不自己造识别/合成轮子而是把 STT/TTS 抽象成模型类型交给你在模型提供方里自由选供应商再用应用级开关 工作流工具两种粒度暴露出来。对开发者而言要做的只有三件事——配模型、开开关、调两个接口。后续如果供应商侧新增情感化合成、语音克隆等能力也都会自动透传到这一套接口里无需改动业务代码。【免费下载链接】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辅助生成（AIGC），仅供参考