企业官网建设流程全解析

• 人工智能
• 语音
• 音频
• 本地部署
• 推理引擎

whisper.cpp 是 OpenAI Whisper 自动语音识别（ASR）模型的高性能 C/C++ 移植实现，以零依赖、低内存占用和跨平台著称，可在手机、嵌入式设备、桌面乃至浏览器（WebAssembly）中离线运行完整推理。本文以仓库根目录 README.md 为主线，结合 include/whisper.h、models/README.md、examples/cli/README.md 等源码与文档，系统讲解环境搭建、模型获取与量化、whisper-cli完整参数、实时流式转写、各硬件加速后端的构建方式以及 C API 二次开发路径，帮助你从零开始把 Whisper 部署到自己的应用中。

项目概览：whisper.cpp 是什么

whisper.cpp 将 OpenAI 的 Whisper 自动语音识别模型移植为纯 C/C++ 实现，核心特征是不依赖任何第三方深度学习框架。模型的全部高层实现在 include/whisper.h 与 src/whisper.cpp 两个文件中，其余代码属于ggml机器学习库（本仓库内的 ggml 目录即为该库的源码）。这种轻量化的实现方式使其非常容易集成到不同平台和应用程序中。

项目的主要能力与特性（均可在仓库中直接印证）：

• 纯 C/C++ 实现，无框架依赖；
• Apple Silicon 一等公民：通过 ARM NEON、Accelerate 框架、Metal 与 Core ML 深度优化；
• x86 架构的 AVX 指令集支持；
• POWER 架构的 VSX 指令集支持；
• 混合 F16 / F32 精度；
• 整数量化支持（Q4、Q5、Q8 等格式）；
• 运行期零内存分配（模型加载后推理过程不再动态分配内存）；
• Vulkan GPU 支持；
• 纯 CPU 推理支持；
• NVIDIA GPU 高效支持（cuBLAS + 自定义 CUDA kernel）；
• OpenVINO 支持（Intel CPU/GPU）；
• Ascend NPU 支持（CANN）；
• C 风格 API（详见 include/whisper.h）。

支持的平台（官方 README 列出的已验证范围）：

• macOS（Intel 与 Arm）
• iOS（示例见 examples/whisper.objc）
• Android（示例见 examples/whisper.android）
• Java（绑定见 bindings/java/README.md）
• Linux / FreeBSD
• WebAssembly（示例见 examples/whisper.wasm）
• Windows（MSVC 与 MinGW）
• Raspberry Pi
• Docker

快速开始：从零跑通一次语音转写

1. 克隆仓库并下载模型

git clone https://github.com/ggerganov/whisper.cpp.git cd whisper.cpp

然后下载一个已转换为ggml格式的 Whisper 模型。以英文base.en模型为例：

sh ./models/download-ggml-model.sh base.en

该脚本位于 models/download-ggml-model.sh，默认从 Hugging Face 上的ggerganov/whisper.cpp仓库拉取预转换模型。脚本内置白名单，支持 tiny / base / small / medium / large-v1 / large-v2 / large-v3 / large-v3-turbo 等数十个变体（含.en纯英文版、-q5_1/-q8_0量化版与-tdrz说话人分段版）。脚本会优先尝试wget2、wget，最后回退到curl完成下载；若本地已存在同名模型文件则直接跳过。

提示：脚本默认把模型保存到models/目录，也可通过第二个参数指定存放路径。不带参数运行时，脚本会列出全部可用模型清单。

2. 构建 whisper-cli 并转写音频

# 构建项目 cmake -B build cmake --build build --config Release # 转写一段音频 ./build/bin/whisper-cli -f samples/jfk.wav

其中 examples/cli 是演示库绝大多数功能的主示例，也可作为其他项目使用whisper.cpp库的参考实现。

一条命令的快捷演示：直接执行make base.en，它会自动下载base.en模型（转换为自定义ggml格式）并对samples目录下所有.wav样本运行推理。

更多模型对应快捷目标：

make -j tiny.en make -j tiny make -j base.en make -j base make -j small.en make -j small make -j medium.en make -j medium make -j large-v1 make -j large-v2 make -j large-v3 make -j large-v3-turbo

3. 输入音频格式要求

