be-more-agent语音识别深度解析:whisper.cpp如何实现树莓派上的离线语音转文字
be-more-agent语音识别深度解析:whisper.cpp如何实现树莓派上的离线语音转文字
be-more-agent 是一个运行在树莓派(Raspberry Pi)上的本地 AI 智能体,它的语音识别环节由 whisper.cpp 引擎驱动,全程离线完成语音转文字,不依赖任何云端 API。本文将带你深入理解它"听你说什么"的完整链路:从麦克风采集、静音检测,到 whisper-cli 命令行转写,再到文字交给大模型"思考"的全过程。
为什么是 whisper.cpp:树莓派离线语音识别的最优解
主流语音识别服务(如各家云端 API)都需要联网、按量计费,而且语音数据会离开你的设备。be-more-agent 的设计目标是 100% 本地运行(详见 README.md),因此语音转文字选用了专为低性能设备优化的 whisper.cpp:
| 对比维度 | 云端语音识别 API | whisper.cpp 本地转写 |
|---|---|---|
| 网络依赖 | 必须联网 | 完全离线 |
| 费用 | 按字符计费 | 免费 |
| 隐私 | 语音上传服务器 | 数据留在本地 |
| 硬件门槛 | 无 | 树莓派即可流畅运行 |
| 延迟 | 受网络波动影响 | 本地推理,延迟稳定 |
项目使用 ggml-base.en.bin 这个 base 规格模型(约 140MB),在 4 线程下即可完成转写,对树莓派 4/5 的 CPU 来说负担很小——这正是"小模型 + C++ 引擎"在边缘设备上的典型玩法。
be-more-agent语音识别监听界面:智能体处于listening聆听状态的绿色笑脸
语音识别的完整流程:从麦克风到文字
整个链路的核心代码都在主脚本 agent.py 中,流程可以概括为:唤醒 → 录音 → 转写 → 思考。
第一步:唤醒词触发录音
智能体并不是时刻在录音频。它先用 OpenWakeWord 引擎持续监听麦克风,只有听到唤醒词(默认 "Hey Jarvis",模型文件 wakeword.onnx)才会进入 listening 状态开始录音。如果唤醒词模型缺失,还可以按回车键手动触发(PTT 模式)。
这一步在 detect_wake_word_or_ptt() 中实现,唤醒词模型要求 16000 Hz 采样率,代码会自动把麦克风实际采样率(48000/44100 等)重采样对齐,避免 ALSA 报错。
第二步:自适应录音与静音检测
唤醒后进入 record_voice_adaptive(),它实现了简洁高效的端点检测(自动判断你什么时候说完了):
- 每 0.05 秒读取一小块音频,计算音量归一化值
- 音量低于阈值
0.006的片段累计达到 1.5 秒 就判定"你说完了",自动停止 - 最长录音 30 秒 兜底,防止一直录
- 录音存为标准 WAV 文件
input.wav(单声道、16-bit 整型)
采样率由 choose_input_samplerate() 自动探测:依次尝试配置值、设备默认值、48000/44100/32000/16000 Hz,用哪个就用哪个,无需手动适配不同麦克风。
第三步:whisper-cli 命令行转写
这是全文最核心的一环。transcribe_audio() 并不用 Python 库,而是直接调用编译好的 whisper.cpp 命令行工具:
./whisper.cpp/build/bin/whisper-cli -m ./whisper.cpp/models/ggml-base.en.bin -l en -t 4 -f input.wav
几个关键参数的含义:
-m:指定模型文件,这里用的是ggml-base.en.bin(base 规格、英文增强版)-l en:强制语言为英文,避免自动检测带来的误判-t 4:使用 4 个 CPU 线程并行推理,基本吃满树莓派的算力-f:输入刚才录好的 WAV 文件
转写结果从标准输出的最后一行解析得到——whisper-cli 的每行输出形如 [00:00:00.000 --> 00:00:02.500] 你说的话,代码取 ] 之后的文字部分,丢掉时间戳前缀,得到干净的用户语句,随后打印 Heard: '...' 并送入下一环节。
第四步:文字交给 Ollama 大模型思考
拿到文字后,be-more-agent 把它连同历史对话一起发给本地 Ollama 服务(默认 gemma3:1b 模型,配置见 config.json),大模型"思考"时屏幕会切换到思考表情:
be-more-agent离线AI智能体thinking思考状态界面
回复内容再经 Piper TTS 念出来,一次完整的"听—想—说"闭环就结束了。
如何更换 Whisper 语音识别模型
如果觉得 base 模型识别率不够,可以升级模型规格。whisper.cpp 官方提供 tiny / base / small / medium 等多个 ggml 模型,替换步骤:
- 把对应规格的
.bin模型文件放到whisper.cpp/models/目录 - 修改 agent.py 中
transcribe_audio()里的模型路径,例如改成ggml-small.en.bin - 重启智能体(
python agent.py或 start_agent.sh)
💡 经验值:树莓派 5 跑 small 模型转写 10 秒语音大约需要几秒到十几秒;如果设备是 4GB 内存的 Pi 4,建议留在 base 规格。注意
ggml-*.en系列只识别英文,想识别中文请换成不带.en的多语言版本(如ggml-base.bin)并调整-l参数为zh。
离线语音转文字常见问题排查
结合 README.md 的 Troubleshooting 章节,几个高频问题的处理思路:
转写结果为空("Transcription empty")
检查 input.wav 是否生成、麦克风音量是否过低;-t 线程数可以按 CPU 核数微调。
录音阶段报 ALSA 错误
通常是采样率不匹配导致。确认 config.json 中的 input_sample_rate 与你的麦克风兼容,或将其置空让程序自动探测。
退出时看到 alsa_snd_pcm_mmap_begin 报错
这是正常的音频流中断提示,不影响功能,可以放心忽略。
识别慢/跟不上说话节奏 换用更小规格模型(tiny/base),或缩短实际对话长度——静音检测的 1.5 秒阈值决定了录音何时停止。
小结
be-more-agent 的语音识别方案值得借鉴:OpenWakeWord 负责"什么时候听",自适应静音检测负责"听到哪里算说完",whisper.cpp 的 whisper-cli 负责"听成什么文字",三者分工清晰、全部离线运行。整套方案不碰任何云 API,普通树莓派就能流畅跑通,是边缘设备做离线语音转文字的完整可抄作业范本。
想体验完整效果,把智能体放在屏幕前说句唤醒词,就会看到它切换成聆听表情、听完话"思考"几秒,然后用语音回答你——就像这样一张待机笑脸背后的完整 AI 流水线:
be-more-agent树莓派AI语音助手idle待机状态界面
相关源码与配置入口:主逻辑 agent.py、模型与硬件配置 config.json、一键安装脚本 setup.sh、Python 依赖清单 requirements.txt。