
whisper.cpp
在 CPU 上极速运行 Whisper,离线语音转文字不求人
项目预览
项目数据
项目介绍
Star 增长趋势
本站每日记录该项目 GitHub 星标变化,观测越久曲线越完整
数据来源:GitHub API 逐日快照 · 收录于 2026-08-10 · 当前星标 ★ 55339
使用教程
ℹ 本教程由 AI 依据该项目 README 整理,个别步骤可能需要按你的环境微调。
环境要求
- 支持平台:macOS(Intel/Arm)、Linux/FreeBSD、Windows(MSVC),另有 iOS/Android/WASM 示例
- 纯 CPU 即可推理,无需 GPU 或云服务(CUDA/ROCm/Vulkan/OpenVINO 等为可选加速)
- 需要 Git 克隆仓库与 C/C++ 构建工具链(README 节选中构建命令被截断)
- 需下载 ggml 格式模型文件,base 模型约 142 MiB 磁盘 / ~388 MB 内存
- 自备或使用仓库内 samples/ 下的 wav 音频文件(如 samples/jfk.wav)
安装与启动步骤
-
1克隆仓库
从 GitHub 拉取 whisper.cpp 源码到本地当前目录。
git clone https://github.com/ggml-org/whisper.cpp.git -
2进入项目目录
切换到刚克隆下来的仓库根目录,后续命令都在此目录执行。
cd whisper.cpp -
3下载模型
用仓库自带脚本下载 ggml 格式模型,base.en 约 142 MiB,体积小适合先跑通。
sh ./models/download-ggml-model.sh base.en -
4编译 whisper-cli
README 节选中该段命令被截断,此处为标准 CMake 构建流程,请以仓库 README 构建章节为准。
cmake -B build cmake --build build -j --config Release -
5运行转录
用 whisper-cli 指定模型和音频文件做语音转文字,支持中英文等多语言。
./build/bin/whisper-cli -m models/ggml-base.bin -f samples/jfk.wav -
6量化模型推理(可选)
内存紧张时改用 q5_0 量化模型,占用更低、速度更快,精度略降。
./build/bin/whisper-cli -m models/ggml-base.en-q5_0.bin ./samples/gb0.wav -
7Docker 跑服务(可选)
挂载模型目录并启动 whisper-server,映射 8080 端口;镜像需提前构建或获取。
docker run -it --rm -p "8080:8080" \ -v path/to/models:/models \ whisper.cpp:main "whisper-server --host 127.0.0.1 -m /models/ggml-base.bin" -
8Conan 安装(可选)
用 Conan 包管理器安装预编译二进制或从源码构建 whisper-cpp。
conan install --requires="whisper-cpp/[*]" --build=missing
关键配置
| 配置项 | 必填 | 说明 | 示例 |
|---|---|---|---|
-m | 是 | 指定 ggml 格式模型文件路径 | models/ggml-base.bin |
-f | 是 | 指定待转录的输入音频文件路径 | samples/jfk.wav |
-t | 否 | 推理使用的线程数,越大通常越快 | 4 |
-tdrz | 否 | 启用说话人转向检测,需搭配 tdrz 模型 | -tdrz |
-m /models/ggml-base.bin | 否 | Docker 服务模式下容器内的模型路径 | /models/ggml-base.bin |
如何确认成功
终端打印出带时间戳的转录文本,形如 [00:00:00.000 --> 00:00:03.800] Okay Houston, we've had a problem here.,即表示运行成功。
常见问题
Q:必须要有 GPU 吗?
A:不需要。whisper.cpp 支持纯 CPU 推理,macOS(Metal/Accelerate/Core ML)、NVIDIA、AMD ROCm、Vulkan 等加速均为可选。
Q:显存/内存不够怎么办?
A:换更小的模型或量化模型,例如 tiny 约 273 MB、base 约 388 MB 内存,量化版可用 ggml-base.en-q5_0.bin。
Q:没有音频文件测试怎么办?
A:README 使用仓库自带的 samples/jfk.wav、samples/gb0.wav、samples/a13.wav,克隆后可直接用。
Q:Docker 镜像从哪来?
A:README 节选只给出 docker run 用法,镜像名 whisper.cpp:main 需自行构建或获取,需提前把模型放到挂载的宿主机目录。
注意事项
- README 节选中 whisper-cli 的构建命令段落被截断,实际构建参数请以仓库 README 的构建章节为准。
- Docker 示例中 path/to/models 需替换为你本机的真实模型目录。
- 模型文件不随仓库分发,必须通过 download-ggml-model.sh 下载或其他方式获取 ggml 格式模型。
- 除 CLI 外仓库还提供 server、bench、WASM 等示例,以及 C 风格 API 便于集成。
核心亮点
- 纯 C/C++ 实现,无 Python 依赖,部署轻量,启动快
- 针对 CPU 深度优化,支持量化,内存占用低,推理速度远超原版
- 跨平台支持(Windows/Linux/macOS/Android/iOS),易于嵌入各类应用
不足之处
- 模型转换和编译配置对新手有一定门槛
- 部分高级功能(如 VAD 集成)需自行实现
适用场景
- 在树莓派或 NAS 上搭建离线语音助手
- 为桌面应用添加本地录音转文字功能
- 嵌入式设备上的实时语音命令识别
替代项目
Vosk、PaddleSpeech、whisper.cpp 的 Rust 绑定(whisper-rs)
同类项目推荐
Llama-AVSR
开源
用大语言模型提升音视频语音识别准确率,解决复杂场景听不清问题
Official Pytorch implementation of "Large Language Models are Strong Audio-Visual Sp···
docker-whisperX
开源
一条命令跑通带说话人分离的词级时间戳语音转写
Dockerfile for WhisperX: Automatic Speech Recognition with Word-Level Timestamps and···
voxtype
开源
按住说话,松手出字,Wayland 离线听写
Voice-to-text with push-to-talk for Wayland compositors
react-native-vosk
开源
在 React Native 里离线跑语音识别,本地转文字不上传
Speech recognition module for react native using Vosk library
whisper-asr-webservice
开源
一行命令部署Whisper语音转文字API,快速集成到你的应用
OpenAI Whisper ASR Webservice API
tambourine-voice
开源
开口说话,文字直接落在光标处
Your personal voice interface for any app. Speak naturally and your words appear whe···
cobra
开源
本地实时判断有没有人说话,省算力又护隐私
On-device voice activity detection (VAD) powered by deep learning
voicetypr
开源
按快捷键说话,文字直接落到光标处
Voicetypr - AI powered offline voice to text dictation tool for busy founders, vibe ···
deepgram-go-sdk
开源
Go 语言接入 Deepgram,快速实现语音转写与合成
Official Go SDK for Deepgram.