SenseVoice-small-onnx多语言ASR部署教程：支持mp3/wav/m4a/flac全格式-程序员充电站

SenseVoice-small-onnx多语言ASR部署教程：支持mp3/wav/m4a/flac全格式

想快速搭建一个能听懂中文、粤语、英语、日语、韩语，还能自动识别情感和音频事件的语音识别服务吗？今天要介绍的SenseVoice-small-onnx模型，就是一个开箱即用的好选择。

它基于ONNX量化技术，模型体积小巧（仅230M），推理速度飞快（10秒音频仅需70毫秒），并且提供了完整的Web界面和REST API。无论你是想做个语音转文字的小工具，还是集成到自己的应用里，这套方案都能让你在几分钟内搞定部署。

接下来，我会带你从零开始，一步步完成环境搭建、服务启动、接口调用，并分享一些实用的技巧和常见问题的解决方法。

1. 环境准备与快速部署

部署这个服务非常简单，只需要几个命令。我们先从最基础的环境准备开始。

1.1 系统要求与依赖安装

这个服务对系统要求不高，主流的Linux发行版（如Ubuntu、CentOS）或者macOS都可以运行。确保你的Python版本在3.8以上。

首先，打开你的终端，执行下面的命令来安装所有必需的依赖包：

pip install funasr-onnx gradio fastapi uvicorn soundfile jieba

这条命令会安装几个核心组件：

funasr-onnx: 这是SenseVoice模型的ONNX推理引擎，是核心。
gradio: 用来构建我们马上要用的Web界面，操作音频文件非常方便。
fastapi和uvicorn: 这是创建REST API服务的基础框架。
soundfile: 用来读取各种格式的音频文件。
jieba: 中文分词工具，让识别出的中文文本更准确。

如果安装过程比较慢，可以考虑使用国内的镜像源，比如清华源：

pip install funasr-onnx gradio fastapi uvicorn soundfile jieba -i https://pypi.tuna.tsinghua.edu.cn/simple

1.2 一键启动语音识别服务

依赖装好后，部署就变得异常简单。服务提供者已经将模型和启动脚本都打包好了。你只需要下载一个启动脚本。

通常，这个启动脚本叫app.py。假设你已经拿到了这个文件，并且放在了你的工作目录下。那么，启动服务只需要一行命令：

python3 app.py --host 0.0.0.0 --port 7860

解释一下这两个参数：

--host 0.0.0.0: 这表示服务监听所有网络接口。简单说，就是不仅你的电脑自己能访问，同一局域网内的其他设备也能访问。
--port 7860: 这是服务运行的端口号，7860是Gradio常用的默认端口。

执行命令后，你会看到终端开始输出日志。当看到类似Running on local URL: http://0.0.0.0:7860的信息时，就说明服务启动成功了！

一个重要的好消息：服务首次启动时，会自动从云端下载所需的ONNX量化模型。并且，它会将模型缓存到本地的/root/ai-models/danieldong/sensevoice-small-onnx-quant路径下。下次再启动时，就会直接使用缓存的模型，无需重复下载，非常省时省心。

2. 三种使用方式上手体验

服务启动后，怎么用呢？它提供了三种方式：直观的Web界面、标准的API接口和灵活的Python代码调用。我们一个一个来看。

2.1 方式一：使用Web界面（最简单）

这是最适合新手快速体验和测试的方式。

打开你的浏览器。
在地址栏输入http://localhost:7860（如果你的服务跑在其他机器上，把localhost换成那台机器的IP地址）。
回车后，你会看到一个干净清爽的网页。

这个界面通常会有以下功能区域：

音频上传区：你可以直接拖拽一个mp3,wav,m4a,flac等格式的音频文件进来，或者点击按钮选择文件。
语言选择区：有一个下拉菜单，可以选择“自动检测”、“中文”、“英语”、“粤语”、“日语”或“韩语”。对于大多数情况，选择“自动检测”就好。
转写按钮：点击后，服务就会开始处理你的音频。
结果显示区：稍等片刻（速度非常快），识别出的文字就会显示在这里。

