FluidAudio 0.15.4 → 0.15.5 升級 + Parakeet Unified/TDT-ja 納入評估 (sister concern from #109)

[kiki830621]

Problem

FluidAudio pin 落後一版：本 repo Package.swift pin exact: 0.15.4（6/16），上游 0.15.5（7/7）帶了實質新能力與一個破壞性變更。2026-07-29 偵察（asr-model-scout）確認：

• Parakeet Unified 0.6B：新後端，原生 Swift mel 前端、詞級時間戳；英文批次 WER/吞吐優於 TDT v3。
• Parakeet TDT Japanese：ja 是本 repo benchmark 主戰場之一，目前未納。
• Custom vocabulary（per-term CTC threshold）：非 Whisper 家族吃 context biasing 的第一條路（目前 biasing 只偏 Whisper prompt）。
• ⚠️ 破壞性變更：DownloadUtils → ModelHub（下載架構重寫，續傳 + 位元組級進度）。
• 0.15.3 已移除實驗性 zh-CN CTC 與 Qwen3 ASR 後端（升級時注意 API 面）。

Type

feature

Expected

1. Pin bump 0.15.4 → 0.15.5（處理 ModelHub API 變更），全測試綠。
2. 評估納入 Parakeet Unified（en）與 TDT Japanese（ja）為可跑 backend/model（ModelGrid pinned rows + 記憶體估計 + 測試）。
3. （可另拆）custom vocabulary 接進 context biasing——非 Whisper 家族的 context.json 路徑。
4. 升級前後各跑一輪 release sweep（measureASR：release 全矩陣 deterministic sweep（pin 版本下每個模型的表現快照） #109 的制度）作為 before/after 證據——新版本＝新 condition，舊測量不得混排（common-ocr-toolchain-freshness 例外 2 紀律）。

Actual

pin 在 0.15.4；ja 無專用模型；非 Whisper 家族無 context biasing。

Impact

• Package.swift（exact pin）、ModelGrid.swift（新 rows + pinned revisions）、ModelRegistry（記憶體估計）、engines 對 ModelHub API 的呼叫面、測試。
• 與 measureASR：release 全矩陣 deterministic sweep（pin 版本下每個模型的表現快照） #109 互補：sweep 提供升級的量測證據。

Source: surfaced during /idd-diagnose #109 sister concern surfacing (Step 3.6)；偵察來源為 2026-07-29 asr-model-scout 報告（FluidAudio releases / Models.md）。

Current Status

• Phase: diagnosed
• Complexity: Spectra (recommend decompose)
• Last update: 2026-07-31

---

Decomposition（2026-08-01）

依本 issue 的 diagnosis「強烈建議先 decompose，不要當單一 monolith 實作」，已拆為
4 個子 issue。本 issue 轉為 epic，不直接實作。

Children

• FluidAudio pin 0.15.4 → 0.15.5（#110 子項 A，B/C 的 blocker） #122 — FluidAudio pin 0.15.4 → 0.15.5（blocker；已查證 DownloadUtils 本 repo 零使用，風險小於原描述）
• Parakeet Unified 0.6B 納入為新 backend（#110 子項 B） #123 — Parakeet Unified 0.6B 納入為新 backend（blocked by FluidAudio pin 0.15.4 → 0.15.5（#110 子項 A，B/C 的 blocker） #122）
• Parakeet TDT Japanese 納入 model grid（#110 子項 C） #124 — Parakeet TDT Japanese 納入 model grid（blocked by FluidAudio pin 0.15.4 → 0.15.5（#110 子項 A，B/C 的 blocker） #122）
• custom vocabulary 接進 context biasing：非 Whisper 家族的第一條路（#110 子項 D） #125 — custom vocabulary 接進 context biasing（blocked by FluidAudio pin 0.15.4 → 0.15.5（#110 子項 A，B/C 的 blocker） #122；預判 Spectra）

原 diagnosis 的子項 E（升級前後各跑一輪 release sweep 作 before/after 證據）不獨立成
issue，已摺進 #122 的 Expected 作為驗證要求——它是 pin bump 的證據產出，不是獨立工作。

依賴鏈

#122 (pin bump) ──┬──> #123 (Unified backend)
                  ├──> #124 (TDT-ja rows)
                  └──> #125 (custom vocab)   ← 亦可獨立於 B/C 進行

已知的橫向缺口（承本 issue Residue）

measurement schema 不記錄 FluidAudio 版本（只有 bestASR 自己的 app_version），使
#122 的 before/after sweep 在資料上難以機械區分。屬 #111/#118 family，已記錄於 #122。

[kiki830621]

Diagnosis

Type

feature

Root Cause / Analysis（需求拆解 + 探勘實據）

#110 是四個獨立 deliverable 綁在一張 issue（issue 自己已標 item 3「可另拆」），且彼此有順序依賴。探勘後有一個降風險的關鍵發現：

破壞性變更（DownloadUtils → ModelHub）對本 repo 很可能是 non-event。 全 Sources/ 零使用 DownloadUtils（grep -rn DownloadUtils Sources/ = 空）。本 repo 對 FluidAudio 的 API 面是高階的：

• AsrModels.download(version:) / AsrModels.load(from:version:)（ParakeetEngine.swift:116-118）
• AsrManager(config:.default, models:)（:119）
• ASRResult.text/.confidence/.duration/.tokenTimings
• DiarizerManager()（DiarizationEngine）

DownloadUtils → ModelHub 是下載層內部重寫；本 repo 不碰下載層，只碰 AsrModels.download/load。所以 pin bump 的真正風險不是 ModelHub，而是「AsrModels.download/load 的 signature 在 0.15.5 有沒有變」+「0.15.3 移除的實驗性 zh-CN CTC / Qwen3 後端本 repo 有沒有依賴」。這兩點是 pin bump 的實際待驗面，遠比 issue 描述聽起來小。

現況錨點：

• Pin：Package.swift:16 exact: "0.15.4"。
• 既有 Parakeet：ModelGrid.swift:52 fluidParakeetRows 有 fluid-parakeet backend 的 parakeet-tdt-0.6b-v3-coreml（en + 24 歐語，recommend/transcribe 的 --language auto 未偵測音訊語言，非英文內容被推薦英文專用後端 #105 已標非 "multi"）。另有 mlx-audio 的 parakeet reference row（:127）。
• 待新增：Parakeet Unified 0.6B（0.15.5 新後端，native Swift mel + word-level timestamps）、Parakeet TDT Japanese（ja）——皆需新 ModelGrid rows + 記憶體估計（ModelRegistry）+ 測試；Unified 可能需新 engine API 面。

Impact

• Package.swift（pin）、ModelGrid.swift（新 rows + pinned revisions）、ModelRegistry（記憶體估計）、ParakeetEngine.swift（Unified API 面，若有）、測試。
• 與 measureASR：release 全矩陣 deterministic sweep（pin 版本下每個模型的表現快照） #109/measurement schema 增 run_kind / decode-determinism provenance 欄位（follow-up from #109 verify） #111 互補：measurement schema 增 run_kind / decode-determinism provenance 欄位（follow-up from #109 verify） #111（剛完成）加的 run_kind / decode_deterministic 正是 FluidAudio 0.15.4 → 0.15.5 升級 + Parakeet Unified/TDT-ja 納入評估 (sister concern from #109) #110 item 4「before/after sweep 作升級證據」所需的 provenance——升級前後的 sweep row 能用 app_version（+ 未來或可加 FluidAudio 版本欄位）機械區分。

Conflict Class

D_diagnose_first — scope 未明、需先讀（已讀）。實作階段觸及 shared abstraction（ModelGrid / BackendID / engine API），且跨「外部依賴升級 → 新模型 → 評估」有順序依賴，拆解後各子 issue 的 conflict class 不同（pin bump = B_resource_serialize 對 Package.resolved；新模型 rows = C_shared_module_coord 對 ModelGrid）。

Complexity

Spectra（但強烈建議先 decompose，不要當單一 monolith 實作）

四個 deliverable 的性質差異大，routing 各異：

子項	建議拆為	性質	routing
A. Pin bump 0.15.4→0.15.5	獨立 issue（基礎、blocker）	驗 AsrModels.download/load signature + 0.15.3 移除面依賴；DownloadUtils 非本 repo 用 → 風險比描述小	Plan（外部依賴 + 破壞性變更疑慮，值 approval gate；實測若 API 無變則近 Simple）
B. Parakeet Unified (en)	獨立 issue	新後端 + 可能新 engine API 面（native mel / word timestamps）+ ModelGrid rows	Plan/Spectra（新 published backend surface）
C. Parakeet TDT ja	獨立 issue	新 ModelGrid rows + 記憶體估計 + ja 測試	Plan
D. Custom vocab → 非 Whisper context biasing	獨立 issue（issue 自己說「可另拆」）	新 context.json 路徑給非 Whisper 家族 = 新 published surface	Spectra
E. Before/after release sweep	依賴 A、#109 infra、#111 provenance	評估方法，受 global freshness 例外 2 紀律約束（工具版本進 condition tuple）	非 code：sweep 執行 + 證據

依賴鏈：A（pin）是 B/C/E 的 blocker；D 獨立；E 依賴 A 完成 + #109 sweep infra + #111 provenance。

Risks

• 升級不可逆污染 evidence base（global common-ocr-toolchain-freshness 例外 2）：FluidAudio 版本改變會改變一個 measured row 的意義——0.15.4 量的 Parakeet 數字與 0.15.5 量的是不同 condition，不可排同一 ranking。E 的 before/after sweep 必須把 FluidAudio 版本記進 condition tuple（目前 schema 只有 app_version——bestASR app 版本 bump 才 tag，FluidAudio 版本未獨立記；可能需要一個 follow-up 加 dep_versions 欄位，與 measurement schema 增 run_kind / decode-determinism provenance 欄位（follow-up from #109 verify） #111/mlx-audio determinism 表示法抉擇：Bool?+nil vs per-backend enum vs document-only（deferred from #111） #118 同源）。
• 0.15.3 移除實驗性 zh-CN CTC / Qwen3——若本 repo 的 ChineseFamilyEngine 依賴，pin bump 會炸（待驗）。
• Unified 若需新 engine API，B 的 scope 會膨脹。

Residue

「FluidAudio 版本進 measurement condition tuple」需要 schema 支援（#111 只加了 run_kind/decode_deterministic，未加 dependency 版本欄位）——E 的完整可比性依賴此，可能是 #111/#118 family 的另一 follow-up，非本 issue 可獨力解。誠實標記。

Vagueness Pre-check

• V1: 3 — 四個 deliverable 各自具體，但「評估納入」（item 2）與 Unified 的 engine API 需求邊界需實測才明（未達 trigger，因方向清楚只是範圍待實作確認）
• V4: 3 — 「全測試綠」「before/after 證據」可驗；Unified 的完成定義依賴其 API 面
• Triggered: no — both axes ≤ 3
  [Layer V: V1=3 V4=3, evaluated under unattended mode（idd-all）, no trigger]

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

(none filed) — 本 issue 本身即需 decompose；「FluidAudio 版本進 condition tuple」的 schema 缺口已在 Residue 標記，屬 #111/#118 family，待使用者決定 decompose 方向後再定是否 file。