注意whisper-cli目前只接受 16-bit WAV 文件，使用前请确保输入已转换。可以用ffmpeg统一转换：

ffmpeg -i input.mp3 -ar 16000 -ac 1 -c:a pcm_s16le output.wav

上面的参数将音频重采样为 16 kHz 单声道 16-bit PCM——这也是 Whisper 模型的采样标准（头文件 include/whisper.h 中定义WHISPER_SAMPLE_RATE 16000）。

4. 获取更多测试音频

make -j samples

该命令会从 Wikipedia 下载若干音频文件，并用ffmpeg转换为 16-bit WAV 格式。仓库自带 samples/jfk.wav 可作为最常用的测试样本。

详细的命令行帮助随时可用./build/bin/whisper-cli -h查看。

模型体系：ggml 格式与可用模型清单

ggml 格式是什么

原始 OpenAI PyTorch 模型经过转换变成自定义ggml二进制格式，以便在 C/C++ 中直接加载。单个ggml模型文件打包了四类内容：

• 模型参数（hparams）；
• mel 滤波器（mel filters）；
• 词汇表（vocabulary）；
• 权重（weights）。

转换由 models/convert-pt-to-ggml.py 脚本完成，其文件头注释详细描述了输出二进制格式的字段布局（各变量的维度数、名称长度、维度、名称、数据）。获取ggml模型有三种途径：

1. 使用 models/download-ggml-model.sh 下载预转换模型；
2. 手动下载预转换模型（可从模型发布渠道获取）；
3. 使用convert-pt-to-ggml.py自行转换：

mkdir models/whisper-medium python models/convert-pt-to-ggml.py ~/.cache/whisper/medium.pt ~/path/to/repo/whisper/ ./models/whisper-medium mv ./models/whisper-medium/ggml-model.bin models/ggml-medium.bin rmdir models/whisper-medium

说明：自行转换需要先克隆 OpenAI Whisper 源码仓库以获取 tokenizer、mel 滤波器等算法资产，并预先在~/.cache/whisper/下载好原始 PyTorch 模型。

可用模型与 SHA 校验值

以下清单来自 models/README.md，模型为多语言版，名称含.en的为纯英文版，后缀-q5_0为量化版，后缀-tdrz支持基于 tinydiarize 的说话人轮次标记：

此外 models/download-ggml-model.sh 还支持tiny-q5_1、tiny-q8_0、base-q5_1、base-q8_0、small-q5_1、small-q8_0、medium-q5_0、medium-q8_0、large-v2-q8_0、large-v3-turbo-q8_0等量化变体。仓库根目录models/下还自带一批以for-tests-为前缀的空模型文件（不含权重），仅供 CI 运行 sanitizer 测试使用，不能用于真实推理。

微调模型与蒸馏模型

社区使用 Hugging Face Transformers 微调的 Whisper 模型与 OpenAI 原始格式略有不同，可用 models/convert-h5-to-ggml.py 读取转换：

python3 ./whisper.cpp/models/convert-h5-to-ggml.py ./whisper-medium/ ./whisper .

蒸馏模型（distil-whisper）也已获得初步支持，转换方式类似。需要留意的是，chunk-based 转写策略尚未实现，因此使用蒸馏模型时转写质量可能不如理想状态。

内存占用参考

官方 README 给出的模型磁盘与运行时内存参考（取决于线程数与硬件，实际值会有浮动）：

量化：显著降低内存与磁盘占用

whisper.cpp 支持对ggml模型做整数量化。量化后的模型占用更少的内存和磁盘空间，且视硬件不同可能获得更高处理效率。创建并使用量化模型的完整流程：

# 用 Q5_0 方法量化模型 cmake -B build cmake --build build --config Release ./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 ./samples/gb0.wav

quantize工具源码位于 examples/quantize/quantize.cpp，其核心流程是：读取输入模型 → 校验GGML_FILE_MAGIC魔数 → 按目标ggml_ftype对张量逐层量化 → 写出新模型文件。从源码可见，默认超参数以 Whisper tiny 为基准（如n_vocab = 51864、n_audio_ctx = 1500、n_text_ctx = 448、n_mels = 80等），量化时依据模型头部信息适配。量化并不会改变模型架构，仅改变权重存储精度，因此在 examples/cli 等示例中通过-m参数即可无缝切换使用。

