handy-computer/transcribe.cpp

# transcribe.cpp C/C++ 语音转文本推理库。通过 [GGUF](https://github.com/ggerganov/gguf) 模型在 [ggml](https://github.com/ggml-org/ggml) runtime 上运行多种 STT 模型家族，并提供 Metal、Vulkan 和 CUDA 后端以实现快速的 GPU 推理，同时包含一条由 tinyBLAS 加速的 CPU 路径。 支持 16 个模型家族和 60 多种变体，涵盖流式和批处理。我们在 [`handy-computer`](https://huggingface.co/handy-computer) 下发布的每一个模型都经过了数值验证，并针对其参考实现进行了 WER 测试。 **支持的模型：** | 家族 | 变体 | 文档 | | --- | --- | --- | | Parakeet | 10 种变体：TDT、RNN-T、CTC、TDT+CTC (110M–1.1B) | [docs/models/parakeet.md](docs/models/parakeet.md) | | Canary | `canary-1b`, `canary-1b-v2`, `canary-1b-flash`, `canary-180m-flash` | [docs/models/canary.md](docs/models/canary.md) | | Canary-Qwen | `canary-qwen-2.5b` (FastConformer + Qwen3-1.7B SALM) | [docs/models/canary-qwen-2.5b.md](docs/models/canary-qwen-2.5b.md) | | Whisper | 12 种变体（从 `tiny` 到 `large-v3-turbo`，以及 `.en` 兄弟版本） | [docs/models/whisper.md](docs/models/whisper.md) | | GigaAM | `gigaam-v3-{e2e-rnnt,e2e-ctc,rnnt,ctc}` | [docs/models/gigaam.md](docs/models/gigaam.md) | | Moonshine | `moonshine-tiny`, `moonshine-base` | [docs/models/moonshine.md](docs/models/moonshine.md) | | Moonshine Streaming | `moonshine-streaming-{tiny,small,medium}` | [docs/models/moonshine-streaming.md](docs/models/moonshine-streaming.md) | | Qwen3-ASR | `qwen3-asr-0.6b`, `qwen3-asr-1.7b` | [docs/models/qwen3-asr.md](docs/models/qwen3-asr.md) | | Cohere Transcribe | `cohere-transcribe-03-2026` | [docs/models/cohere-transcribe-03-2026.md](docs/models/cohere-transcribe-03-2026.md) | | SenseVoice | `sensevoice-small` | [docs/models/sensevoice-small.md](docs/models/sensevoice-small.md) | | FunASR Nano | `fun-asr-nano-2512`, `fun-asr-mlt-nano-2512` | [docs/models/fun-asr-nano.md](docs/models/fun-asr-nano.md) | | Nemotron Speech Streaming | `nemotron-speech-streaming-en-0.6b` | [docs/models/nemotron-speech-streaming-en-0.6b.md](docs/models/nemotron-speech-streaming-en-0.6b.md) | | Nemotron 3.5 ASR Streaming | `nemotron-3.5-asr-streaming-0.6b`（多语言，40 种语言环境） | [docs/models/nemotron-3.5-asr-streaming-0.6b.md](docs/models/nemotron-3.5-asr-streaming-0.6b.md) | | Multitalker Parakeet Streaming | `multitalker-parakeet-streaming-0.6b-v1`（仅支持单说话人 ASR 路径） | [docs/models/multitalker-parakeet-streaming-0.6b-v1.md](docs/models/multitalker-parakeet-streaming-0.6b-v1.md) | | Granite Speech 4 / 4.1 | `granite-4.0-1b-speech`, `granite-speech-4.1-2b{,-plus,-nar}` | [docs/models/granite-speech.md](docs/models/granite-speech.md) | | Voxtral | `voxtral-mini-3b-2507`, `voxtral-small-24b-2507`（audio-LLM；转写 + 翻译） | [docs/models/voxtral.md](docs/models/voxtral.md) | | Voxtral Realtime | `voxtral-mini-4b-realtime-2602`（流式 audio-LLM） | [docs/models/voxtral-realtime.md](docs/models/voxtral-realtime.md) | | MedASR | `medasr`（Conformer + CTC，英文医疗听写，受限访问） | [docs/models/medasr.md](docs/models/medasr.md) | | MOSS Transcribe-Diarize | `moss-transcribe-diarize`（audio-LLM；支持带有内联说话人分离的英文与中文 ASR） | [docs/models/moss-transcribe-diarize.md](docs/models/moss-transcribe-diarize.md) | 各变体的模型卡片位于 [`docs/models/`](docs/models/) 下。 ## 构建 ``` cmake -B build cmake --build build ``` 在 Apple Silicon 上会自动启用 Metal。对于 Vulkan（Linux/Windows）： ``` # Ubuntu/Debian sudo apt install build-essential cmake libvulkan-dev glslc libopenblas-dev cmake -B build -DTRANSCRIBE_VULKAN=ON cmake --build build ``` 在 Windows 上，请参阅 [完整构建指南](docs/build-windows.md) 以了解 Vulkan SDK 设置、Visual Studio 命令，以及针对异常深层检出目录的 short-build-root 回退机制。 对于 CUDA（Linux + NVIDIA GPU）： ``` # 要求 PATH 中包含 CUDA toolkit (nvcc) cmake -B build -DTRANSCRIBE_CUDA=ON cmake --build build ``` `libopenblas-dev` 是可选的，但推荐使用。它可将主机端解码器加速约 10-15 倍。如果没有它，构建过程会自动回退到标量路径。 tinyBLAS（Justine Tunney 的 `llamafile_sgemm` kernel）默认开启。 要构建量化工具： ``` cmake -B build -DTRANSCRIBE_BUILD_TOOLS=ON cmake --build build ``` ## 模型 所有支持模型的预构建 GGUF 文件都托管在 Hugging Face 的 [`handy-computer`](https://huggingface.co/handy-computer) 下。每个模型的独立文档 （见上文表格中的链接）都包含了每种量化版本的直接下载链接。 仅当您需要不同的 dtype 或尚未预构建的 checkpoint 时，才需从源码进行转换。 ### 转换为 GGUF 转换器通过 `ASRModel.from_pretrained` 直接从 NVIDIA 的 NeMo checkpoint 加载。 需要 [uv](https://docs.astral.sh/uv/)；parakeet 环境自带 NeMo 及其依赖项。 ``` uv run --project scripts/envs/parakeet \ scripts/convert-parakeet.py nvidia/parakeet-tdt-0.6b-v2 ``` 这将遵循 llama.cpp 风格的 `-.gguf` 命名规范，写入 `models/parakeet-tdt-0.6b-v2/parakeet-tdt-0.6b-v2-F32.gguf`。 传入本地的 `.nemo` 路径或解压后的目录即可进行离线转换。 ### 量化 `transcribe-quantize` 工具可从参考 GGUF 生成更小的模型。可用的预设包括：`F16`、`Q8_0`、`Q6_K`、`Q5_K_M`、 `Q4_K_M`。 ``` build/bin/transcribe-quantize \ models/parakeet-tdt-0.6b-v2/parakeet-tdt-0.6b-v2-F32.gguf \ models/parakeet-tdt-0.6b-v2/parakeet-tdt-0.6b-v2-Q4_K_M.gguf \ --quant Q4_K_M ``` ## 用法 ``` build/bin/transcribe-cli -m models/parakeet-tdt-0.6b-v2/parakeet-tdt-0.6b-v2-F32.gguf samples/jfk.wav ``` 输入必须是 16 kHz 单声道 WAV。使用 `ffmpeg` 或 `sox` 转换其他格式： ``` ffmpeg -i input.mp3 -ar 16000 -ac 1 output.wav ``` ## Bindings 官方 bindings 封装了 C API 以供其他语言使用： | 语言 | 路径 | | --- | --- | | Python | [bindings/python](bindings/python) | | TypeScript / JavaScript | [bindings/typescript](bindings/typescript) | | Rust | [bindings/rust/transcribe-cpp](bindings/rust/transcribe-cpp) | | Swift / ObjC | [bindings/swift](bindings/swift) | 请参阅 [`docs/bindings.md`](docs/bindings.md) 了解 bindings 的生成方式 以及如何与头文件保持同步。 ## 测试 ``` cd build && ctest ``` 部分测试需要真实的模型文件。使用以下命令启用它们： ``` cmake -B build -DTRANSCRIBE_BUILD_REAL_MODEL_TESTS=ON cmake --build build TRANSCRIBE_PARAKEET_GGUF=path/to/model.gguf ctest --test-dir build ``` 关于新移植版本所需的模型家族冒烟测试、数值验证和基准测试 模式，请参阅 [`docs/model-family-testing.md`](docs/model-family-testing.md)。 ## 项目布局 ``` include/transcribe.h Public C API (single header) src/ Library internals (C++17) src/arch/parakeet/ Parakeet family implementation src/arch/cohere/ Cohere Transcribe family implementation examples/cli/ CLI binary source tools/transcribe-quantize/ Quantization tool source bindings/ Python, TypeScript, Rust, and Swift bindings docs/ Porting and validation guidance scripts/ Python converter + test tooling ggml/ Vendored ggml (see ggml/UPSTREAM for pinned SHA) src/third_party/miniz/ Vendored miniz deflate codec (see its UPSTREAM file) samples/ Test audio files tests/ Unit and smoke tests ``` ## 许可证 transcribe.cpp 基于 MIT 许可证。详情请参阅 [LICENSE](LICENSE)。内置的 第三方组件（ggml、miniz — 均为 MIT 许可证）已在 [THIRD-PARTY-LICENSES.md](THIRD-PARTY-LICENSES.md) 中注明。

标签：Bash脚本, C/C++, ggml, Vectored Exception Handling, 事务性I/O, 人工智能, 可视化界面, 实时告警, 机器学习推理, 用户模式Hook绕过, 语音识别, 语音转文本, 边缘计算, 逆向工具