你可以立刻找一个带语音的音频文件试试，感受一下它的识别速度和准确度。

2.2 方式二：调用REST API（最通用）

如果你想在自己的程序、手机App或者网页里集成语音识别功能，那么调用API是最佳选择。

服务启动后，会自动提供一个标准的REST API接口。它的地址是http://localhost:7860/api/transcribe。

如何调用？你可以使用任何能发送HTTP请求的工具，比如curl（命令行）、Postman（图形化工具），或者用Python的requests库。

这里给你一个最直接的curl命令示例：

curl -X POST "http://localhost:7860/api/transcribe" \ -F "file=@/你的路径/audio.wav" \ -F "language=auto" \ -F "use_itn=true"

简单解释一下这个命令：

-X POST：表示这是一个POST请求。
-F "file=@..."：这里指定你要识别的音频文件路径。支持mp3,wav,m4a,flac等常见格式。
-F "language=auto"：告诉服务自动检测音频的语言。
-F "use_itn=true"：这是一个很实用的选项。ITN是“逆文本正则化”的缩写。开启后，它会把“百分之二十”转换成“20%”，把“三点五”转换成“3.5”，让结果更符合数字和符号的书写习惯。

执行命令后，API会返回一个JSON格式的结果，里面就包含了识别出的文本。

2.3 方式三：Python代码直接调用（最灵活）

如果你是在Python环境中做开发，想要更精细地控制识别过程，那么直接调用模型库是最灵活的方式。

下面是一个完整的Python示例：

# 导入模型类 from funasr_onnx import SenseVoiceSmall # 1. 初始化模型 # 指定模型缓存路径，batch_size表示一次可以处理多少条音频，quantize=True表示使用量化模型（更快更小） model = SenseVoiceSmall( model_dir="/root/ai-models/danieldong/sensevoice-small-onnx-quant", batch_size=10, quantize=True ) # 2. 准备音频文件列表 # 可以同时传多个音频文件路径，模型会批量处理，效率更高 audio_files = ["audio1.wav", "audio2.mp3", "lecture.m4a"] # 3. 执行语音识别 # language="auto" 让模型自动检测语言，use_itn=True 开启逆文本正则化 results = model(audio_files, language="auto", use_itn=True) # 4. 打印结果 # results 是一个列表，顺序对应 audio_files 里的每个音频 for i, text in enumerate(results): print(f"音频 {audio_files[i]} 的识别结果：") print(text) print("-" * 30)

这段代码做了四件事：加载模型、准备音频、执行识别、输出结果。你可以轻松地把它嵌入到你的数据处理流水线或自动化脚本中。

3. 核心功能与实用技巧

了解了基本用法，我们再来深入看看它的一些核心功能和能让你用得更顺手的小技巧。

3.1 理解“多语言”和“富文本转写”

这是SenseVoice-small的两个核心亮点。

真正的多语言识别：它不仅仅是支持几种语言。模型内置了超过50种语言的识别能力。当你选择language="auto"时，它会先自动判断你音频里说的是哪种语言，然后再用对应的模型去识别，准确率很高。当然，如果你明确知道是中文或英语，直接指定language="zh"或language="en"，理论上会有一点点速度上的优势。

什么是“富文本转写”？这可不是简单的把声音变成文字。它包含了更高级的信息：

情感识别：它能分析说话人的语气，尝试判断这段语音是高兴的、悲伤的、愤怒的还是中性的。这在分析客服录音、访谈资料时特别有用。
音频事件检测：它能识别出音频背景里的其他声音，比如掌声、笑声、音乐声、键盘声等。这对于会议纪要或者视频内容分析来说，能提供更丰富的上下文信息。

这些“富信息”通常会以特定的标签或结构化数据的形式，包含在API返回的完整结果中。你可以查看更详细的API文档来获取它们。

3.2 处理长音频和批量任务

实际应用中，我们遇到的音频可能很长（比如一堂课），或者需要处理成百上千个文件。这里有一些技巧。

