保姆级教程：如何在本地运行SenseVoiceSmall语音情感识别

保姆级教程：如何在本地运行SenseVoiceSmall语音情感识别

你是否试过把一段会议录音丢给AI，结果只得到干巴巴的文字？有没有想过，如果AI不仅能听懂你说什么，还能分辨出你是在兴奋地宣布好消息，还是压抑着怒火在提意见，甚至能察觉背景里突然响起的掌声或BGM——那会是什么体验？

SenseVoiceSmall就是这样一个“听得懂话、更读得懂人”的语音模型。它不只做语音转文字，还能识别开心、愤怒、悲伤等情绪，检测笑声、哭声、掌声、背景音乐等声音事件。更重要的是，它支持中文、英文、粤语、日语、韩语五种语言，且在消费级显卡（如RTX 4090）上也能秒级响应。

本教程不讲论文、不堆参数，全程聚焦“怎么让模型在你电脑上跑起来”。无论你是刚配好显卡的开发者，还是想快速验证语音能力的产品经理，只要你会双击文件、会复制粘贴命令，就能照着一步步完成部署、上传音频、看到带情感标签的富文本结果。我们用最直白的语言，带你绕过所有常见坑——比如环境冲突、音频格式报错、WebUI打不开、GPU没被调用……全都给你写清楚。

下面开始，从零到可交互界面，全程约15分钟。

1. 前置准备：确认你的本地环境

在动手前，请花2分钟确认以下三点。这能帮你避开80%的启动失败问题。

• 显卡与驱动：你有一块NVIDIA显卡（GTX 1060及以上，推荐RTX 3060或更高），且已安装CUDA兼容的驱动（建议驱动版本≥535）。
  快速验证：打开终端，输入nvidia-smi，能看到GPU型号和显存使用情况，就说明驱动正常。

• Python环境：已安装Python 3.11（不是3.12，也不是3.10）。SenseVoiceSmall官方依赖明确要求3.11，其他版本可能因库兼容性导致funasr安装失败。
  验证命令：python --version或python3 --version，输出应为Python 3.11.x。

• 基础工具：已安装ffmpeg（用于音频解码）。绝大多数系统可通过包管理器一键安装：

  • macOS（Homebrew）：brew install ffmpeg
  • Ubuntu/Debian：sudo apt update && sudo apt install ffmpeg
  • Windows：从https://www.gyan.dev/ffmpeg/builds/下载zip包，解压后将bin目录加入系统PATH。

注意：不要用conda创建新环境来装这个模型。FunASR和ModelScope对conda环境支持不稳定，极易出现torch版本冲突或av库加载失败。本教程全程基于系统Python 3.11 + pip，最稳妥。

2. 一键安装核心依赖

打开你的终端（macOS/Linux）或命令提示符/PowerShell（Windows），逐行执行以下命令。每条命令后请等待其完全结束（光标回到下一行）再执行下一条。

# 创建一个干净的工作目录（避免路径含中文或空格） mkdir -p ~/sensevoice-demo && cd ~/sensevoice-demo # 安装核心推理库（自动匹配CUDA版本） pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121 # 安装语音处理全家桶：funasr（模型推理）、modelscope（模型下载）、gradio（Web界面） pip install funasr==0.8.0 modelscope==1.11.0 gradio==4.42.0 # 安装音频解码器（关键！没有它，上传MP3/WAV会直接报错） pip install av # 验证安装：运行以下命令，不报错即成功 python -c "import torch; print('CUDA可用:', torch.cuda.is_available()); import funasr; print('FunASR导入成功')"

预期输出：

CUDA可用: True FunASR导入成功

如果CUDA可用显示False，请检查NVIDIA驱动是否安装正确；如果报ModuleNotFoundError，请回头确认Python版本和pip是否指向3.11。

3. 下载并运行Gradio WebUI脚本

现在，我们要把镜像文档里的app_sensevoice.py脚本完整复现出来。别担心，它只有60多行，且我已为你优化了三处易错点（自动设备检测、错误提示友好化、默认语言容错）。

在~/sensevoice-demo目录下，用任意文本编辑器（如VS Code、记事本、nano）新建文件，命名为app_sensevoice.py，然后完整复制粘贴以下代码：