whisper-cli 完整参数说明

whisper-cli是功能最全的命令行入口，其参数表完整继承自 examples/cli/README.md。以下是全部选项及默认值：

usage: ./build-pkg/bin/whisper-cli [options] file0.wav file1.wav ... options: -h, --help [default] show this help message and exit -t N, --threads N [4 ] number of threads to use during computation -p N, --processors N [1 ] number of processors to use during computation -ot N, --offset-t N [0 ] time offset in milliseconds -on N, --offset-n N [0 ] segment index offset -d N, --duration N [0 ] duration of audio to process in milliseconds -mc N, --max-context N [-1 ] maximum number of text context tokens to store -ml N, --max-len N [0 ] maximum segment length in characters -sow, --split-on-word [false ] split on word rather than on token -bo N, --best-of N [5 ] number of best candidates to keep -bs N, --beam-size N [5 ] beam size for beam search -ac N, --audio-ctx N [0 ] audio context size (0 - all) -wt N, --word-thold N [0.01 ] word timestamp probability threshold -et N, --entropy-thold N [2.40 ] entropy threshold for decoder fail -lpt N, --logprob-thold N [-1.00 ] log probability threshold for decoder fail -tp, --temperature N [0.00 ] The sampling temperature, between 0 and 1 -tpi, --temperature-inc N [0.20 ] The increment of temperature, between 0 and 1 -debug, --debug-mode [false ] enable debug mode (eg. dump log_mel) -tr, --translate [false ] translate from source language to english -di, --diarize [false ] stereo audio diarization -tdrz, --tinydiarize [false ] enable tinydiarize (requires a tdrz model) -nf, --no-fallback [false ] do not use temperature fallback while decoding -otxt, --output-txt [false ] output result in a text file -ovtt, --output-vtt [false ] output result in a vtt file -osrt, --output-srt [false ] output result in a srt file -olrc, --output-lrc [false ] output result in a lrc file -owts, --output-words [false ] output script for generating karaoke video -fp, --font-path [/System/Library/Fonts/Supplemental/Courier New Bold.ttf] path to a monospace font for karaoke video -ocsv, --output-csv [false ] output result in a CSV file -oj, --output-json [false ] output result in a JSON file -ojf, --output-json-full [false ] include more information in the JSON file -of FNAME, --output-file FNAME [ ] output file path (without file extension) -np, --no-prints [false ] do not print anything other than the results -ps, --print-special [false ] print special tokens -pc, --print-colors [false ] print colors -pp, --print-progress [false ] print progress -nt, --no-timestamps [false ] do not print timestamps -l LANG, --language LANG [en ] spoken language ('auto' for auto-detect) -dl, --detect-language [false ] exit after automatically detecting language --prompt PROMPT [ ] initial prompt (max n_text_ctx/2 tokens) -m FNAME, --model FNAME [models/ggml-base.en.bin] model path -f FNAME, --file FNAME [ ] input WAV file path -oved D, --ov-e-device DNAME [CPU ] the OpenVINO device used for encode inference -dtw MODEL --dtw MODEL [ ] compute token-level timestamps -ls, --log-score [false ] log best decoder scores of tokens -ng, --no-gpu [false ] disable GPU -fa, --flash-attn [false ] flash attention --suppress-regex REGEX [ ] regular expression matching tokens to suppress --grammar GRAMMAR [ ] GBNF grammar to guide decoding --grammar-rule RULE [ ] top-level GBNF grammar rule name --grammar-penalty N [100.0 ] scales down logits of nongrammar tokens

这些参数与 C API 中的whisper_full_params结构体（见 include/whisper.h）一一对应。比如-t/--threads对应n_threads、-bo/--best-of对应greedy.best_of、-bs/--beam-size对应beam_search.beam_size，而--temperature与--temperature-inc对应temperature/temperature_inc（温度回退机制参考了 OpenAI 原始 transcribe 流程）。--grammar系列参数则允许用 GBNF 文法约束解码输出，仓库 grammars 目录下提供了colors.gbnf、chess.gbnf、assistant.gbnf等现成文法示例。

实验性解码特性：分段控制、词级时间戳与说话人分段

控制文本段长度

默认按语义断句输出，若需限制每段最大长度（例如 16 字符），使用-ml 16：

