零基础教程：3步搞定SenseVoice-Small语音识别API调用

你是不是想给自己的应用加个语音转文字功能，但一看到“模型部署”、“API调用”这些词就头疼？觉得那是大厂工程师才搞得定的高级活？

别担心，今天我就带你换个思路。不用懂深度学习，不用配复杂环境，甚至不用写几行代码，就能把专业级的语音识别能力集成到你的项目里。秘诀就是找到一个“开箱即用”的预置服务，然后像点外卖一样调用它。

SenseVoice-Small就是这样一个“宝藏模型”。它来自阿里，主打轻量、快速、多语言，尤其对中文和粤语的支持特别好。更棒的是，现在有开发者把它打包成了一个完整的ONNX量化服务镜像，里面连Web界面和API都给你写好了。你只需要启动它，然后通过简单的HTTP请求，就能把音频变成带情感标签的文本。

这篇文章就是为你准备的“傻瓜式”操作指南。我会用最直白的话，带你走完从启动服务到成功调用的完整三步。无论你是前端开发、产品经理，还是对技术好奇的爱好者，都能跟着做下来。我们的目标很简单：让你在10分钟内，亲眼看到语音识别的神奇效果。

1. 环境准备：一分钟启动你的专属语音识别服务

1.1 为什么选择这个预置镜像？

在开始动手之前，我们先聊聊为什么推荐你直接用这个打包好的镜像。自己从头搭建一个语音识别环境有多麻烦？我来给你数数：

首先，你得安装Python、PyTorch、CUDA驱动，版本还得一一对应，错一个就可能报一堆你看不懂的错误。然后，你要去网上下载几百兆的模型文件，速度慢还不稳定。最后，你还得自己写一个Web服务，把模型包进去，处理HTTP请求，调试端口……这一套下来，没个大半天搞不定，而且绝大部分时间都在解决环境问题，而不是真正用上功能。

这个 sensevoice-small-语音识别-onnx模型(带量化后) 镜像，就是来帮你跳过所有这些坑的。它就像一台预装好所有软件和游戏的“游戏主机”，你插上电就能玩。具体来说，它里面已经包含了：

• 完整的运行环境：Ubuntu系统、Python、所有必需的库（funasr-onnx, gradio, fastapi等）。
• 下载好的模型：SenseVoice-Small的ONNX量化模型，已经放在指定路径，你不用再下载。
• 现成的应用程序：一个基于Gradio的Web界面和一个基于FastAPI的API服务，代码都写好了。
• 优化过的配置：模型经过了量化处理，体积更小（约230MB），推理速度更快，对硬件要求也更低。

你的任务从“搭建一个系统”变成了“使用一个服务”，难度直线下降。

1.2 启动服务的两种简单方法

拿到镜像后，怎么让它跑起来呢？这里提供两种最通用的方法，你可以根据你的情况选择。

方法一：在支持Docker的环境运行（推荐）

如果你有自己的云服务器、本地电脑（支持Docker），或者在使用一些提供容器服务的云平台，这是最直接的方式。假设镜像已经打包成了Docker镜像，你只需要一行命令：

docker run -p 7860:7860 -p 8000:8000 your-sensevoice-image-name

这行命令的意思是：运行这个镜像，并把容器内部的7860和8000端口映射到你电脑的相同端口上。运行成功后，服务就在后台启动了。

方法二：在提供预置镜像的平台上启动

现在很多AI算力平台（比如CSDN星图）都提供了“镜像广场”功能。你只需要：

1. 在平台上找到这个名为“sensevoice-small-语音识别-onnx模型(带量化后)”的镜像。
2. 点击“启动”或“部署”。
3. 选择你想要的算力规格（CPU或GPU都可以，GPU更快）。
4. 等待一两分钟，平台会自动完成所有部署工作，并给你一个访问地址。

这种方式完全不用你操心服务器、网络这些底层问题，最适合快速验证想法。

无论用哪种方法，当服务成功启动后，你都会获得一个访问入口。接下来，我们就可以去真正地使用它了。

2. 快速上手：通过Web界面零代码体验

2.1 访问Web UI，像用App一样简单

服务启动后，最快速的体验方式就是使用它自带的Web界面。这就像打开一个网页版的语音识别工具，完全不需要写任何代码。

根据镜像文档的说明，这个Web服务通常运行在 7860 端口。怎么访问呢？

• 如果你在本地电脑运行：打开浏览器，直接访问 http://localhost:7860。
• 如果你在云平台或远程服务器运行：平台会给你一个外网可访问的地址，比如 http://你的服务器IP:7860 或一个专属域名。

打开这个链接，你会看到一个简洁的网页界面。这个界面是用Gradio框架搭建的，交互非常直观。你可能会看到以下几个核心区域：

1. 音频上传区域：一个让你拖放或点击选择音频文件的地方。
2. 语言选择下拉框：可以选择“自动检测”、“中文(zh)”、“英语(en)”、“粤语(yue)”等。
3. 一个“提交”或“转写”按钮。
4. 结果显示区域：用来展示识别后的文字。

2.2 上传音频，立刻看到识别结果

现在，让我们来实际测试一下。找一段你想转成文字的音频文件，格式支持WAV、MP3、M4A等常见格式。

操作步骤：

1. 点击上传区域，选择你的音频文件（比如一段你说“今天天气不错，我们出去走走吧”的录音）。
2. 在语言选择框里，可以选“auto”（自动检测）或者根据你的音频内容手动选择，比如“zh”（中文）。
3. 点击“提交”按钮。

稍等片刻（对于短音频几乎是瞬间），下方的结果框里就会显示出识别出的文字。如果一切顺利，你就能看到“今天天气不错，我们出去走走吧”这句话。

