SenseVoice-small-ONNX实战教程：Python调用funasr-onnx批量转写wav/mp3

SenseVoice-small-ONNX实战教程：Python调用funasr-onnx批量转写wav/mp3

你是不是经常需要处理大量的音频文件，比如会议录音、访谈记录或者播客内容，然后手动把它们转成文字？这个过程不仅耗时耗力，还容易出错。今天，我要给你介绍一个能彻底解决这个痛点的工具——SenseVoice-small-ONNX。

这是一个基于ONNX量化后的多语言语音识别模型，支持中文、粤语、英语、日语、韩语等多种语言。最棒的是，它提供了Python接口，让你能用几行代码就实现音频文件的批量转写。想象一下，以前需要花几个小时手动转录的工作，现在几分钟就能自动完成，而且准确率还很高。

接下来，我会手把手带你从零开始，部署这个服务，并用Python调用它来批量处理你的wav和mp3文件。无论你是开发者、内容创作者，还是需要处理语音数据的任何人，这篇教程都能让你快速上手。

1. 环境准备与快速部署

在开始写代码之前，我们需要先把服务环境搭建好。别担心，整个过程非常简单，跟着步骤走就行。

1.1 系统要求与依赖安装

首先，确保你的电脑上已经安装了Python（建议3.8或以上版本）。打开你的终端（Windows用户用命令提示符或PowerShell，Mac和Linux用户用终端）。

我们需要安装几个必要的Python包。在终端里输入下面这行命令：

pip install funasr-onnx gradio fastapi uvicorn soundfile jieba

这条命令会一次性安装所有需要的库：

• funasr-onnx：这是核心的语音识别库，提供了SenseVoice模型的ONNX版本接口。
• gradio和fastapi：用来构建Web界面和API服务，这样我们不仅能通过代码调用，还能通过网页上传文件。
• uvicorn：一个轻量级的ASGI服务器，用来运行我们的FastAPI应用。
• soundfile：用来读取和处理音频文件。
• jieba：中文分词工具，能提升中文语音识别的准确率。

安装过程大概需要一两分钟，取决于你的网速。如果一切顺利，你会看到“Successfully installed”的提示。

1.2 下载与配置模型

模型文件有点大（大约230MB），但好消息是，我们提供了缓存机制，你只需要下载一次。

服务会自动从指定的路径加载模型。默认情况下，它会检查/root/ai-models/danieldong/sensevoice-small-onnx-quant这个目录。如果你第一次运行，模型不存在，它会自动下载。

不过，为了更稳定，我建议你提前准备好模型文件。你可以通过这个链接手动下载，然后放到对应的目录里。如果你不知道放哪里，没关系，直接运行服务，它也会帮你处理好。

1.3 启动语音识别服务

环境准备好后，启动服务就一行命令的事。在你的项目目录下，创建一个新的Python文件，比如叫app.py，然后把服务启动代码放进去。

不过，更简单的方法是直接使用我们提供的启动脚本。打开终端，进入你存放代码的目录，运行：

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

如果你没有现成的app.py，别急，我马上会告诉你怎么创建。现在先假设你已经有了。

运行命令后，你会看到一些启动日志，最后出现“Application startup complete”之类的提示，就说明服务启动成功了。

这时候，打开你的浏览器，访问http://localhost:7860，你应该能看到一个简洁的Web上传界面。如果能看到，恭喜你，服务已经正常运行了！

2. 核心功能与基础使用

服务跑起来了，我们来看看它到底能做什么，以及怎么通过网页快速试用。

2.1 服务的主要能力

这个SenseVoice-small-ONNX服务可不是简单的语音转文字，它有几个很实用的特性：

多语言自动识别：你不需要告诉它音频是什么语言，它能自动检测超过50种语言，包括中文、英语、日语、韩语、粤语等等。对于混合语言的音频（比如中英夹杂），它也能很好地处理。

富文本转写：除了把语音转成文字，它还能识别出说话人的情感（比如高兴、生气、平静），以及音频中的事件（比如笑声、掌声、背景音乐）。这在分析会议录音或访谈内容时特别有用。

飞快的速度：经过ONNX量化优化后，模型推理速度非常快。官方数据是，10秒钟的音频，转写只需要大约70毫秒。这意味着处理一小时的音频文件，理论上几分钟就能搞定。

