vllm-metal 语音转文字指南：Whisper 与 Qwen3-ASR 在 Mac 上本地跑通

vllm-metal 是 vLLM 面向 Apple Silicon 的社区硬件插件，让 Whisper 与 Qwen3-ASR 语音转文字（STT）模型直接在 Mac 的 GPU 上本地运行。无需显卡、不上传音频，一条命令即可搭建 OpenAI 兼容的本地转写服务，本文带你从零到跑通 👇

一、为什么在 Mac 上本地跑语音转文字？

传统方案要么依赖云端 API（隐私风险 + 按量付费），要么自己搭 CUDA 环境。vllm-metal 基于 MLX 计算后端，把 vLLM 完整跑在 Apple Silicon 上：

• 🔒隐私优先：会议录音、访谈音频全程不出本机
• 📄OpenAI 兼容 API：直接对接现有应用的转写接口，无缝切换
• 🎯模型全规格：从 39M 的 Whisper Tiny 到 1.5B 的 Whisper Large V3 均可运行

二、环境要求与安装步骤

硬件要求：Apple Silicon（M1 及以上）+ macOS 15 (Sequoia) 或更高版本。

第 1 步：克隆仓库并安装

git clone https://gitcode.com/gh_mirrors/vl/vllm-metal cd vllm-metal ./install.sh source ~/.venv-vllm-metal/bin/activate

安装脚本会自动配置 Python 环境与预编译组件，无需编译器。稳定版本可改用 Homebrew 安装（详见 docs/installation.md 与 install.sh）。

第 2 步：安装 STT 可选依赖

pip install 'vllm-metal[stt]'

第 3 步：安装 ffmpeg（可选）

仅当你要转写 mp3、m4a、flac 等非 WAV 格式时需要；WAV 文件可直接处理：

brew install ffmpeg

三、30 秒跑通第一条转写

以最常见的 Whisper Small 为例：

# 启动转写服务 vllm serve openai/whisper-small --port 8000 # 提交音频文件 curl -X POST http://localhost:8000/v1/audio/transcriptions \ -F "file=@recording.wav"

几秒后就能拿到形如{"text": "Hello, world."}的返回结果。Qwen3-ASR 同理，把模型名换成Qwen/Qwen3-ASR-0.6B即可。

四、Whisper vs Qwen3-ASR：怎么选？

💡选型建议：追求成熟生态、多语言手动控制选 Whisper（中文场景推荐 small 以上规格）；想要轻量、自动识别语言选 Qwen3-ASR-0.6B。完整模型清单见 docs/stt.md。

五、API 参数速查表

转写接口为POST /v1/audio/transcriptions，常用参数：

verbose_json格式还会返回language和duration字段，方便后续做字幕对齐。

六、源码结构与常见问题

• STT 运行时核心：vllm_metal/stt/，其中 Whisper 与 Qwen3-ASR 的解码逻辑分别位于 vllm_metal/stt/whisper/ 和 vllm_metal/stt/qwen3_asr/
• 请求边界适配：vllm_metal/stt/serve.py，负责把 vLLM 请求归一化为音频特征
• 冒烟测试脚本：tools/stt_sampling_serve_smoke.py，可一键验证转写服务是否正常

常见问题排查：

1. ⚠️ 端口被占用 → 换--port参数，脚本会自动探测可用端口
2. ⚠️ 非 WAV 格式报错 → 安装 ffmpeg（见第三节第 3 步）
3. ⚠️ 服务启动慢 → 首次运行会拉取模型权重并缓存，属正常现象

从克隆仓库到拿到第一条转写文本，整个过程通常不超过 10 分钟。现在，你的 Mac 已经是一个私有的语音转文字工作站了 🎉