$ ./build/bin/whisper-cli -m ./models/ggml-base.en.bin -f ./samples/jfk.wav -ml 16 [00:00:00.000 --> 00:00:00.850] And so my [00:00:00.850 --> 00:00:01.590] fellow [00:00:01.590 --> 00:00:04.140] Americans, ask [00:00:04.140 --> 00:00:05.660] not what your [00:00:05.660 --> 00:00:06.840] country can do [00:00:06.840 --> 00:00:08.430] for you, ask [00:00:08.430 --> 00:00:09.440] what you can do [00:00:09.440 --> 00:00:10.020] for your [00:00:10.020 --> 00:00:11.000] country.

词级时间戳

把--max-len设为 1 即可获得逐词时间戳，配合-sow/--split-on-word可强制按词而非按 token 切分：

$ ./build/bin/whisper-cli -m ./models/ggml-base.en.bin -f ./samples/jfk.wav -ml 1 [00:00:00.000 --> 00:00:00.320] [00:00:00.320 --> 00:00:00.370] And [00:00:00.370 --> 00:00:00.690] so [00:00:00.690 --> 00:00:00.850] my [00:00:00.850 --> 00:00:01.590] fellow [00:00:01.590 --> 00:00:02.850] Americans [00:00:02.850 --> 00:00:03.300] , ...

词级时间戳依赖 include/whisper.h 中定义的 token 级时间数据（whisper_token_data结构体中的t0/t1字段）与word_thold（默认 0.01）等阈值控制。

置信度颜色编码

添加--print-colors参数后，转写文本会按实验性颜色策略输出，用颜色直观区分高/低置信度词：

./build/bin/whisper-cli -m models/ggml-base.en.bin -f samples/gb0.wav --print-colors

说话人分段（tinydiarize，实验性）

基于 tinydiarize 方案的本地说话人轮次检测，需要搭配-tdrz模型：

# 下载 tinydiarize 兼容模型 ./models/download-ggml-model.sh small.en-tdrz # 运行并添加 -tdrz 参数 ./build/bin/whisper-cli -f ./samples/a13.wav -m ./models/ggml-small.en-tdrz.bin -tdrz

输出中会以[SPEAKER_TURN]标记说话人切换点：

[00:00:00.000 --> 00:00:03.800] Okay Houston, we've had a problem here. [SPEAKER_TURN] [00:00:03.800 --> 00:00:06.200] This is Houston. Say again please. [SPEAKER_TURN] [00:00:06.200 --> 00:00:08.260] Uh Houston we've had a problem. ...

对应地，C API 提供whisper_full_get_segment_speaker_turn_next()查询某段后是否预测为说话人轮次切换；whisper_full_params中的tdrz_enable字段控制该特性开关。

卡拉 OK 风格视频生成

利用-owts参数输出“逐词高亮”的卡拉 OK 风格视频生成脚本，需要系统装有ffmpeg：

./build/bin/whisper-cli -m ./models/ggml-base.en.bin -f ./samples/jfk.wav -owts source ./samples/jfk.wav.wts ffplay ./samples/jfk.wav.mp4

-owts会生成一个.wav.wtsbash 脚本，source执行后调用ffmpeg渲染出当前朗读词被高亮的 mp4 视频。仓库 examples/generate-karaoke.sh 提供了更便捷的封装脚本。

多模型对比视频

scripts/bench-wts.sh 可生成不同模型在同一音频上的横向对比视频：

./scripts/bench-wts.sh samples/jfk.wav ffplay ./samples/jfk.wav.all.mp4

硬件加速后端：构建选项与适用场景

Apple Silicon：Metal 与 Core ML

在 Apple Silicon 上，推理默认通过 Metal 在 GPU 上全量执行。若进一步启用 Core ML，Encoder 推理可交由 Apple Neural Engine（ANE）运行，相比纯 CPU 可获得数倍加速。配置步骤：

1. 安装 Python 依赖：

   pip install ane_transformers pip install openai-whisper pip install coremltools

   • 需确认 Xcode 已安装并执行xcode-select --install安装命令行工具；
   • 建议使用 Python 3.10；建议使用 macOS Sonoma（14）或更新版本，旧版本系统可能出现转写幻觉问题；
   • 可选：使用 Miniconda 管理环境，如conda create -n py310-whisper python=3.10 -y。

