SenseVoiceSmall代码实例：批量处理音频文件的Python脚本

1. 引言：为什么需要批量处理？

你有没有遇到过这种情况：手头有几十个会议录音、客户访谈或课程音频，想快速转成文字做归档？一个个上传到 WebUI 点击识别，不仅费时，还容易出错。这时候，自动化脚本就是你的救星。

本文要讲的，不是怎么用 Gradio 点点点，而是如何利用SenseVoiceSmall 模型的 Python API，写一个能自动遍历文件夹、批量识别音频、输出带情感和事件标签的文字结果的实用脚本。

我们基于阿里开源的funasr库，结合模型自带的富文本后处理能力，打造一个真正能“干活”的工具。无论你是做内容分析、客户服务质检，还是学术研究，这个脚本能帮你把重复劳动交给机器。

核心价值：
学完这篇，你将掌握：
如何在代码中调用 SenseVoiceSmall 模型
如何实现多语言自动识别与情感/事件标注
如何批量处理整个文件夹的音频
输出结构化文本，方便后续分析

2. 环境准备与模型加载

2.1 安装依赖

确保你的环境已经安装了必要的库。如果你使用的是官方镜像，大部分依赖已经就绪，只需确认以下包：

pip install funasr modelscope gradio av

funasr：阿里巴巴语音识别工具包，支持 SenseVoiceSmall。
av：用于高效音频解码（比 librosa 快很多）。
gradio：虽然我们不用 WebUI，但它内部依赖可能被 funasr 调用。

2.2 初始化模型

这是最关键的一步。我们需要加载SenseVoiceSmall模型，并配置好参数，让它能处理长音频、检测情感和声音事件。

from funasr import AutoModel from funasr.utils.postprocess_utils import rich_transcription_postprocess import os # 加载模型 model = AutoModel( model="iic/SenseVoiceSmall", trust_remote_code=True, device="cuda:0", # 使用 GPU 加速，若无 GPU 改为 "cpu" vad_model="fsmn-vad", # 启用语音活动检测 vad_kwargs={"max_single_segment_time": 30000}, # 单段最长 30 秒 )

参数说明：

参数	作用
`trust_remote_code=True`	允许加载远程自定义模型代码
`device="cuda:0"`	使用第一块 GPU，提升推理速度
`vad_model`	启用语音分割，避免静音段干扰
`max_single_segment_time`	控制每段语音长度，防止显存溢出

3. 批量处理脚本设计

3.1 核心逻辑拆解

我们要实现的功能是：

给定一个音频文件夹路径
遍历所有.wav,.mp3等常见格式
对每个文件调用模型识别
将结果保存为同名.txt文件
支持自动语言识别或指定语言

3.2 完整脚本实现

import os from funasr import AutoModel from funasr.utils.postprocess_utils import rich_transcription_postprocess # 初始化模型（只加载一次，复用） model = AutoModel( model="iic/SenseVoiceSmall", trust_remote_code=True, device="cuda:0", vad_model="fsmn-vad", vad_kwargs={"max_single_segment_time": 30000}, ) def batch_transcribe_folder( input_dir: str, output_dir: str, language: str = "auto", # 可选: zh, en, yue, ja, ko use_itn: bool = True, ): """ 批量转录音频文件夹 Args: input_dir: 音频文件夹路径 output_dir: 输出文本文件夹路径 language: 语言设置，"auto" 表示自动识别 use_itn: 是否启用文本正规化（如数字转汉字） """ # 创建输出目录 os.makedirs(output_dir, exist_ok=True) # 支持的音频格式 audio_exts = {".wav", ".mp3", ".flac", ".m4a", ".ogg"} # 遍历文件夹 for filename in os.listdir(input_dir): file_path = os.path.join(input_dir, filename) # 跳过非文件和非音频 if not os.path.isfile(file_path): continue _, ext = os.path.splitext(filename.lower()) if ext not in audio_exts: print(f"跳过非音频文件: {filename}") continue print(f"正在处理: {filename} ...") try: # 调用模型识别 res = model.generate( input=file_path, cache={}, language=language, use_itn=use_itn, batch_size_s=60, merge_vad=True, merge_length_s=15, ) if len(res) == 0: result_text = "识别失败：未检测到有效语音" else: raw_text = res[0]["text"] # 使用内置后处理清洗富文本标签 clean_text = rich_transcription_postprocess(raw_text) result_text = clean_text # 保存为同名 .txt 文件 txt_filename = os.path.splitext(filename)[0] + ".txt" txt_path = os.path.join(output_dir, txt_filename) with open(txt_path, "w", encoding="utf-8") as f: f.write(result_text) print(f"✅ 已保存结果: {txt_path}") except Exception as e: print(f"❌ 处理 {filename} 时出错: {str(e)}") with open(os.path.join(output_dir, "error.log"), "a", encoding="utf-8") as f: f.write(f"{filename}: {str(e)}\n") # 使用示例 if __name__ == "__main__": batch_transcribe_folder( input_dir="./audios", # 替换为你的音频文件夹 output_dir="./transcripts", # 输出文件夹 language="auto", # 自动识别语言 )

4. 脚本功能详解

4.1 富文本后处理：让标签更易读

SenseVoice 的原始输出会包含类似<|HAPPY|>、<|BGM|>这样的标签。直接看有点乱，所以我们用rich_transcription_postprocess做清洗。

比如：

原始输出： "<|zh|><|HAPPY|>今天天气真好！<|LAUGHTER|>哈哈哈<|en|><|SAD|>I'm feeling blue..." 清洗后： "[开心] 今天天气真好！[笑声] 哈哈哈 [悲伤] I'm feeling blue..."

这个函数会自动转换语言码、情感和事件标签，输出人类可读的格式，非常适合后续分析。

4.2 多语言自动识别

通过设置language="auto"，模型会自动判断每段语音的语言。这对于混合语种的对话特别有用，比如中英夹杂的会议记录。

如果你确定全是中文，可以设为language="zh"，提升一点准确率。

4.3 错误处理与日志记录

脚本中加入了异常捕获机制。如果某个音频损坏或格式不支持，不会导致整个任务中断，而是记录错误并继续处理下一个文件。

同时生成error.log，方便事后排查问题。

5. 实际使用建议

5.1 推荐的音频格式

虽然模型支持多种格式，但为了稳定性和效率，建议：

采样率：16kHz（模型训练数据主流）
声道数：单声道（节省资源）
编码：PCM WAV 或 MP3（兼容性好）

你可以用ffmpeg提前批量转换：

# 批量转为 16k 单声道 wav for file in *.mp3; do ffmpeg -i "$file" -ar 16000 -ac 1 "${file%.mp3}.wav" done

5.2 性能优化技巧

场景	建议
显存有限	减小`batch_size_s`（如设为 30）
长音频多	启用`merge_vad=True`，合并短句
追求速度	使用 GPU，避免 CPU 推理
多任务并发	启动多个进程分摊文件夹