ggml-org/whisper.cpp · 上手攻略

• 仓库：ggml-org/whisper.cpp
• 链接：https://github.com/ggml-org/whisper.cpp
• 分类：ai
• 作者：Jay
• 更新：2026-07-12

这是什么

whisper.cpp 是 OpenAI Whisper 自动语音识别（ASR）模型的纯 C/C++ 实现，不依赖任何第三方 ML 框架。相比 Python 原版，它可以脱离 Python 环境、在各类硬件上高效运行，从树莓派、手机到 GPU 服务器都能部署。截至 2026 年 7 月最新稳定版为 v1.9.1，Stars 超过 5.1 万，是目前最流行的本地语音识别方案之一。

解决什么问题

• 隐私安全：音频不上云，完全本地处理，适合医疗、法务、金融等敏感场景
• 硬件普适：支持 Mac（Apple Silicon Metal）、NVIDIA GPU（CUDA）、AMD GPU（ROCm）、x86（AVX）、ARM、CPU 等几乎所有主流硬件
• 高性能推理：整数量化支持（4-bit、5-bit 等），大幅降低内存占用
• 轻量嵌入：无外部依赖，可内嵌到各类应用（iOS App、Android 应用、物联网设备）

快速安装

方式一：源码编译（macOS / Linux / Windows 均适用）

# 克隆仓库
git clone https://github.com/ggml-org/whisper.cpp.git
cd whisper.cpp

# 下载 Whisper 模型（ggml 格式）
# 可选：tiny.en / base.en / small.en / medium.en / large-v3 等
bash ./models/download-ggml-model.sh base.en

# CMake 编译
cmake -B build
cmake --build build -j --config Release

# 转写示例音频
./build/bin/whisper-cli -f samples/jfk.wav

⚠️ 注意：whisper-cli 目前仅支持 16-bit WAV 文件。输入为 MP3、FLAC 等格式时需先转换： bash ffmpeg -i input.mp3 -ar 16000 -ac 1 -c:a pcm_s16le output.wav

方式二：macOS 一键上手

# 自动下载 base.en 模型并运行所有 samples/*.wav 示例文件
make base.en

方式三：Python bindings（ pip 安装）

pip install whisper.cpp

核心用法

命令行转写

# 使用默认模型（需提前下载到 models/ 目录）
./build/bin/whisper-cli -m models/ggml-base.en.bin -f your_audio.wav

# 查看所有可用参数
./build/bin/whisper-cli -h

# 指定线程数（默认自动检测）
./build/bin/whisper-cli -m models/ggml-base.en.bin -f audio.wav -t 4

# 输出带时间戳的逐句字幕（SRT 格式）
./build/bin/whisper-cli -m models/ggml-base.en.bin -f audio.wav --output-srt

支持的模型规格与内存占用

💡 推荐起步：先用 base.en（英文模型，体积小、速度快），熟悉后再换 small 或 medium 提升准确率。

整数量化（减少内存占用）

# 编译量化工具
cmake -B build
cmake --build build -j --config Release

# 将已有 ggml 模型量化（以 base.en 为例）
./build/bin/quantize models/ggml-base.en.bin models/ggml-base.en-q5_0.bin q5_0

# 使用量化模型
./build/bin/whisper-cli -m models/ggml-base.en-q5_0.bin -f audio.wav

Apple Silicon（Mac）Metal GPU 加速

macOS 上默认通过 Metal 调用 GPU，无需特殊编译选项：

cmake -B build
cmake --build build -j --config Release
# 直接运行即可自动使用 Metal GPU
./build/bin/whisper-cli -m models/ggml-base.en.bin -f audio.wav

如需 Core ML 加速编码器（需 macOS 14+）：

# 安装依赖
pip install ane_transformers openai-whisper coremltools

# 生成 Core ML 模型
bash ./models/generate-coreml-model.sh base.en

# 重新编译（启用 Core ML 支持）
cmake -B build -DWHISPER_COREML=1
cmake --build build -j --config Release

NVIDIA GPU 加速（CUDA）

cmake -B build -DGGML_CUDA=1
cmake --build build -j --config Release
./build/bin/whisper-cli -m models/ggml-base.en.bin -f audio.wav

Vulkan（跨厂商 GPU 支持）

cmake -B build -DGGML_VULKAN=1
cmake --build build -j --config Release

Docker 部署

# 使用官方容器镜像（已包含 CUDA 支持）
docker run --gpus all -v $(pwd):/workspace ghcr.io/ggml-org/whisper.cpp \
  ./build/bin/whisper-cli -m models/ggml-base.en.bin -f /workspace/audio.wav

典型适用场景

坑与注意

1. 输入格式限制：whisper-cli 只能读 16-bit WAV，必须先用 ffmpeg 转换
2. 语言模型选择：英文音频用 *.en 模型（体积更小、准确率更高），中文或 multilingual 场景用无后缀模型
3. Core ML 首轮慢：ANE 编译模型到设备特定格式需要数分钟，之后正常运行
4. CUDA 架构：RTX 5000 系列需加 -DCMAKE_CUDA_ARCHITECTURES="86" 参数编译
5. 中文支持：Whisper 本身支持近百种语言（含中文），但 base.en 等英文模型无法识别中文，需下载 multilingual 模型如 large-v3
6. 量化精度损失：Q5_0 量化精度损失较小，但 Q4_0/Q4_1 可能导致少量读音相近字错误

与同类对比

一句话推荐结论

whisper.cpp 是目前最值得推荐的本地语音识别方案：纯 C/C++ 实现无需 Python 环境、主流硬件全覆盖（Mac/NVIDIA/AMD/Intel/ARM）、完整整数量化生态，隐私敏感场景和边缘部署的首选。