2. 生成 Core ML 模型（以base.en为例）：

   ./models/generate-coreml-model.sh base.en

   生成物为models/ggml-base.en-encoder.mlmodelc目录。

3. 带 Core ML 支持构建：

   cmake -B build -DWHISPER_COREML=1 cmake --build build -j --config Release

4. 正常运行示例，加载日志可见 Core ML 相关输出：

   $ ./build/bin/whisper-cli -m models/ggml-base.en.bin -f samples/jfk.wav whisper_init_state: loading Core ML model from 'models/ggml-base.en-encoder.mlmodelc' whisper_init_state: first run on a device may take a while ... whisper_init_state: Core ML model loaded system_info: n_threads = 4 / 10 | AVX = 0 | AVX2 = 0 | AVX512 = 0 | FMA = 0 | NEON = 1 | ARM_FMA = 1 | F16C = 0 | FP16_VA = 1 | WASM_SIMD = 0 | BLAS = 1 | SSE3 = 0 | VSX = 0 | COREML = 1 |

   首次运行较慢是因为 ANE 服务会把 Core ML 模型编译为设备特定格式，后续运行会明显更快。Core ML 实现细节参考 src/coreml 目录（包含 encoder/decoder 的 Core ML 实现与头文件）。

NVIDIA GPU：CUDA 加速

借助 cuBLAS 与自定义 CUDA kernel，Whisper 可在 NVIDIA 显卡上高效推理。前提是已安装 CUDA 工具链，然后：

cmake -B build -DGGML_CUDA=1 cmake --build build -j --config Release

对应的 GPU 内核实现位于 ggml/src/ggml-cuda 目录，支持fattn（flash attention）、mmvq（矩阵向量量化）等多种优化 kernel。GPU 设备选择由 include/whisper.h 中whisper_context_params的gpu_device字段控制。

Vulkan GPU 支持

跨厂商 GPU 加速方案，只要显卡驱动支持 Vulkan API 即可：

cmake -B build -DGGML_VULKAN=1 cmake --build build -j --config Release

Vulkan 后端实现位于 ggml/src/ggml-vulkan，其中包含大量.comp计算着色器（add、mul、norm、rope、softmax、dequant 等算子）。

BLAS CPU 支持（OpenBLAS）

Encoder 处理可通过 OpenBLAS 在 CPU 上加速。需预先安装 OpenBLAS，然后：

cmake -B build -DGGML_BLAS=1 cmake --build build -j --config Release

OpenVINO 支持

在支持 OpenVINO 的平台上（x86 CPU、Intel 集成/独立 GPU），Encoder 推理可转移到 OpenVINO 设备执行，获得显著加速。

1. 建立 Python 虚拟环境并安装依赖（建议 Python 3.10）：

   Windows：

   cd models python -m venv openvino_conv_env openvino_conv_env\Scripts\activate python -m pip install --upgrade pip pip install -r requirements-openvino.txt

   Linux / macOS：

   cd models python3 -m venv openvino_conv_env source openvino_conv_env/bin/activate python -m pip install --upgrade pip pip install -r requirements-openvino.txt

2. 生成 OpenVINO encoder 模型（以base.en为例）：

   python convert-whisper-to-openvino.py --model base.en

   产物为ggml-base.en-encoder-openvino.xml/.binIR 模型文件，建议移动到ggml模型同目录——这是 OpenVINO 扩展运行时默认搜索的位置。

3. 安装 OpenVINO 工具包并设置环境（以 Linux 为例source .../setupvars.sh，Windows 为setupvars.bat），然后构建：

   cmake -B build -DWHISPER_OPENVINO=1 cmake --build build -j --config Release

