如果你最近想把手头的录音、会议、课程视频变成文字稿又不想把音频传到云端、不想按分钟付费whisper.cpp 大概是目前最值得折腾的本地语音转文字方案。它在你的电脑上离线运行免费使用对中文的支持也算能打还能直接输出 SRT 字幕Windows、macOS、Linux 三个平台都有现成部署方式。我最初接触它是因为要给一段内部培训视频补字幕在线语音转文字的服务要么限时长要么质量一般要么收费不便宜。试了一圈下来whisper.cpp 成了我的默认选择。这篇文章把从部署到出字幕的完整流程写出来适合视频创作者、播客剪辑、学生党、以及所有对语音内容有整理需求的人。1. 为什么本地部署 whisper.cpp 而不是用在线 API在线语音转文字 API 大家应该都用过确实方便但问题也不少音频要上传隐私心里没底按分钟计费长视频成本吓人文件太大还可能被限制网络不稳定的时候直接没法用。whisper.cpp 把这些问题一次性解决了因为整个模型都在本地跑音频不出电脑也就不存在“偷偷上传”这回事。更重要的是它是开源的核心代码和模型都可以自己掌握不会哪天接口改版或者涨价就抓瞎。1.1 OpenAI Whisper 和 whisper.cpp 到底差在哪先简单区分概念。OpenAI Whisper 是一个开源语音识别模型最初是用 PyTorch 写的跑起来需要 Python 环境和大量依赖哪怕只是想转一段 5 分钟的音频也要先搭一个完整的环境。whisper.cpp 则是社区大佬 Georgi Gerganov 用 C/C 重新实现的一个版本核心目的就是干掉这些繁琐依赖让模型能在普通电脑上直接编译运行。用一句话总结原版 Whisper 像是实验室里的精密仪器什么都能干但需要一整套配套设备whisper.cpp 像是把核心功能塞进了一个便携工具箱拿来就用。它会把你下载好的模型转成 ggml 格式配合量化压缩让模型占用的内存和计算资源大幅下降。所以哪怕你没有 NVIDIA 显卡只有一颗普通 CPU也能跑起来只是速度快慢的问题。1.2 免费离线不是一句口号它解决了哪些真问题很多工具都宣传“免费离线”但真正用起来才发现只是噱头。whisper.cpp 不是它从运行到输出全都在本地完成没有隐藏的网络请求也不存在“试用期结束要付费”这回事。对隐私敏感的人来说这一条非常关键尤其是采访录音、患者谈话、内部会议这类不能外传的内容放在本地转写才安心。另一个容易被忽略的好处是稳定性。很多在线接口白天高峰期排队深夜又维护时间不等人。whisper.cpp 只要编译好了、模型下载好了随时都能用出差在高铁上没网也能处理手头的录音。配合脚本还能批量处理几十个文件一台老笔记本挂一晚上第二天早上全部转完这种体验在线服务很难给到。1.3 哪些场景最适合用 whisper.cpp我实际用下来的感觉它最擅长这几类场景视频字幕制作、课程笔记整理、播客逐字稿、记者采访录音整理、以及知识库素材入库前的中转处理。只要是“把语音变成文字”这件事它都能覆盖只是输出质量要看你选的模型和音频条件。但要注意它不适合做实时对话式语音助手那种场景。whisper.cpp 有 stream 例子但它是“整段音频处理”的思路延迟比较高不是为低延迟双向交互设计的。如果你需要的是实时字幕直播另找专门方案会更合适。清晰定位之后才知道该在什么环节用它而不是拿着锤子看什么都是钉子。2. 部署前先选对模型硬件要求与模型下载很多人一上来就 clone 源码、然后直接下最大的模型结果机器卡死。这个项目其实很像做饭菜谱、食材、锅具要匹配。whisper.cpp 的模型从 tiny 到 large 有好几个尺寸选错尺寸体验天差地别。这一节我专门讲硬件和模型怎么选帮你少走弯路。2.1 硬件需求没有 GPU 也能跑但内存很关键whisper.cpp 最大的优点就是不需要 GPU纯 CPU 也能跑。但“能跑”和“跑得舒服”是两回事。最关键的不是算力而是内存。模型加载时需要把权重全部放进内存比如 large 模型量化后大概 2-3GB再加上运行时的缓存和系统占用8GB 内存的机器会非常紧张。所以我给你一个保守参考tiny/base 适合 4GB 内存的机器small 建议 8GBmedium 建议 16GBlarge 最好 32GB。CPU 的指令集也会影响速度。比较新的处理器支持 AVX2whisper.cpp 能利用这些指令加速矩阵运算如果是十年前的 CPU跑 small 都会很吃力。Apple Silicon 用户有福M1/M2 芯片能直接走 Metal 加速跑 medium 的速度比同价位 Intel CPU 快不少。如果你有 NVIDIA 显卡也可以通过编译支持 cuBLAS 或 Vulkan 来加速但这就不是必需的了。2.2 模型怎么选tiny/base/small/medium/large 参数对比官方提供了好几种大小的模型我按中文场景整理了一张表方便你对照选择模型参数量量化后文件大小中文识别质量CPU 推理速度推荐场景tiny39M约 75MB能听出大概错误较多非常快快速测试、低配置机器base74M约 142MB简单短句还行复杂句子吃力快噪音低、短音频small244M约 466MB日常中文能到可用级别中等我的主力选择medium769M约 1.5GB中文准确率明显提升较慢正式字幕、复杂音频large-v31550M约 2.9GB效果最好但资源要求高很慢高要求、专业术语多这个文件大小是量化后的大概值不同量化精度会有浮动。我的经验是临时转个笔记用 small 足够做交付给别人的字幕用 mediumlarge 除非音频里全是专业名词、口音又重否则性价比不高。2.3 获取 whisper.cpp 源码和模型文件的三种方式第一步是拿到源码。最常规的办法git clone https://github.com/ggerganov/whisper.cpp.git cd whisper.cpp如果你嫌编译麻烦也可以直接去项目的 Release 页面下载 Windows 预编译包解压后里面有 main.exe省去整个编译过程。Linux 和 macOS 用户还是推荐源码编译后面我会说为什么。模型文件同样有几个来源。最简单的是使用官方脚本bash models/download-ggml-model.sh small这条命令会把对应名字的模型下载到 models 目录下。也可以手动到模型发布仓库里找 ggml-small.bin 这类文件放进 models 文件夹。下载模型时注意别中断文件不完整会导致后续加载直接报错。建议下载完看一眼文件大小是否和标注一致。3. 三平台编译安装实测Windows、macOS、Linux 都能一把过很多教程把编译说得很吓人其实真动手就会发现大部分时间花在解决环境问题上。我把三个平台的实测步骤写清楚你照着做基本不会翻车。3.1 Windows 上最快的两条路直接下载 Release 或 VS 编译如果你只是要转文字不想碰编译器最省心的方法是去 GitHub Releases 页面下载带 win-x64 字样的 zip 包解压后里面就有 main.exe。再配合模型文件打开 CMD 就能跑。实测这个预编译版本在 Windows 10/11 上都能直接运行杀毒软件偶尔会误报把它加白名单就好。如果你想自己编译推荐用 Visual Studio Build Tools。安装的时候勾选“使用 C 的桌面开发”工作负载装好后打开“x64 Native Tools Command Prompt for VS 2022”进入 whisper.cpp 目录依次执行cmake -B build -DCMAKE_BUILD_TYPERelease cmake --build build --config Release编译完成后可执行文件在 build\bin\Release 下面一般会生成 main.exe。这个过程大概十分钟取决于你机器性能。自己编译的好处是能拿到最新的代码而且可以根据 CPU 特性做优化跑起来更稳。3.2 macOS 编译Apple Silicon 有意外惊喜macOS 的编译简单不少。先用 Homebrew 或者 Xcode 命令行工具把基础环境准备好xcode-select --install然后进入 whisper.cpp 目录直接 makemake -j4Apple Silicon 芯片会自动启用 Metal 后端不需要额外配置。我实测在 M1 MacBook Air 上跑 medium 模型一段 20 分钟的音频大概几分钟就能出结果散热和功耗控制都不错。如果你用的是 Intel Mac也没问题就是以 CPU 推理的方式运行速度会慢一些。3.3 Linux 编译和常见依赖坑Linux 编译最标准。Ubuntu/Debian 先装依赖sudo apt update sudo apt install build-essential git然后make -j$(nproc)CentOS/RHEL 系则用yum groupinstall Development Tools。编译成功后模型文件放到 models 目录运行./main就能测试了。如果你有 NVIDIA GPU 想加速可以改用 CMake 并开启 cuBLAScmake -B build -DWHISPER_CUBLASON cmake --build build --config Release这里提醒一句Linux 下最容易踩的坑是没装 make 和 g报错信息五花八门其实只是基础工具缺失。先检查gcc --version和make --version不报错再继续。4. 核心命令从入门到进阶参数决定识别质量别急着跑模型先把 whisper.cpp 的常用参数搞清楚。它不复杂核心就是几个开关但用不用、怎么用识别质量差别很大。4.1 第一条命令把 WAV 转成文本假设你已经有了一个 16kHz 单声道 WAV 文件最简单的转写命令是./main -m models/ggml-small.bin -f audio.wav -l zh -otxt参数解释一下-m指定模型路径-f指定输入音频-l zh告诉它语音是中文-otxt表示输出纯文本文件。运行完后会生成 audio.txt打开就是转写结果。Windows 下把主程序换成main.exe即可参数完全一样。注意输入文件格式很关键。whisper.cpp 对音频格式的要求比较死最好提前用 ffmpeg 转成 16kHz、单声道、PCM 编码的 WAV。如果你直接丢一个 MP3 进去有可能会报错或者识别结果奇怪。后面我会给具体的转换命令。4.2 中文识别不理想的常见参数调整很多中文用户说 whisper.cpp 识别不准其实大都是两个原因模型太小或者没指定语言。忘加-l zh时它会先去自动检测语言检测错了就全输出英文这个坑我踩过不止一次。所以中文音频务必加上-l zh。第二个常用参数是线程数-t。默认值一般是 4如果你的 CPU 核心多可以加到 8 甚至更高速度提升明显。但也不要盲目拉满超过物理核心数反而会因为调度开销而变慢。第三个参数是 beam size用-bo 5表示 beam search 宽度为 5结果会更准确但耗时也更长。日常快速草稿用默认的贪心解码就行正式字幕再开 beam。还有一个容易被忽略的参数是提示词-p相当于给模型“开小灶”。比如你转写的是技术分享可以写./main -m models/ggml-medium.bin -f lecture.wav -l zh -otxt -p 以下是关于大模型部署和向量数据库的技术讲座。模型会根据提示词里的词增强相关内容的识别概率对专有名词很有帮助。4.3 一键生成 SRT 字幕和 VTT 字幕生成字幕是 whisper.cpp 的拿手好戏。要输出 SRT 文件加上-osrt参数./main -m models/ggml-medium.bin -f lecture.wav -l zh -osrt运行完会在同目录生成 lecture.srt格式大概是1 00:00:00,000 -- 00:00:03,500 大家好今天我们来讲...如果你需要网页播放器更通用的 VTT 格式用-ovtt。命令行里如果提示-osrt不被识别说明你用的版本比较老换成--output-srt或者先用./main --help看下支持的参数名。SRT 文件生成标准能直接拖进剪映、PR、PotPlayer 这些软件里用。4.4 从视频里抽音频再转文字的正确姿势whisper.cpp 不能直接吃视频文件所以得先把视频里的音频抽出来。ffmpeg 是标准方案命令如下ffmpeg -i video.mp4 -vn -ar 16000 -ac 1 -c:a pcm_s16le audio.wav解释一下参数-vn表示不要视频轨-ar 16000把采样率设成 16kHz-ac 1转成单声道-c:a pcm_s16le指定 PCM 编码。这一步做完得到的就是 whisper.cpp 最喜欢吃的音频格式。然后再接转写命令整体流程就通了。其实可以把转音频和转写写成一条链但我不建议用管道方式直接塞给 whisper.cpp因为它对 stdin 输入的支持在不同版本里差异很大。稳妥的做法是先落地成 WAV再转写中间文件以后也可以复用。5. 视频转字幕完整实操从 MP4 到 SRT 仅需三步前面参数讲得再多不如完整走一遍流程。我这里用一个 30 分钟的中文教学视频做演示目标是生成一份可以直接用的 SRT 字幕。5.1 准备工作ffmpeg 和音频重采样先确认你的电脑装了 ffmpeg终端里执行ffmpeg -version能看到信息就行。没装的话Windows 用户可以下载 ffmpeg 的 Windows 构建包把 bin 目录加到系统环境变量macOS 用brew install ffmpegLinux 用sudo apt install ffmpeg。这一步是后续所有操作的基础。把教学视频放到工作目录比如 lecture.mp4。先抽音频ffmpeg -i lecture.mp4 -vn -ar 16000 -ac 1 -c:a pcm_s16le lecture.wav抽出来的 lecture.wav 大约为每分钟 1.9MB30 分钟视频大概 57MB大小完全可接受。5.2 正式转写medium 模型跑 30 分钟中文视频使用 medium 模型开启 8 线程加上提示词跑一遍./main -m models/ggml-medium.bin -f lecture.wav -l zh -osrt -t 8 -bo 5 -p 这是一段编程教学视频涉及Python、数据库、API接口。我实测下来30 分钟音频在 8 核 CPU 上开 medium 模型大概要 20 到 40 分钟不同机器差异很大。等待期间不要急它不像在线接口那样秒出结果但胜在不用花钱。如果时间紧张可以把-bo去掉速度能快不少。转写完成后检查 lecture.srt 文件。如果发现有些句子明显断开错误或者时间轴有点乱可以用编辑器微调。因为 whisper.cpp 是按语音片段切分的它不太懂人类的标点符号所以 SRT 会时不时出现一句话被拆成两行、或者两句合并成一行的情况人工校对这一步省不掉。5.3 批量操作一次处理多个视频的脚本示例做播客或者课程整理时经常要一次处理十几个文件。手动一条条执行太累这时候用脚本批量跑最舒服。Windows 批处理的例子echo off for %%f in (*.mp4) do ( ffmpeg -i %%f -vn -ar 16000 -ac 1 -c:a pcm_s16le %%~nf.wav main.exe -m models\ggml-small.bin -f %%~nf.wav -l zh -osrt -t 4 )Linux/macOS 的 shell 脚本for f in *.mp4; do ffmpeg -i $f -vn -ar 16000 -ac 1 -c:a pcm_s16le ${f%.mp4}.wav ./main -m models/ggml-medium.bin -f ${f%.mp4}.wav -l zh -osrt -t 4 done这里用了 small 模型做示例批量场景里它速度更快不容易把整台机器拖到卡死。跑之前建议先处理一个文件确认路径没问题再全量跑不然几十个文件跑到一半才发现模型路径写错很浪费时间。5.4 字幕校对和简单美化生成 SRT 后我一般用 VS Code 或 Notepad 打开。先全局查找替换明显错误的人名、专有名词然后从头到尾通读一遍重点是语句断句和时间轴。对于字幕时间轴偶尔出现的“延迟”问题如果不是特别严重多数播放器都能手动调整。如果想直接把字幕烧进视频ffmpeg 也能做ffmpeg -i lecture.mp4 -vf subtitleslecture.srt -c:a copy output.mp4注意这个命令需要 ffmpeg 编译时带 libass 支持。如果不支持用剪辑软件导也很方便甚至可以直接把 SRT 拖进视频编辑软件里重新对一遍。6. 高频问题排查与避坑速查手册再顺手的工具也会遇到问题。这一节我把从编译到识别整个链路里最容易踩的坑集中整理一下基本覆盖了新手 90% 的报错。6.1 编译阶段最常见的三个错误第一个是 Windows 下提示make 不是内部或外部命令。这基本可以确定你没装 Visual Studio 的生成工具或者没在 VS 的命令行窗口里操作。解决方法是装 Build Tools然后打开“x64 Native Tools Command Prompt”不要用普通的 CMD。第二个是 Linux 下提示gcc: command not found。这是因为系统没有基础编译环境执行sudo apt install build-essential就能解决。别去网上搜各种奇怪的参数往往是基础依赖没装。第三个是 CMake 找不到编译器。多半是打开 CMake 之前没加载 VS 环境变量。Windows 上务必用“x64 Native Tools Command Prompt for VS 2022”来跑 CMake而不是普通 PowerShell。6.2 中文识别成英文或乱码不是模型不行是参数没给对中文全识别成英文绝大多数情况是没加-l zh。这个参数在旧版里甚至要写成-l Chinese新版用zh就行。如果加了还是不行检查一下音频里是不是没有有效语音或者开头有很长一段广告音乐模型被干扰了。乱码还有一种情况是终端编码问题Windows 老版终端默认 GBK输出 UTF-8 中文会显示乱码。这不影响生成文件内容你用文本编辑器打开 txt 或 srt 都是正常的不用纠结终端显示。6.3 识别速度太慢怎么办速度慢是高频问题但原因通常很直接。模型太大、线程太少、CPU 太老三选一或多选。快速方案是换 small 模型并把线程数调高到物理核心数附近比如-t 8。如果还是慢关闭 beam search用贪心解码。如果你愿意折腾可以考虑编译 GPU 加速版本。whisper.cpp 支持 cuBLAS 和 VulkanNVIDIA 显卡用户用 cuBLAS 提升最明显A 卡和核显可以试 Vulkan。Apple Silicon 用户不用管默认 Metal 加速就挺快。还有一点Windows 杀毒软件如果实时扫描很积极也会拖慢读写速度把 whisper.cpp 的工作目录加入排除项。6.4 SRT 时间轴合并和偏移问题字幕时间轴不准往往不是引擎的 bug而是输入音频的问题。比如说话中间有大段停顿模型会把这些停顿也算进同一个片段导致字幕出现时间过长或过短。解决办法是先用剪辑软件切掉头尾空白和过长的静音段再导出来转写。如果你的字幕整体都偏移了固定时间可以用 ffmpeg 的adelay或者字幕编辑工具批量调整。偶尔也会遇到两个 SRT 重叠那多半是同一个文件名残留了旧文件生成前先删掉旧版再跑一次。6.5 问题排查对照表症状可能原因解决办法编译时报 make 不存在没有安装构建工具Windows 装 VS Build ToolsLinux 装 build-essential加载模型报文件损坏模型下载不完整删除重新下载检查文件大小中文识别成英文没有指定语言加-l zh转写结果全是乱码终端编码问题用文本编辑器打开输出文件识别极其缓慢CPU 太老或模型过大换 small 模型开 GPU 加速输出 SRT 时间轴不准音频有长静音/噪声预处理音频消除空白段落程序直接崩溃输入格式不对或内存不足用 ffmpeg 转成 16kHz WAV换小模型7. 最后分享几个我实测有效的经验说了这么多最后聊一点个人使用习惯。我现在的工作流已经稳定了草稿用 small 模型几分钟就能出全文正式交稿用 medium配合提示词和人工校对基本能到可以直接用的水平。large 我很少碰因为普通机器等不起而提升的准确率对多数视频来说不值得多花几倍时间。还有一个我强烈建议你试一下的小技巧转写前先做响度归一化。音频音量忽大忽小、低语不清是识别准确率的大敌。用 ffmpeg 做一次简单的响度平衡ffmpeg -i input.wav -af loudnormI-16:TP-1.5:LRA11 normalized.wav处理完的音频再去转写尤其对手机录音、会议拾音这类素材提升非常明显。我现在已经把这个命令写进批处理脚本里了每次都会先跑一遍。环境不同效果可能有差异但大概率不会让你失望。whisper.cpp 是个还在持续更新的项目隔几个月就有新版本、新模型、新后端。如果你遇到文档里没见过的问题先pull一下最新代码很多坑其实早就在新版里修过了。希望这篇教程能帮你把本地语音转文字这条路走顺。