当前位置：首页 > news >正文

SenseVoice-Small语音识别模型在Vue3项目中的实战应用

news 2026/3/26 19:10:10

SenseVoice-Small语音识别模型在Vue3项目中的实战应用

最近在做一个需要语音交互的前端项目，客户要求能实时把用户说的话转成文字，而且要快、要准。一开始考虑用云服务，但涉及到隐私和网络延迟问题，最终还是决定把模型直接放在前端跑。试了几个方案，最后用上了SenseVoice-Small这个轻量级语音识别模型，结合Vue3和WebAssembly，效果还挺让人惊喜的。

这篇文章，我就来分享一下我们是怎么在Vue3项目里，把SenseVoice-Small用起来的。整个过程从模型加载、音频采集，到实时识别和结果展示，我会把关键步骤和踩过的坑都讲清楚。如果你也在琢磨怎么给前端应用加个“耳朵”，让用户能直接说话操作，那这篇实战经验应该能帮到你。

1. 为什么选择前端语音识别？

在做技术选型的时候，我们主要考虑了三个方向：调用大厂的云端API、自建后端服务转发、或者直接把模型塞到浏览器里跑。各有各的优缺点。

云端API：像一些大厂提供的服务，开箱即用，识别率通常很高。但问题也很明显：第一是贵，按调用次数或时长收费，用户量一大成本就上去了；第二是延迟，音频数据要上传到云端，识别完再返回，网络不好的时候体验很差；第三是隐私，用户的语音数据要离开本地，有些敏感场景下客户不接受。
自建后端服务：自己搭服务器跑模型，可控性强，数据不出私域。但这意味着你要维护一套后端架构，要考虑模型推理的资源消耗、并发请求处理，开发量和运维成本都不低。
前端本地识别：模型直接下载到用户的浏览器里，录音、识别全在本地完成。最大的好处就是零网络延迟和绝对的数据隐私。用户说完话，文字几乎立刻就出来了，体验非常流畅。而且没有服务器成本，用户越多，边际成本越低。

当然，前端识别也有它的挑战，主要就是模型大小和计算性能。浏览器的资源是有限的，模型不能太大，不然下载慢、加载卡。SenseVoice-Small这个模型，就是专门为边缘设备和Web场景设计的，体积小巧，识别精度在轻量级模型里表现不错，正好契合我们的需求。

所以，如果你的应用场景对实时性和隐私要求高，并且你愿意在用户体验上做点投资（处理一下模型加载和兼容性），那么前端语音识别是个非常值得考虑的方案。

2. 项目环境搭建与核心思路

我们的技术栈很明确：Vue3 + TypeScript + Vite。Vue3的Composition API用起来很灵活，非常适合组织这种有复杂状态逻辑的语音识别功能。

首先，创建一个新的Vue3项目：

npm create vue@latest my-voice-app # 按照提示，选择TypeScript和必要的特性即可。 cd my-voice-app npm install

接下来，要安装处理音频和模型的核心依赖。SenseVoice-Small通常以ONNX格式提供，我们需要能在浏览器里运行ONNX模型的工具。

npm install onnxruntime-web

onnxruntime-web是微软推出的Web版ONNX运行时，它支持WebAssembly后端，能让我们在浏览器里高效地运行神经网络模型。

整个功能的核心思路可以拆解成一条清晰的流水线：

权限获取与音频采集：通过浏览器的getUserMediaAPI拿到麦克风权限，并获取原始的音频流（PCM数据）。
音频预处理：把原始音频流转换成模型需要的输入格式，比如特定的采样率（16kHz）、单声道，并可能需要进行分帧、加窗等处理。
模型加载与推理：使用onnxruntime-web加载提前转换好的SenseVoice-Small模型文件（.onnx）。将预处理后的音频数据送入模型，得到识别的结果（通常是字符或单词的概率序列）。
后处理与展示：将模型输出的“粗糙”结果，转换成通顺的句子或段落，并实时显示在Vue组件的界面上。

下面，我们就沿着这条流水线，看看具体代码怎么写。

3. 实现语音识别核心流水线

3.1 音频采集与预处理

我们创建一个Vue3的Composable函数useVoiceRecognition来封装所有逻辑，这样复用性会很好。

首先，处理麦克风权限和音频流捕获：