4. 运行日志可见 OpenVINO 加载信息与设备选择：

   $ ./build/bin/whisper-cli -m models/ggml-base.en.bin -f samples/jfk.wav whisper_ctx_init_openvino_encoder: loading OpenVINO model from 'models/ggml-base.en-encoder-openvino.xml' whisper_ctx_init_openvino_encoder: first run on a device may take a while ... whisper_openvino_init: path_model = models/ggml-base.en-encoder-openvino.xml, device = GPU, cache_dir = models/ggml-base.en-encoder-openvino-cache whisper_ctx_init_openvino_encoder: OpenVINO model loaded system_info: n_threads = 4 / 8 | ... | OPENVINO = 1 |

   首次运行较慢：OpenVINO 需将 IR 模型编译为设备特定 blob 并缓存，后续运行会直接复用缓存。默认设备为 CPU，可通过-oved参数切换。OpenVINO 集成源码见 src/openvino/whisper-openvino-encoder.cpp，C API 侧对应whisper_ctx_init_openvino_encoder()。

Ascend NPU 支持（CANN）

Ascend NPU 通过 CANN 与 AI Core 提供推理加速。已验证设备：

需先安装 CANN toolkit，然后构建：

cmake -B build -DGGML_CANN=1 cmake --build build -j --config Release

运行方式与常规一致：

./build/bin/whisper-cli -f samples/jfk.wav -m models/ggml-base.en.bin -t 8

注意：若在 Ascend NPU 上遇到问题，可在项目讨论区以[CANN]为前缀提报；若在自己的设备上跑通，也欢迎更新“已验证设备”表格。

实时语音输入：whisper-stream

examples/stream 演示了从麦克风做实时推理的朴素实现：工具每半秒采样一次并持续运行转写。

cmake -B build cmake --build build --config Release ./build/bin/stream -m ./models/ggml-base.en.bin -t 8 --step 500 --length 5000

即每 500 ms 采样一帧、累计 5000 ms 音频执行一次转写。该工具依赖 SDL2 采集麦克风音频，构建前需安装：

# Debian 系 sudo apt-get install libsdl2-dev # Fedora sudo dnf install SDL2 SDL2-devel # macOS brew install sdl2 cmake -B build -DWHISPER_SDL2=ON cmake --build build --config Release

滑窗模式 + VAD：将--step设为 0 即进入滑窗模式——仅当检测到语音活动后才转写：

./build/bin/whisper-stream -m ./models/ggml-base.en.bin -t 6 --step 0 --length 30000 -vth 0.6

此时使用一个非常基础的 VAD 检测器，-vth决定 VAD 阈值：值越大越容易判定为静音。一般0.6左右可用，具体需按场景调优。检测到静音时，工具会转写最近--length毫秒的音频并输出便于解析的转写块。该示例另有浏览器版本 examples/stream.wasm。

性能评估：whisper-bench 与 bench.py

examples/bench 提供whisper-bench工具：只运行模型的 Encoder 部分并打印耗时，用于横向比较不同系统配置下的推理性能。

此外 scripts/bench.py 提供多模型、多音频的批量基准脚本，用 Python 编写、易于修改扩展：

python3 scripts/bench.py -f samples/jfk.wav -t 2,4,8 -p 1,2

默认对models目录下任意标准模型执行测试，输出结果为 CSV 文件，方便后续统计分析。

C API 与二次开发

最小集成示例

include/whisper.h 头文件自带基本用法注释，展示最直接的库调用方式：

#include "whisper.h" // ... whisper_context_params cparams = whisper_context_default_params(); struct whisper_context * ctx = whisper_init_from_file_with_params("/path/to/ggml-base.en.bin", cparams); if (whisper_full(ctx, wparams, pcmf32.data(), pcmf32.size()) != 0) { fprintf(stderr, "failed to process audio\n"); return 7; } const int n_segments = whisper_full_n_segments(ctx); for (int i = 0; i < n_segments; ++i) { const char * text = whisper_full_get_segment_text(ctx, i); printf("%s", text); } whisper_free(ctx);

其中pcmf32是 32 位浮点格式的 RAW 音频数据。头文件中还定义了关键常量：WHISPER_SAMPLE_RATE 16000（采样率）、WHISPER_N_FFT 400（FFT 点数）、WHISPER_HOP_LENGTH 160（hop 长度）、WHISPER_CHUNK_SIZE 30（30 秒分块）。

核心调用链

从 C API 可以清晰看到 Whisper 推理的四个阶段，这也是 src/whisper.cpp 内部的实际调用链：

1. whisper_pcm_to_mel()：将 RAW PCM 音频转换为 log mel 频谱图；
2. whisper_encode()：对频谱图运行 Encoder；
3. whisper_decode()：运行 Decoder 获得下一个 token 的 logits 与概率；
4. whisper_full()：一站式完成 “PCM → log mel → encoder → decoder → text” 全流程。

