在 Dify 里搭了个客服助手，想加个按住说话的功能。聊天框旁边找了半天没有麦克风图标，翻文档才知道，语音输入不是默认开着的，得先接一个语音转文字的模型。

先配语音转文字的模型

语音输入背后是转写，先把录音变成文字，再交给大模型。要在模型供应商里配一家支持转写的服务并填好密钥，应用里才会出现录音入口。只配了对话模型不够，这两类是分开的，配错了怎么点都没反应。

浏览器不给麦克风，按钮就是摆设

首次点麦克风，浏览器会弹权限询问，点了拒绝之后就不再问，按钮看着能点，实际没反应。到地址栏左边的站点设置里把麦克风改回允许，刷新页面再试。系统层面也要看，笔记本的麦克风有没有被静音、有没有被别的软件独占。

  • 页面必须是加密连接或者本机地址，普通 http 下浏览器直接禁用麦克风。
  • 自建部署时，容器要能访问外部的转写接口，内网环境常卡在这一步。
  • 录音时间太长容易失败，切成短句分段发更稳。

格式这块也常出问题。浏览器录音输出的是网页常用的音频封装，交给转写接口前要确认对方支持这种格式。有的服务只吃固定采样率的单声道文件，直接丢过去会返回参数错误，看着像模型坏了，其实只是格式不对。转成常见的音频文件再传，成功率明显高一些。

自建还有一层：前面套了反向代理时，页面是加密连接，转写请求却被转到普通的后端地址，浏览器会当成混合内容拦掉，控制台里一串红字。把代理的转发规则和证书配好，录音按钮才会真的发出请求。

转出来不准怎么调

先排除环境噪音，再确认语言参数设的是中文。采样率和格式不匹配，识别率会明显下降，录音端最好统一成常见的音频格式。专业术语多的场景，转写结果要人工看一眼，别直接把错的词喂进知识库。

测试顺序建议倒过来：先用一段本地录好的音频直接调转写接口，确认模型通了，再回页面测麦克风。这样出问题时能立刻分清是模型没配好，还是权限没给。

这条链路里，模型、权限、网络三段任何一段断了，表现都是没反应。排查就按这三段顺序走，比反复重装快得多。