// composables/useVoiceRecognition.ts import { ref, onUnmounted } from 'vue'; export function useVoiceRecognition() { const isRecording = ref(false); const transcript = ref(''); // 识别出的文字 const error = ref<string | null>(null); let mediaStream: MediaStream | null = null; let audioContext: AudioContext | null = null; let processor: ScriptProcessorNode | null = null; // 注意：ScriptProcessorNode已废弃，但部分场景下简单演示可用。 // 生产环境建议使用AudioWorklet，但配置更复杂。 // 1. 请求麦克风权限并开始捕获 const startRecording = async () => { error.value = null; try { // 获取麦克风音频流 mediaStream = await navigator.mediaDevices.getUserMedia({ audio: true }); // 创建音频上下文 audioContext = new (window.AudioContext || (window as any).webkitAudioContext)(); const source = audioContext.createMediaStreamSource(mediaStream); // 创建处理器来获取原始音频数据 // 这里使用已废弃的ScriptProcessorNode仅作简单示例 processor = audioContext.createScriptProcessor(4096, 1, 1); source.connect(processor); processor.connect(audioContext.destination); // 当有音频数据块可用时，这个回调会被触发 processor.onaudioprocess = (event) => { const inputData = event.inputBuffer.getChannelData(0); // 获取单声道PCM数据 // 这里可以在这里对inputData进行预处理，然后送入识别队列 // 例如：convertAndSendToModel(inputData); }; isRecording.value = true; } catch (err) { error.value = `无法访问麦克风: ${err}`; console.error('麦克风访问错误:', err); } }; // 2. 停止录音 const stopRecording = () => { if (processor) { processor.disconnect(); processor = null; } if (mediaStream) { mediaStream.getTracks().forEach(track => track.stop()); mediaStream = null; } if (audioContext && audioContext.state !== 'closed') { audioContext.close(); audioContext = null; } isRecording.value = false; }; // 组件卸载时清理资源 onUnmounted(() => { stopRecording(); }); return { isRecording, transcript, error, startRecording, stopRecording, }; }

拿到PCM数据后，还需要预处理。SenseVoice-Small模型通常要求输入是特定采样率（如16kHz）、单声道的浮点数组。我们的onaudioprocess回调拿到的是浏览器默认采样率（通常是48kHz）的数据，所以需要重采样，并可能要做归一化。

3.2 模型加载与推理

这是最核心的一步。我们需要把模型文件（比如sensevoice-small.onnx）放在项目的public目录下，这样可以通过URL直接加载。

我们在Composable里增加模型加载和推理的逻辑：

// composables/useVoiceRecognition.ts (续) import * as ort from 'onnxruntime-web'; export function useVoiceRecognition() { // ... 之前的状态和音频捕获代码 ... let session: ort.InferenceSession | null = null; const isModelLoaded = ref(false); // 加载ONNX模型 const loadModel = async (modelUrl: string = '/models/sensevoice-small.onnx') => { try { // 配置ONNX Runtime Web，使用WebAssembly后端以获得最佳性能 ort.env.wasm.wasmPaths = 'https://cdn.jsdelivr.net/npm/onnxruntime-web@latest/dist/'; // 注意：实际项目中需要将wasm文件正确配置或托管 session = await ort.InferenceSession.create(modelUrl, { executionProviders: ['wasm'], // 指定使用WASM }); isModelLoaded.value = true; console.log('SenseVoice-Small 模型加载成功'); } catch (err) { error.value = `模型加载失败: ${err}`; console.error('模型加载错误:', err); } }; // 模拟推理函数（实际处理需要根据模型输入输出调整） const runInference = async (audioData: Float32Array): Promise<string> => { if (!session) { throw new Error('模型未加载'); } // 1. 将音频数据预处理成模型需要的形状，例如 [1, sequence_length, feature_dim] // 这里需要根据SenseVoice-Small模型的具体输入要求来写 // 可能包括：重采样到16kHz，提取MFCC或FBank特征等。 // 以下是一个高度简化的示例： const tensor = new ort.Tensor('float32', audioData, [1, audioData.length, 1]); // 2. 准备输入，输入名称需要查看模型信息确定 const feeds: Record<string, ort.Tensor> = { input: tensor }; // 'input' 是示例名称 // 3. 运行模型 const results = await session.run(feeds); // 4. 处理输出，输出名称也需要查看模型信息确定 // 假设输出名为'output'，且是字符概率 const outputTensor = results.output; const predictions = outputTensor.data; // 可能是Int32Array或Float32Array // 5. 将模型输出（如token ids）解码成字符串 // 这里需要一个解码器（Decoder），可能集成在模型中或需要单独处理 const decodedText = decodePredictions(predictions); // 这是一个需要你实现的函数 return decodedText; }; // 一个简单的解码示例占位函数 function decodePredictions(predictions: any): string { // 实际情况复杂得多，可能涉及CTC解码、语言模型融合等 console.log('收到模型原始输出:', predictions); return `[识别结果: ${predictions.length} 帧]`; // 占位 } // 在组件挂载时或用户点击时加载模型 // onMounted(() => { loadModel(); }); return { // ... 之前返回的状态和方法 ... isModelLoaded, loadModel, // 可能需要暴露一个触发推理的方法 }; }