另有whisper_full_parallel()可将音频分块并行处理（某些场景可提速，但分块首尾的转写准确率可能下降）。解码策略由whisper_sampling_strategy枚举定义，支持WHISPER_SAMPLING_GREEDY（贪心，对应 OpenAI GreedyDecoder）与WHISPER_SAMPLING_BEAM_SEARCH（束搜索，对应 OpenAI BeamSearchDecoder）两种。

回调与精细控制

whisper_full_params（见 include/whisper.h）支持多种回调：

• whisper_new_segment_callback：每个新文本段生成时回调（流式场景推荐使用回调而非print_realtime）；
• whisper_progress_callback：进度更新回调；
• whisper_encoder_begin_callback：Encoder 开始前回调，返回 false 可中止计算；
• whisper_logits_filter_callback：采样前修改 logits；
• abort_callback：ggml 计算前的中止检查。

参数层面还覆盖：temperature/temperature_inc（温度与回退）、entropy_thold/logprob_thold/no_speech_thold（解码失败判定阈值）、suppress_blank/suppress_nst（空白与非语音 token 抑制）、language/detect_language（语言指定或自动检测，whisper_lang_auto_detect()底层参考了 OpenAI 的 decoding 实现）、initial_prompt（初始提示，最多n_text_ctx/2个 token）、以及 GBNF 文法约束（grammar_rules、grammar_penalty）。

性能信息与系统信息

C API 还提供whisper_print_timings()/whisper_get_timings()输出各阶段耗时（sample / encode / decode / batchd / prompt），以及whisper_print_system_info()打印 CPU 特性（AVX、NEON、FMA、BLAS、COREML、OPENVINO 等），CLI 启动时打印的system_info行即来源于此。

官方示例矩阵

仓库 examples 目录提供了从 CLI 到完整 App 的多层次参考实现（部分可跑在浏览器里）：

安装与生态

通过 Conan 安装

可使用 Conan 安装预编译二进制或从源码构建：

conan install --requires="whisper-cpp/[*]" --build=missing

语言绑定

官方与社区为多种语言提供了绑定，仓库内可直接查看的有：

• Go： bindings/go，含 go-whisper 示例；
• Java： bindings/java；
• Ruby： bindings/ruby；
• JavaScript / WebAssembly： bindings/javascript 与 libwhisper.worker.js；
• 此外社区还维护 Rust、Objective-C/Swift、.NET、Python、R、Unity 等绑定，详见根 README.md 的 Bindings 章节。

测试与质量保障

仓库 tests 目录包含test-c.c（C API 冒烟测试）、tests/run-tests.sh（端到端转写对比，含en-0-ref.txt等参考输出）以及多个语言的单元测试（如 bindings/go/pkg/whisper/context_test.go）。配合models/下for-tests-前缀的空模型，CI 可运行各类 sanitizer 测试而不需下载大模型。

已知限制

• 仅推理（Inference only）：whisper.cpp 目前只提供推理能力，不包含训练/微调流程；模型训练仍需在 PyTorch 生态中完成，再通过转换脚本导入。

总结：如何选择你的部署路径

综合上文，可以按以下思路快速落地：

• 本机体验：sh ./models/download-ggml-model.sh base.en+cmake -B build && cmake --build build --config Release+./build/bin/whisper-cli -f samples/jfk.wav，全程无需 Python 框架；
• 资源受限设备：优先选择tiny/base或-q5_0/-q8_0量化模型，量化流程见上文“量化”一节；
• 性能敏感场景：按硬件选择后端——Apple Silicon 用 Metal/Core ML，NVIDIA 用-DGGML_CUDA=1，Intel 平台用 OpenVINO 或 Vulkan，华为昇腾用 CANN；
• 实时/流式场景：参考 examples/stream 的滑窗 + VAD 模式；
• 产品化集成：以 include/whisper.h 的 C API 为契约，参考 examples/server 的 HTTP 服务形态或 examples/cli 的参数组织方式，并结合对应语言绑定快速接入现有技术栈。

• 人工智能
• 语音
• 音频
• 本地部署
• 推理引擎