Whisper-WebUI macOS 安装与常见问题排查
不少朋友在 macOS 上部署 Whisper-WebUI 时，常因依赖冲突或硬件加速失效而卡住。特别是搭载 Apple Silicon 芯片的设备，架构差异导致直接运行容易出错。结合过往经验，这套配置流程能帮你避开大部分坑。
前置准备
先确认系统安装了 Git 和 Python。版本选择上，3.10 到 3.11 最为稳妥，新版 Python 偶尔会与旧版依赖库产生兼容性问题。如果你习惯用 Homebrew，可以这样安装：
brew install [email protected]
构建独立环境
别把依赖装在全局里，否则后续维护会很麻烦。创建一个虚拟环境相当于给项目划了一块专属地盘。
# 初始化环境
python3 -m venv venv
source venv/bin/activate
# 拉取代码
git clone https://github.com/jianfch/stable-whisper.git
cd stable-whisper
这里有个细节：部分依赖涉及底层编译，如果提示找不到头文件，记得先安装 Xcode 命令行工具：xcode-select --install。
依赖安装与启动
进入目录后，直接安装需求即可。
pip install -r requirements.txt
安装完成后，运行启动脚本。如果终端显示仍在调用 CPU，可能是 MPS（Metal Performance Shaders）未被识别。这通常与 PyTorch 版本有关，确保你安装的是支持 Apple Silicon 的版本。
避坑指南
- 内存溢出：Whisper 模型体积不小，跑大模型时留意内存监控，必要时限制并发数。
- 权限问题：macOS 对麦克风访问控制严格，首次运行时需在'系统设置'中授权。
- 版本更新：开源项目迭代快，定期 pull 最新代码能解决不少已知 Bug。
按这个流程走一遍，基本能解决 90% 的安装障碍。剩下的具体问题，还得看具体的报错日志来对症下药。