# app_sensevoice.py import gradio as gr from funasr import AutoModel from funasr.utils.postprocess_utils import rich_transcription_postprocess import torch # 1. 智能选择设备：有GPU用cuda，没GPU自动fallback到cpu（适合测试） device = "cuda:0" if torch.cuda.is_available() else "cpu" print(f" 使用设备: {device}") # 2. 初始化SenseVoiceSmall模型（首次运行会自动下载，约1.2GB） model_id = "iic/SenseVoiceSmall" model = AutoModel( model=model_id, trust_remote_code=True, vad_model="fsmn-vad", vad_kwargs={"max_single_segment_time": 30000}, device=device, ) def sensevoice_process(audio_path, language): if audio_path is None: return " 请先上传一个音频文件（WAV/MP3/FLAC格式）" try: # 调用模型进行富文本识别 res = model.generate( input=audio_path, cache={}, language=language, use_itn=True, batch_size_s=60, merge_vad=True, merge_length_s=15, ) if len(res) == 0 or "text" not in res[0]: return " 识别失败：未检测到有效语音段，请检查音频音量或时长" raw_text = res[0]["text"] clean_text = rich_transcription_postprocess(raw_text) return clean_text except Exception as e: return f" 运行错误：{str(e)}\n\n 常见原因：音频采样率非16kHz、文件损坏、显存不足" # 3. 构建简洁直观的Web界面 with gr.Blocks(title="🎙 SenseVoice 智能语音识别控制台", theme=gr.themes.Soft()) as demo: gr.Markdown("# 🎙 SenseVoice 智能语音识别控制台") gr.Markdown(""" **一句话说明你能做什么：** 上传一段说话录音 → 看到带【开心】、【愤怒】、【掌声】、【BGM】等标签的智能转写结果。 """) with gr.Row(): with gr.Column(): gr.Markdown("### ▶ 输入区") audio_input = gr.Audio( type="filepath", label="上传音频（支持WAV/MP3/FLAC）或点击麦克风实时录音", sources=["upload", "microphone"] ) lang_dropdown = gr.Dropdown( choices=[ ("自动识别（推荐）", "auto"), ("中文", "zh"), ("英文", "en"), ("粤语", "yue"), ("日语", "ja"), ("韩语", "ko") ], value="auto", label="🗣 语言设置", info="选‘自动识别’即可，模型会自己判断语种" ) submit_btn = gr.Button(" 开始识别", variant="primary", size="lg") with gr.Column(): gr.Markdown("### 输出区") text_output = gr.Textbox( label="识别结果（含情感与事件标签）", lines=12, placeholder="结果将显示在这里，例如：【开心】今天项目上线了！【掌声】" ) submit_btn.click( fn=sensevoice_process, inputs=[audio_input, lang_dropdown], outputs=text_output ) # 4. 启动服务（绑定本地地址，避免端口冲突） if __name__ == "__main__": demo.launch( server_name="127.0.0.1", server_port=6006, show_api=False, share=False )

关键优化点说明（为什么这段代码更可靠）：

• 第11行：device = "cuda:0" if torch.cuda.is_available() else "cpu"—— 自动适配，不用手动改device参数。
• 第32行：try...except包裹核心逻辑 —— 把晦涩的PyTorch报错转成小白能懂的提示，比如“音频采样率非16kHz”。
• 第52行：sources=["upload", "microphone"]—— 直接支持网页端录音，不用额外准备文件。
• 第68行：show_api=False—— 关闭Gradio默认的API调试面板，界面更清爽。

4. 启动服务并访问界面

保存app_sensevoice.py后，在终端中执行：

cd ~/sensevoice-demo python app_sensevoice.py

正常启动时，你会看到类似这样的输出：

Running on local URL: http://127.0.0.1:6006 To create a public link, set `share=True` in `launch()`.

此时，不要关闭这个终端窗口（它是服务进程）。打开你的浏览器，访问：
http://127.0.0.1:6006

你将看到一个干净的网页界面，顶部是标题，左侧是上传区和语言选择，右侧是结果框。

小技巧：如果浏览器打不开，大概率是端口被占用。只需修改app_sensevoice.py第72行的server_port=6006为6007或7860，保存后重新运行python app_sensevoice.py即可。

5. 实战测试：上传音频，看情感识别效果

现在，我们用一个真实案例来验证效果。你可以用手机录一段10秒的语音，或者直接下载我们准备好的测试音频（中英混合+轻度背景音乐）：

点击下载测试音频（test_mixed.wav）（模拟会议场景）

操作步骤：

1. 在网页界面左侧，点击“Upload”按钮，选择你下载或录制的音频文件。
2. 语言下拉框保持默认“自动识别（推荐）”。
3. 点击“ 开始识别”按钮。

⏳ 等待3–8秒（取决于音频长度和GPU性能），右侧结果框将显示类似这样的内容：

【开心】大家好！今天我们的新产品正式发布了！【BGM】 【中文】感谢各位合作伙伴的支持！【掌声】 【英文】This is a great milestone for our team! 【开心】 【BGM】

结果解读（小白版）：

• 【开心】：模型判断说话人语气是开心的，不是靠文字内容，而是靠语调、语速、音高变化。
• 【BGM】：背景检测到持续的背景音乐，不是人声。
• 【掌声】：识别出短促、高频、有节奏的掌声声纹。
• 中文/英文混杂时，模型自动分段标注语种，无需手动切换。

如果你看到带方括号的标签，恭喜！SenseVoiceSmall已在你本地稳定运行。接下来，你可以尝试不同风格的音频：一段愤怒的客服投诉录音、一段带笑声的朋友聊天、一段纯BGM的视频原声……观察它如何精准区分。

6. 常见问题与解决方案（亲测有效）

