SenseVoice-Small ONNX保姆级教程：Mac M1/M2芯片本地部署全流程

SenseVoice-Small ONNX保姆级教程：Mac M1/M2芯片本地部署全流程

你是不是也想在Mac上搞一个本地语音识别工具，但又担心自己的M1/M2芯片跑不动？或者被那些动辄几十G的模型和复杂的配置劝退？

今天，我就带你手把手搞定一个轻量级的本地语音识别神器——SenseVoice-Small ONNX版。它最大的特点就是“小”和“快”，经过Int8量化后，内存占用直接降了75%，在MacBook上跑起来毫无压力。你上传一段音频，它就能自动识别成带标点的文字，整个过程完全在本地进行，你的录音数据不会上传到任何服务器。

接下来，我会从零开始，带你完成从环境准备到实际使用的全流程。就算你之前没怎么接触过Python或者命令行，跟着步骤走也能搞定。

1. 环境准备：给你的MacBook打好基础

在开始部署之前，我们需要确保电脑上已经安装了必要的软件。别担心，步骤都很简单。

1.1 安装Homebrew（如果你还没有的话）

Homebrew是Mac上的一个软件包管理器，可以让我们非常方便地安装各种开发工具。打开你的“终端”应用（在“应用程序”->“实用工具”里可以找到），然后输入下面这行命令：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

按回车后，根据提示操作即可。安装过程中可能会要求你输入电脑的登录密码。

1.2 安装Python和必要的库

SenseVoice-Small ONNX工具是用Python写的，所以我们先要确保有合适的Python环境。

建议使用Python 3.9或3.10版本，兼容性最好。你可以通过Homebrew来安装：

brew install python@3.9

安装完成后，我们还需要几个关键的Python库。在终端里依次执行以下命令：

# 安装核心的语音识别框架 pip3 install funasr # 安装ONNX运行时，这是模型加速的关键 pip3 install onnxruntime # 安装Streamlit，用来构建我们那个简洁的网页操作界面 pip3 install streamlit # 安装模型管理工具 pip3 install modelscope

这些命令会从网络下载并安装所需的软件包，稍等片刻即可。

2. 获取工具代码与模型

环境准备好了，接下来我们把工具本身的代码和已经优化好的模型文件拿到手。

2.1 下载工具代码

你可以直接从代码托管平台（如GitHub）下载这个项目的压缩包，或者使用git命令克隆（如果你安装了git的话）。这里假设你下载了一个ZIP包并解压到了桌面上一个名为sensevoice-onnx-tool的文件夹里。

2.2 下载Int8量化模型

这是最关键的一步。原始的SenseVoice-Small模型比较大，而这里我们使用的是经过Int8量化的特殊版本。你可以把它理解成把模型“瘦身”了，在几乎不影响识别准确率的情况下，大大减少了它对内存的占用。

你需要从指定的地方下载这个量化模型文件（通常是一个.onnx文件），然后把它放到你项目文件夹里的model子目录下。如果model文件夹不存在，就新建一个。

完成后，你的文件夹结构看起来应该是这样的：

sensevoice-onnx-tool/ ├── app.py # 主程序文件 ├── requirements.txt # 依赖库列表 └── model/ └── sensevoice_small_int8.onnx # 下载的量化模型文件

3. 快速启动：一键运行识别工具

所有东西都就位了，现在让我们启动它。整个过程非常简单。

3.1 启动服务

打开终端，使用cd命令进入到你的项目文件夹。比如，如果你的文件夹在桌面：

cd ~/Desktop/sensevoice-onnx-tool

然后，运行下面这个启动命令：

streamlit run app.py

你会看到终端里开始滚动一些信息，最后会出现这样两行：

You can now view your Streamlit app in your browser. Local URL: http://localhost:8501 Network URL: http://192.168.x.x:8501

3.2 打开操作界面

现在，打开你Mac上的任意浏览器（Safari、Chrome都可以），在地址栏里输入http://localhost:8501然后按回车。

