快速上手 whisper.cpp：把语音转文字搬回自己设备的完整指南

快速上手 whisper.cpp：把语音转文字搬回自己设备的完整指南

【免费下载链接】whisper.cppPort of OpenAI's Whisper model in C/C++项目地址: https://gitcode.com/GitHub_Trending/wh/whisper.cpp

whisper.cpp 是 OpenAI Whisper 语音识别模型的 C/C++ 移植版本，它把离线语音转文字的能力装进一个轻量级命令行工具，让你在自己的电脑或低配置设备上完成本地语音识别，音频全程不离开本机。本教程面向新手和低配置设备用户：不装 Python 环境，不依赖云服务，跟着命令敲就能跑通。

为什么要把语音识别搬回本地

假设你手头有一段 30 分钟的会议录音，里面提到内部项目代号和客户名称。走云端识别服务意味着先把这段音频上传到别人的服务器——内容过一遍别人的机器，你只能选择信任。而把识别跑在本地，音频从头到尾只经过你自己的设备，敏感内容不外流。

本地方案对低配置设备也友好。原始的 Python 版 Whisper 需要完整的 Python 环境加 GPU 才算舒服，普通笔记本跑起来容易卡顿。whisper.cpp 用 C/C++ 重写并配合底层张量库 GGML（一种专为机器学习计算设计的底层库，负责矩阵乘法等核心运算）做了深度优化，内存占用比 Python 版本低 60% 以上，识别准确率却基本持平。一台只有 4GB 内存的旧笔记本，跑 tiny 模型（运行内存约 273MB）完全没问题。

另外一个容易被忽略的好处：同一套代码在 Windows、macOS、Linux 上行为一致，Android、iOS 也都有对应的集成示例（见 examples/whisper.android 和 examples/whisper.objc），不存在"换个系统重学一遍"的麻烦。

动手前先确认：设备要求和路线选择

先花一分钟判断你的设备和路线，能少走弯路。

设备要求

• 内存：至少 4GB（运行 tiny 或 base 模型），处理 medium 模型建议 8GB 以上
• 磁盘：源码加一个基础模型，2GB 空闲空间足够
• 工具：Git、CMake 3.18 以上、一个 C++ 编译器（GCC 9+、Clang 10+ 或 MSVC）

两条路线

💡 如果你是第一次接触命令行编译，编译路线也没那么可怕：本项目构建命令就两行，后文会给出完整命令。Ubuntu/Debian 上缺依赖时用sudo apt install build-essential cmake git补齐即可。

跑通第一条转录

下面把构建、下载模型、执行转录串成一条连续流程，按顺序敲完就能看到结果。

第 1 步，拿到源码：

git clone https://gitcode.com/GitHub_Trending/wh/whisper.cpp cd whisper.cpp

第 2 步，编译出whisper-cli命令行工具（CMake 是跨平台的构建配置工具，它把源码编译成可执行程序）：

cmake -B build cmake --build build --config Release

第 3 步，下载一个转好的模型文件，然后对仓库自带的 示例音频 跑第一条转录：

sh ./models/download-ggml-model.sh base.en ./build/bin/whisper-cli -m models/ggml-base.en.bin -f samples/jfk.wav

看到终端里逐句打印出 "And so my fellow Americans..." 这样的文本，说明整条链路已经通了。

两个新手常见的坑提前说明：

⚠️whisper-cli目前只吃 16-bit WAV 文件。你的录音如果是 MP3、FLAC 或其他格式，先用 ffmpeg 转一下：

ffmpeg -i 输入.mp3 -ar 16000 -ac 1 -c:a pcm_s16le 输出.wav

⚠️ 嫌上面步骤多？仓库 Makefile 里有一条快捷命令make base.en，它会一口气完成"下载 base.en 模型 + 编译 + 对 samples 目录所有 wav 跑识别"，适合只想看效果的场景。

按场景选模型