重要提示：上面的runInference函数是高度简化的。真实集成SenseVoice-Small需要：

准确的输入输出名称：使用netron等工具打开.onnx模型文件，查看输入输出节点的确切名称。
完整的音频特征提取：模型接受的不是原始PCM，而是如FBank或MFCC的声学特征。你需要在前端实现或集成一个特征提取库（例如librosa.js的某些功能）。
复杂的解码器：语音识别模型输出通常是帧级别的字符或音素概率，需要CTC解码算法（如Beam Search）将其转换成合理的文字。这部分可能模型已集成，也可能需要额外处理。

3.3 构建Vue3组件

有了Composable，构建UI组件就很简单了。

<!-- components/VoiceRecorder.vue --> <template> <div class="voice-recorder"> <div v-if="error" class="error-message"> {{ error }} </div> <div class="controls"> <button @click="toggleRecording" :disabled="!isModelLoaded" :class="{ recording: isRecording }" > {{ isRecording ? '停止录音' : '开始录音' }} </button> <button @click="loadModel" :disabled="isModelLoaded"> {{ isModelLoaded ? '模型已加载' : '加载识别模型' }} </button> </div> <div class="status"> 模型状态: {{ isModelLoaded ? '就绪' : '未加载' }} 录音状态: {{ isRecording ? '进行中...' : '已停止' }} </div> <div class="transcript-box"> <h3>识别结果：</h3> <p>{{ transcript || '（等待语音输入...）' }}</p> </div> </div> </template> <script setup lang="ts"> import { useVoiceRecognition } from '@/composables/useVoiceRecognition'; const { isRecording, transcript, error, isModelLoaded, startRecording, stopRecording, loadModel } = useVoiceRecognition(); const toggleRecording = () => { if (isRecording.value) { stopRecording(); } else { startRecording(); } }; // 组件挂载时自动加载模型（可选） import { onMounted } from 'vue'; onMounted(() => { loadModel(); }); </script> <style scoped> .voice-recorder { padding: 20px; border: 1px solid #eee; border-radius: 8px; max-width: 600px; margin: 20px auto; } .controls button { margin-right: 10px; padding: 10px 20px; font-size: 16px; } .controls button.recording { background-color: #ff4444; color: white; } .error-message { color: red; margin-bottom: 15px; } .transcript-box { margin-top: 20px; padding: 15px; background-color: #f9f9f9; border-radius: 4px; min-height: 100px; } </style>

4. 性能优化与实践建议

把模型跑在浏览器里，性能是个绕不开的话题。这里有几个我们实践下来觉得有用的点：

模型量化：如果模型提供方有INT8量化版本的ONNX模型，一定要用。量化后的模型体积更小，加载更快，在WASM上推理速度也会有显著提升。
智能分块推理：不要等用户说一整段话才送进模型。可以设置一个缓冲区，比如每采集到1秒的音频（对应16000个采样点），就做一次特征提取和推理。这样能实现更低的“逐字”延迟感。但要注意处理好上下文连贯性，避免句子被切碎。
使用Web Worker：音频预处理和模型推理都是计算密集型任务，如果放在主线程，会阻塞UI响应，导致页面卡顿。可以把onnxruntime-web的推理过程放到Web Worker中，主线程只负责UI更新和音频数据传递。
缓存模型：模型文件可能有好几MB甚至十几MB。可以利用浏览器的Cache API或Service Worker对模型文件进行缓存，用户第二次访问时就不需要重新下载了，极大提升首次加载后的启动速度。
降级方案：虽然WASM兼容性已经很好，但还是要考虑极端情况。可以设计一个降级方案：如果WASM加载失败或推理速度过慢，自动切换为向后端发送音频流进行识别的模式，保证核心功能可用。