一个简洁、清爽的网页界面就会出现在你面前。这意味着你的本地语音识别服务已经成功启动并运行起来了！

4. 操作指南：如何使用这个识别工具

界面打开了，我们来看看怎么用它。整个操作流程就三步：上传、点击、查看。

4.1 第一步：上传你的音频文件

在网页界面上，你会看到一个很明显的按钮，写着“📂 上传音频文件”或者类似字样。

• 点击它，会弹出你电脑的文件选择窗口。
• 支持格式：你可以上传WAV、MP3、M4A、OGG、FLAC这些常见的音频格式，不需要事先转换。
• 小建议：虽然理论上支持长音频，但为了快速看到效果且避免占用太多内存，建议先上传一段1-3分钟的音频试试。

4.2 第二步：开始识别

上传完文件后，界面上会出现一个“🚀 开始识别”或“识别”按钮。

• 放心点击它。点击后，按钮可能会变成“正在推理...”，表示工具正在后台忙活。
• 后台在做什么：这个过程是全自动的。工具会先检查你的音频，然后用我们加载好的量化模型进行语音识别，识别完还会自动给文字加上合适的标点符号。

4.3 第三步：查看和复制结果

识别完成后，界面上的状态会变成“✅ 完成”。

• 结果在哪：识别出来的文字会显示在一个大的文本框里，这个文本框通常叫做“识别结果”。
• 文字质量：你会看到一段带有逗号、句号等标点的完整文本，可读性很高。里面的数字也会被自动转成“100”、“2023年”这种书写格式。
• 怎么用：你可以直接用鼠标在文本框里全选（Command+A），然后复制（Command+C）这段文字，粘贴到你的笔记、文档或者任何需要的地方。

5. 可能遇到的问题与解决办法

第一次运行，可能会碰到一些小状况，别慌，基本都是常见问题。

5.1 首次运行标点模型加载慢

现象：第一次点击“识别”时，等待时间比较长（可能几十秒），终端里在下载东西。原因：这是正常的！工具除了主模型，还需要一个专门加标点的小模型。这个模型会在第一次使用时，从国内的ModelScope平台自动下载并缓存到你的电脑里。解决：耐心等待第一次下载完成。之后再用，就会直接从本地缓存加载，速度飞快。

5.2 端口被占用

现象：运行streamlit run app.py时提示端口8501已被占用。解决：关掉之前可能没正确退出的终端窗口，或者用这个命令指定另一个端口：

streamlit run app.py --server.port 8502

然后在浏览器访问http://localhost:8502即可。

5.3 内存不足警告

现象：处理很长（比如超过30分钟）的音频文件时，可能提示内存不足。解决：这是本地工具的物理限制。建议先将长音频用剪辑软件（比如Mac自带的“语音备忘录”或QuickTime Player）分割成10分钟以内的小段，分批识别。

6. 总结

好了，到这里，你已经成功在Mac M1/M2上部署了一个完全本地运行的语音识别工具。我们来回顾一下你都完成了什么：

1. 搭建了环境：安装了Python和几个必要的库，给工具运行铺好了路。
2. 部署了轻量模型：使用了经过Int8量化的SenseVoice-Small模型，让它能在你的MacBook上流畅运行，不卡顿。
3. 启动了一个本地服务：通过Streamlit，你拥有了一个通过浏览器就能操作的图形界面，点点鼠标就能用。
4. 实现了语音转文字：上传音频，一键识别，得到带标点的规整文字，并且所有过程都在你本地电脑完成，隐私有保障。

这个工具特别适合一些日常场景：比如整理会议录音、将访谈内容转为文字稿、或者为视频快速生成字幕草稿。它可能不是功能最全的，但绝对是上手最快、对硬件最友好的本地方案之一。

你可以多试试不同口音、不同背景噪音的音频，看看它的识别效果。玩得开心！

获取更多AI镜像

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