whisper.cpp 完整实战教程语音转文字、字幕生成与实时转录一次通关【免费下载链接】whisper.cppPort of OpenAIs Whisper model in C/C项目地址: https://gitcode.com/GitHub_Trending/wh/whisper.cpp想在无网环境把录音秒变文字想在树莓派上跑离线语音助手whisper.cpp 就是为此而生的——它是 OpenAI Whisper 模型的 C/C 移植版无第三方运行依赖编译后只有一个可执行文件CPU 即可推理还能按需接上 CUDA、Metal、OpenVINO 等加速后端。这篇教程不罗列特性直接带你从零编译、首次转录一路做到实时麦克风转录与语法约束的语音指令。先聊一个真实的低效场景团队里要转写每周例会录音以前的做法是装 Python 版 whisper光 torch 依赖就占好几个 G还得祈祷有 GPU数据传到云端 API又过不了隐私审计。直到换成 whisper.cpp一台 4 核的旧笔记本量化后的 base 模型 300MB 内存不到一段 11 秒的音频秒级出结果全程离线。这就是它值得你花半小时上手的原因同样的识别质量部署成本低一个数量级。速通五步搭出最小可用环境别急着研究参数先让第一段音频跑出文字建立正反馈。第 1 步拉取仓库git clone https://gitcode.com/GitHub_Trending/wh/whisper.cpp cd whisper.cpp第 2 步编译cmake -B build cmake --build build --config Release为什么推荐 CMake 而不是根目录的 MakefileCMake 能按需开关组件GPU、SDL2、ffmpeg后续加加速后端时不用改构建方式只加一行-D选项。编译产物统一落在build/bin/下面几个工具都在这里。第 3 步下载模型sh ./models/download-ggml-model.sh base.en模型默认存到models/命名规则是ggml-型号.bin。入门阶段选base.en最稳体积适中、英文识别质量够用、加载快。第 4 步跑通第一次转录./build/bin/whisper-cli -f samples/jfk.wav -l en-l en显式声明语言省去自动检测的开销。仓库自带的samples/jfk.wav是肯尼迪演讲片段正常你会看到带时间戳的分段输出类似[00:00:00.000 -- 00:00:11.000] And so my fellow Americans, ask not what your country can do for you, ask what you can do for your country.看到这行输出环境就通了。第 5 步跑个分心里有底./build/bin/whisper-bench -m ./models/ggml-base.en.bin -t 4bench 只跑编码器部分输出 encode time 和总耗时可作为后续调优前后的对比基线。建议把这组数字存下来后面折腾量化、线程数时对照着看提升了多少。动手前先算一笔资源账。不同模型对磁盘和内存的要求差很多别一上来就上 large型号文件大小运行期内存典型场景tiny75 MiB约 273 MB树莓派、低功耗设备base142 MiB约 388 MB通用入门、实时转录small466 MiB约 852 MB追求中等精度medium1.5 GiB约 2.1 GB高精度离线转写large2.9 GiB约 3.9 GB质量优先、资源充裕一张表看懂核心参数whisper-cli 的参数有几十个但日常高频使用的就十来个。按用途分成四组先记住这张速查表分组参数作用建议值运行-t N推理线程数CPU 核数的 1~2 倍运行-p N并行处理流水线数2~4多核收益明显输入-l LANG指定语言auto自动检测已知语言时显式指定输入-tr翻译成英文输出多语言转英文时开启约束-mc N文本上下文 token 上限默认 -1 不限约束-ml N每段最大字符数字幕场景设 40~80约束-bo N/-bs N采样候选数 / 束搜索宽度默认 5精度不够再调大输出-otxt-oj-ocsv输出 TXT / JSON / CSV按下游用途组合输出-osrt-ovtt输出 SRT / VTT 字幕视频场景常用输出-of NAME输出文件前缀批量任务必备调试-pp打印处理进度长音频必开两个容易被忽略但很值的参数-fa开启 Flash Attention支持的硬件上能显著提速--prompt ...塞一句领域上下文比如以下是医疗问诊录音能明显压低专业术语的错字率。实战一把会议录音变成可检索的转写稿目标一段 40 分钟的 MP3 会议录音 → 带时间戳的文本稿 JSON 结构化数据方便检索和二次加工。为什么先转 WAVwhisper-cli 目前只吃 16-bit PCM 的 WAV。Whisper 训练时用的就是 16kHz 单声道所以转换时顺手把采样率、声道对齐既符合模型输入规格又省解码开销ffmpeg -i meeting.mp3 -ar 16000 -ac 1 -c:a pcm_s16le meeting.wav转写并同时导出多格式./build/bin/whisper-cli -m models/ggml-medium.bin -l zh -t 8 -pp \ -f meeting.wav -otxt -oj -ocsv -of meeting_result一次性生成meeting_result.txt、meeting_result.json、meeting_result.csv。JSON 里的核心结构是 segments 数组每段带 start/end 毫秒时间戳和文本足够你写脚本按关键词切片、做摘要。结果解读与提速技巧如果发现专有名词识别率低加--prompt 公司名: 星河科技; 人名: 张伟, 李娜这类提示如果某些词反复误识用--suppress-regex (嗯|啊|那个)把口头禅压掉。中文长录音建议-mc 1024稍微放开上下文让模型记得更早的内容。实战二批量视频字幕流水线目标一个文件夹里 20 集课程视频全部生成 SRT 字幕。做法先用 ffmpeg 批量抽音频再循环调用 whisper-cli。用一段小循环串起来for f in videos/*.mp4; do base$(basename $f .mp4) ffmpeg -i $f -vn -ar 16000 -ac 1 -c:a pcm_s16le wavs/$base.wav ./build/bin/whisper-cli -m models/ggml-small.en.bin -t 8 -pp \ -f wavs/$base.wav -osrt -ovtt -ml 42 -of subs/$base done-ml 42把每段压到一行字幕的合理长度避免出现整屏大字。SRT 给播放器、VTT 给网页端一次全出。想要卡拉 OK 效果再加-owts生成 ffmpeg 脚本执行后能在视频里逐词高亮歌词——做歌词视频或者带读视频很实用细节见 examples/cli/README.md。实战三接上麦克风做实时转录目标边说话边出字延迟控制在秒级用作会议实时字幕或语音输入。这里用到独立工具whisper-stream它依赖 SDL2 采集麦克风先装库再编译# Debian/Ubuntu sudo apt-get install libsdl2-dev # macOS brew install sdl2 cmake -B build -DWHISPER_SDL2ON cmake --build build --config Release跑起来./build/bin/whisper-stream -m models/ggml-base.en.bin -t 8 --step 500 --length 5000两个关键旋钮解释清楚--step 500表示每 500ms 采样一次新音频并触发一轮转录越小延迟越低、CPU 压力越大--length 5000是送入模型的上下文窗口越大越记得住前文、单次耗时越长。新手直接抄上面的值再按体验微调。进阶静音触发模式。把--step设成 0 进入滑动窗口模式工具内置了简易 VAD语音活动检测检测到人声才转录安静时完全不跑模型适合长时间挂机./build/bin/whisper-stream -m models/ggml-base.en.bin -t 6 --step 0 --length 30000 -vth 0.6-vth是 VAD 阈值调大更容易判定为静音0.6 附近是多数场景的甜点值详见 examples/stream/README.md。实战四语法约束下的语音指令目标识别结果必须落在预定义命令集合内杜绝模型自由发挥——这是语音助手、智能家居控制器的刚需。whisper-cli 支持用 GBNF 语法文件约束解码。仓库自带一个颜色语法 grammars/colors.gbnf内容大致是从 red/green/blue 等颜色词中按模式组合用它识别颜色指令./build/bin/whisper-cli -f color_cmd.wav --grammar grammars/colors.gbnf想让设备听懂开灯/关灯/调亮度写一份home_commands.gbnf后同样用--grammar指过去再配合--grammar-rule command指定顶层规则。更省事的方案是直接用whisper-command的 guided mode——把允许的指令逐行写进文件模型只在这些候选中做分类./build/bin/whisper-command -m models/ggml-base.en.bin -cmd ./examples/command/commands.txtguided mode 的实际收益是性能候选集合小编码器可以只跑一部分在树莓派这类弱设备上也能实时响应参考 examples/command/README.md。量化与硬件加速性能优化的两个杠杆杠杆一模型量化。把 FP16 权重压成低比特整数体积和内存立减代价是轻微精度损失。官方提供quantize工具一条命令完成./build/bin/quantize models/ggml-base.en.bin models/ggml-base.en-q5_0.bin q5_0三个常用档位怎么选档位体积压缩精度代价用武之地q4_0约减半轻微内存极紧的嵌入式设备q5_0约减四成极小多数场景的平衡点q8_0约减四分之一基本无损对精度敏感的生产任务杠杆二硬件后端。编译时通过-D开关启用运行时代码零改动# NVIDIA GPU需 CUDA 工具链 cmake -B build -DGGML_CUDAON # Apple Silicon cmake -B build -DGGML_METALON # Intel 平台 cmake -B build -DWHISPER_OPENVINOONOpenVINO 场景下额外用-oved GPU指定推理设备。无论哪个后端CPU 版都保留作为兜底——这正是 C/C 移植版最省心的点换机器不用换方案。另注意旧文档里的WHISPER_CUDA、WHISPER_METAL写法已废弃统一用GGML_*前缀。高频问题与避坑清单症状根因解法报内存不足模型档位超出硬件换小模型或用 q5_0 量化版cannot open file音频不是 16-bit PCM WAVffmpeg 转成 16kHz 单声道GPU 始终不生效编译时没开对应后端加-DGGML_CUDAON后重编中文识别全是拼音/乱码语言没指定显式-l zh别依赖 auto-tdrz无效果用了普通模型必须配small.en-tdrz专用模型stream 编译失败缺 SDL2先装 libsdl2-dev 再-DWHISPER_SDL2ON长音频越到后面越飘上下文被截断调大-mc或-ac还有一条容易踩的坑-of指定的前缀不要带扩展名工具会按输出格式自动补全.srt、.json手写扩展名会导致文件错位。下一步从会跑到能交付到这里你已经覆盖了离线转写、字幕、实时流、指令识别四条主线。继续进阶有四个方向做服务whisper-server提供 HTTP 接口把转录能力封装成微服务见 examples/server/。嵌进你的代码项目提供 C APIinclude/whisper.h官方 Go/Java/Ruby/JavaScript 绑定在 bindings/ 下写业务层不用碰 C。浏览器里跑WASM 版本 examples/whisper.wasm/ 可让转录完全发生在用户浏览器。自训练模型接入models/convert-pt-to-ggml.py可把微调过的 PyTorch 权重转成 ggml 格式私有词表也能落地。现在就去把第一步跑通克隆仓库、编译、听一次 jfk.wav 的出字。十分钟后你就拥有了一个完全离线、可嵌入、可量产的语音转文字引擎。动手吧跑通第一个命令再回来选方向。【免费下载链接】whisper.cppPort of OpenAIs Whisper model in C/C项目地址: https://gitcode.com/GitHub_Trending/wh/whisper.cpp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考