MacOS 系统 Whisper-WebUI 崩溃问题排查与修复方案
Whisper-WebUI 是一个基于 Gradio 构建的浏览器界面，集成了 OpenAI Whisper、faster-whisper 和 insanely-fast-whisper 等多种实现，支持从文件、YouTube 和麦克风生成字幕，还能进行语音到文本翻译和文本到文本翻译。
为什么 M2 芯片会报 Segmentation Fault？
在 MacBook Pro M2 Max 上运行 Whisper-WebUI 时，终端可能显示"使用 cpu 设备检测到"，紧接着出现 Python 进程的 EXC_BAD_ACCESS 错误。这种内存访问违规通常意味着：
- Python 版本不兼容：项目推荐使用 Python 3.10-3.12，但 3.12.3 在某些情况下可能存在兼容性问题
- 依赖库冲突：特别是 PyTorch 与 Apple Silicon 芯片的适配问题
- 多线程资源泄漏：从警告信息中可以看到"泄漏的信号量对象"
技术深挖：崩溃背后的真相
通过分析项目结构，发现 Whisper-WebUI 的模块化设计相当完善：
modules/
├── whisper/ # 核心转录模块
├── translation/ # 翻译功能
├── uvr/ # 背景音乐分离
├── vad/ # 语音活动检测
└── diarize/ # 说话人分离
问题主要出现在 modules/whisper/whisper_factory.py 中的设备检测逻辑。在 MacOS 上，系统可能无法正确识别 M 系列芯片的 GPU 能力，导致默认回退到 CPU 模式。
解决方案：3 步搞定稳定运行
第 1 步：环境配置优化
首先检查你的 Python 环境。建议使用 conda 创建独立环境：
conda create -n whisper-webui python=3.11
conda activate whisper-webui
然后编辑 requirements.txt 文件，确保 PyTorch 配置正确：
# 针对 Apple Silicon 芯片的配置
--extra-index-url https://download.pytorch.org/whl/cpu
第 2 步：依赖安装技巧
使用项目的安装脚本是最稳妥的方式：
# 对于 MacOS 用户
./install.sh
如果遇到权限问题，记得先给脚本执行权限：
chmod +x install.sh
chmod +x start-webui.sh
第 3 步：启动参数调优
在 MacOS 上启动时，添加适当的参数可以显著提升稳定性：
./start-webui.sh --whisper_type faster-whisper
实践指南：避坑要点
经过实际测试，总结了几条关键经验：
- ：Python 3.11 是目前最稳定的选择