多种使用方式：你可以通过网页直接上传文件，也可以通过REST API用代码调用，非常灵活。

2.2 通过Web界面快速试用

在浏览器打开http://localhost:7860后，你会看到一个简单的上传界面。通常会有这几个部分：

1. 文件上传区域：点击或者拖拽你的音频文件（wav、mp3、m4a、flac等格式都支持）到这里。
2. 语言选择：一般默认是“auto”（自动检测），你也可以手动指定，比如“zh”代表中文，“en”代表英语。
3. ITN开关：ITN是“逆文本正则化”的缩写。简单说，就是它会智能地把“百分之二十”转换成“20%”，把“三点五”转换成“3.5”。建议保持开启，这样转写结果更规范。
4. 转写按钮：上传文件并设置好选项后，点击按钮开始转写。

稍等几秒，页面就会显示转写结果。你可以看到识别出的文字，如果音频中有多个人说话，还会用不同的标签区分说话人。

除了转写界面，服务还提供了两个有用的地址：

• http://localhost:7860/docs：这是自动生成的API文档页面，你可以在这里看到所有可用的接口和参数，甚至可以直接在网页上测试API调用。
• http://localhost:7860/health：健康检查页面，如果返回“healthy”，说明服务运行正常。

3. Python批量转写实战

网页试用很方便，但真正的威力在于用Python批量处理。下面我就带你写一个完整的脚本，一次性转写整个文件夹里的音频文件。

3.1 单个音频文件转写

我们先从简单的开始，看看怎么用Python转写单个文件。创建一个新的Python文件，比如叫batch_transcribe.py，然后输入以下代码：

from funasr_onnx import SenseVoiceSmall import os # 1. 初始化模型 # 指定模型路径，如果模型不存在会自动下载 model_path = "/root/ai-models/danieldong/sensevoice-small-onnx-quant" model = SenseVoiceSmall(model_path, batch_size=1, quantize=True) print("模型加载成功！") # 2. 转写单个音频文件 audio_file = "你的音频文件.wav" # 替换成你的文件路径 result = model([audio_file], language="auto", use_itn=True) # 3. 输出结果 print("转写结果：") print(result[0]) # result是一个列表，第一个元素就是转写文本

这段代码做了三件事：

1. 初始化SenseVoiceSmall模型，指定模型路径和参数。batch_size=1表示一次处理一个文件，quantize=True表示使用量化后的模型，速度更快。
2. 调用模型的转写功能，传入音频文件路径。language="auto"让模型自动检测语言，use_itn=True开启逆文本正则化。
3. 打印转写结果。

运行这个脚本，如果一切正常，你会看到音频文件的文字内容被打印出来。第一次运行可能会慢一点，因为要加载模型，之后就会很快了。

3.2 批量转写整个文件夹

单个文件处理很简单，但我们要的是批量处理。下面这个函数可以处理一个文件夹里所有的音频文件：

import glob from pathlib import Path def transcribe_folder(folder_path, output_dir="transcripts"): """ 批量转写文件夹内的所有音频文件 Args: folder_path: 音频文件夹路径 output_dir: 转写结果保存目录 """ # 支持常见的音频格式 audio_extensions = ['*.wav', '*.mp3', '*.m4a', '*.flac', '*.ogg'] audio_files = [] # 收集所有音频文件 for ext in audio_extensions: audio_files.extend(glob.glob(os.path.join(folder_path, ext))) if not audio_files: print(f"在 {folder_path} 中没有找到音频文件") return print(f"找到 {len(audio_files)} 个音频文件") # 创建输出目录 os.makedirs(output_dir, exist_ok=True) # 初始化模型（只需一次） model_path = "/root/ai-models/danieldong/sensevoice-small-onnx-quant" model = SenseVoiceSmall(model_path, batch_size=min(10, len(audio_files)), quantize=True) # 批量转写 for i, audio_file in enumerate(audio_files, 1): print(f"正在处理 ({i}/{len(audio_files)}): {os.path.basename(audio_file)}") try: # 转写当前文件 results = model([audio_file], language="auto", use_itn=True) transcript = results[0] # 保存结果到文本文件 output_file = os.path.join( output_dir, f"{Path(audio_file).stem}_transcript.txt" ) with open(output_file, 'w', encoding='utf-8') as f: f.write(transcript) print(f" 已保存到: {output_file}") except Exception as e: print(f" 处理失败: {str(e)}") print("\n批量转写完成！") # 使用示例 if __name__ == "__main__": # 替换成你的音频文件夹路径 audio_folder = "你的音频文件夹路径" transcribe_folder(audio_folder)