试试更多功能：

• 试试英文音频：上传一段英文录音，语言选择“en”或“auto”，看看识别效果。
• 试试“逆文本正则化(ITN)”：界面上可能有一个“使用ITN”的复选框。勾选它再识别，看看效果。ITN会把“百分之二十”转换成“20%”，把“三点五”转换成“3.5”，让文本更规范。
• 看看还能返回什么：除了文本，这个服务还可能返回识别出的语言类型、音频时长等信息，留意一下结果展示。

通过这个Web界面，你已经完成了最核心的语音转文字功能验证。它直观地证明了服务是正常工作的，模型效果也符合预期。接下来，我们要学习更强大的方式——通过API调用，把这能力集成到你自己的程序里。

3. 核心实战：通过API将能力集成到你的程序

3.1 调用REST API，一行命令出结果

Web界面虽好，但不能自动化。要让你的软件、脚本或网站能使用语音识别，必须通过API（应用程序编程接口）。这个镜像已经提供了一个标准的REST API。

API的地址通常是服务地址加上 /api/transcribe 路径，端口一般是 7860（和Web界面相同）或专门的API端口 8000。最通用的调用方法是使用 curl 命令，在终端（Linux/Mac）或命令提示符/PowerShell（Windows）里操作。

基础调用示例： 假设你的服务地址是 http://localhost:7860，你有一个名为 my_audio.wav 的音频文件。

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

逐行解释：

• -X POST：表示这是一个POST请求。
• -F "file=@my_audio.wav"：以表单形式上传文件，@后面是你的本地音频文件路径。
• -F "language=auto"：设置语言参数为自动检测。
• -F "use_itn=true"：开启逆文本正则化。

执行命令后，终端会直接打印出JSON格式的识别结果，类似于：

{
  "text": "今天天气不错，我们出去走走吧。",
  "language": "zh",
  "duration": 3.2
}

恭喜你！你已经通过命令行成功调用了语音识别API。这意味着任何能发送HTTP请求的程序，现在都可以使用这个功能了。

3.2 使用Python代码，灵活集成

对于开发者来说，用Python调用API是最常见的方式。你可以使用 requests 这个非常流行的库。

首先，确保安装了requests库：pip install requests

然后，可以编写如下Python脚本：

import requests

# 1. 定义API地址和音频文件路径
api_url = "http://localhost:7860/api/transcribe"
audio_file_path = "path/to/your/audio.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("识别文本:", result.get('text'))
    print("检测语言:", result.get('language'))
    print("音频时长:", result.get('duration'), "秒")
else:
    print("请求失败，状态码:", response.status_code)
    print("错误信息:", response.text)

把 audio_file_path 换成你的文件路径，运行这个脚本，就能在Python环境中得到识别结果。

进阶用法：处理多个文件 如果你想批量处理一个文件夹里的所有音频文件，可以这样写：

import requests
import os

api_url = "http://localhost:7860/api/transcribe"
audio_folder = "path/to/your/audio_folder"

for filename in os.listdir(audio_folder):
    if filename.endswith(('.wav', '.mp3', '.m4a')):
        file_path = os.path.join(audio_folder, filename)
        files = {'file': open(file_path, 'rb')}
        
        try:
            resp = requests.post(api_url, files=files, data={'language': 'auto'})
            if resp.status_code == 200:
                print(f"{filename}: {resp.json().get('text')[:50]}...")  # 打印前50个字符
            else:
                print(f"{filename}: 识别失败")
        except Exception as e:
            print(f"{filename}: 请求异常 - {e}")
        finally:
            files['file'].close()  # 记得关闭文件

通过这个脚本，你可以轻松实现音频文件的批量转写。

3.3 直接使用模型库（高级可选）

除了HTTP API，这个镜像的环境里也预装了 funasr-onnx 库，允许你直接在Python代码中加载模型进行推理。这种方式延迟更低，适合对性能要求极高的场景。

在你的Jupyter Notebook或Python脚本中（确保在服务所在的环境运行），可以这样写：

from funasr_onnx import SenseVoiceSmall

# 指定模型路径（镜像中已预置）
model_dir = "/root/ai-models/danieldong/sensevoice-small-onnx-quant"

# 初始化模型
model = SenseVoiceSmall(model_dir, batch_size=1, quantize=True)

# 进行识别
audio_paths = ["audio1.wav", "audio2.wav"]  # 音频文件列表
results = model(audio_paths, language="auto", use_itn=True)

# 打印结果
for i, result in enumerate(results):
    print(f"音频 {audio_paths[i]} 的识别结果：")
    print(result)  # result 就是识别出的文本字符串
    print("-" * 20)

这种方法跳过了HTTP通信的开销，速度最快，但要求你的代码必须运行在和模型同一个环境中。

4. 总结

回顾一下，我们只用了三步就完成了从零到一的语音识别API调用：

1. 启动服务：利用预置的 sensevoice-small-onnx 镜像，一分钟内启动一个包含Web界面和API的完整语音识别服务，跳过了所有环境配置的麻烦。
2. 界面验证：通过访问 http://地址:7860 的Web界面，上传音频文件，零代码验证核心功能，直观感受识别效果。
3. API集成：通过 curl 命令或简单的Python requests 库代码，调用 /api/transcribe 接口，将语音识别能力轻松集成到你自己的任何应用程序或脚本中。

SenseVoice-Small模型在这个量化版本下，表现出色：支持中、英、粤、日、韩等多种语言自动识别，推理速度快，资源占用低。无论是想给应用添加语音输入，还是批量处理录音文件，这个方案都提供了一个极其便捷的起点。

---

获取更多AI镜像

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