如何调用SenseVoiceSmall API？Python代码实例详细说明

1. 什么是 SenseVoiceSmall？

你有没有遇到过这样的问题：一段语音里不仅有说话内容，还藏着情绪、背景音乐甚至掌声笑声，但普通语音识别只能告诉你“说了什么”，却无法感知“怎么说的”和“环境怎么样”？这时候，SenseVoiceSmall就派上用场了。

这是阿里巴巴达摩院开源的一款多语言语音理解模型，它不只是把声音转成文字，还能听出说话人是开心还是生气，背景有没有音乐或掌声。换句话说，它能做富文本语音识别（Rich Transcription）——不仅能识字，还能读心。

这个模型支持中文、英文、粤语、日语、韩语五种语言，特别适合需要情感分析或多语种混合识别的场景，比如客服质检、视频内容分析、智能助手等。

更贴心的是，镜像已经集成了Gradio WebUI，即使你不写代码，也能上传音频直接看结果。而如果你是开发者，想在自己的项目中调用它的 API，这篇文章就是为你准备的。

2. 环境准备与依赖安装

2.1 基础环境要求

要顺利运行 SenseVoiceSmall 模型并调用其 API，你需要确保以下环境条件：

Python 版本：3.11
PyTorch：2.5（建议使用 GPU 版本以获得更快推理速度）
硬件建议：至少配备一块 NVIDIA 显卡（如 RTX 4090），开启 CUDA 加速后可实现秒级转写

2.2 必要的 Python 库

通过 pip 安装以下核心库：

pip install funasr modelscope gradio av torch torchaudio

其中：

funasr：阿里推出的语音识别工具包，SenseVoiceSmall 基于此框架加载
modelscope：用于从 ModelScope 平台下载模型权重
av：高效音频解码库，处理.wav、.mp3等格式
gradio：构建可视化界面（可选，仅用于本地测试）

提示：如果遇到av安装失败，可以尝试先用 conda 安装：conda install -c conda-forge pyav

3. 初始化模型并调用 API

3.1 最简调用示例

下面是最基础的 Python 脚本，展示如何加载模型并进行一次语音识别：

from funasr import AutoModel from funasr.utils.postprocess_utils import rich_transcription_postprocess # 初始化模型 model = AutoModel( model="iic/SenseVoiceSmall", trust_remote_code=True, device="cuda:0", # 使用 GPU 推理 ) # 执行识别 res = model.generate(input="example.wav", language="auto") # 后处理：将原始标签转换为易读格式 raw_text = res[0]["text"] clean_text = rich_transcription_postprocess(raw_text) print("原始输出：", raw_text) print("清洗后：", clean_text)

运行后你会看到类似这样的输出：

原始输出： <|zh|><|HAPPY|>今天天气真好啊！<|LAUGHTER|>哈哈哈<|en|><|NEUTRAL|>It's a beautiful day. 清洗后： [中文][开心] 今天天气真好啊！[笑声] 哈哈哈 [英文][中性] It's a beautiful day.

是不是很直观？一句话里既有中英文切换，又有情绪变化和笑声标注，全部被准确捕捉到了。

3.2 参数详解：让你掌控每一个细节

虽然默认调用很简单，但在实际应用中，你可能需要根据业务需求调整参数。以下是常用参数说明：

参数名	说明
`language`	指定语言模式： `auto`：自动检测 `zh`：中文 `en`：英文 `yue`：粤语 `ja`：日语 `ko`：韩语
`use_itn`	是否启用 ITN（Inverse Text Normalization），例如把“2025年”还原成“二零二五年”
`batch_size_s`	按时间分批处理，单位为秒，默认 60s，适合长音频
`merge_vad`	是否合并 VAD（语音活动检测）片段，避免断句太碎
`merge_length_s`	合并后的最大片段长度，防止过长

示例：处理长音频并控制分段

