# SenseVoice-small-onnx API文档详解：/api/transcribe接口字段与错误码说明 今天咱们来聊聊一个非常实用的语音识别工具——SenseVoice-small-onnx。如果你正在寻找一个支持多语言、速度快、还能识别情感和音频事件的语音转文字服务，那这篇文章就是为你准备的。 我会带你深入了解它的核心API接口 `/api/transcribe`，把每个请求字段、返回结果和可能遇到的错误码都掰开揉碎了讲清楚。无论你是想快速集成到自己的项目里，还是想搞清楚某个参数到底怎么用，看完这篇文章，你都能心里有数。 ## 1. 服务概览与核心价值 SenseVoice-small-onnx 是一个基于 ONNX 量化格式的轻量级语音识别模型。简单来说，它把复杂的语音识别模型“压缩”了一下，让它在保持高精度的同时，跑得更快、占用的资源更少。 它的核心价值非常突出： - **多语言支持**：不仅能识别中文、英语、日语、韩语，还支持粤语，并且能自动检测超过50种语言。 - **功能丰富**：不只是干巴巴地转文字，还能识别说话人的情感（比如高兴、生气），以及检测音频中的事件（比如笑声、咳嗽）。 - **速度飞快**：官方数据显示，处理10秒的音频，推理时间仅需70毫秒左右，这对于实时应用来说非常友好。 - **开箱即用**：提供了完整的 REST API 和 Web 界面，部署和调用都极其简单。 接下来，我们就直奔主题，看看如何通过API来使用它。 ## 2. /api/transcribe 接口详解 `/api/transcribe` 是这个服务最核心的接口，所有语音转文字的任务都通过它来完成。它是一个标准的 HTTP POST 接口。 ### 2.1 如何调用接口 调用这个接口非常简单，使用 `curl` 命令或者任何你熟悉的 HTTP 客户端（如 Python 的 `requests` 库）都可以。 **基础调用示例 (使用 curl):** ```bash curl -X POST "http://localhost:7860/api/transcribe" \ -F "file=@你的音频文件.wav" \ -F "language=auto" \ -F "use_itn=true" ``` *说明：假设服务运行在本地的 7860 端口，你需要将 `你的音频文件.wav` 替换为实际路径。* **Python 调用示例 (使用 requests 库):** ```python import requests url = "http://localhost:7860/api/transcribe" files = {'file': open('你的音频文件.wav', 'rb')} data = {'language': 'auto', 'use_itn': 'true'} response = requests.post(url, files=files, data=data) result = response.json() print(result) ``` ### 2.2 请求参数（字段说明） 当你向 `/api/transcribe` 发送请求时，可以携带以下几个参数。这些参数都是以 `multipart/form-data` 的形式传递的。 | 参数名 | 是否必填 | 类型 | 默认值 | 说明 | | :--- | :--- | :--- | :--- | :--- | | **`file`** | **是** | File | - | 需要转写的音频文件。支持常见格式如 WAV, MP3, M4A, FLAC 等。 | | **`language`** | 否 | String | `"auto"` | 指定音频的语言。服务会优先使用此参数进行识别。设为 `"auto"` 则开启自动语言检测。 | | **`use_itn`** | 否 | Boolean | `true` | 是否启用逆文本正则化。强烈建议开启，它能让数字、单位等表达更规范。 | **参数详解：** 1. **`file` (音频文件)** 这是最重要的参数。你需要上传一个音频文件。服务内部会对音频进行解码和处理，所以你无需担心采样率、位深等问题，常见的格式都能很好地支持。 2. **`language` (语言)** 这个参数给了你控制权。虽然服务能自动检测语言，但如果你明确知道音频内容是什么语言，直接指定会得到更准确、更快速的结果。 - **`auto`**: 让模型自动检测语言。这是默认选项，非常方便。 - **`zh`**: 中文（普通话）。 - **`yue`**: 粤语。 - **`en`**: 英语。 - **`ja`**: 日语。 - **`ko`**: 韩语。 *建议：对于单一语言的音频，指定语言代码；对于混合语言或不确定的情况，使用 `auto`。* 3. **`use_itn` (逆文本正则化)** 这是一个能显著提升转写文本可读性和实用性的功能。 - **`true` (开启)**: 模型会将口语化的数字、单位等转换为标准的书面格式。 - 例如：`“今天花了三百二十一元”` → `“今天花了321元”` - 例如：`“百分之十五的增长率”` → `“15%的增长率”` - **`false` (关闭)**: 输出原始识别的文本。 *建议：在绝大多数场景下，都保持 `use_itn=true`，除非你需要原始的、未归一化的文本输出。* ### 2.3 响应结果解析 当接口调用成功，你会收到一个 JSON 格式的响应。这个响应结构清晰，包含了转写的文本和丰富的元信息。 **成功的响应示例：** ```json { "text": "大家好，欢迎使用SenseVoice语音识别服务。", "language": "zh", "segments": [ { "start": 0.0, "end": 3.5, "text": "大家好，", "emotion": "neutral", "events": [] }, { "start": 3.5, "end": 6.8, "text": "欢迎使用SenseVoice语音识别服务。", "emotion": "happy", "events": [] } ], "duration": 6.8, "sampling_rate": 16000 } ``` **响应字段说明：** | 字段名 | 类型 | 说明 | | :--- | :--- | :--- | | **`text`** | String | **转写的完整文本**。这是最核心的结果，将所有`segments`中的文本拼接而成。 | | **`language`** | String | 识别出的音频语言代码（如 `zh`, `en`）。如果你请求时指定了语言，这里会返回你指定的值；如果用的是 `auto`，这里就是模型检测的结果。 | | **`segments`** | Array[Object] | **音频分段信息**。这是一个数组，将整个音频按语义或时间切分成多个片段，每个片段包含更详细的信息。 | | ↳ `start` | Float | 该片段在音频中的开始时间（秒）。 | | ↳ `end` | Float | 该片段在音频中的结束时间（秒）。 | | ↳ `text` | String | 该片段对应的转写文本。 | | ↳ `emotion` | String | 该片段中检测到的主要情感。例如：`neutral` (中性), `happy` (高兴), `angry` (生气), `sad` (悲伤) 等。 | | ↳ `events` | Array[String] | 该片段中检测到的音频事件列表。例如：`[“laughter”]` (笑声), `[“cough”]` (咳嗽) 等。 | | **`duration`** | Float | 输入音频的总时长（秒）。 | | **`sampling_rate`** | Integer | 音频处理时使用的采样率（赫兹）。通常是16000Hz。 | **这个响应结构的好处：** - `text` 字段让你直接拿到最终结果。 - `segments` 字段为高级应用提供了可能，比如为视频生成带情感标签的字幕，或者分析一段会议录音中不同时间点的氛围。 ## 3. 错误码与常见问题排查 即使服务再稳定，调用过程中也可能遇到问题。了解错误码能帮你快速定位和解决。 ### 3.1 HTTP 状态码与错误响应 接口遵循 RESTful 风格，使用标准的 HTTP 状态码。 - **`200 OK`**: 请求成功，响应体即为上一节介绍的转写结果。 - **`400 Bad Request`**: **客户端请求有误**。这是最常见的错误，响应体是JSON格式的错误描述。 - **`500 Internal Server Error`**: **服务器内部错误**。通常是服务端处理音频或模型推理时出现了意外问题。 **当发生错误时（如400），响应格式如下：** ```json { "detail": "具体的错误描述信息" } ``` ### 3.2 常见错误场景与解决方案 下面我结合常见的“坑”，给出具体的错误信息和解决办法。 | 错误场景 | 可能返回的错误信息 (`detail`) | 原因分析与解决方案 | | :--- | :--- | :--- | | **未上传文件** | `“field ‘file’ is required.”` | 请求中缺少必需的 `file` 字段。检查你的代码，确保正确附加了音频文件。 | | **文件格式不支持** | `“Failed to decode audio file.”` | 上传的音频文件格式怪异或已损坏。尝试使用标准格式（如WAV, MP3）重新录制或转换。 | | **文件为空或太小** | `“Audio file is too short or empty.”` | 上传的音频文件没有有效内容或时长极短。请检查音频文件是否正常。 | | **语言参数错误** | `“Invalid language code ‘xyz’. Supported: [‘auto’， ‘zh’， …]”` | `language` 参数传入了不支持的语言代码。请核对上文支持的语言列表。 | | **服务器模型加载失败** | `“Model loading error.”` (通常伴随500错误) | 服务端首次启动时下载模型失败，或模型文件损坏。检查服务器网络，或确认模型缓存路径 `/root/ai-models/...` 下文件是否完整。 | | **服务器正忙或内部错误** | 无具体信息或Python异常栈 | 服务器压力过大或出现未处理的异常。查看服务日志 (`python3 app.py` 启动的控制台输出) 获取详细信息。 | **排查步骤建议：** 1. **检查基础连接**：先用浏览器访问 `http://localhost:7860/health`，看看服务是否健康运行。 2. **检查请求格式**：确认你的请求是 `POST` 方法，内容类型是 `multipart/form-data`，并且 `file` 字段正确。 3. **检查音频文件**：尝试用一个时长超过2秒、格式标准的WAV或MP3文件进行测试。 4. **查看服务日志**：在运行 `app.py` 的终端里，能看到最详细的错误信息，这是排查问题的金钥匙。 ## 4. 进阶使用与实践建议 掌握了基础调用和错误处理，我们来看看如何用得更好。 ### 4.1 处理长音频文件 SenseVoice-small-onnx 模型本身支持长音频。但通过 HTTP API 上传大文件时，需要注意： - **网络超时**：上传和转录大文件耗时较长，确保你的 HTTP 客户端设置了足够的超时时间。 - **内存考虑**：虽然模型高效，但一次性将很长的音频加载到内存，对服务端仍有压力。对于极长的音频（如数小时），考虑在客户端先进行切割，再分段发送。 ### 4.2 理解情感与事件检测 `segments` 里的 `emotion` 和 `events` 字段提供了额外的价值维度。 - **情感识别 (`emotion`)**：适用于客服质检、内容情感分析等场景。请注意，情感识别是基于音频特征的估算，在复杂环境下准确率会有波动。 - **音频事件检测 (`events`)**：可以用于过滤非语音部分（如咳嗽、敲门声），或在高亮精彩片段（如笑声、掌声）的应用中发挥作用。 ### 4.3 性能优化点 - **指定语言**：如果业务场景语言固定，在请求中明确指定 `language=’zh’` 等，可以避免自动检测的开销，速度更快。 - **连接复用**：如果需要频繁调用，请使用 HTTP 连接池（如 `requests.Session`），避免重复建立连接的开销。 - **模型预热**：如果是自建服务，在启动后可以先发送一个简短的测试请求，完成模型的初始化加载，这样第一个真实请求的延迟会更低。 ## 5. 总结 SenseVoice-small-onnx 通过一个设计清晰的 `/api/transcribe` 接口，提供了强大而便捷的语音识别能力。我们来回顾一下重点： 1. **接口调用很简单**：用 `curl` 或 `requests` 库，上传文件并指定参数即可。 2. **核心参数就三个**：`file`（必须），`language`（建议指定），`use_itn`（建议开启）。 3. **返回结果很丰富**：不仅拿到完整文本 (`text`)，还能获得带时间戳、情感和事件的分段详情 (`segments`)。 4. **错误排查有方向**：遇到 `400` 错误，仔细检查请求格式和文件；遇到 `500` 错误，查看服务端日志。 5. **进阶使用有价值**：利用好情感和事件信息，能让你的应用更智能。 无论是集成到在线会议工具里做实时字幕，还是分析客服录音，或者处理个人语音备忘录，这个服务都是一个非常可靠的选择。希望这份详细的文档能帮助你顺利上手，用好这个工具。 --- > **获取更多AI镜像** > > 想探索更多AI镜像和应用场景？访问 [CSDN星图镜像广场](https://ai.csdn.net/?utm_source=mirror_blog_end)，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。