这个函数的功能很全面：

• 自动扫描文件夹里的wav、mp3、m4a、flac、ogg格式的音频文件
• 显示处理进度，告诉你正在处理第几个文件
• 把每个音频的转写结果保存为单独的文本文件
• 文件名和原音频文件对应，只是扩展名改成_transcript.txt
• 加了异常处理，即使某个文件出错也不会影响其他文件

3.3 高级功能：情感识别与说话人分离

SenseVoice-small-ONNX不只是转写文字，还能识别情感和区分不同说话人。下面这个示例展示如何使用这些高级功能：

def transcribe_with_details(audio_file): """ 转写音频并获取详细信息 """ from funasr_onnx import SenseVoiceSmall model_path = "/root/ai-models/danieldong/sensevoice-small-onnx-quant" model = SenseVoiceSmall(model_path, batch_size=1, quantize=True) # 转写，获取完整结果（包含时间戳、情感等信息） # 注意：实际API可能返回字典或特定对象，这里用伪代码示意 result = model.transcribe_with_details(audio_file, language="auto") # 假设result是一个字典，包含以下信息 # 实际使用时请查看官方文档或打印result查看结构 transcript = result.get("text", "") segments = result.get("segments", []) # 分段信息 emotions = result.get("emotions", []) # 情感分析 speakers = result.get("speakers", []) # 说话人信息 print("完整转写文本：") print(transcript) print("\n" + "="*50 + "\n") print("分段详情（带时间戳）：") for seg in segments: start = seg.get("start", 0) end = seg.get("end", 0) text = seg.get("text", "") print(f"[{start:.2f}s - {end:.2f}s]: {text}") if emotions: print("\n情感分析：") for emotion in emotions: print(f"- {emotion}") if speakers and len(speakers) > 1: print(f"\n检测到 {len(speakers)} 个说话人") return result # 使用示例 if __name__ == "__main__": result = transcribe_with_details("你的音频文件.wav")

这段代码展示了如何获取转写的详细信息。实际使用时，你需要查看funasr-onnx的官方文档，了解返回结果的具体格式。通常，这些信息对于会议记录分析、访谈内容整理、客服质检等场景非常有用。

4. 实战技巧与常见问题

掌握了基本用法后，我再分享一些实战技巧，帮你更好地使用这个工具。

4.1 性能优化建议

如果你要处理大量音频文件，这些优化建议能让程序跑得更快：

批量处理策略：SenseVoiceSmall初始化时可以设置batch_size参数，这个值表示一次处理多少个文件。如果你的内存足够大，可以适当调大这个值（比如10或20），这样能显著提升处理速度。但要注意，太大的批次可能会占用过多内存。

# 根据文件数量动态设置batch_size file_count = len(audio_files) batch_size = min(10, file_count) # 不超过10，避免内存不足 model = SenseVoiceSmall(model_path, batch_size=batch_size, quantize=True)

文件预处理：如果音频文件特别长（比如超过1小时），可以考虑先分割成小段，比如每10分钟一段。这样有两个好处：一是避免内存不足，二是如果某段处理失败，不会影响整个文件。

并行处理：对于大量文件，你可以用Python的concurrent.futures模块实现并行处理：

from concurrent.futures import ThreadPoolExecutor import threading def process_single_file(audio_file, output_dir, model): """处理单个文件的函数，用于并行处理""" # ... 处理逻辑 ... pass # 创建线程池并行处理 def parallel_transcribe(audio_files, output_dir, max_workers=4): model_path = "/root/ai-models/danieldong/sensevoice-small-onnx-quant" model = SenseVoiceSmall(model_path, batch_size=1, quantize=True) with ThreadPoolExecutor(max_workers=max_workers) as executor: futures = [] for audio_file in audio_files: future = executor.submit(process_single_file, audio_file, output_dir, model) futures.append(future) # 等待所有任务完成 for future in futures: future.result()

