作者Maris5188在AI电商飞速发展的今天“高效交互”成为核心竞争力——用户不想再逐字打字描述购物需求“说一句话就能下单”成为新的体验痛点。我们在覆盖Web、公众号H5、微信小程序三端的智能电商对话平台灵机一物中通过两条并行技术路线完美落地语音输入功能实现了购物全流程的语音交互闭环。本文从产品需求出发拆解多端语音输入的核心技术选型、工程落地细节、代码实现及实战踩坑解决方案所有代码可直接复用适合前端、后端开发者参考助力快速落地类似语音交互功能。一、产品需求背景极简灵机一物支持用户通过自然语言完成购物全流程搜索、下单、查订单等后台数据显示微信H5端用户偏好语音输入Web端需具备实时音频能力为后续Voice-to-Voice铺路据此确定“一套架构两条路线”的技术方案。二、核心架构设计附完整流程图核心设计理念语音只是输入通道不渗透到下游业务逻辑。无论用户打字还是说话最终均转化为文字消息统一进入意图识别引擎再路由到对应智能体降低开发成本并保证多端体验一致。多端架构图可直接复制使用plain text┌─────────────────────────────────────────────────────────────────────┐│语音输入入口 ││ ││ ┌──────────────┐ ┌──────────────────┐ ┌──────────────────┐ ││ │ Web 端 │ │ 公众号 H5 端 │ │ 微信小程序端 │ ││ │ VoiceButton │ │ AudioDom 组件 │ │ allowVoice │ ││ │ (WavRecorder) │ │ (微信 JS-SDK) │ │ IM SDK 原生 │ ││ └──────┬───────┘ └────────┬─────────┘ └────────┬─────────┘ │└─────────┼─────────────────────┼─────────────────────────┼───────────┘│ │ │▼ ▼ ▼┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐│ WebSocket 实时流 │ │ 本地语音识别 │ │ IM SDK 内置 ││ PCM16 音频块 │ │ wx.translateVoice│ │ 语音消息处理 ││ on_audio_chunk │ │ → 文字结果 │ │ ││ on_audio_end │ │ → DOM 注入 │ │ │└────────┬─────────┘ └────────┬─────────┘ └────────┬─────────┘│ │ │└─────────────────────┼───────────────────────┘│▼┌──────────────────────┐│ 意图识别引擎 ││ IntentAnalyzer ││ (文字统一入口) │└──────────┬───────────┘│┌───────┬────────┼────────┬────────┐▼ ▼ ▼ ▼ ▼购物Agent 订单Agent 客服Agent 砍价Agent 试穿Agent三、技术落地两条路线完整实现附可复用代码路线一Web端——基于AudioWorklet的实时音频流Web端核心需求是“实时性”放弃已废弃的ScriptProcessorNode主线程运行易导致音频断裂选用AudioWorklet独立音频线程采样级处理不受UI影响。3.1录音采集WavRecorder工具类实现移植自OpenAI Realtime Console并适配增强完整调用流程plain textbegin(deviceId) //打开麦克风初始化AudioWorklet│├── getUserMedia() // 获取麦克风媒体流├── new AudioContext({ sampleRate: 24000 })├── 加载AudioWorklet模块(audio_processor)├── 创建AnalyserNode(FFT频谱分析, fftSize8192)└── 注册消息回调(chunk事件→累积→触发回调)│record(chunkProcessor, chunkSize) // 开始录音│└── AudioWorklet持续采集→process()方法每帧调用├── 检测是否有实际音频(跳过前导静音)├── 多声道数据分块├── Float32→Int16 PCM转换└── postMessage({mono, raw})→主线程回调│end() // 停止录音│├── 导出完整WAV文件├── 断开所有音频节点└── 停止媒体流关键设计跳过前导静音提升识别准确率、分块传输减少延迟。3.2音频编码PCM16核心代码可直接复制选择PCM16而非MP3/Opus核心优势零编码延迟、兼容主流STT服务、带宽可控24000Hz采样率每秒48KB。javascript// Float32 [-1.0, 1.0] → Int16 [-32768, 32767]floatTo16BitPCM(float32Array) {const buffer new ArrayBuffer(float32Array.length * 2);const view new DataView(buffer);for (let i 0; i float32Array.length; i) {const s Math.max(-1, Math.min(1, float32Array[i]));view.setInt16(i * 2, s 0 ? s * 0x8000 : s * 0x7FFF, true);}return new Int16Array(buffer);}3.3 WebSocket传输与后端处理Python代码利用Chainlit内置WebSocket实时上送音频块后端实现两个装饰器即可完成接收与识别pythonimport chainlit as clcl.on_audio_chunkasync def on_audio_chunk(chunk: cl.InputAudioChunk):逐块接收PCM16音频流if not cl.user_session.get(audio_buffer):cl.user_session.set(audio_buffer, bytearray())cl.user_session.get(audio_buffer).extend(chunk.data)cl.on_audio_endasync def on_audio_end():录音结束触发语音识别audio_buffer cl.user_session.get(audio_buffer)# 1. 拼装WAV头 PCM数据# 2. 调用STT服务(Whisper/Google Cloud Speech)# 3. 将识别文字作为消息处理text await stt_service.transcribe(audio_buffer)await on_message(cl.Message(contenttext))3.4频谱可视化与音频播放优化AudioAnalysis组件选用“voice”模式32Hz-2000Hz人声区间通过Canvas绘制实时波形WavStreamPlayer实现PCM16流式播放支持中断与文字对齐。路线二公众号H5端——微信JS-SDK语音识别规避Web Audio API在微信内置浏览器的限制选用微信JS-SDK贴合用户习惯且识别准确率更高。3.1 AudioDom组件一站式解决方案JS-SDK初始化防重复跨组件存活plain text页面加载│├── 检查globalWxInitialized(模块级变量防重复初始化)│├── fetch(/api/wechat/config?url当前URL)│ └── 获取appId, timestamp, nonceStr, signature│├── 动态加载jweixin-1.6.0.js(主CDN备用CDN)│└── wx.config({jsApiList: [startRecord, stopRecord, translateVoice]})├── wx.ready() → globalWxConfigStatus success└── wx.error() → 重试(最多3次, 指数退避, 单次5s超时)3.2用户交互流程与录音动效plain text1.用户按住录音键 → wx.startRecord()设置60秒最大录音2. 用户松开 → wx.stopRecord() → 回调localId微信本地音频标识3. 调用微信语音识别 → wx.translateVoice({localId, isShowProgressTips: 1})4. 识别结果注入输入框 → 操作DOM触发自定义事件5. MessageComposer监听事件 → 防抖→onSubmit(text) → 进入标准流程录音动效核心代码模拟真实波形javascriptconst drawBars () {bars.forEach((bar, i) {const envelope Math.sin(time * bar.speed bar.phase);const height baseHeight envelope * bar.amplitude * maxHeight;//绘制圆角矩形适配UI风格});};路线三微信小程序端——一行配置启用javascriptagentConfig: {allowVoice: true, //展示语音按钮allowWebSearch: true,allowUploadFile: true,allowUploadImage: true,// ...其他配置}四、多语言适配配置化实现19种语言适配通过Chainlit翻译文件配置无需修改代码json{speech: {start: 开始录音,stop: 停止录音,connecting: 连接中}}五、实战踩坑4个关键问题及解决方案重点坑1AudioWorklet多线程通信不确定性问题postMessage异步通信无法确定操作是否执行完成。解决方案事件回执机制核心代码片段javascript//主线程发送事件_event(name, data) {const id this._lastEventId;this.processor.port.postMessage({ event: name, id, data });return new Promise((resolve) {const check setInterval(() {if (this.eventReceipts[id]) {resolve(this.eventReceipts[id].data);delete this.eventReceipts[id];clearInterval(check);}}, 10);setTimeout(() reject(), this.eventTimeout);});}坑2微信JS-SDK重复初始化问题React组件重挂载导致脚本重复加载、config:fail。解决方案模块级全局变量控制仅初始化一次。坑3语音识别结果无法注入React输入框问题直接操作DOM被React虚拟DOM diff覆盖。解决方案双保险注入javascriptconst nativeInputValueSetter Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype, value).set;nativeInputValueSetter.call(inputElement, text);inputElement.dispatchEvent(new Event(input, { bubbles: true }));window.dispatchEvent(new CustomEvent(audio-recognition-complete, { detail: { text } }));坑4采样率不统一导致识别准确率下降问题前端、传输、后端采样率不一致语音变调无报错。解决方案全局配置24000Hz采样率Chainlit配置WavRecorder默认统一。六、数据流全景与设计原则数据流图完整可复制plain text┌─────────────┐│用户说话 │└──────┬──────┘│┌──────────────────────┼──────────────────────┐│ │ │▼ ▼ ▼┌───────────┐ ┌─────────────┐ ┌─────────────┐│ Web 端 │ │ 公众号 H5 │ │ 微信小程序 ││ │ │ │ │ ││ getUserMedia │ wx.start- │ │ IM SDK ││ AudioWorklet │ Record() │ │ 原生语音 ││ PCM16 分块 │ │ │ │ │└─────┬─────┘ └──────┬──────┘ └──────┬──────┘│ │ │▼ ▼ │┌───────────┐ ┌─────────────┐ ││ WebSocket │ │ wx.translate│ ││ 流式传输 │ │ Voice() │ │└─────┬─────┘ └──────┬──────┘ ││ │ │▼ │ │┌───────────┐ │ ││ 服务端 STT │ │ ││ Whisper/ │ │ ││ Google ASR │ │ │└─────┬─────┘ │ ││ │ │▼ ▼ ▼┌──────────────────────────────────────────────────────┐│ 文字消息 │└───────────────────────┬──────────────────────────────┘│▼┌─────────────────┐│ IntentAnalyzer ││ 意图识别引擎 │└────────┬────────┘│┌───────┬───────┼───────┬────────┐▼ ▼ ▼ ▼ ▼购物 订单 客服 砍价 试穿Agent Agent Agent Agent Agent三条可复用设计原则语音只是输入通道不渗透业务层一套架构两条路线Web实时、微信原生配置化而非代码化提升迭代效率。技术栈Chainlit FastAPI LangGraph Web Audio API 微信JS-SDK项目灵机一物 — 智能电商代理协作平台作者Maris5188