手把手教你用SenseVoice搭建多语言语音识别API-育师

手把手教你用SenseVoice搭建多语言语音识别API

1. 引言

想象一下，你正在开发一个国际化的在线会议应用，用户来自世界各地，说着不同的语言。会议结束后，你需要自动生成一份包含中文、英语、日语等多种语言的会议纪要。手动转录？效率太低。找第三方服务？成本太高且数据安全无法保障。

今天，我要带你亲手搭建一个属于自己的多语言语音识别服务。我们将使用SenseVoice Small这个轻量级模型，它基于ONNX量化技术，不仅识别准确，而且速度飞快。最重要的是，我们将把它封装成一个标准的REST API，让你可以像调用天气预报接口一样，轻松地把语音识别能力集成到你的任何项目中。

这篇文章会从零开始，带你完成环境搭建、服务部署、API调用和实际应用的全过程。即使你之前没有接触过语音识别，也能跟着步骤一步步实现。我们开始吧。

2. 环境准备与快速部署

2.1 理解我们要用的工具

在开始动手之前，我们先简单了解一下核心组件：

SenseVoice Small：这是我们今天的主角，一个专门为语音识别优化的小模型。它最大的特点是“小身材，大能量”——模型经过压缩（量化），体积很小，但识别多种语言的能力很强。
ONNX：你可以把它想象成一个“通用翻译器”。不同的深度学习框架（如PyTorch、TensorFlow）训练出的模型，通过ONNX可以转换成一种统一的格式，方便在各种设备上高效运行。
FastAPI：一个用来快速构建Web API的Python框架。我们将用它来创建一个接收音频文件、返回识别文字的接口。
Gradio：一个能快速生成可视化Web界面的库。有了它，我们不需要写前端代码，就能有一个上传音频、查看识别结果的网页。

我们的目标就是把这些工具组合起来，搭建一个既可以通过网页操作，又可以通过代码调用的语音识别服务。

2.2 一步到位的部署命令

最让人兴奋的部分来了：如果你使用的是提供了预置环境的云平台或容器服务（例如CSDN星图镜像），整个过程可以简化到只需几条命令。

假设你已经进入了一个包含所需模型的Linux环境，按照以下步骤操作：

安装必要的Python包：打开终端，执行下面的命令。这些包包含了模型推理、Web服务和音频处理的所有依赖。
```
pip install funasr-onnx gradio fastapi uvicorn soundfile jieba
```
启动语音识别服务：安装完成后，直接运行启动脚本。下面的命令会启动一个Web服务，它同时提供了网页界面和API接口。
```
python3 app.py --host 0.0.0.0 --port 7860
```
- --host 0.0.0.0表示服务可以被网络上的其他设备访问。
- --port 7860指定了服务运行的端口号。
验证服务是否启动成功：看到终端输出类似Uvicorn running on http://0.0.0.0:7860的信息后，就说明服务已经跑起来了。你可以通过以下方式访问：
- 网页操作界面：在浏览器中打开http://你的服务器IP地址:7860
- API交互文档：打开http://你的服务器IP地址:7860/docs，这里可以看到所有API的详细说明和测试界面。
- 服务健康检查：打开http://你的服务器IP地址:7860/health，如果返回{"status":"healthy"}，说明服务状态正常。

重要提示：在预置的镜像环境中，模型通常已经提前下载并放置在特定路径（如/root/ai-models/...）。服务启动时会自动加载这个缓存好的模型，避免了漫长的模型下载等待时间，真正做到“开箱即用”。

3. 分步实践：从网页测试到代码调用

服务启动后，我们分别从“小白用户”和“开发者”两个视角，来看看怎么使用它。

3.1 通过网页界面快速体验（适合所有人）

这是最简单直观的方式，不需要写任何代码。

在浏览器打开http://localhost:7860（如果服务运行在本机）。
你会看到一个简洁的上传界面。
点击上传按钮，选择一个你的音频文件（支持.wav,.mp3,.m4a,.flac等常见格式）。
在“语言”选项里，你可以：
- 选择auto（推荐）：让模型自动检测音频是哪种语言。
- 手动指定：比如你知道是中文就选zh，是英语就选en。
点击“提交”按钮。
稍等片刻（对于10秒的音频，通常不到1秒），下方就会显示出识别出的文字结果。

这个界面非常适合快速测试音频文件的识别效果，或者进行小批量的文件转写。

3.2 通过API接口集成到你的系统（适合开发者）

作为开发者，我们更关心如何用程序来调用这个服务。它提供了一个标准的REST API，使用起来非常简单。

使用curl命令测试：在终端里，你可以用一行命令完成语音识别。

curl -X POST "http://localhost:7860/api/transcribe" \ -F "file=@/path/to/your/audio.wav" \ -F "language=auto" \ -F "use_itn=true"

-X POST：表示这是一个POST请求。
-F "file=@..."：指定要上传的音频文件路径。
-F "language=auto"：设置语言为自动检测。
-F "use_itn=true"：这是一个很实用的选项，ITN（逆文本正则化）能把“百分之二十”自动转换成“20%”，把“三点五元”转换成“3.5元”，让结果更规范。

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

使用 Python 代码调用：在实际项目中，我们更多是用编程语言来调用。下面是一个完整的Python示例：