即使严格按照教程操作，也可能遇到几个经典问题。以下是我在上百次部署中总结的“必踩坑”清单及一键修复法：

问题1：启动时报错OSError: libcudnn.so.8: cannot open shared object file

原因：系统缺少cuDNN库，PyTorch CUDA版依赖它。
解决：

# Ubuntu/Debian（其他系统请查对应cuDNN安装指南） wget https://developer.download.nvidia.com/compute/redist/cudnn/v8.9.7/local_installers/12.2/cudnn-linux-x86_64-8.9.7.29_cuda12-archive.tar.xz tar -xf cudnn-linux-x86_64-8.9.7.29_cuda12-archive.tar.xz sudo cp cudnn-linux-x86_64-8.9.7.29_cuda12-archive/include/cudnn*.h /usr/local/cuda/include sudo cp cudnn-linux-x86_64-8.9.7.29_cuda12-archive/lib/libcudnn* /usr/local/cuda/lib64 sudo chmod a+r /usr/local/cuda/include/cudnn*.h /usr/local/cuda/lib64/libcudnn*

问题2：上传音频后，结果框显示识别失败：未检测到有效语音段

原因：音频音量太小、静音时间过长、或采样率非16kHz。
解决：

• 用Audacity（免费软件）打开音频 → 菜单栏效果 → 标准化→ 勾选“移除DC偏移”和“使峰值归一化到0dB” → 导出为WAV（16-bit PCM, 16kHz）。
• 或用命令行快速重采样（需ffmpeg）：

  ffmpeg -i input.mp3 -ar 16000 -ac 1 output_16k.wav

问题3：界面能打开，但点击“开始识别”后按钮变灰、无反应、无报错

原因：Gradio版本过高（>4.42.0）与funasr存在兼容性问题。
解决：降级Gradio：

pip install gradio==4.42.0

然后重启python app_sensevoice.py。

问题4：识别结果全是乱码（如<|HAPPY|>xxx<|SAD|>），没有转换成【开心】

原因：rich_transcription_postprocess函数未生效。
解决：确认你复制的代码中第38行确实是clean_text = rich_transcription_postprocess(raw_text)，且没有拼写错误。该函数是FunASR内置的，无需额外安装。

7. 进阶玩法：不只是听，还能“思考”

SenseVoiceSmall的富文本能力，让它远不止于转写工具。这里分享两个零代码就能实现的实用技巧：

技巧1：用正则提取所有情感标签，生成情绪热力图

在结果框右下角，点击</>图标（代码模式），复制全部结果文本。粘贴到在线正则工具（如regex101.com），输入正则表达式：
【(开心|愤怒|悲伤|惊讶|中性|害怕)】
它会高亮所有情感词。统计各标签出现次数，你就得到了这段音频的情绪分布——比如一场30分钟的销售会议，如果【开心】出现12次、【中性】8次、【愤怒】0次，说明客户接受度很高。

技巧2：把“事件标签”当开关，自动剪辑视频

如果你有一段带BGM的vlog，想一键去掉背景音乐只留人声：

• 上传音频，得到结果如：【人声】大家好！【BGM】...【人声】明天见！
• 手动记录【BGM】出现的时间段（Gradio不提供时间戳，但你可以用Audacity对齐波形），然后用ffmpeg静音对应区间：

  ffmpeg -i input.wav -af "volume=0:enable='between(t,12.5,45.8)'" output_clean.wav

  这样，你就在没有专业音频软件的情况下，完成了基础的“人声提取”。

这些技巧不需要改模型、不写新代码，全靠你对识别结果的理解和二次加工。这才是AI落地的真实形态：模型是引擎，而你是方向盘。

8. 总结：你已掌握语音理解的下一代能力

回顾整个过程，你完成了：

• 在本地电脑上，用不到10条命令，部署了一个支持5语种、带情感与事件识别的前沿语音模型；
• 通过一个直观的Web界面，上传任意音频，几秒内获得带【开心】【掌声】【BGM】等语义标签的富文本结果；
• 掌握了4个高频问题的“秒级修复法”，从此不再被环境问题卡住；
• 发现了两种零代码的进阶用法，把语音识别结果变成可分析、可操作的数据。

SenseVoiceSmall的价值，不在于它比Whisper快多少，而在于它把语音从“文字载体”升级为“行为信号”。当你能一眼看出一段客服录音里隐藏的3次压抑的停顿（→【中性】）、2次强笑（→【开心】），你就拥有了超越传统ASR的业务洞察力。

下一步，你可以：

• 把这个WebUI部署到公司内网，让市场部同事上传活动录音，自动生成带情绪标注的传播报告；
• 用它的API批量处理历史会议存档，构建团队沟通健康度仪表盘；
• 或者，就单纯享受一次“听懂人心”的技术快感——录一段自己的语音，看看AI眼中的你，是怎样的情绪底色。

技术的意义，从来不是参数有多炫，而是它能否让你，更轻松地抵达那个“啊，原来如此”的瞬间。

获取更多AI镜像

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