whisper.cpp 命令行实战手册从零搭建到实时语音识别的完整进阶路线【免费下载链接】whisper.cppPort of OpenAIs Whisper model in C/C项目地址: https://gitcode.com/GitHub_Trending/wh/whisper.cpp还在为音频转文字折腾 Python 环境、被 GPU 显存吓得不敢上手还在担心语音识别工具联网上传隐私数据、录音文件只能一帧一帧手动处理whisper.cpp 把 OpenAI Whisper 模型用纯 C/C 重写无需 Python、无外部依赖单文件编译、离线运行一条命令就能把 WAV 音频变成带时间戳的文字稿。读完本文你将能够在 10 分钟内完成环境搭建并跑通第一条转录按场景精准挑选模型与量化方案用 8 种输出格式对接字幕、数据分析等工作流掌握说话人分离、实时转录、语法约束与硬件加速四项进阶玩法最后借助 3 个实战案例和 1 份排错清单独立解决绝大多数语音识别问题。一、动手前先认清两件事它能做什么不能做什么很多人第一次用 whisper.cpp 时都会问它和 OpenAI 官方 Whisper 有什么区别简单说官方实现是 Python PyTorch而 whisper.cpp 是同一套模型权重的 C/C 移植推理引擎换成了轻量的 ggml 张量库。这意味着零依赖部署不需要 conda、不需要 torch、不需要 CUDA 工具链一条cmake命令就能编出可执行文件完全离线模型下载到本地后所有推理都在本机完成音频数据不出设备隐私敏感场景友好极致轻量tiny 模型只有 75 MiB老旧的树莓派、嵌入式设备也能跑跨平台Linux、macOS、Windows、iOS、Android、浏览器WebAssembly全覆盖但它也有明确的边界输入音频必须是 16-bit PCM 的 WAV 格式采样率一般要求 16 kHz、单声道。拿到 MP3、M4A 或视频里的音轨需要先用 ffmpeg 转一道。这一点后面会反复用到先记住这个转换模板ffmpeg -i 输入.mp3 -ar 16000 -ac 1 -c:a pcm_s16le 输出.wav小贴士-ar 16000强制 16 kHz 采样率-ac 1转单声道-c:a pcm_s16le指定 16-bit PCM 编码。这三项是 whisper.cpp 的标准入场券。二、三步完成环境搭建克隆、编译、验证第一步克隆仓库git clone https://gitcode.com/GitHub_Trending/wh/whisper.cpp cd whisper.cpp第二步编译项目Linux/macOS 与 WindowsMSVC通用 CMake 流程cmake -B build cmake --build build --config ReleaseWindows 用户如果想显式指定编译器可以在第一步加上生成器参数cmake -B build -G Visual Studio 17 2022 cmake --build build --config Release编译产物统一在build/bin/下Linux/macOS 是whisper-cliWindows 是whisper-cli.exe。第三步下载模型并验证./models/download-ggml-model.sh base.en ./build/bin/whisper-cli -m models/ggml-base.en.bin -f samples/jfk.wav终端里出现带时间戳的英文文本就说明整个链路已经打通。资源占用速查表按部署场景划分方便你快速对号入座部署场景推荐模型磁盘占用内存占用典型耗时1 分钟音频嵌入式/树莓派tiny75 MiB~273 MB数秒入门尝鲜/实时转录base142 MiB~388 MB1~2 秒日常转录够用small466 MiB~852 MB3~5 秒高精度正式场合medium1.5 GiB~2.1 GB10 秒以上追求极致准确率large-v32.9 GiB~3.9 GB半分钟以上避坑提醒内存占用指的是推理时的峰值常驻内存不是模型文件大小。8 GB 内存的机器跑 large 会非常吃力建议从 small 起步。三、选对模型是第一道分水岭命名规则、量化与下载策略读懂模型文件名的三个后缀whisper.cpp 的模型命名隐藏了三条关键信息.en后缀仅英文专用模型体积相同但英文准确率更高、速度更快没有这个后缀的是多语言模型支持中文等 90 余种语言-q5_0后缀量化模型体积压缩到原来的四成左右精度损失极小-tdrz后缀支持 tinydiarize 说话人转换检测的专用模型量化资源受限环境的减脂方案量化就是把模型的浮点权重压缩成低精度整数换来体积和内存的下降。whisper.cpp 提供了独立的quantize工具./build/bin/quantize models/ggml-base.en.bin models/ggml-base.en-q5_0.bin q5_0常用量化档位权衡表以 large-v3 为例量化档位压缩后体积相对原模型精度表现适用场景q8_0~2.2 GiB保留约 75%几乎无损精度优先又缺内存q5_0~1.1 GiB保留约 38%极小损失综合性价比之王q4_0~1 GiB 以下保留约 33%轻微损失极度受限环境量化后的模型直接通过-m指定即可使用用法和原版完全一致。小贴士官方还直接提供了large-v3-turbo-q5_0547 MiB这类出厂即量化的模型下载脚本里直接指定名字就行省去自己转换的步骤。两条下载路径# 路径一脚本一键下载推荐 ./models/download-ggml-model.sh large-v3-turbo # 路径二make 快捷方式同时自动跑 samples 目录下的示例音频 make -j large-v3-turbo四、核心玩法把一次转录任务拆成四个可控环节环节 1音频准备——把一切格式统一成 WAVwhisper-cli 只认 16-bit PCM WAV。转换模板在前面出现过这里补两个高频变体视频提音轨、批量转换。# 视频提取音轨 ffmpeg -i 视频.mp4 -vn -ar 16000 -ac 1 -c:a pcm_s16le 音频.wav # 批量转换目录下所有 mp3 for f in *.mp3; do ffmpeg -i $f -ar 16000 -ac 1 -c:a pcm_s16le ${f%.mp3}.wav; done环节 2语言与翻译——识别、检测、翻译三件套whisper-cli 默认语言是英文en处理中文或多语言内容必须显式指定# 指定中文识别 ./build/bin/whisper-cli -m models/ggml-medium.bin -l zh -f 音频.wav # 让模型自动检测语言适合多语言混排的录音 ./build/bin/whisper-cli -m models/ggml-medium.bin -l auto -f 音频.wav # 只做语言检测不转录快速确认音频语种 ./build/bin/whisper-cli -m models/ggml-medium.bin -l auto -dl -f 音频.wav # 翻译成英文输入任意语言输出统一英文 ./build/bin/whisper-cli -m models/ggml-medium.bin -l zh -tr -f 音频.wav参数逐个说清楚-l/--language取值en、zh、ja等语言代码或auto自动检测。指定正确语言能显著提升准确率和速度因为省去了语言识别的开销-dl/--detect-language检测完语言立即退出适合做批量语种摸底-tr/--translate把识别结果翻译成英文注意它只能翻译成英文想中译英之外的方向请另想办法环节 3输出格式——八种格式各有各的舞台这是 whisper-cli 最实用的能力之一一次转录可以同时导出多种格式# 同时输出纯文本 SRT 字幕 JSON ./build/bin/whisper-cli -f 音频.wav -otxt -osrt -oj -of 导出文件名 # 不指定 -of 时默认以输入文件名命名 ./build/bin/whisper-cli -f 音频.wav -osrt # 生成 音频.srt输出格式对照表参数格式典型用途-otxt纯文本文字稿、会议纪要-osrtSRT 字幕视频字幕兼容性最好-ovttWebVTT网页视频字幕-olrcLRC 歌词歌词滚动显示-ocsvCSV 表格数据分析、Excel 处理-ojJSON程序对接、二次开发-ojfJSON 完整版含模型结构、逐 token 概率等调试信息-owts卡拉 OK 脚本生成可执行的 ffmpeg 逐词高亮脚本-of/--output-file可以指定输出文件的基础名不带扩展名一次指定、多格式共享。环节 4时间戳与进度控制——精细到毫秒的指挥棒# 跳过前 30 秒只处理 60 秒内容 ./build/bin/whisper-cli -f 长录音.wav -ot 30000 -d 60000 # 去掉时间戳纯文本输出 ./build/bin/whisper-cli -f 音频.wav -nt # 显示处理进度百分比 ./build/bin/whisper-cli -f 长录音.wav -pp # 限制每段文字的最大长度按字符并允许在单词边界切分 ./build/bin/whisper-cli -f 音频.wav -ml 80 -sow高频参数速查-ot/--offset-t起始偏移毫秒跳过开头静音或废话-d/--duration处理时长毫秒只处理片段适合长文件试跑-ml/--max-len单段最大字符数数值越小字幕切得越碎-sow/--split-on-word按单词边界切段而不是按 token对英文字幕更友好-t/--threads计算线程数默认取 CPU 核心数与 4 的较小值建议调到物理核心数的 1~2 倍避坑提醒-ot和-d的单位是毫秒别按秒写——把-d 60000写成-d 60只会得到 60 毫秒的转录结果。五、进阶玩法一用采样策略对抗幻觉和低质量音频Whisper 模型有个著名的毛病面对静音、噪声或听不懂的内容时会一本正经地编造文本。whisper-cli 提供了一整套采样控制参数来治这个病。温度与回退机制# 降低随机性让输出更稳定适合访谈、朗读等口齿清晰的内容 ./build/bin/whisper-cli -f 音频.wav -tp 0.0 # 禁止温度回退解码失败时不做二次尝试直接报错 ./build/bin/whisper-cli -f 音频.wav -tp 0.0 -nf-tp/--temperature采样温度取值 0~1。0 表示完全贪心解码输出最确定调高则增加随机性可能脑补出更流畅但不可信的句子-tpi/--temperature-inc温度增量。默认 0.2即当模型因置信度过低触发回退时每次把温度加 0.2 重试最多加到 1.0-nf/--no-fallback关闭上述回退机制。当你的音频内容固定、可预期时如固定话术的语音指令加上它能避免无意义的重复计算置信度门槛三件套# 熵阈值片段熵值超过 2.4 判定为听不懂触发重采样 ./build/bin/whisper-cli -f 音频.wav -et 2.4 # 对数概率阈值低于 -1.0 的片段同样触发重采样 ./build/bin/whisper-cli -f 音频.wav -lpt -1.0-et/--entropy-thold解码结果的熵阈值。熵高意味着模型犹豫不决超过阈值就判定本次解码失败-lpt/--logprob-thold对数概率阈值作用类似从概率角度兜底这两个参数是温度回退机制的触发器片段一旦被判为失败whisper-cli 就会按-tpi的步长升温重试。所以想让它们生效别同时加-nf。束搜索与候选数# 束搜索同时保留 5 条最优路径综合决策 ./build/bin/whisper-cli -f 音频.wav -bs 5 # 贪心采样保留 2 个候选 ./build/bin/whisper-cli -f 音频.wav -bo 2-bs/--beam-size束搜索宽度越大越准也越慢官方默认 5-bo/--best-of贪心采样保留的候选数默认 5小贴士默认的采样方式是贪心-bo只有显式指定-bs才启用束搜索。两者二选一别同时调。词汇级抑制直接堵住脏话和口头禅# 用正则抑制嗯啊等语气词 ./build/bin/whisper-cli -f 音频.wav --suppress-regex (嗯|啊|那个|然后就是) # 单词级时间戳调低概率门槛拿到更精确的逐词时间 ./build/bin/whisper-cli -f 音频.wav -wt 0.05--suppress-regex匹配到的 token 会被直接禁止输出对付口头禅、脏话、特定人名非常有效-wt/--word-thold单词时间戳的概率阈值默认 0.01。调低会输出更多单词级时间戳供-owts之类的功能使用六、进阶玩法二说话人分离两种方案按需取方案 A双声道能量对比-di无需专用模型如果录音是立体声、且两个人分别录在左右声道比如分轨录制的访谈、会议whisper-cli 可以直接对比两个声道的能量来判断谁在说话./build/bin/whisper-cli -m models/ggml-base.en.bin -di -f 双声道访谈.wav -osrt输出时会在每段前面标注(speaker 0)或(speaker 1)。原理很朴素比较时间段内左右声道的平均绝对振幅能量高的一侧判为该段发言人两侧能量接近则标?。方案 Btinydiarize 单声道说话人转换-tdrz双声道方案对单声道的普通录音无能为力这时需要 tdrz 专用模型./models/download-ggml-model.sh small.en-tdrz ./build/bin/whisper-cli -m models/ggml-small.en-tdrz.bin -tdrz -f 单声道录音.wav它会在说话人切换的位置插入[SPEAKER_TURN]标记方便后续脚本切分。注意tdrz 模型目前只有英文版本中文场景暂时只能用方案 A 或其他外部方案。避坑提醒-di需要输入文件本身是双声道 WAVffmpeg 转码时别加-ac 1保持-ac 2-tdrz必须搭配 tdrz 模型否则参数会被静默忽略。七、进阶玩法三实时转录用 stream 工具接管麦克风离线转文件解决的是存量音频而 stream 示例解决的是正在发生的对话。它持续从麦克风采集音频按固定窗口滚动识别cmake --build build --target stream ./build/bin/stream -m models/ggml-base.en.bin -t 4 --step 500 --length 5000两个核心参数是一对跷跷板--step每次推进的音频步长毫秒默认 500。越小响应越灵敏但计算频率越高CPU 占用越大--length送入模型的上下文窗口毫秒默认 5000。越大越能结合前文语境但单次推理耗时越长调优口诀延迟敏感如语音助手就缩小--step、放大线程数准确率敏感如会议同传就放大--length换取上下文连贯。注意 stream 默认也是英文模型中文场景记得加-l zh并换多语言模型。八、进阶玩法四语法约束与硬件加速把性能榨到最后一滴语法约束让识别结果只能长成规定样子GBNF 语法文件可以把识别结果约束在指定格式内特别适合语音指令、菜单点选、命令控制等结构化场景# 让输出只能是颜色名称的组合项目自带示例语法 ./build/bin/whisper-cli -f 指令.wav --grammar grammars/colors.gbnf # 自定义语法只认打开/关闭 设备名两种模式 ./build/bin/whisper-cli -f 指令.wav --grammar 我的语法.gbnf --grammar-rule command语法文件写法colors.gbnf 的简化版root :: (red | green | blue | yellow | black | white) (space (red | green | blue | yellow | black | white))* space :: --grammar语法文件路径--grammar-rule顶层规则名默认root--grammar-penalty非语法 token 的惩罚系数默认 100越大越死板这套机制的价值在于识别结果天然满足下游程序的解析需求省去一层后处理纠错。硬件加速按你的设备选一条路whisper-cli 默认优先使用 GPU编译时若启用了对应后端-ng/--no-gpu可强制回到纯 CPU# CPU 平台 ./build/bin/whisper-cli -f 音频.wav -ng # NVIDIA GPU编译时启用 CUDA cmake -B build -DGGML_CUDA1 cmake --build build --config Release ./build/bin/whisper-cli -f 音频.wav # Apple Silicon编译时启用 Metal默认就是第一公民 cmake -B build -DGGML_METAL1 cmake --build build --config Release # 支持 Flash Attention 的 GPU 上进一步提速 ./build/bin/whisper-cli -f 音频.wav -faIntel 设备还有一条 OpenVINO 路线先在models/目录下执行python convert-whisper-to-openvino.py --model base.en生成 IR 模型再以-DWHISPER_OPENVINO1编译最后用-oved GPU指定推理设备。小贴士CPU 上也可以先试试-faFlash Attention部分 x86 CPU 与 ARM 平台同样受益。九、实战案例三个场景串起全部知识点案例 1播客访谈批量转文字稿背景手上有 10 期每期约 1 小时的播客音频MP3需要整理成带说话人标注的文字稿归档。# 步骤 1批量转 WAV16 kHz 单声道 for f in episode*.mp3; do ffmpeg -i $f -ar 16000 -ac 1 -c:a pcm_s16le ${f%.mp3}.wav; done # 步骤 2逐集转录输出纯文本 SRT JSON 三份 for f in episode*.wav; do ./build/bin/whisper-cli -m models/ggml-medium.bin -l zh \ -f $f -otxt -osrt -oj -pp -t 8 done # 步骤 3用 jq 从 JSON 抽取纯文本拼接成完整文稿 jq -r .transcription[].text episode01.json episode01.txt收益原始录音变成可搜索、可引用的结构化资产SRT 还能直接给视频剪辑用。案例 2多语言视频一键生成双语字幕背景一段中英混说的 vlog 视频要生成带时间轴的中文字幕并烧录进画面。# 步骤 1从视频提取音轨 ffmpeg -i vlog.mp4 -vn -ar 16000 -ac 1 -c:a pcm_s16le vlog.wav # 步骤 2自动检测语言并转录多语言模型 auto ./build/bin/whisper-cli -m models/ggml-large-v3.bin -l auto -f vlog.wav -osrt -of subtitles # 步骤 3把字幕烧录进视频 ffmpeg -i vlog.mp4 -vf subtitlessubtitles.srt vlog_带字幕.mp4收益-l auto让中英混说自动分流-of subtitles统一命名最后一步 ffmpeg 直接完成压制。案例 3口述写作——把语音备忘录变成 Markdown 初稿背景没有键盘的场景下想记录灵感用手机录一段语音回电脑后一键变成文字稿。# 步骤 1手机录音转 WAV ffmpeg -i 灵感录音.m4a -ar 16000 -ac 1 -c:a pcm_s16le 灵感.wav # 步骤 2中文转录去掉时间戳抑制口头禅控制段落长度 ./build/bin/whisper-cli -m models/ggml-small.bin -l zh \ -f 灵感.wav -otxt -nt \ --suppress-regex (嗯|啊|呃|那个|就是说) -ml 60 # 步骤 3把生成的 灵感.txt 改名成 Markdown作为初稿继续编辑收益识别结果干净利落没有时间戳噪音口头禅被正则拦截-ml 60保证段落长度适合直接阅读几乎零成本进入写作状态。十、常见问题排查对话式排错清单问报错failed to open ... for reading模型文件明明在答检查-m的路径是否写对。默认值是models/ggml-base.en.bin如果你没下载 base.en 模型或下载的是ggml-base.bin多语言版文件名对不上就会打开失败。用ls models/核对一下实际文件名。问转录出来一堆乱码或空白中文识别结果奇差答多半是用错模型了。.en后缀的模型只懂英文处理中文必须用不带后缀的多语言模型如ggml-small.bin同时显式加-l zh。另外确认音频确实是 16 kHz 单声道 WAV——采样率不对会直接导致识别质量崩塌。问明明加了-ng想禁用 GPU却提示 GPU 初始化失败答-ng/--no-gpu是布尔标志不带参数值。写-ng 0或-ng 1反而会把它当未知参数。如果 GPU 后端编译时没启用比如没加-DGGML_CUDA1程序本身就在跑 CPU加不加-ng没区别。问长音频跑到一半内存暴涨进程被杀答模型选太大了。按第三节的表格换小一号的模型或改用量化版本。另外-mc/--max-context可以限制文本上下文 token 数默认 -1 表示不限制-ac/--audio-ctx可以限制音频上下文都是压内存的手段但会牺牲长文连贯性。问输出里出现大量重复的胡言乱语幻觉答经典问题。按优先级试三招① 加-tp 0.0关闭随机性② 调低-et熵阈值让低置信片段更快触发回退重试③ 检查音频开头是否有长段静音用-ot跳过它——静音是幻觉的第一大温床。问SRT 字幕时间轴和画面对不上答whisper 的时间戳是段级的本身存在几百毫秒误差。追求逐词精确可以用-dtw指定 DTW 模型计算 token 级时间戳或者用-sow让切段更贴近单词边界减小单段内的时间漂移。十一、总结与下一步从会用走向会造到这里你已经走完了装环境 → 选模型 → 跑转录 → 调参数 → 玩进阶 → 做实战 → 查排错的完整闭环。回头看看收获掌握了 CMake 编译与模型下载学会了按场景在 5 档模型和 3 档量化之间做权衡能把一次转录拆成音频、语言、输出、时间戳四个可控环节会用采样策略对抗幻觉、用双通道或 tdrz 做说话人分离、用 stream 接麦克风实时识别、用 GBNF 约束输出结构三个实战案例则把这些能力串成了可复用的工作流。如果想继续深挖下面四条路值得探索嵌入你的应用项目提供纯 C 风格 APIinclude/whisper.h并已有 Go、Java、Ruby、JavaScript 等官方 binding把识别能力做成你产品的一个模块浏览器端部署whisper.wasm 让模型跑在浏览器里实现完全离线的 Web 语音应用服务端零成本微调专属模型用models/convert-pt-to-ggml.py或convert-h5-to-ggml.py把 Hugging Face 上微调过的 Whisper 权重转成 ggml 格式打造你的领域专用识别器深度性能优化针对特定硬件AVX2、ARM NEON、Ascend NPU调整编译选项或研究 ggml 的算子实现把推理延迟再压一个量级语音识别这条路whisper.cpp 给了你一个足够低的天花板起点——现在轮到你的音频说话了。【免费下载链接】whisper.cppPort of OpenAIs Whisper model in C/C项目地址: https://gitcode.com/GitHub_Trending/wh/whisper.cpp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考