Ahdaa/kong-tai-gi-ggml

Breeze-ASR-26 GGML（whisper.cpp 量化版）

本 repo 為 MediaTek-Research/Breeze-ASR-26 的 whisper.cpp / GGML 量化衍生版本，供需要在端側（macOS / iOS / Android 旗艦機）離線執行臺語 ＋ 國語語音辨識的應用使用。

「TâiUânUē」即「臺灣話」。原模型針對臺語（Taigi / 閩南語）＋ 國語 ＋ Taigi/國語 code-switching 設計，輸出為漢字（不是臺羅拼音）。

---

模型來源

• 基底模型：MediaTek-Research/Breeze-ASR-26
• 基底架構：OpenAI Whisper-large-v2 微調（架構零改動，vocab/added_tokens 完全一致）
• 支援語言：臺語（Taigi / 閩南語）、國語（Mandarin）、中英 code-switching
• 輸出：漢字（含臺語漢字寫法，非臺羅拼音）

本 repo 的 GGML 檔由 whisper.cpp 官方腳本對 Breeze-ASR-26 直接轉換產出，不含任何模型結構修改或重新訓練。

---

轉換方式

使用 whisper.cpp 官方工具鏈：

# 1) 取得原模型
git clone https://github.com/openai/whisper
huggingface-cli download MediaTek-Research/Breeze-ASR-26 --local-dir ./Breeze-ASR-26

# 2) HuggingFace -> GGML（FP16）
python whisper.cpp/models/convert-h5-to-ggml.py ./Breeze-ASR-26 ./whisper ./out
mv out/ggml-model.bin out/ggml-breeze-f16.bin

# 3) 量化
./whisper.cpp/build/bin/whisper-quantize out/ggml-breeze-f16.bin out/ggml-breeze-asr-26-q4_0.bin q4_0
./whisper.cpp/build/bin/whisper-quantize out/ggml-breeze-f16.bin out/ggml-breeze-asr-26-q5_k.bin q5_k
./whisper.cpp/build/bin/whisper-quantize out/ggml-breeze-f16.bin out/ggml-breeze-asr-26-q8_0.bin q8_0

註：whisper.cpp 使用自家的 GGML 二進制容器（magic 0x67676d6c），與 llama.cpp 的 GGUF 不同。本檔可直接被 whisper.cpp 0.9.x 載入。

---

量化版本對照

檔名	量化	大小	用途	量化精度損失
ggml-breeze-asr-26-q4_0.bin	Q4_0（4-bit 純線性）	~848 MB	預設：精簡版，4–8 GB RAM 機型首選；whisper.cpp 在 ARMv8 上對 Q4_0 有專用 SIMD kernel，舊機型推論最快	對 FP16 baseline CER 上升幅度 < 1%（小樣本量測）
ggml-breeze-asr-26-q5_k.bin	Q5_K（全張量 q5_K）	~1.0 GB	標準版：8 GB+ 旗艦手機 / Mac / 平板首選	在三段測試音訊上對 FP16 輸出完全一致（CER 0%）
ggml-breeze-asr-26-q8_0.bin	Q8_0	~1.5 GB	高品質版：對量化精度敏感的場景	對 FP16 輸出完全一致（CER 0%）

Spike 量測（Apple M4 Pro / Metal）：Q5_K 對 24.81 秒音訊推論 2.78 秒（real-time × 8.9），Q8_0 為 2.55 秒（× 9.7）。Pixel 4（Snapdragon 855）30 秒音訊：Q5_K 約 100 秒，Q4_0 約 68 秒（**+32% 速度**，因 ARM SIMD kernel 對 Q4_0 最佳化）。FP16 版本因體積過大（~3.1 GB）不在此 repo 上架，需要的使用者請自行依上述指令重做轉換。

---

使用方式

1. whisper.cpp CLI

./build/bin/whisper-cli \
  -m ./ggml-breeze-asr-26-q5_k.bin \
  -f ./your_audio.wav \
  -l zh \
  -nt

• -l zh：強制中文 / 臺語語境（內部走 Whisper 的 zh token）
• -nt：不輸出 timestamps（純文字輸出）

