在搭载 Apple Silicon 的 Mac 上部署 Whisper-WebUI,依赖冲突、MPS 不生效这类问题太常见了。下面是我反复踩坑后沉淀下来的一套流程,按这个走能省不少力气。
环境准备
先装好 Git,然后解决 Python 版本问题。3.10 或 3.11 最稳,我用 3.12 试过几次,总有 wheel 编译不过。如果你用 Homebrew,直接:
brew install [email protected]
搞个虚拟环境
千万别把依赖直接灌到系统 Python 里,后面清理起来会让你后悔。给项目划一块独立的地盘:
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 对麦克风访问管得严,第一次运行如果什么都没反应,去'系统设置'里把终端或 IDE 的权限打开。
代码更新:开源项目迭代快,隔段时间 git pull 一次,很多已知 bug 就自然消失了。
总体上,这套流程能覆盖绝大多数安装问题,剩下的就看具体报错对症下药了。

