SenseVoice-small-ONNX部署教程：API响应JSON字段含义与错误码详解

1. 快速了解SenseVoice语音识别服务

SenseVoice-small是一个基于ONNX量化的多语言语音识别模型，专门为实际应用场景优化。这个模型最吸引人的地方在于它既能保持高质量的识别效果，又有着极快的推理速度——10秒的音频只需要70毫秒就能完成识别，真正做到了又快又准。

这个服务支持中文、粤语、英语、日语、韩语等多种语言，还能自动检测音频的语言类型。更实用的是，它不仅能转写文字，还能识别说话人的情感状态和音频中的特殊事件，比如笑声、掌声等，让你的应用更加智能化。

通过简单的REST API接口，你可以轻松地将语音识别功能集成到自己的项目中，无论是Web应用、移动应用还是桌面程序，都能快速接入。

2. 环境准备与快速部署

2.1 安装必要依赖

在开始之前，我们需要先安装一些必要的Python包。打开终端，执行以下命令：

pip install funasr-onnx gradio fastapi uvicorn soundfile jieba

这些包各自有不同的作用：

• funasr-onnx：核心的语音识别库
• gradio和fastapi：用于构建Web界面和API服务
• uvicorn：ASGI服务器，用于运行FastAPI应用
• soundfile：处理音频文件
• jieba：中文分词工具

2.2 启动语音识别服务

安装完依赖后，使用以下命令启动服务：

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

服务启动后，你可以通过以下地址访问：

• Web界面：http://localhost:7860（可以直接上传音频文件测试）
• API文档：http://localhost:7860/docs（查看详细的API接口说明）
• 健康检查：http://localhost:7860/health（检查服务是否正常运行）

3. API接口使用详解

3.1 基础调用方法

SenseVoice提供了简单的REST API接口，使用curl命令就能快速测试：

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

这个命令会上传一个名为audio.wav的音频文件，让服务自动检测语言并进行转写。use_itn=true表示开启逆文本正则化，会把"三"转换成"3"这样的数字格式。

3.2 Python代码调用示例

如果你更喜欢用Python来调用，这里有一个完整的示例：

from funasr_onnx import SenseVoiceSmall

# 初始化模型，使用量化版本提升性能
model = SenseVoiceSmall(
    "/root/ai-models/danieldong/sensevoice-small-onnx-quant",
    batch_size=10,
    quantize=True
)

# 识别单个音频文件
result = model(["audio.wav"], language="auto", use_itn=True)
print(result[0])

这段代码首先初始化模型，指定模型路径和批处理大小，然后对音频文件进行识别。language="auto"让模型自动检测语言，适合多语言场景。

4. API响应JSON字段详解

当你调用API接口后，会收到一个结构化的JSON响应。了解每个字段的含义非常重要，这样才能正确地处理识别结果。

4.1 成功响应字段说明

成功的识别响应通常包含以下字段：

{
  "status": "success",
  "message": "转写成功",
  "data": {
    "text": "你好，这是一个测试音频",
    "language": "zh",
    "segments": [
      {
        "start": 0.0,
        "end": 2.5,
        "text": "你好，",
        "emotion": "neutral",
        "events": []
      }
    ],
    "itn_text": "你好，这是一个测试音频"
  },
  "processing_time": 0.075
}

各个字段的详细含义：

• status: 请求状态，成功时为"success"
• message: 详细的处理消息
• data: 核心的识别数据
  • text: 转写后的文本内容
  • language: 识别出的语言代码
  • segments: 分段识别结果（包含时间戳和情感信息）
  • itn_text: 经过逆文本正则化处理后的文本
• processing_time: 处理耗时（秒）

4.2 分段信息详解

segments字段提供了更详细的时间分段信息，对于需要精确定位的应用特别有用：

• start和end: 该段语音的开始和结束时间（秒）
• text: 该时间段的转写文本
• emotion: 情感状态（neutral-中性, happy-高兴, sad-悲伤, angry-生气）
• events: 音频事件列表，如["laughter"]表示笑声

5. 错误码与异常处理

5.1 常见错误码说明

在实际使用中，可能会遇到各种错误情况。以下是常见的错误码及其含义：

{
  "status": "error",
  "error_code": "AUDIO_TOO_LONG",
  "message": "音频长度超过限制（最长300秒）",
  "details": "当前音频时长350秒"
}

主要错误码分类：

错误码	含义	解决方法
AUDIO_FORMAT_UNSUPPORTED	不支持的音频格式	转换为mp3、wav等支持的格式
AUDIO_TOO_LONG	音频过长	拆分音频或使用更短的录音
AUDIO_TOO_SHORT	音频过短	确保音频至少0.5秒
LANGUAGE_NOT_SUPPORTED	不支持的语言	检查语言参数是否正确
MODEL_LOAD_FAILED	模型加载失败	检查模型路径和权限
INTERNAL_ERROR	内部错误	查看服务日志获取详细信息

5.2 错误处理最佳实践

在实际应用中，建议这样处理错误：

import requests

try:
    response = requests.post(
        "http://localhost:7860/api/transcribe",
        files={"file": audio_file},
        data={"language": "auto", "use_itn": "true"}
    )
    
    result = response.json()
    
    if result["status"] == "success":
        # 处理成功结果
        text = result["data"]["text"]
        print(f"识别结果: {text}")
    else:
        # 处理错误
        error_code = result["error_code"]
        error_msg = result["message"]
        print(f"识别失败: {error_code} - {error_msg}")
        
except requests.exceptions.RequestException as e:
    print(f"网络请求失败: {e}")
except ValueError as e:
    print(f"JSON解析失败: {e}")

这种处理方式能够优雅地应对各种异常情况，确保你的应用不会因为识别服务的问题而崩溃。

6. 实用技巧与优化建议

6.1 提升识别准确率

根据实际使用经验，这里有一些提升识别准确率的小技巧：

• 音频质量很重要：尽量使用清晰的音频，避免背景噪音
• 选择合适的语言：如果知道录音的语言，直接指定而不是用auto
• 分段处理长音频：对于很长的音频，可以先分割成小段再识别
• 调整音频格式：使用16kHz采样率的wav格式通常效果最好

6.2 性能优化建议

如果你需要处理大量音频，可以考虑这些优化措施：

# 批量处理多个音频文件，提升效率
results = model([
    "audio1.wav", 
    "audio2.wav", 
    "audio3.wav"
], language="zh", use_itn=True)

for i, result in enumerate(results):
    print(f"音频{i+1}: {result}")

批量处理可以显著减少总体处理时间，特别适合后台处理大量录音文件的场景。

7. 总结

通过这篇教程，你应该已经全面了解了SenseVoice-small-ONNX语音识别服务的API使用方法和响应格式。关键要点包括：

• API调用简单直观，支持REST和Python两种方式
• 响应JSON结构清晰，包含转写文本、语言信息、时间分段等丰富数据
• 错误处理机制完善，提供了详细的错误码和解决方法
• 支持多语言识别和富文本转写，满足各种应用场景需求

在实际使用时，记得处理好各种异常情况，并根据你的具体需求调整参数设置。这个服务的优势在于识别速度快、准确率高，而且支持丰富的输出信息，无论是做字幕生成、会议记录还是语音分析，都能提供很好的支持。

---

获取更多AI镜像

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