SenseVoice-small部署教程WSL2子系统Windows本地开发环境完整搭建1. 前言为什么要在本地部署语音识别如果你正在寻找一个能在自己电脑上离线运行的语音识别工具那么你来对地方了。今天我要分享的是如何在Windows电脑上通过WSL2子系统完整搭建SenseVoice-small语音识别服务的本地开发环境。你可能会有疑问现在在线语音识别服务那么多为什么还要费劲在本地部署呢原因其实很简单隐私与安全你的会议录音、客户对话、医疗咨询等敏感语音数据完全不需要上传到云端在本地就能处理。离线可用没有网络也能用出差、户外、网络不稳定的地方随时都能把语音转成文字。成本可控一次部署长期使用没有按次计费没有API调用限制。定制灵活你可以根据自己的需求调整参数甚至基于这个模型进行二次开发。SenseVoice-small是一个轻量级的多任务语音模型特别适合在资源有限的设备上运行。它支持50多种语言包括中文、英文、日文、韩文、粤语等还能识别说话人的情感。最重要的是它提供了ONNX量化版本这意味着它能在没有GPU的普通电脑上流畅运行。接下来我会手把手带你完成整个部署过程从WSL2环境配置到服务启动每一步都有详细的说明和代码示例。即使你之前没接触过Linux也能跟着教程顺利完成。2. 环境准备安装WSL2和Ubuntu2.1 什么是WSL2WSL2Windows Subsystem for Linux 2是微软在Windows 10/11上提供的Linux子系统。简单来说它让你能在Windows里运行一个完整的Linux系统而且性能接近原生Linux。对于我们部署AI应用来说WSL2有几个明显优势直接使用Linux环境很多AI工具和库在Linux上支持更好文件系统互通Windows和Linux的文件可以互相访问资源占用合理比虚拟机更轻量启动更快开发体验统一可以用Windows的编辑器在Linux环境里运行代码2.2 安装WSL2和Ubuntu打开Windows PowerShell以管理员身份运行依次执行以下命令# 启用WSL功能 dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart # 启用虚拟机平台功能 dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart # 重启电脑必须步骤 # 重启后继续下面的步骤 # 设置WSL2为默认版本 wsl --set-default-version 2 # 安装Ubuntu 22.04 LTS长期支持版本更稳定 wsl --install -d Ubuntu-22.04安装过程中系统会提示你创建Linux用户名和密码。记住这个密码后续sudo命令需要用到。安装完成后你可以在开始菜单找到Ubuntu并打开或者直接在PowerShell中输入wsl进入Linux环境。2.3 配置WSL2基础环境第一次进入Ubuntu我们先做一些基础配置# 更新软件包列表 sudo apt update # 升级已安装的包 sudo apt upgrade -y # 安装常用工具 sudo apt install -y curl wget git vim htop net-tools # 设置时区选择亚洲/上海 sudo timedatectl set-timezone Asia/Shanghai # 查看WSL版本确认安装成功 wsl --version如果看到WSL版本信息说明安装成功。现在你有了一个完整的Linux开发环境接下来我们开始安装Python和必要的依赖。3. 安装Python和项目依赖3.1 安装MinicondaPython环境管理虽然Ubuntu自带Python但我们推荐使用Miniconda来管理Python环境这样可以避免系统Python的版本冲突。# 下载Miniconda安装脚本 wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh # 运行安装脚本 bash Miniconda3-latest-Linux-x86_64.sh # 按照提示按Enter阅读协议然后输入yes同意 # 安装位置使用默认的/home/你的用户名/miniconda3 # 最后输入yes让conda初始化shell # 关闭并重新打开终端或者运行 source ~/.bashrc # 验证安装 conda --version3.2 创建专门的Python环境我们为SenseVoice创建一个独立的Python环境避免与其他项目冲突# 创建名为sensevoice的Python环境使用Python 3.9 conda create -n sensevoice python3.9 -y # 激活环境 conda activate sensevoice # 验证Python版本 python --version # 应该显示 Python 3.9.x # 升级pip pip install --upgrade pip3.3 安装PyTorch和相关依赖SenseVoice-small基于PyTorch我们需要安装适合CPU运行的版本因为WSL2默认不直接支持GPU# 安装PyTorch CPU版本2.0.0版本兼容性较好 pip install torch2.0.0 torchvision0.15.0 torchaudio2.0.0 --index-url https://download.pytorch.org/whl/cpu # 安装ONNX Runtime用于运行量化模型 pip install onnxruntime # 安装其他必要依赖 pip install numpy pandas scipy pip install flask gradio # Web界面框架 pip install soundfile librosa # 音频处理 pip install transformers # 可能需要的模型加载工具 # 验证安装 python -c import torch; print(fPyTorch版本: {torch.__version__}) python -c import onnxruntime; print(fONNX Runtime版本: {onnxruntime.__version__})4. 下载和配置SenseVoice-small模型4.1 下载模型文件SenseVoice-small的ONNX量化版本已经预先转换好我们可以直接从仓库下载# 创建项目目录 mkdir -p ~/sensevoice-project cd ~/sensevoice-project # 下载模型文件这里以示例仓库为例实际可能需要从官方渠道获取 # 假设模型文件存放在某个公开位置 wget https://example.com/models/sensevoice-small-onnx-quant.zip # 解压模型文件 unzip sensevoice-small-onnx-quant.zip -d models/ # 或者使用git克隆如果提供git仓库 # git clone https://github.com/username/sensevoice-small-onnx.git models/如果模型文件较大下载可能需要一些时间。你也可以考虑从其他镜像源下载或者使用已有的模型文件。4.2 准备项目代码我们需要一个Web界面来使用这个语音识别服务。这里我提供一个简单的Gradio应用示例创建app.py文件import gradio as gr import numpy as np import soundfile as sf import onnxruntime as ort import tempfile import os from pathlib import Path class SenseVoiceRecognizer: def __init__(self, model_path): 初始化语音识别器 self.model_path model_path self.session None self.load_model() def load_model(self): 加载ONNX模型 try: # 创建ONNX Runtime会话 providers [CPUExecutionProvider] # 使用CPU执行 self.session ort.InferenceSession( self.model_path, providersproviders ) print(f模型加载成功: {self.model_path}) print(f输入名称: {[input.name for input in self.session.get_inputs()]}) print(f输出名称: {[output.name for output in self.session.get_outputs()]}) except Exception as e: print(f模型加载失败: {e}) raise def preprocess_audio(self, audio_path, target_sr16000): 预处理音频文件 # 读取音频文件 audio, sr sf.read(audio_path) # 转换为单声道 if len(audio.shape) 1: audio np.mean(audio, axis1) # 重采样到目标采样率 if sr ! target_sr: # 简单的重采样实现实际项目中建议使用librosa.resample import scipy.signal as sp num_samples int(len(audio) * target_sr / sr) audio sp.resample_poly(audio, target_sr, sr) # 归一化 audio audio / np.max(np.abs(audio)) if np.max(np.abs(audio)) 0 else audio return audio.astype(np.float32) def recognize(self, audio_path, languageauto): 执行语音识别 try: # 预处理音频 audio_data self.preprocess_audio(audio_path) # 准备模型输入这里需要根据实际模型调整 # 假设模型输入需要特定形状 input_name self.session.get_inputs()[0].name # 这里需要根据实际模型调整输入数据的形状 # 例如如果模型期望的是(1, sequence_length)的形状 audio_input np.expand_dims(audio_data, axis0) # 运行推理 outputs self.session.run(None, {input_name: audio_input}) # 处理输出这里需要根据实际模型调整 # 假设第一个输出是文本 text_result outputs[0] # 简单的后处理如果是numpy数组转换为字符串 if isinstance(text_result, np.ndarray): # 这里需要根据实际输出格式解码 # 假设输出是字符索引 text .join([chr(int(x)) for x in text_result.flatten() if x 0]) else: text str(text_result) return { text: text, language: language, status: success } except Exception as e: return { text: f识别失败: {str(e)}, language: language, status: error } def create_web_interface(model_path): 创建Web界面 # 初始化识别器 recognizer SenseVoiceRecognizer(model_path) def process_audio(audio_file, language): 处理音频文件 if audio_file is None: return 请先上传或录制音频文件, result recognizer.recognize(audio_file, language) if result[status] success: details f语言: {result[language]}\n状态: 识别成功 return result[text], details else: return result[text], 识别失败请检查音频文件 # 创建Gradio界面 with gr.Blocks(titleSenseVoice 语音识别) as demo: gr.Markdown(# ️ SenseVoice 语音识别) gr.Markdown(上传音频文件或使用麦克风录音支持50种语言识别) with gr.Row(): with gr.Column(): # 音频输入 audio_input gr.Audio( label上传音频或录音, typefilepath ) # 语言选择 language gr.Radio( choices[auto, zh, en, yue, ja, ko], valueauto, label选择语言, infoauto: 自动检测语言 ) # 功能开关 itn_enabled gr.Checkbox( label启用逆文本标准化, valueTrue, info将一百二十转换为120 ) # 按钮 with gr.Row(): recognize_btn gr.Button( 开始识别, variantprimary) clear_btn gr.Button(️ 清除) with gr.Column(): # 识别结果 text_output gr.Textbox( label识别结果, lines10, placeholder识别结果将显示在这里... ) # 详细信息 detail_output gr.Textbox( label详细信息, lines4, placeholder识别详情将显示在这里... ) # 按钮事件 recognize_btn.click( fnprocess_audio, inputs[audio_input, language], outputs[text_output, detail_output] ) def clear_all(): return None, auto, True, , clear_btn.click( fnclear_all, inputs[], outputs[audio_input, language, itn_enabled, text_output, detail_output] ) # 示例音频 gr.Markdown(### 示例音频) gr.Examples( examples[ [example_zh.wav, zh], [example_en.wav, en] ], inputs[audio_input, language], label点击示例快速体验 ) return demo if __name__ __main__: # 模型路径 - 根据实际位置修改 model_path ./models/sensevoice-small.onnx # 检查模型文件是否存在 if not Path(model_path).exists(): print(f错误: 模型文件不存在: {model_path}) print(请确保模型文件已下载并放置在正确位置) exit(1) # 创建并启动Web界面 demo create_web_interface(model_path) demo.launch( server_name0.0.0.0, server_port7860, shareFalse )创建requirements.txt文件gradio4.0.0 onnxruntime1.15.0 numpy1.24.0 soundfile0.12.0 scipy1.10.0 librosa0.10.04.3 安装项目依赖# 确保在sensevoice环境下 conda activate sensevoice # 安装项目依赖 cd ~/sensevoice-project pip install -r requirements.txt5. 配置和启动服务5.1 准备示例音频文件为了测试识别效果我们需要一些示例音频文件# 创建示例音频目录 mkdir -p ~/sensevoice-project/examples # 这里我们可以用文本转语音生成简单的测试音频 # 首先安装TTS库 pip install gtts # 创建测试脚本 cat create_test_audio.py EOF from gtts import gTTS import os # 创建中文测试音频 text_zh 你好这是一个语音识别测试今天天气真好。 tts_zh gTTS(texttext_zh, langzh) tts_zh.save(examples/example_zh.wav) # 创建英文测试音频 text_en Hello, this is a speech recognition test. The weather is nice today. tts_en gTTS(texttext_en, langen) tts_en.save(examples/example_en.wav) print(测试音频已生成) EOF # 运行脚本生成测试音频 python create_test_audio.py5.2 配置启动脚本创建启动脚本方便以后快速启动服务cat start_sensevoice.sh EOF #!/bin/bash # SenseVoice-small 语音识别服务启动脚本 echo SenseVoice-small 语音识别服务启动 echo 时间: $(date) echo # 激活conda环境 source ~/miniconda3/etc/profile.d/conda.sh conda activate sensevoice # 进入项目目录 cd ~/sensevoice-project # 检查模型文件 if [ ! -f ./models/sensevoice-small.onnx ]; then echo 错误: 模型文件不存在! echo 请确保模型文件已下载到 ./models/sensevoice-small.onnx exit 1 fi # 检查端口是否被占用 PORT7860 if lsof -Pi :$PORT -sTCP:LISTEN -t /dev/null ; then echo 端口 $PORT 已被占用尝试停止现有服务... lsof -ti:$PORT | xargs kill -9 2/dev/null sleep 2 fi # 启动服务 echo 启动SenseVoice语音识别服务... echo 服务地址: http://localhost:7860 echo python app.py EOF # 给启动脚本添加执行权限 chmod x start_sensevoice.sh5.3 启动服务并测试现在一切准备就绪让我们启动服务# 启动服务 cd ~/sensevoice-project ./start_sensevoice.sh如果一切正常你会看到类似这样的输出 SenseVoice-small 语音识别服务启动 时间: Wed Mar 12 10:30:00 CST 2024 启动SenseVoice语音识别服务... 服务地址: http://localhost:7860 Running on local URL: http://0.0.0.0:7860现在打开你的Windows浏览器访问http://localhost:7860你应该能看到SenseVoice的Web界面。5.4 测试语音识别功能在Web界面中你可以上传测试音频点击上传区域选择我们刚才生成的example_zh.wav或example_en.wav选择语言中文音频选zh英文音频选en或者用auto自动检测点击识别点击 开始识别按钮查看结果识别结果会显示在文本框中如果模型加载正确你应该能看到识别出的文字。第一次运行可能会比较慢因为需要加载模型。6. 常见问题与解决方案6.1 模型加载失败问题启动时提示模型加载失败解决方案# 检查模型文件是否存在 ls -la ~/sensevoice-project/models/ # 检查模型文件权限 chmod r ~/sensevoice-project/models/* # 检查ONNX Runtime版本 python -c import onnxruntime; print(onnxruntime.__version__) # 尝试重新安装ONNX Runtime pip uninstall onnxruntime -y pip install onnxruntime1.15.06.2 端口被占用问题7860端口已被其他程序占用解决方案# 查看哪个进程占用了7860端口 sudo lsof -i :7860 # 停止占用端口的进程如果是其他重要服务请勿随意停止 # 或者修改app.py中的端口号 # demo.launch(server_port7861) # 改为78616.3 音频处理错误问题上传音频后识别失败解决方案# 安装完整的音频处理库 pip install pydub audiomentations # 检查音频文件格式 file examples/example_zh.wav # 转换音频格式如果需要 pip install ffmpeg-python # 或者使用系统ffmpeg sudo apt install ffmpeg6.4 内存不足问题处理大音频文件时内存不足解决方案# 在app.py中添加音频分段处理 def process_large_audio(audio_path, chunk_duration30): 分段处理大音频文件 chunk_duration: 每段时长秒 import soundfile as sf import numpy as np audio, sr sf.read(audio_path) chunk_size chunk_duration * sr chunks [] for i in range(0, len(audio), chunk_size): chunk audio[i:ichunk_size] # 保存临时文件并处理 temp_file ftemp_chunk_{i}.wav sf.write(temp_file, chunk, sr) # 处理这个chunk # ...6.5 性能优化建议如果你的电脑配置较低可以尝试以下优化# 在app.py的模型加载部分添加优化选项 session_options ort.SessionOptions() session_options.intra_op_num_threads 4 # 设置线程数 session_options.execution_mode ort.ExecutionMode.ORT_SEQUENTIAL session_options.graph_optimization_level ort.GraphOptimizationLevel.ORT_ENABLE_ALL self.session ort.InferenceSession( self.model_path, sess_optionssession_options, providers[CPUExecutionProvider] )7. 进阶使用与开发7.1 集成到其他应用SenseVoice-small可以很容易地集成到你的Python应用中# sensevoice_integration.py import sys sys.path.append(/path/to/sensevoice-project) from sensevoice_recognizer import SenseVoiceRecognizer class MyApplication: def __init__(self): self.recognizer SenseVoiceRecognizer( model_path/path/to/models/sensevoice-small.onnx ) def process_meeting_audio(self, audio_path): 处理会议录音 result self.recognizer.recognize(audio_path, languagezh) # 保存识别结果 with open(meeting_transcript.txt, w, encodingutf-8) as f: f.write(f会议记录:\n{result[text]}) # 进一步处理提取关键词、生成摘要等 # ... return result def batch_process(self, audio_files): 批量处理音频文件 results [] for audio_file in audio_files: result self.recognizer.recognize(audio_file, languageauto) results.append({ file: audio_file, text: result[text], language: result[language] }) return results # 使用示例 if __name__ __main__: app MyApplication() # 处理单个文件 result app.process_meeting_audio(meeting.wav) print(f识别结果: {result[text]}) # 批量处理 audio_files [audio1.wav, audio2.wav, audio3.wav] results app.batch_process(audio_files) for r in results: print(f{r[file]}: {r[text][:50]}...)7.2 添加新功能你可以基于SenseVoice-small开发更多实用功能# advanced_features.py import re from datetime import datetime class EnhancedSenseVoice(SenseVoiceRecognizer): def __init__(self, model_path): super().__init__(model_path) def extract_keywords(self, text, top_n10): 从文本中提取关键词简单实现 # 去除标点符号 text_clean re.sub(r[^\w\s], , text) # 分词这里使用简单空格分词中文需要更复杂的分词 words text_clean.lower().split() # 统计词频 from collections import Counter word_counts Counter(words) # 返回最常见的词 return word_counts.most_common(top_n) def generate_summary(self, text, max_sentences3): 生成摘要简单实现 sentences re.split(r[。.!?], text) sentences [s.strip() for s in sentences if s.strip()] # 简单的摘要取前几个句子 summary 。.join(sentences[:max_sentences]) 。 return summary def detect_speakers(self, audio_path, num_speakers2): 说话人分离需要额外模型 # 这里可以集成pyannote.audio等说话人分离工具 # 返回不同说话人的时间段 return [ {speaker: Speaker1, start: 0.0, end: 10.5}, {speaker: Speaker2, start: 10.5, end: 25.0} ] def export_transcript(self, text, formattxt): 导出转录文本 timestamp datetime.now().strftime(%Y%m%d_%H%M%S) if format txt: filename ftranscript_{timestamp}.txt with open(filename, w, encodingutf-8) as f: f.write(text) elif format srt: filename ftranscript_{timestamp}.srt # 生成SRT字幕格式 # ... elif format json: filename ftranscript_{timestamp}.json import json data { timestamp: timestamp, text: text, language: auto } with open(filename, w, encodingutf-8) as f: json.dump(data, f, ensure_asciiFalse, indent2) return filename7.3 性能监控和日志添加监控和日志功能便于问题排查# monitoring.py import logging import time from functools import wraps # 配置日志 logging.basicConfig( levellogging.INFO, format%(asctime)s - %(name)s - %(levelname)s - %(message)s, handlers[ logging.FileHandler(sensevoice.log), logging.StreamHandler() ] ) logger logging.getLogger(__name__) def log_execution_time(func): 记录函数执行时间的装饰器 wraps(func) def wrapper(*args, **kwargs): start_time time.time() result func(*args, **kwargs) end_time time.time() logger.info(f{func.__name__} 执行时间: {end_time - start_time:.2f}秒) return result return wrapper def log_audio_info(func): 记录音频信息的装饰器 wraps(func) def wrapper(audio_path, *args, **kwargs): import os import soundfile as sf file_size os.path.getsize(audio_path) / 1024 / 1024 # MB duration len(sf.read(audio_path)[0]) / 16000 # 秒 logger.info(f处理音频: {audio_path}) logger.info(f文件大小: {file_size:.2f}MB, 时长: {duration:.2f}秒) return func(audio_path, *args, **kwargs) return wrapper class MonitoredSenseVoice(SenseVoiceRecognizer): log_execution_time log_audio_info def recognize(self, audio_path, languageauto): 重写recognize方法添加监控 try: result super().recognize(audio_path, language) logger.info(f识别成功: {audio_path}, 语言: {language}) return result except Exception as e: logger.error(f识别失败: {audio_path}, 错误: {str(e)}) raise8. 总结通过这篇教程我们完成了SenseVoice-small在WSL2 Windows本地开发环境的完整搭建。让我们回顾一下关键步骤环境搭建我们安装了WSL2和Ubuntu创建了独立的Python环境安装了所有必要的依赖。这个环境不仅适用于SenseVoice也可以用于其他AI项目的开发。模型部署我们下载了SenseVoice-small的ONNX量化模型这个版本特别适合在CPU上运行不需要GPU也能获得不错的识别效果。服务启动我们创建了一个基于Gradio的Web界面让语音识别服务可以通过浏览器轻松访问。这个界面支持文件上传和实时录音两种输入方式。功能测试我们生成了测试音频验证了识别功能正常工作。虽然示例代码中的模型接口是简化的但实际部署时你需要根据真实的模型输入输出格式进行调整。进阶开发我展示了如何将SenseVoice集成到其他应用中以及如何添加关键词提取、摘要生成等高级功能。这些示例代码可以作为你进一步开发的基础。实际应用场景这个本地部署的语音识别服务可以用于离线会议记录在保密会议中本地处理录音个人语音笔记快速将想法转为文字多媒体内容处理为视频生成字幕客户服务质检分析通话录音完全本地处理保护隐私教育辅助实时语音转文字帮助听障人士性能提示SenseVoice-small作为轻量级模型在普通CPU上也能有不错的表现。对于实时应用建议将音频分段处理对于批量处理可以考虑添加队列机制。后续优化方向添加更多语言支持集成说话人分离功能添加实时流式识别优化内存使用支持更长音频添加模型热更新功能现在你已经拥有了一个完全本地化的语音识别服务既保护了隐私又不受网络限制。你可以基于这个基础继续开发更多有趣的应用。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。