对于长音频（超过1分钟）：模型本身对输入长度有一定限制。最佳实践是先将长音频切割成30-60秒的片段，再分别识别。你可以使用pydub这样的音频处理库来轻松完成切割：

from pydub import AudioSegment # 加载长音频 long_audio = AudioSegment.from_file("long_lecture.mp3") # 按每段30秒切割（30000毫秒） segment_length_ms = 30000 segments = [long_audio[i:i + segment_length_ms] for i in range(0, len(long_audio), segment_length_ms)] # 保存每个片段并识别 for idx, segment in enumerate(segments): segment.export(f"segment_{idx}.wav", format="wav") # ... 调用识别API或模型 ...

对于批量任务：在初始化SenseVoiceSmall模型时，我们设置了batch_size=10。这意味着模型可以同时处理10个音频片段。批量处理的速度远高于逐个处理。因此，尽可能将你的音频文件组织成列表一次性传给模型，能极大提升效率。

3.3 确保最佳识别效果

虽然模型很强，但喂给它的音频质量也会影响结果。做好下面几点，能让识别准确率更高：

音频格式优先选择：WAV或FLAC这类无损格式，或者高码率（如192kbps以上）的MP3。压缩得太厉害的音频会损失细节。
采样率处理：模型通常期望16kHz的采样率。如果你的音频是其他采样率（比如44.1kHz的音乐文件），最好在识别前进行转换。pydub也可以做这件事：
```
from pydub import AudioSegment audio = AudioSegment.from_file("input.mp3") audio = audio.set_frame_rate(16000) # 设置为16kHz audio.export("output.wav", format="wav")
```
环境噪音：尽量使用在安静环境下录制的人声清晰的音频。如果背景噪音太大，可以考虑先用一些开源音频降噪工具（如noisereduce库）做预处理。

4. 常见问题与排错指南

最后，我们来看看在部署和使用过程中，可能会遇到哪些问题，以及怎么解决。

4.1 部署与启动问题

问题：pip install安装某些包失败（特别是funasr-onnx）。
- 解决：这通常是因为网络问题或缺少系统依赖。首先，尝试使用国内镜像源（如清华源）。其次，在Linux系统上，确保已安装gcc、g++和make等编译工具。对于funasr-onnx，可以查看其官方文档是否有预编译的wheel文件。
问题：启动app.py时提示端口7860被占用。
- 解决：有两种方法。一是找出并关闭占用7860端口的程序（如另一个Gradio服务）。二是修改启动命令，换一个端口，例如python3 app.py --port 8000。
问题：服务启动成功，但浏览器访问localhost:7860打不开。
- 解决：首先确认服务是否真的在运行（检查终端日志）。如果服务运行在远程服务器（如云主机）上，你需要访问http://<服务器公网IP>:7860。同时，确保服务器的安全组或防火墙规则允许了7860端口的入站流量。

4.2 模型与识别问题

问题：第一次启动下载模型很慢，或者失败。
- 解决：模型会自动缓存到/root/ai-models/目录。如果下载中断，可以手动清理该目录后重试。也可以尝试在网络条件更好的环境下进行首次部署。
问题：识别结果中，数字、日期、金额等格式不符合习惯（如“一二三”而不是“123”）。
- 解决：请确保在调用API或模型时，设置了use_itn=true（逆文本正则化）。这个功能就是专门用来处理这类格式转换的。
问题：对于混合了多种语言的音频（如中英夹杂），识别效果不理想。
- 解决：当前模型在处理“语码转换”（即一句话里混用多种语言）时仍有挑战。对于这类音频，可以尝试指定一个主要语言（如language="zh"），可能会比language="auto"得到更连贯的结果。未来模型版本可能会针对此进行优化。
问题：如何获取情感识别和音频事件检测的结果？
- 解决：默认的Web界面和简化的API示例可能只返回文本。完整的识别结果包含更多元数据。你需要查阅funasr-onnx库的详细文档，查看SenseVoiceSmall模型返回结果的完整数据结构，从中提取情感和事件标签字段。