whisper.cpp quantization table assumes q5_0 exists for all models — tiny/base ship q5_1 on HF (404 guidance URL)

[kiki830621]

Problem

發現途徑：2026-07-02 真實多模型驗證（使用者要求以 HuggingFace 實際模型驗證，非 mock）時，對 ggerganov/whisper.cpp 逐檔 HTTP 探測：

ggml-tiny-q5_0.bin → 404      ggml-tiny-q5_1.bin → 200      ggml-tiny-q8_0.bin → 200
ggml-base-q5_0.bin → 404      ggml-base-q5_1.bin → 200      ggml-base-q8_0.bin → 200

ModelRegistry.quantizations[.whisperCpp] = ["q5_0", "q8_0"] 假設所有模型都有 q5_0，但 HF 發佈的 tiny/base（以及 small）是 q5_1，q5_0 只存在於 medium/large 系。後果：

1. WhisperCppEngine 的 model-missing 錯誤訊息會給使用者一個 404 的 curl URL（誠實錯誤變成誤導指引）
2. benchmark 枚舉的 q5_0 候選對 tiny/base/small 永遠只能失敗（warn-continue 噪音）

Type

bug

Expected

量化檔位表按模型尺寸區分可用性（tiny/base/small → q5_1/q8_0；medium/large 系 → q5_0/q8_0），或改為下載前探測；錯誤訊息中的 URL 必須實際存在。

Actual

單一 ["q5_0","q8_0"] 清單套用全模型；tiny/base 的 q5_0 指引 URL 為 404。

Impact

• Sources/BestASRKit/Models/ModelRegistry.swift（quantizations 表 → per-model 對應）
• openspec/specs/asr-engine 或 registry 相關 spec 的量化描述
• 測試：對照表 + 錯誤訊息 URL 格式

---

Current Status