res = model.generate( input="long_audio.wav", language="auto", use_itn=True, batch_size_s=30, # 每30秒处理一批 merge_vad=True, merge_length_s=10, # 合并成不超过10秒的句子 )

这在处理会议录音、访谈等长语音时非常有用，既能保证流畅性，又不会丢失上下文。

4. 构建自己的 API 服务

如果你想把这个模型集成到后端系统中，提供一个 HTTP 接口供其他服务调用，可以使用 Flask 或 FastAPI 快速搭建。

4.1 使用 Flask 搭建 RESTful API

from flask import Flask, request, jsonify from funasr import AutoModel from funasr.utils.postprocess_utils import rich_transcription_postprocess import os app = Flask(__name__) # 全局加载模型（启动时初始化一次） model = AutoModel( model="iic/SenseVoiceSmall", trust_remote_code=True, device="cuda:0" ) @app.route('/transcribe', methods=['POST']) def transcribe(): if 'audio' not in request.files: return jsonify({"error": "缺少音频文件"}), 400 file = request.files['audio'] temp_path = "/tmp/temp_audio.wav" file.save(temp_path) try: # 调用模型识别 res = model.generate( input=temp_path, language=request.form.get("language", "auto"), use_itn=True ) if len(res) == 0: return jsonify({"error": "识别失败"}), 500 raw_text = res[0]["text"] clean_text = rich_transcription_postprocess(raw_text) return jsonify({ "raw": raw_text, "text": clean_text }) finally: if os.path.exists(temp_path): os.remove(temp_path) if __name__ == '__main__': app.run(host='0.0.0.0', port=5000)

保存为api_server.py，运行：

python api_server.py

然后就可以用 curl 测试：

curl -X POST http://localhost:5000/transcribe \ -F "audio=@test.wav" \ -F "language=zh"

返回 JSON 结果：

{ "raw": "<|zh|><|HAPPY|>你好呀，今天很开心！", "text": "[中文][开心] 你好呀，今天很开心！" }

这样你就拥有了一个轻量级的语音理解 API 服务！

5. 高级技巧与实用建议

5.1 如何提取情感和事件标签？

有时候你不需要完整文本，而是只想知道这段音频里有没有愤怒情绪或掌声。可以通过正则提取关键标签：

import re def extract_emotions_and_events(text): emotions = re.findall(r'<\|(HAPPY|ANGRY|SAD|NEUTRAL)\|>', text) events = re.findall(r'<\|(BGM|APPLAUSE|LAUGHTER|CRY)\|>', text) return { "emotions": list(set(emotions)), "events": list(set(events)) } # 示例 info = extract_emotions_and_events(raw_text) print(info) # 输出：{'emotions': ['HAPPY'], 'events': ['LAUGHTER']}

这个功能非常适合做自动化内容审核或情绪趋势分析。

5.2 多语种混合识别实战

现实中的语音常常是中英夹杂，比如：“这个 feature 很 nice！” SenseVoiceSmall 对这种场景支持非常好。

测试一下：

输入音频内容（口语）：

“这个 proposal 写得不错，but 下面这部分 needs improvement.”

输出结果：

[中文][中性] 这个 proposal 写得不错，[英文][中性] but 下面这部分 needs improvement.

可以看到，它不仅能识别语言切换，还能保持每段的情绪状态独立判断。

5.3 性能优化小贴士

GPU 加速：务必使用device="cuda:0"，否则 CPU 推理会慢很多
批量处理：对多个音频文件，建议循环调用model.generate()，避免重复加载模型
缓存机制：对于长时间服务，保持模型常驻内存，不要每次请求都重新加载
音频预处理：尽量使用 16kHz 单声道 WAV 格式，减少重采样开销

6. 常见问题与解决方案

6.1 音频格式不支持怎么办？

虽然模型内部会自动重采样，但某些编码格式（如 AAC in MP4）可能导致av解码失败。

解决方法：提前用ffmpeg转换为标准格式：

ffmpeg -i input.mp4 -ar 16000 -ac 1 -c:a pcm_s16le output.wav

参数说明：

-ar 16000：采样率 16k
-ac 1：单声道
-c:a pcm_s16le：PCM 编码，兼容性最好

6.2 情感识别不准？

注意：情感识别基于声学特征，对语速、音量、背景噪音敏感。建议：

避免在嘈杂环境中录音
说话者尽量清晰表达
不要过度依赖单一标签，结合上下文综合判断

6.3 如何离线部署？

如果你希望完全脱离网络运行（比如内网环境），可以：

提前下载模型到本地目录：

from modelscope.hub.snapshot_download import snapshot_download model_dir = snapshot_download('iic/SenseVoiceSmall')

加载时指定本地路径：

model = AutoModel(model=model_dir, trust_remote_code=True)

7. 总结

SenseVoiceSmall 是目前少有的同时支持多语言识别 + 情感分析 + 声音事件检测的开源语音模型。无论是做内容分析、用户体验监控，还是开发智能对话系统，它都能提供远超传统 ASR 的信息维度。

本文带你一步步实现了：

✅ 环境搭建与依赖安装
✅ 模型初始化与基本调用
✅ 富文本后处理与标签提取
✅ 自建 API 服务（Flask）
✅ 实战技巧与性能优化
✅ 常见问题排查

现在你可以轻松地将“听懂声音”这件事升级为“理解声音”。下一步，不妨试试把它接入你的客服系统，自动标记客户情绪；或者集成到视频平台，自动生成带情绪标注的字幕。

技术的价值不在于多复杂，而在于多有用。SenseVoiceSmall 正是一个既强大又接地气的工具。

获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。