import requests # 1. 设置API地址和音频文件路径 api_url = "http://localhost:7860/api/transcribe" audio_file_path = "meeting_recording.wav" # 2. 准备要上传的数据 files = {'file': open(audio_file_path, 'rb')} data = {'language': 'auto', 'use_itn': True} # 3. 发送POST请求 response = requests.post(api_url, files=files, data=data) # 4. 处理返回结果 if response.status_code == 200: result = response.json() print("识别成功！") print(f"识别文本：{result.get('text')}") # 结果中可能还包含语言类型、情感标签等信息 print(f"检测到的语言：{result.get('language')}") else: print(f"识别失败，状态码：{response.status_code}") print(response.text)

这段代码清晰展示了调用流程：构造请求 -> 发送 -> 解析结果。你可以轻松地把它嵌入到你的后台系统、自动化脚本或任何需要语音转文字功能的地方。

3.3 直接使用模型库进行高级开发

如果你需要进行更底层的操作，比如批量处理大量音频，或者对推理过程有特殊控制，可以直接使用funasr-onnx这个Python库。

from funasr_onnx import SenseVoiceSmall # 1. 指定量化模型的存放路径 model_dir = "/root/ai-models/danieldong/sensevoice-small-onnx-quant" # 2. 加载模型 # batch_size=10 表示一次可以处理10个音频文件，效率更高 model = SenseVoiceSmall(model_dir, batch_size=10, quantize=True) # 3. 准备音频文件列表 audio_list = ["audio1.wav", "audio2.mp3", "audio3.flac"] # 4. 执行识别 # language="auto" 表示自动检测语言 # use_itn=True 开启逆文本正则化 results = model(audio_list, language="auto", use_itn=True) # 5. 打印结果 for i, result in enumerate(results): print(f"文件 {audio_list[i]} 的识别结果：") print(result[0]) # result[0] 是识别文本 print("-" * 30)

这种方式给了开发者最大的灵活性，适合构建高性能的语音处理流水线。

4. 核心功能与实用技巧

4.1 它到底能识别哪些语言？

这是SenseVoice的一个核心优势。它不仅仅支持常见的几种语言，其内置的自动检测功能可以识别超过50种语言。对于我们日常使用，下表列出了最常用的选项：

语言代码	代表语言	使用场景举例
`auto`	自动检测	不确定音频语言时的首选，非常方便。
`zh`	中文（普通话）	国内会议录音、中文播客、客服电话录音。
`yue`	粤语	广东、香港地区的方言录音。
`en`	英语	国际会议、英文教学视频、英文播客。
`ja`	日语	日剧台词、日语学习材料、日本客户沟通。
`ko`	韩语	韩语歌曲、韩剧、韩国产品发布会。

技巧：即使你明确知道是中文会议，也可以先尝试用auto。如果检测结果准确，说明你的服务在应对多语言混合场景时也会很可靠。

4.2 让识别结果更规范：ITN功能

use_itn=true这个参数强烈建议开启。它就像一个小助手，帮你把口语化的数字、单位转换成书面格式。

转换前：“本次项目预算大概需要一百二十五万元”
转换后：“本次项目预算大概需要125万元”
转换前：“请于下午三点十五分前提交报告”
转换后：“请于下午3:15前提交报告”

这个功能对于生成正式的会议纪要、报告摘要等文本尤其有用，能省去大量后期整理的时间。

4.3 处理长音频和不同格式

长音频怎么办？模型本身对音频长度没有严格限制。但对于非常长的音频（如1小时以上的录音），建议在上传前或调用API前，先将其切割成15-30分钟一段。这样做的稳定性更好，即使某一段处理失败，也不会影响整个文件。
支持哪些格式？常见的音频格式基本都支持，例如.wav,.mp3,.m4a(AAC),.flac,.ogg等。如果遇到不常见的格式，可以使用ffmpeg工具先将其转换为标准的.wav或.mp3格式。

5. 常见问题与排查指南

在部署和使用过程中，你可能会遇到一些小问题。这里列出几个常见的：

问题：启动服务时提示“端口7860已被占用”。
- 解决：换一个端口号启动即可。例如：python3 app.py --host 0.0.0.0 --port 7861。之后访问地址也要相应改为http://localhost:7861。
问题：上传音频后，识别结果为空或乱码。
- 排查1：检查音频文件是否损坏。可以用播放器打开听听看。
- 排查2：检查音频的采样率。模型通常针对16kHz的音频优化最佳。如果音频采样率是44.1kHz或48kHz，识别效果可能会下降。可以使用音频编辑工具或ffmpeg进行降采样转换。
```
ffmpeg -i original.mp3 -ar 16000 -ac 1 converted.wav
```
问题：API调用返回错误，但网页界面正常。
- 排查：首先检查API的URL和端口是否正确。然后，用curl命令或http://localhost:7860/docs页面里的“Try it out”功能测试一下，看是否是客户端代码的问题。
问题：服务启动很慢，卡在加载模型。
- 解决：首次启动时，如果模型路径为空，服务会尝试从网络下载模型。请确保模型已按文档说明放置在正确的缓存路径（如/root/ai-models/...）。如果网络环境不佳，也可以手动下载模型文件放到对应目录。