企业官网建设流程全解析

如何用transcribe-bench跑基准测试：backend×变体×量化矩阵完整教程

【免费下载链接】transcribe.cppggml speech-to-text inference for 16+ model families项目地址: https://gitcode.com/GitHub_Trending/tr/transcribe.cpp

transcribe-bench是 transcribe.cpp（一个基于 ggml 的 C/C++ 语音识别推理库，支持 Whisper、Parakeet、Qwen3-ASR 等 16+ 模型家族）内置的性能基准测试工具。它能把「推理后端 backend × 模型变体 variant × 量化方案 quant × 音频样本 sample」四个维度组成一张完整的测试矩阵，逐格测出 mel 前端、编码器、解码器三阶段耗时与实时率（RTF），并输出可归档、可对比的 JSON 报告——这是做性能回归检查和后端选型时最顺手的工具。

一、transcribe-bench 是什么，测什么

工具本体只有一个 C++ 源文件 tools/transcribe-bench/main.cpp，定位很明确：一次加载模型，先做不计时预热（--warmup，默认 1 次），再做计时迭代（--iters，默认 2 次），把每次迭代按阶段拆开计时。

除了速度，它还会输出转写文本和 token 序列的 SHA256 指纹——这样一旦某次优化悄悄改变了识别结果，报告 diff 里会立刻暴露，性能数字再好看也不敢蒙混过关。

二、先构建：让 transcribe-bench 出现在 build/bin 里

transcribe-bench 属于开发者工具，需要显式打开TRANSCRIBE_BUILD_TOOLS开关（见 tools/CMakeLists.txt）：

cmake -B build -DTRANSCRIBE_BUILD_TOOLS=ON cmake --build build

不同后端的构建方式略有差异：

• CPU：默认构建即可，无需 GPU
• Metal（Apple Silicon）：默认自动启用
• Vulkan（Linux/Windows）：cmake -B build -DTRANSCRIBE_VULKAN=ON
• CUDA（Linux + NVIDIA）：cmake -B build -DTRANSCRIBE_CUDA=ON

三、手动跑一格：最小上手示例

不赶时间可以先单独跑一个「模型 × 样本」组合感受一下：

build/bin/transcribe-bench \ --model models/parakeet-tdt-0.6b-v2/parakeet-tdt-0.6b-v2-F16.gguf \ --sample samples/jfk.wav \ --iters 5 --warmup 2 --backend cpu

关键参数速查：

四、真正的用法：用 Python 驱动跑完整矩阵

手敲命令行只能测一格；scripts/bench/run.py 才是设计给日常用的矩阵驱动器。它会自动探测本机（CPU 型号、系统）、发现models/下所有变体，然后按 backend 循环调用 transcribe-bench，把结果聚合成每（variant, backend）一份 JSON：

# 全量矩阵：models/ 下所有变体 × 默认三档量化 × jfk,dots 两个样本 uv run scripts/bench/run.py # 只测一个变体、指定后端和迭代次数 uv run scripts/bench/run.py --models Qwen3-ASR-0.6B --backends cpu --iters 20 --warmup 5 # 给报告起个稳定名字，方便日后对比（重复运行会覆盖同名文件） uv run scripts/bench/run.py --backends cpu --name pre-refactor

几个新手最关心的细节：

1. --models支持三种写法：变体目录名（Qwen3-ASR-0.6B）、HF 风格（Qwen/Qwen3-ASR-0.6B，自动去掉 org 前缀）、或直接指定某个.gguf文件路径
2. --quants默认是f16,q8_0,q4_k_m三档标准量化层；部分模型（如 Qwen3-ASR）发布的是BF16而非F16，记得改成--quants bf16,q8_0,q4_k_m
3. 缺文件只警告不报错：某变体没有对应量化的 GGUF 时会被跳过并提示，不会中断整个矩阵
4. --dry-run强烈建议先跑一遍：只打印将执行的后端和单元格清单，不实际测试，适合先确认矩阵规模

报告落在reports/perf/<机器名>/时间戳_变体_后端.json，机器名由 CPU 型号派生，不同机器的结果天然不会互相覆盖。每个单元格里还带git_sha，能精确回溯到是哪份代码产出的数字。

五、出版级配置：--profile 一键复现官方基准

项目发布到模型仓库的速度表不是随手测的，而是由 catalog/_benchmark_profiles.json 里的「发布档案」（默认asr-publication-v2）严格约束：固定Q8_0与Q4_K_M两档量化、jfk/dots两个样本、3 次计时迭代、1 次预热，且指定了目标机器和后端（如 Apple M4 Max 跑cpu+metal，AMD 轻薄本跑cpu+vulkan并强制 55°C 以下冷却门槛，避免热降频污染数据）。

uv run scripts/bench/run.py --profile

带上--profile后，quants、samples、backends、iters、warmup 全部由档案接管，手动指定会被直接拒绝——这是刻意设计，保证「发布数字」和「实验数字」永远不混淆。单语言微调模型还会自动换成本语言短/长样本，避免在分布外音频上跑出不可比的循环解码结果。

六、对比两次运行：compare.py 出差异表

测完了要回答的问题是：我这次改动到底是提速还是变慢？用 scripts/bench/compare.py 按（变体, 后端, 量化, 样本）四元组对齐两份报告，直接给出每个单元格的耗时差：

uv run scripts/bench/compare.py \ --baseline reports/perf/xxx/pre-refactor_*.json \ --candidate reports/perf/xxx/post-refactor_*.json # 加 5% 回归门槛：任何单元格 wall_ms 回退超 5% 就以退出码 1 失败，可直接进 CI uv run scripts/bench/compare.py --threshold 5.0 \ --baseline reports/perf/xxx/baseline_*.json \ --candidate reports/perf/xxx/candidate_*.json

输出就是一张整齐的表格：variant / backend / quant / sample / wall_ms(A) / wall_ms(B) / delta% / status，一眼定位哪个格子回退。

七、新手常见坑清单 📌

• 忘了开工具开关：默认构建没有transcribe-bench，驱动会提示build the missing target
• Vulkan/CUDA 统一构建要靠显式指定：自动探测无法从路径判断二进制是否编译了 GPU 后端，请显式--backends vulkan（或cuda/rocm），否则可能被保守跳过
• metal 只能跑在 macOS：在 Linux 上显式请求 metal 会得到清晰的 unavailable 报错
• 样本必须 16 kHz 单声道 WAV：仓库 samples/ 目录下有jfk.wav、dots.wav等现成样本，其他音频先用 ffmpeg 转一下
• 别盯着平均值看：wall_ms（墙钟）才是用户可感知的数字，rtf_compute_mean只是三阶段计时之和，适合看阶段瓶颈

总结

整套工作流可以概括为三步：构建开启工具开关 →scripts/bench/run.py铺满 backend×variant×quant×sample 矩阵 →scripts/bench/compare.py用阈值把关回归。配合--name命名基线和--profile出版档案，你得到的就是一套可复现、可审计、可进 CI 的语音识别性能基准体系。更多细节可查阅官方文档 docs/tools/benchmarking.md。

【免费下载链接】transcribe.cppggml speech-to-text inference for 16+ model families项目地址: https://gitcode.com/GitHub_Trending/tr/transcribe.cpp