模型大小直接决定速度和内存占用。仓库 models/README.md 给出的实测数据是：tiny 占 75MiB 磁盘、运行约 273MB 内存；base 142MiB、约 388MB；small 466MiB、约 852MB；medium 1.5GiB、约 2.1GB；large 2.9GiB、约 3.9GB。按你的场景对号入座：

低配置设备 / 快速预览：选 tiny 或 tiny.en（.en表示英文专用版本，同体积下英文场景表现更好）。中端 CPU 笔记本处理一小时音频大约 10 分钟，实时对话类应用也够用。

日常录音转写、中英混合会议：选 base 或 base.en，速度与准确率的平衡点。多语言模型base支持约 99 种语言，中文录音用它。

正式会议纪要、播客归档：选 small 或 small.en。准确率明显提升，4GB 内存的机器也能扛。

追求最高准确率的专业转录：medium 起步，机器配置高（16GB 内存以上）再考虑 large 系列。

下载命令统一格式：

sh ./models/download-ggml-model.sh <模型名>

不传参数运行该脚本会列出全部可用模型名。下载好的文件默认落在models/目录下。

调得更准更快

跑通之后，日常用得上的就下面这几个参数（完整参数表见./build/bin/whisper-cli -h）。

控制语言和输出

• -l zh：指定语言，中文录音建议显式指定，比自动检测更稳
• --output-txt 结果.txt：把文本写进文件（还有--output-srt生成字幕、--output-json输出结构化结果，会议记录想留时间戳就用 srt）
• --prompt "节目名是XX，主持人是XX"：给模型一段背景提示，专有名词识别率会明显提升

控制速度

• -t 4：设置线程数。经验值是 CPU 物理核心数的一半，老机器设 2 也够
• --split-on-word：长音频按词切分段，减少长文件处理时的内存波动
• -tr：把识别结果翻译成英文（多语言模型的附加能力）

硬件加速：有 NVIDIA 显卡的用户，编译时改成cmake -B build -DGGML_CUDA=1；Vulkan 显卡用-DGGML_VULKAN=1；Apple Silicon 上 Metal 后端默认启用。这些改动只影响编译阶段，二进制跑起来后用法完全一样。

量化省内存：量化是把模型权重从 16 位浮点压成低比特整数，牺牲一点精度换取更小的体积和内存。编译出的quantize工具可以自制：

./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 samples/jfk.wav

base.en-q5_0这类量化版本模型仓库也提供现成的，直接sh ./models/download-ggml-model.sh base.en-q5_0下载即可，4GB 内存机器跑 small 级任务时可优先考虑。

遇到卡点怎么办

识别结果偏差大、满屏同音错字

按顺序排查：确认模型与音频语言匹配（中文别用.en模型）；换大一档模型（base → small）；用 ffmpeg 重新导出干净音频再试；最后用--prompt补充领域词汇背景。四步走完，绝大多数准确率问题能定位。

提示 "failed to load model" 或文件无效

模型文件下载中断是最常见原因——重新运行下载脚本（脚本检测到文件已存在会跳过，损坏文件建议手动移到其他位置再下）。其次确认-m后面的路径相对于你当前所在目录是对的，cd到别的目录再跑老命令是高频错误。

编译阶段报错

CMake 版本低于 3.18 会报配置错误，升级到新版重跑；GCC/Clang 版本太旧（低于 9/10）会报不支持的语法。清理重来用cmake -B build --fresh或删掉 build 目录后重新执行前面两行构建命令即可，源码不需要改动。

资源索引

• README：官方完整说明，含 Core ML、OpenVINO 等进阶后端
• 模型下载脚本：列出全部可用模型名
• 示例音频：jfk.wav 等测试素材
• 命令行工具源码：whisper-cli 的完整参数实现
• Android 集成示例：移动端本地识别参考

低配置设备 + 本地语音识别的组合，核心思路就是：tiny/base 模型起步，量化压缩兜底，参数少而准地调。跑通第一条转录之后，剩下的只是把模型和参数换成匹配你场景的那一组。

【免费下载链接】whisper.cppPort of OpenAI's Whisper model in C/C++项目地址: https://gitcode.com/GitHub_Trending/wh/whisper.cpp