简介：面向离线语音识别场景，这份压缩包提供基于whisper.cpp的完整可编译方案，适合需要本地部署、不依赖云端API的开发者。包内含真正的语音识别引擎源码、ggml系列模型文件（base/small/tiny），以及Go服务器代码（main.go）、C包装层（whisper_wrapper.c），并附编译脚本、启动脚本、测试页面与配置文件，打通了从模型加载到HTTP服务的完整链路，可直接在Windows环境编译运行。资源共1013个文件，涵盖cpp/hpp源码、cu/cuh GPU相关文件、go服务代码、bat脚本、bin模型及vue/html前端等类型，整体约630MB，结构清晰。目前已有711人浏览学习，适合有C++/Go基础、想快速上手离线语音识别的进阶开发者，也适合作为二次开发或集成到其他项目的参考基座。
1. 通过 whisper 做编译后的离线语音识别：没网机器上的语音转写，到底卡在哪
说到通过 whisper 做编译后的离线语音识别，我最典型的场景是给一台完全不联网的工控机做语音转写：录音带着点方言口音，要求本地出文字，不能走任何云端服务。一开始跑原版 Python 推理，一秒钟音频要等上大半天，模型冷启动能拖到几十秒，CPU 占用和内存波动都让人焦虑。把 whisper 编译成原生二进制、模型换成量化格式之后，同样一台机器上推理速度快了不止一个量级，交付物也从一个依赖一堆 Python 包的环境，变成一个可执行文件加一个模型文件。
下面顺着这条链路展开：编译到底解决了什么、有哪几种编译姿势、从零怎么跑通、哪些参数真正影响效果，以及我实际踩过的五个坑。适合谁看？准备把语音识别放进内网系统、嵌入式设备和私有化交付方案的开发者，尤其是被 Python 版推理的速度和部署复杂度折腾过的人。
2. 为什么必须“编译后”：从脚本到原生二进制，离线场景的唯一出路
2.1 原版 Python 推理的瓶颈：解释器、张量分配与模型加载黑匣子
先把原版推理为什么慢这件事说透。whisper 的原版 Python 实现，推理链路是“Python 调度深度学习框架算子”，音频读进来先转 log mel 特征，然后进入 Transformer 解码循环。每一步都有 Python 层参与：候选排序、温度采样、文本后处理、时间戳对齐，全在解释器里跑。解释器本身不是瓶颈的全部，更麻烦的是张量的生命周期：每个解码 step 都要创建新的中间张量，Python 的垃圾回收不定时触发，内存分配器频繁向系统要页。这就导致一个现场很常见的体感——同一段音频同一个模型，连续跑三次，耗时在 3 秒、5 秒、2 秒之间波动。做定时任务的人最怕这种抖动。
模型加载也是个黑匣子。原版加载 large 模型，要反序列化权重、做图优化、建立算子执行计划，冷启动几十秒是常态。在离线交付场景，这意味着用户每次重启服务都要等半分钟才能开始识别，体验上基本属于不可用状态。而编译后的方案把这些全部固化：模型加载变成一次内存映射，推理循环变成确定性的机器指令，内存分配在启动阶段一次性规划完。波动不是被优化掉了，而是这个路径上根本没有 Python 层。
这里还要提一个很多人忽略的点：Python 的 GIL 虽然不影响深度学习算子的底层计算，但在解码循环、文本后处理这些 CPU 密集且不释放 GIL 的环节，多线程并行度会被锁住。也就是说，同样的四核机器，原版推理能利用到的并行能力远低于编译版。这个差距在长音频和高并发场景下会被放大，最终体现为“为什么换了机器还是这么慢”的困惑。
2.2 三种编译落地形式的取舍：C++ 移植、ONNX 导出与专用推理后端
把 whisper 编译落地的形式，我在项目里实际接触过三类，各有明确适用边界。
第一类是社区移植的 C++ 实现，模型转成 ggml 格式并量化。优势是单文件可执行、C 接口简单、ARM 平台支持好，模型可以量化到 q5_0/q8_0，内存占用能压到很低。交付时就是一个二进制加一个模型文件，非常适合内网和嵌入式。缺点是生态新特性跟进慢，精调能力相对弱。
第二类是导出 ONNX 再挂 ONNX Runtime。适合已有 ONNX 推理管线的团队，模型产线能统一到同一套工具链。但 whisper 的解码逻辑不只有模型推理，还有复杂的 beam search 和文本处理，这部分 ONNX Runtime 不帮你实现，得用 C++ 或 C# 自己重写。我的经验是：如果团队没有现成的 ONNX Runtime 基建，不要为了“标准格式”而选这条路，工程量比想象中大很多。
第三类是 CTranslate2 这类专用推理后端，它把模型转成自己的量化布局，支持 fp16/int8，服务端并发能力很强。基于它的 whisper 推理方案在 CPU 服务端上性能非常能打。缺点是交付物要带上对应的运行时库，体积比单文件方案大，部署时依赖目录要打点清楚。
三个方向的取舍，我用一张表总结：
| 落地形式 | 交付物形态 | 优点 | 适合场景 |
|---|---|---|---|
| C++ 移植版 | 单文件 + 模型文件 | 启动快、体积小、ARM 友好 | 嵌入式、内网交付 |
| ONNX 导出 | 模型文件 + ONNX Runtime | 统一工具链 | 已有 ONNX 基建的团队 |
| 专用推理后端 | 运行时库 + 模型文件 | 并发强、量化成熟 | 服务端批量识别 |
我的选择逻辑：目标机是嵌入式盒子和低配 ARM 板，用第一类；目标是 x86 服务器、需要高并发在线识别，用第三类；团队已有 ONNX 生态，才考虑第二类。别只看“标准格式”这种概念，先看目标机上能不能少装东西、出了问题你能不能现场排查。
2.3 “编译”的两层含义：代码编译与模型转换，缺一不可
“编译”这个词在 whisper 生态里容易产生歧义，我第一次做的时候就栽在这里。它其实包含两层：第一层是把推理代码编译成目标平台的可执行文件；第二层是把模型权重从 PyTorch 格式转换成推理引擎专用的格式，比如 ggml 或 CTranslate2 格式。
这两层必须匹配。如果你只编译了代码，却拿着原版权重去加载，程序会在读取模型时直接报错，或者识别出一堆乱码。反过来，模型转了格式但代码是旧版本，也可能因为协议不匹配崩溃。所以“编译后的离线语音识别”严格说应该是“代码编译 + 模型转换”的组合。
实操顺序也很重要。我的习惯是先把模型转换好，再编译代码，最后跑一个固定测试音频确认格式匹配。因为代码编译报错容易定位，模型转换失败则经常是半程中断，两个问题混在一起时排查效率极低。后面第三章我会按这个顺序展开。量化档位也有讲究：q8_0 几乎无损但文件大，q5_0 文件小但质量略有下降。离线交付我默认 q5_0，除非客户明确要求最高精度。
2.4 离线环境对编译版的核心诉求：体积、冷启动与 CPU 兼容
离线这两个字，意味着目标机器可能没有外网、没有编译器、甚至没有管理员权限。这时候编译版必须提前想清楚三件事。
第一是体积。语音模型本身就是大头，small 量化后也要两百多 MB，large 量化后能到 1.5 GB 上下。加上程序、动态库、音频转码工具，整体交付物可能超过 2 GB。内网传输倒还好，但嵌入式设备的存储往往以 GB 计，选型时要先确认磁盘余量。第二是冷启动。多数离线识别不是常驻服务，而是按需唤起。进程启动到能开始识别的时间段，编译版能做到几百毫秒到一两秒，Python 版动辄几秒甚至几十秒。在交互式场景，这个差异是决定性的。第三是 CPU 指令集兼容。这是离线交付最容易翻车的点：开发机的 CPU 支持 AVX2，编译产物在客户的老 CPU 上直接非法指令崩溃。后面第五章我会专门讲怎么规避。
另外，离线盒子通常是无风扇设计，长时间满线程推理会触发降频，识别速度反而下降。这也是为什么线程数不是越大越好，第四章会给出具体配置习惯。
3. 编译 whisper 离线识别模块：从零到跑通的最小可复现流程
3.1 准备构建环境：编译器、CMake 与 ffmpeg 的离线安装要点
Linux 下我一般这样准备基础环境：
# Debian/Ubuntu 类系统，一次性装好构建工具与音频解码工具 sudo apt-get update sudo apt-get install -y build-essential cmake git ffmpeg pkg-config # 确认版本 cc --version cmake --version ffmpeg -version | head -n 1build-essential 提供 gcc/g++，cmake 负责构建配置，ffmpeg 用来把非 WAV 格式的录音转成 whisper 能吃的 16 kHz 单声道 PCM。离线环境要注意：apt 包要提前镜像好，或者用内网源；更彻底的方式是在开发机上用静态编译，把 ffmpeg 的转码能力并进交付物，部署机不装 ffmpeg 也能跑。我一般会在部署机同时准备一份静态 ffmpeg，反正也就几十 MB，却能省掉一大类“音频格式不支持”的现场问题。
3.2 编译 C++ 推理程序：CMake 命令与参数说明
把源码拉下来之后，进入目录执行：
# 生成 Release 构建，并同时产出动态库 cmake -B build -DCMAKE_BUILD_TYPE=Release -DWHISPER_BUILD_SHARED=ON # 按 CPU 核数并行编译 cmake --build build -j$(nproc) # 查看产物 ls -l build/bin/参数说明：
-DCMAKE_BUILD_TYPE=Release：不开这个选项，默认编译出来是低优化版本，推理性能能差一个数量级。这是最常见“明明是编译版，怎么还是慢”的原因。-DWHISPER_BUILD_SHARED=ON：生成动态库，方便用 C++ 写自己的宿主程序链接进去。如果做嵌入式交付，可以改为 OFF，用静态链接减少部署文件数。-j$(nproc)：用满 CPU 核编译，通常一两分钟就能编完。
编译完之后，build/bin/ 下会出现命令行识别工具。先用它验证模型和基础功能，再考虑写自己的程序。命令行工具也是后面排查问题最快的入口，千万别跳过这一步直接写代码。
3.3 模型下载与格式转换：从 PyTorch 权重到量化文件
模型这块，常见做法是用源码仓库里的下载脚本，或者从模型托管平台下载已经转换好的 ggml 文件。以中文识别为例，我一般选 small 或 medium。模型文件拿到后，先确认是什么版本：文件名里带.en的是纯英文模型，中文识别不能用；多语言版本文件不带 .en。这一步错了后面全是坑。
然后跑一次命令行验证：
# -m 指定模型路径，-f 指定音频，-l zh 固定中文，-t 4 表示 4 个线程 ./build/bin/whisper-cli -m models/ggml-small.bin -f test.wav -l zh -t 4如果输出的中文正常且时间戳对得上，说明模型与推理代码匹配。补充一点：如果只有原版 PyTorch 权重，需要先转换成 ggml 格式。转换脚本在源码仓库里通常自带的，先导出成 fp32 的 ggml 文件，再用量化工具压成 q5_0 或 q8_0。这个过程要在有 Python 环境的开发机上完成，目标部署机不需要 Python。
3.4 用 C++ 写最小识别程序：初始化、推理与逐段取文本
命令行工具满足不了业务集成时，就用 SDK 接口自己写宿主程序。一个最小例子：
#include "whisper.h" #include <cstdio> #include <vector> // 简化版：读取 16kHz 单声道 WAV 并返回 float 数组 // 实际工程中要解析 WAV 头、处理多声道合并和重采样 std::vector<float> load_wav(const char* path); int main(int argc, char** argv) { if (argc < 3) { fprintf(stderr, "usage: %s model.bin audio.wav\n", argv[0]); return 1; } // 初始化上下文：加载模型到内存 struct whisper_context* ctx = whisper_init_from_file(argv[1]); if (!ctx) { fprintf(stderr, "failed to load model\n"); return 1; } std::vector<float> pcm = load_wav(argv[2]); // 参数：固定中文、贪心解码、4 线程 whisper_full_params params = whisper_full_default_params(WHISPER_SAMPLING_GREEDY); params.language = "zh"; params.n_threads = 4; params.print_timestamps = false; // 执行完整识别 int ret = whisper_full(ctx, params, pcm.data(), pcm.size()); if (ret != 0) { fprintf(stderr, "whisper_full error %d\n", ret); whisper_free(ctx); return ret; } // 分段取出文本，每段大约对应一个句子 int n = whisper_full_n_segments(ctx); for (int i = 0; i < n; ++i) { printf("%s\n", whisper_full_get_segment_text(ctx, i)); } whisper_free(ctx); return 0; }逻辑说明：
whisper_init_from_file只做一次，不要在循环里反复调用，否则冷启动开销会吃掉编译版的性能优势。pcm必须是 16 kHz 单声道 float 数组；如果输入是 44.1 kHz 立体声，要先在预处理阶段完成重采样和声道合并。whisper_full是同步调用，一次跑完整段音频；简单场景够用，长音频和流式场景用第 6 章的分块方案。- 取文本用
whisper_full_n_segments和whisper_full_get_segment_text，按段迭代即可。
编译宿主程序：
# -I 指向头文件目录，-L 指向动态库目录，-lwhisper 链接 whisper 动态库 c++ -std=c++11 -O2 -I/path/to/whisper/include example.cpp \ -L/path/to/whisper/build -lwhisper -o offline_recognizer运行时如果提示找不到动态库，用LD_LIBRARY_PATH指过去，或者把动态库拷到/usr/local/lib并执行ldconfig。
3.5 验证“真离线”：断网、移走 Python 依赖后的运行检查
最后一步是验证交付物真的能离线跑。我的检查清单：
# 1. 确认进程没有外部网络连接（看网络系统调用的 trace） strace -e trace=network ./offline_recognizer model.bin test.wav 2>&1 | head # 2. 确认动态库不依赖 Python 环境 ldd ./offline_recognizer | grep -i python || echo "no python dependency" # 3. 确认模型文件就在本地 ls -lh model.binstrace看网络连接不是必须的，但内网交付时很有说服力；ldd检查动态库依赖，确保部署机上不需要额外的 Python 运行时。更硬核的验证是把整个目录复制到一台全新的、没装任何开发工具的机器上直接跑，能出正确结果就算通过。
4. 离线识别效果调优：模型规格、固定语言与解码参数怎么配
4.1 模型规格怎么选：tiny 到 large 的体积、内存与质量权衡
模型规格是第一个要定的参数。表格里的数字是量级参考，不同版本会略有差异：
| 规格 | 量化后体积（约） | 进程内存（约） | 中文识别质量 | 推荐场景 |
|---|---|---|---|---|
| tiny | 40 MB 级别 | 250 MB 级别 | 只适合标准普通话，带口音就废 | 演示、日志关键词过滤 |
| base | 75 MB 级别 | 400 MB 级别 | 比 tiny 好一截，仍不适用正式场景 | 原型验证 |
| small | 250 MB 级别 | 1 GB 级别 | 日常口音能扛，内网交付的及格线 | 通用离线识别 |
| medium | 800 MB 级别 | 2 GB 级别 | 同音字和专有名词明显改善 | 质检、会议记录 |
| large | 1.5 GB 级别 | 4 GB 级别 | 最好，但算力和内存要求高 | 高配服务器离线转写 |
我的默认推荐是 small，理由很实在：内网机器的 CPU 和内存预算有限，small 的质量在标准普通话和轻度方言场景下已经能落地；medium 用于录音质量较好的场景，提升同音字准确率；large 只在高配服务器上考虑，因为同样一段音频，large 比 small 慢 4 倍以上，不是所有业务都等得起。
提醒一下，别只看模型文件大小就断定内存占用。推理时的中间激活、上下文缓存、特征缓冲区都会额外吃内存，small 量化后文件虽然只有两百多 MB，但整个进程常驻内存经常到 1 GB。选型时要留出至少一倍余量，不然现场 OOM 了再换模型更被动。
4.2 固定语言参数：中文场景下跳过语言检测的实际效果
固定语言为zh能省去模型启动后的语种检测步骤。第一次用自动检测的时候，一段带口音的普通话有时会被判成粤语或夹杂英文，导致解码路径错乱，输出里混入英文单词。设置params.language = "zh"之后，解码直接从中文状态开始，识别结果会稳定很多。
但固定语言不是万能的。如果文本里大量夹英文品牌名，比如“PLC 控制器”“UPS 电源”，英文单词照样能识别出来，只是整体解码走中文路径。还有少数情况：一段纯英文录音硬设zh，效果会下降，这时候用auto反而好。所以我的做法是：默认固定zh，对英文比例高的数据单独开一个自动检测实例，两个实例并存在服务里，按需切换。
4.3 解码参数：beam_size、best_of 与上下文开关的正确用法
解码参数是离线识别里最容易产生误会的地方。whisper 解码有两个模式：greedy 和 beam search。命令行里经常出现的beam_size、best_of，很多人搞混，我直接说结论：
- greedy 模式：每步取概率最高的 token，快，但遇到长句和噪声容易“一条路走到黑”。
- beam search 模式：同时维护多个候选路径，最后选整体概率最高的一条，慢一些但更稳。small 模型下
beam_size=5是常用起点，增加到 8 收益很小，耗时却明显上涨。 best_of只在采样模式生效，跟 beam search 是两个东西。命令行工具如果没显式指定采样模式，默认是 greedy，这时候调-bs会发现根本没有效果。我在早期项目里就干过这事，调了半天参数，结果模式没切。
C++ SDK 里对应：
// 显式切到 beam search 模式，beam_size 才会生效 whisper_full_params params = whisper_full_default_params(WHISPER_SAMPLING_BEAM_SEARCH); params.beam_size = 5; params.best_of = 5;temperature 这个参数也经常被忽视。whisper 默认不是固定温度，而是先低温度贪心尝试，如果结果不理想（比如终止符概率过低），自动提高温度重试。离线识别场景我的建议是保持默认，因为语音识别和文本生成不一样，随机性大不是好事，低温度更稳。只有那种反复重试仍然失败的噪声录音，调高温度才有一点机会。参数调优在语音识别里经常像玄学，但其实抓住模式、束宽、语言三项，大部分问题都能解释。
4.4 线程数与 CPU 指令集：实时倍率（RTF）的配置习惯
实时倍率（RTF）= 识别耗时 / 音频时长，RTF 小于 1 意味着处理速度比音频本身快，这是离线识别最重要的性能指标。
CPU 场景下的实测规律：
- 线程数从 1 加到 4，RTF 改善最明显；到 8 线程往往边际递减，因为内存带宽先到瓶颈。
- 超线程机器上开满线程反而可能略降，因为两个线程抢同一物理核的缓存。
- 指令集影响比想象中大：支持 AVX2 的编译产物比纯 x86-64 兼容版本快约一倍。这是编译版与编译版之间的差异，很多人不知道。
我的配置习惯：
- 工控机/盒子：
n_threads=4，关掉超线程，模型选 small + q5_0 - 普通服务器：
n_threads=8，模型 small 或 medium - 高配服务器：medium 或 large，
n_threads调到 12 到 16，优先保证 RTF < 0.3
只要 RTF 落在预算内，线程数和模型规格就不用再折腾；一味追求更低的 RTF 而升 large 模型，往往得不偿失。
5. 离线语音识别避坑指南：五个高频翻车点与排查思路
5.1 程序换机器就崩溃：非法指令与 CPU 指令集兼容
现象：程序在开发机编译通过，放到另一台机器上运行，一进识别就报非法指令（SIGILL），或者初始化模型时直接崩溃；有的表现为识别过程中段错误。
原因：编译时默认或显式启用了本机 CPU 的高级指令集，比如 AVX2、FMA、AVX512，部署机的 CPU 型号较老不支持，CPU 一执行到对应指令就非法退出。
解决：先查部署机的 CPU 标志位，再用兼容指令集重新编译：
# 查看 CPU 支持的指令集 lscpu | grep Flags # 用 x86-64-v2 兼容级别重新编译 cmake -B build -DCMAKE_BUILD_TYPE=Release \ -DCMAKE_C_FLAGS="-march=x86-64-v2" \ -DCMAKE_CXX_FLAGS="-march=x86-64-v2" cmake --build build -j说明：x86-64-v2基本覆盖了 2009 年以后的大多数 x86 处理器，兼顾兼容性和基础 SIMD 加速。如果部署机实在太老，只能退到-march=x86-64，性能损失明显，但至少能跑。这类问题最难查的地方在于开发机上一切正常，所以交付前一定要在目标型号的机器上做冒烟测试。
5.2 中文全变成拼音：模型文件、编码与音频解码三处排查
现象：设置了固定中文，输出结果却是拼音串或者一堆乱码；更隐蔽的是部分中文正常，人名地名全变成拼音。
原因：常见因素有三个。第一，使用的是纯英文模型，文件名带.en，它根本没有中文词表；第二，终端或程序的输出编码不是 UTF-8，中文显示为乱码；第三，源音频如果是 mp3 格式但命名成 wav，解码器读出的是压缩数据，whisper 内部把它当 PCM 解析，波形错乱之后识别文本完全不可信。
解决：按顺序排查。先确认模型文件不带.en后缀，再检查程序输出流，设置为 UTF-8 环境；音频统一用 ffmpeg 转成 16 kHz 单声道 WAV 再喂给识别模块。
# 统一转码：16kHz、单声道、PCM 编码 ffmpeg -y -i input.mp3 -ar 16000 -ac 1 -f wav output.wav这个转码命令要写进预处理管道，别让识别模块直接吃原始文件。花一分钟转码，能省掉无数个“为什么识别结果是乱的”的半夜电话。
5.3 CPU 机器识别速度骤降：量化与编译优化双双丢失
现象：同一个模型在带 GPU 的开发机上运行飞快，交付到无 GPU 的客户端后，速度慢到不可接受，甚至比原版 Python 还慢。
原因：模型是 fp32 未量化版本，代码编译时也没对目标 CPU 做指令集优化。GPU 上推理快是因为显存带宽和算子库，换成 CPU 后所有计算都退化成通用指令，速度自然雪崩。
解决：换用 q5_0 或 q8_0 量化模型，编译时开-O3和合适的-march。同时要建立独立的 CPU 基准验证，而不是拿 GPU 上的耗时来验收：
# 用同一段 60 秒音频作为验收基准，real 时间除以 60 就是 RTF time ./offline_recognizer model.bin benchmark.wav如果 RTF 超过预算，先降模型规格，再考虑换指令集优化。我的经验是：在纯 CPU 机器上，q5_0 的 small 模型比 fp32 的 small 模型快 30% 到 50%，对离线场景来说，这个优化是零成本的，只是换个模型文件的事。
5.4 长音频后半段文本错乱：上下文窗口与切段拼装
现象：30 分钟录音，前面 10 分钟识别正常，后面开始重复、丢字，甚至出现完全没有逻辑的句子。
原因：whisper 的解码上下文长度有限，长音频按窗口滑动时，后半段窗口丢失了关键上文信息，条件概率漂移；同时某些提示词只作用于开头窗口，后续窗口被前面生成的错误“带偏”，错误会累积。
解决：三种常用手段。
- 增大音频上下文：
./build/bin/whisper-cli -m models/ggml-small.bin -f long.wav -l zh --audio-context 512- 关闭“以前面文本为上下文”的机制，减少错误累积：
./build/bin/whisper-cli -m models/ggml-small.bin -f long.wav -l zh --no-context说明：--no-context让每个窗口独立解码，不依赖前面文本；坏处是前后措辞一致性可能变差，但对中文长音频来说往往更稳定。 3. 自己切段：把长音频切成 30 秒一段，段与段之间重叠 2 秒，识别后按时间戳拼装，重叠部分取置信度高的一段。这个方案可控性最强，第 6 章会展开。
注意：不要同时开--no-context又指望前文提到过的名词能延续，那是两个相反的诉求，只能二选一。
5.5 并发识别崩溃或 OOM：context 非线程安全与池化设计
现象：服务里开线程池并发识别，运行一段时间后进程崩溃，或者内存以模型大小乘以并发数线性增长，直到 OOM。
原因：whisper 的 context 内部是有状态的解码器，多个线程共享同一个 context 会互相污染解码状态。每次 init 一个 context 都会独立加载一遍模型权重，N 个并发就是 N 份权重，内存与并发数线性放大。
解决：做 context 池化。启动时按最大并发数预先创建好 context，任务从池里取一个，用完归还，不做现场 init/free。
// 伪代码：池化思路 class WhisperPool { std::vector<whisper_context*> contexts; // 初始化 N 个 context，复用同一模型文件 // 任务到达时从池中取空闲 context，识别后归还 };如果内存仍不够，就降并发数或者换 q5_0 量化模型。进程池方案也可以：每个 worker 子进程持有独立 context，主进程通过消息队列分发音频路径，优点是不存在线程互相污染的问题，缺点是进程生命周期要自己维护。别为了省模型加载时间去做“多线程共享 context”，翻车概率非常高，现场排查也极其痛苦。
6. 把编译后的 whisper 用得更顺手：连续音频分块与提示词缓存技巧
6.1 长音频流式分块：重叠窗口、去重与落盘兜底
工程上大多数离线识别不是干净的 30 秒片段，而是几十分钟的录音。我一般这样处理：固定窗口 30 秒，窗口间重叠 2 秒；每个窗口独立转写，拿到带时间戳的分段结果；拼装时丢弃重叠区域里靠后的重复段，以时间戳为准。
// 伪代码：长音频分块 for (offset = 0; offset < total_samples; offset += step) { // step = 窗口长度 - 重叠长度 // 取 offset 到 offset + 窗口长度的 PCM 片段 // 调用 whisper_full，按时间戳保存分段结果 }时间戳对齐靠 whisper 返回的 segment 起止时间；重叠区域去掉后，拼接出来的文本就是连续句子。第一次做的时候我吃过亏：没做重叠，窗口边界上的词被切碎，识别结果碎成一节一节的，加了 2 秒重叠基本消失。另一个习惯是落盘兜底：每识别完一个窗口，立即把结果追加写到输出文件，别等全部完成再写。离线任务动辄几十分钟，万一程序崩溃，有中间结果就能断点续传，而不是从头再来。这算是我的后悔药。
6.2 提示词通道：把领域词汇交给 initial prompt
whisper 支持在解码开始时给模型一段提示文本，这个通道在离线场景里非常值得用：
// 领域词汇提示，显著改善专业词识别 params.initial_prompt = "以下是关于设备运维的普通话录音，涉及PLC、变频器、轴承温度、振动值。";作用机制是模型在解码时偏向使用提示词里出现过的词汇和语境。最典型的是“变频器”这种词，不提示很可能被听成“变平器”“变屏器”；提示词里列上，命中概率会高很多。中文场景我还会在提示词开头写“以下是普通话录音”，进一步强化语言路径。
提示词不是热词表，它不保证强制输出某个词，只是在解码分布里起偏置作用。想强制纠正，只能在后处理里做文本替换。另外提示词不要太长，建议控制在 50 个汉字以内，太长反而挤压音频信息本身。这个边界要清楚。
我最后一次交付离线识别模块，就是栽在模型文件拿错成.en版本，现场演示中文全变成拼音，客户倒吸一口凉气的声音我到现在还记得。后来我把“模型是否多语言、指令集兼容、UTF-8 环境”写进部署检查清单，每次交付先跑三段固定测试音频再签字。这种教训，经历过一次就够了。希望帮到你。
本文还有配套的精品资源，点击获取
