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

实践指南：避坑要点

经过实际测试，总结了几条关键经验：