2. Python（whisper-cpp-python）

from whisper_cpp_python import Whisper

w = Whisper(model_path="./ggml-breeze-asr-26-q5_k.bin")
result = w.transcribe(audio_path="./your_audio.wav", language="zh")
print(result["text"])

3. Flutter（whisper_flutter_new）

import 'package:whisper_flutter_new/whisper_flutter_new.dart';

final whisper = Whisper(model: WhisperModel.custom(
  path: '/path/to/ggml-breeze-asr-26-q5_k.bin',
));

final result = await whisper.transcribe(
  transcribeRequest: TranscribeRequest(
    audio: '/path/to/your_audio.wav',
    language: 'zh',
    isTranslate: false,
  ),
);

print(result.text);

---

已知行為差（vs 原模型 server pipeline）

在 whisper.cpp pipeline 下執行時，中英 code-switching 段落內的英文詞彙會傾向被意譯為漢字（例：meeting → 會議、Collaboration → 合作、Slack channel → Slab 頻道）。

這個差異不是來自量化（Q5_K / Q8_0 / FP16 三者輸出在量測樣本中完全一致），而是來自 whisper.cpp 與 faster-whisper（HF 原模型常用之 server-side runtime）兩條 decoding pipeline 的 sampling 超參、suppress_tokens、initial prompt 等預設不同。

如需保留原始英文詞，可在 whisper.cpp 端嘗試：

• 提供 --prompt 給 initial prompt（如先描述語料背景）
• 調 --temperature 0 並關閉 fallback
• 調整 --suppress-regex

對純中文段落、純英文段落、單純臺語段落，本量化模型輸出與 FP16 baseline 一致。

---

硬體需求

繼承 spec/decisions/adr-009-offline-inference.md §3 白名單，依量化版本分層：

Q4_0（精簡版，預設）— 4–8 GB RAM 機型也能跑

平台	條件
iOS	iPhone 13 mini 或更新（4 GB+ RAM 即可）
iPadOS	M1 以上的 iPad
Android	RAM ≥ 6 GB 且 ARM64-v8a 且 Android 12 (API 31) 以上
macOS	Apple Silicon（M1+）
Windows	x86_64 + 12 GB RAM（保留）

Q5_K（標準版）/ Q8_0（高品質版）— 旗艦白名單

平台	條件
iOS	A17 Pro 或更新（iPhone 15 Pro / 15 Pro Max / 16 系列以上）
iPadOS	M1 以上的 iPad
Android	RAM ≥ 8 GB 且 ARM64-v8a 且 Android 12 (API 31) 以上，且旗艦 SoC 白名單（Snapdragon 8 Gen 2+, Tensor G3+, Dimensity 9200+）
macOS	Apple Silicon（M1+）原生（不走 Rosetta）
Windows	x86_64 + 16 GB RAM（保留）

不在白名單的機器（如 Pixel 4），可裝 Q4_0 但推論時間會明顯較長（Pixel 4 / Snapdragon 855 實測 30 秒音訊約 68 秒）。如果需要即時體驗，建議使用 Server-side 推論（MediaTek-Research/Breeze-ASR-26 原模型 + faster-whisper）。

---

校驗

下載後請以 SHA256SUMS 比對：

shasum -a 256 -c SHA256SUMS

---

License & 引用

本 repo 內的 GGML 量化衍生模型沿用基底模型的 Apache License 2.0。

@misc{mediatek2026breezeasr26,
  title  = {Breeze-ASR-26: A Whisper-large-v2 fine-tune for Taigi, Mandarin, and code-switching ASR},
  author = {MediaTek Research},
  year   = {2026},
  url    = {https://huggingface.co/MediaTek-Research/Breeze-ASR-26}
}

---

相關連結

• 原模型：https://huggingface.co/MediaTek-Research/Breeze-ASR-26
• whisper.cpp：https://github.com/ggerganov/whisper.cpp
• 本 repo（待建立）：https://huggingface.co/Ahdaa/kong-tai-gi-ggml
• TâiUânUē App（離線版主要消費者）：[GitHub repo TBD]