4.2 常见问题与解决方法

在实际使用中，你可能会遇到一些问题，这里我整理了几个常见的：

问题1：模型下载慢或失败

• 解决方法：可以尝试手动下载模型文件。模型通常托管在Hugging Face或ModelScope上，找到SenseVoice-small-ONNX的页面，下载model_quant.onnx文件（大约230MB），然后放到/root/ai-models/danieldong/sensevoice-small-onnx-quant目录下。如果这个目录不存在，就自己创建。

问题2：内存不足

• 症状：处理大文件或批量处理时程序崩溃，报内存错误。
• 解决方法：减小batch_size，比如从10降到5或2。或者把长音频文件分割成小段处理。

问题3：转写准确率不够高

• 可能原因：音频质量差、背景噪音大、说话人口音重、语速过快等。
• 解决方法：尝试先用音频编辑软件降噪、提高音量。对于重要内容，可以手动校对修改。另外，确保使用最新版本的funasr-onnx库。

问题4：不支持某种音频格式

• 解决方法：SenseVoice-small-ONNX支持常见的音频格式，但如果你有特殊格式的文件，可以先用FFmpeg转换：

  # 安装ffmpeg（如果还没安装） # Ubuntu/Debian: sudo apt install ffmpeg # macOS: brew install ffmpeg # 转换为wav格式 ffmpeg -i input.特殊格式 output.wav

问题5：如何获取说话人分离和情感识别结果

• 解决方法：查看funasr-onnx的官方文档，找到返回完整结果的方法。通常不是用model()直接调用，而是用model.transcribe()或类似的方法，它会返回一个包含更多信息的字典或对象。

4.3 实际应用场景示例

这个工具在实际工作中有很多应用场景，我举几个例子：

场景1：会议记录自动化每周团队会议都有录音，以前需要人工整理会议纪要，现在可以自动转写。你只需要把录音文件放到一个文件夹，运行批量转写脚本，几分钟就能得到文字稿。再结合说话人分离功能，还能知道谁说了什么。

场景2：播客内容整理如果你是播客创作者，每期节目录制后都需要整理文字稿用于发布。用这个工具，一小时的节目，转写加校对可能只需要半小时，大大提高了效率。

场景3：外语学习材料制作找到外语听力材料，用这个工具转写成文字，然后对照原文学习。支持多语言的特点特别适合语言学习者。

场景4：客服录音分析批量处理客服通话录音，不仅转写成文字，还能分析客户情感（满意、不满、愤怒等），帮助改进服务质量。

5. 总结

通过这篇教程，你应该已经掌握了SenseVoice-small-ONNX语音识别服务的使用方法。我们来回顾一下重点：

核心收获：

1. 快速部署：只需几行命令就能搭建一个功能强大的语音识别服务，支持网页界面和API调用。
2. 批量处理：用Python脚本可以轻松处理成百上千个音频文件，大大节省人工转录时间。
3. 多语言支持：自动识别中文、英语、日语、韩语、粤语等50多种语言，对混合语言音频也有不错的效果。
4. 高级功能：除了基本转写，还支持情感识别、说话人分离、逆文本正则化等实用功能。

使用建议：

• 对于常规使用，Web界面（http://localhost:7860）最方便，适合偶尔处理几个文件。
• 对于批量处理，一定要用Python脚本，可以自动化整个流程。
• 处理大量文件时，注意内存使用，适当调整batch_size参数。
• 重要内容建议人工校对，目前AI转写的准确率虽然很高，但还不是100%。

下一步探索： 如果你对这个工具感兴趣，可以尝试：

• 结合其他工具，比如把转写结果自动翻译成其他语言
• 开发一个简单的Web应用，让团队成员都能上传音频文件
• 尝试不同的模型参数，看看对转写效果的影响

语音识别技术正在快速发展，像SenseVoice-small-ONNX这样的工具让普通开发者也能轻松使用先进的AI能力。希望这篇教程能帮你节省大量时间，让你更专注于内容创作或数据分析，而不是繁琐的转录工作。

获取更多AI镜像

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