• Phase: closed
• Updated: 2026-07-02 (closed)
• Complexity: Simple · Conflict Class: A_parallel_safe
• Verify: PASS (0 blocking; PR fix: per-model whisper.cpp quantization table — HF-accurate variants, drift-guarded (#5) #10)
• Diagnosis: whisper.cpp quantization table assumes q5_0 exists for all models — tiny/base ship q5_1 on HF (404 guidance URL) #5 (comment)

[kiki830621]

Diagnosis

Type

bug

Root Cause

ModelRegistry.quantizations[.whisperCpp] = ["q5_0", "q8_0"] 是單一清單套用全模型，但 HF ggerganov/whisper.cpp 的量化檔位按模型尺寸而異（issue 內 HTTP 探測證據：tiny/base 的 q5_0 404、q5_1/q8_0 200）。WhisperCppEngine 的 model-missing 錯誤直接用 modelFileName(model:quantization:) 組 URL → 對不存在的檔位給出 404 指引；benchmark 枚舉也對 tiny/base/small 產出必敗的 q5_0 候選。

Impact

• Sources/BestASRKit/Models/ModelRegistry.swift（quantizations 表、defaultQuantization）
• Sources/BestASRKit/Router/ColdStartPrior.swift 若 default quant 簽名改為 per-model 需跟動
• 測試：registry 對照表、（可選）URL 存在性標註
• Spec 零波及：living specs 不 pin 具體量化值（枚舉/預設屬實作資料）

Strategy

• 實作前對 HF 補探測 small/medium/large 系的 q5_0/q5_1/q8_0 可用性（一次 curl -I 掃描），據實建表
• quantizations 改 per-(backend, model) 對應（tiny/base/small → q5_1/q8_0；medium/large 系依探測）；defaultQuantization(for:) 增 model 參數
• 更新 callers（ColdStartPrior、benchmark 枚舉、list-models 輸出）
• 測試：per-model 表 + 預設值參數化斷言；錯誤訊息 URL 由表組出（不再可能 404 檔位）
• 用既存 GGML 檔重跑一次 benchmark 枚舉確認 q5_1 候選出現、q5_0 消失

Conflict Class

A_parallel_safe — 獨立檔案（ModelRegistry + ColdStartPrior + tests），無共享 mutable 資源；與 #7（WhisperKitEngine/BenchmarkRunner）檔案不相交。

Complexity

Simple — root cause 明確、修法自包含（資料表 + 簽名連動），無對外 API 契約變更（Layer 2 未命中），無 Layer P 信號（非併發/遷移敏感）。

Risks

• HF repo 檔位未來變動 → 表仍可能過時；緩解：錯誤訊息保留「列出該模型實際可用檔位」而非單一 URL
• defaultQuantization 簽名改動的 caller 遺漏 → 編譯器擋

Residue

(none)

Vagueness Pre-check

• V1: 2 — issue 含明確 expected/actual 與實測證據（HTTP 探測 / 修復對照 / X-REAL 數字）
• V4: 2 — 驗收可測（URL 不 404 / regression 測試 / X-REAL 上升）
• Triggered: no — both axes ≤ 3
  [Layer V evaluated under UNATTENDED MODE — /idd-all orchestrator]

Sister Concerns Filed (mid-diagnose, v2.47.0+ #528)

(none surfaced) — #5/#6/#7 本身即同一輪真實驗證的姊妹 findings，已互相關聯。

[kiki830621]

Verify: #5

Engine

dynamic-workflow backend — 4 distinct-lens reviewers + devil's advocate + Codex（gpt-5.5 xhigh）；6/6 完成、0 process gap。

要求覆蓋率

3/3 + 超額 — per-model 表 ✓（DA 以 HF API 獨立複核全 13 檔位，含 large-v3 只有 q5_0——正確地偏離 issue 原文的錯誤預期「medium/large 系 → q5_0/q8_0」）；指引 URL 實測 HTTP 200 ✓；callers 全遷移 ✓。

Findings（合併後，14 → triage）

#	Severity	Finding	Source	Action
1	MEDIUM	BestASRKit public API break（quantizations dict 移除、defaultQuantization 改簽名）	codex	決策明示：pre-1.0 無 tag/外部消費者，蓄意 break、不留 shim——CHANGELOG ### Changed 記錄
2	MEDIUM	Issue Impact 列的 spec 量化描述沒動；benchmark spec「cross product」句已不準	DA 獨家	In-scope fixed（spec 枚舉措辭同步 per-(backend,model)）
3,7,8,10,11	LOW	.claude/.idd/routing-stats.jsonl（#6 的 telemetry）被 git add -A 掃進 #5 commit；DA 深化：idd-verify 每輪 append → 會復發	codex+security+regression+DA	In-scope fixed（untracked + gitignored）
4,5,6	LOW	default arm 對未來模型是猜測、鎖表測試抓不到新模型漂移、[0] force-index	codex+logic	In-scope fixed（顯式 arms、未知→空列、guarded precondition、drift-guard 測試）
9	LOW	測試 fixtures 仍用 404 組合（small+q5_0）；缺 guidance-檔名契約測試	DA 獨家	In-scope fixed（fixtures → q5_1；GuidanceFileNameTests 全表掃描）
12-14	INFO	無 prompt injection；HF 全表獨立複核通過；docs commit 未入 ensemble diff（DA 已人工補審，factually consistent）	security+DA	記錄

In-scope fixes

Commit 552cfc7（同 branch）。125 tests / 34 suites 綠。

Scope Check

telemetry 檔為唯一 scope creep，已移除；其餘 diff 緊扣 registry/callers/tests/spec。

Result

PASS（verify-gated） — 0 blocking；MEDIUM ×2 分別以「明示決策」與「in-scope fix」消解；無 follow-up 需另立 issue。PR: #10

[kiki830621]

Closing Summary

Problem

ModelRegistry.quantizations[.whisperCpp] 用單一 ["q5_0","q8_0"] 清單套用全模型，但 HF ggerganov/whisper.cpp 的檔位按模型尺寸而異。後果：model-missing 錯誤訊息對 tiny/base/small 給出 404 的下載 URL（誠實錯誤變誤導指引）、benchmark 枚舉產生永遠失敗的 q5_0 候選。真實多模型驗證時以 HTTP 探測發現。

Root Cause

量化可用性被假設為 backend 級常量，實際是 per-(backend, model) 的不規則分布（HF 實測三種模式：tiny/base/small → q5_1+q8_0；medium/large-v3-turbo → q5_0+q8_0；large-v3 → 只有 q5_0）。表格是猜測而非數據。

Solution

quantizations(for:model:) per-model 顯式表（逐列鎖到 HF 實測；未知模型回空列而非猜測，defaultQuantization 以具名 precondition 防空列）；callers 全遷移（BenchmarkRunner 枚舉、Router cold-start、list-models）；benchmark spec 枚舉措辭同步；測試鎖表 + GuidanceFileNameTests 全表掃描。BestASRKit API 蓄意 pre-1.0 break（CHANGELOG 記錄）。

Verification

6-AI verify（dynamic-workflow）PASS，0 blocking（master report）——DA 以 HF API 獨立複核全 13 檔位（含修正 issue 原文對 large-v3 的錯誤預期）。實測：q5_1 指引 URL HTTP 200（原 q5_0 為 404）；合併後整合 131 tests 綠 + 跨 backend smoke 枚舉正確。

Changes

• d7ac6d4 fix: per-model quantization table（branch）
• 813e1a6 docs: CHANGELOG + README note（branch）
• 552cfc7 fix: verify findings — explicit arms/drift guards/spec sync/telemetry untracked（branch）
• f4f129d（squash-merge to main via PR fix: per-model whisper.cpp quantization table — HF-accurate variants, drift-guarded (#5) #10）

Merge-completeness

Gate 標記 d7ac6d4/813e1a6 為 orphan → judged false-positive with evidence（intra-branch supersession：內容被同 branch 552cfc7 改寫後隨 tip squash 進 main；功能內容逐項驗證在 main）。

Residue Acknowledgement

Diagnosis residue 為 (none) — no acknowledgement needed.

Distribution Sync

• Detected: plugin (bestasr, git-based marketplace)
• Choice: not applicable — this issue doesn't ship
• Outcome: 修復在 core binary；plugin shell（skills/plugin.json）未變、無 binary release 管道；marketplace 使用者於下次 claude plugin marketplace update 自然取得新 code
• At: 2026-07-02T01:29:13Z