轉錄幻覺過濾 Phase 3：decode-param knobs (WhisperKit)

[kiki830621]

Problem / Motivation

Phase A (#98) filters hallucinations after decode (denylist post-processing). A complementary approach is to suppress them at the source via WhisperKit decode parameters, so fewer hallucinations are generated in the first place.

Type

feature

Expected

Expose decode-param knobs in makeDecodeOptions (WhisperKit engine): noSpeechThreshold, compressionRatioThreshold, logProbThreshold, and possibly chunkingStrategy. These currently take WhisperKit defaults.

Notes / Caveats

• WhisperKit-only — these knobs don't apply to Parakeet / whisper.cpp / other backends, so this is complementary to the backend-agnostic post-decode filter (轉錄後過濾 Whisper 常見幻覺（no-speech 段的罐頭字幕 / 重複殘影） #98 Phase A + Phase 2), not a replacement.
• Can't target a specific known string the way the denylist can; it reduces hallucination rate generically.
• Lower priority than Phase 2 (confidence-gated post-decode gate helps all Whisper-family backends; decode-params help only WhisperKit).

Source: deferred from #98 (Phase 3), filed at /idd-close time.

[kiki830621]

Diagnosis

Type

feature

Root Cause / Analysis

Requirements breakdown:

1. Decode-param knobs — WhisperKitEngine.makeDecodeOptions currently sets language/prompt/deterministic only; WhisperKit's DecodingOptions exposes noSpeechThreshold, compressionRatioThreshold, and logProbThreshold which today ride WhisperKit defaults. Expose all three as optional (Double?, nil = keep WhisperKit's default) on TranscribeOptions, wired through to makeDecodeOptions.
2. CLI flags — --no-speech-threshold / --compression-ratio-threshold / --logprob-threshold, help text marked "(WhisperKit only)". Other engines ignore the fields (they never read them) — documented, not warned per-run (a warning on every non-WhisperKit transcribe would be noise; routing already explains which backend ran).
3. chunkingStrategy — the issue itself marks it "possibly"; smallest-blast-radius call is to defer it (different value domain, no threshold semantics) and record as residue.
4. Relationship to 轉錄幻覺過濾 Phase 2：confidence-gated (full) 模式 #100: these knobs suppress hallucinations at decode time (fewer bad segments generated); 轉錄幻覺過濾 Phase 2：confidence-gated (full) 模式 #100 filters what still leaks post-decode. Complementary, both land on the shared branch.

Impact

• Models/DataModels.swift (TranscribeOptions: 3 optional fields), Engines/WhisperKitEngine.swift (makeDecodeOptions wiring), Sources/bestasr/BestASRCommand.swift (3 CLI options), tests (spy-pipeline assertion that the options reach DecodingOptions; defaults stay WhisperKit's when nil).
• Shares files with 轉錄幻覺過濾 Phase 2：confidence-gated (full) 模式 #100 → same cluster branch/PR.

Strategy

• TranscribeOptions gains optional noSpeechThreshold / compressionRatioThreshold / logProbThreshold (nil = WhisperKit default)
• makeDecodeOptions applies them only when non-nil (existing spy-seam tests extended: set → reaches DecodingOptions; unset → DecodingOptions defaults untouched)
• CLI flags + help text "(WhisperKit only)"; README doc-sync
• chunkingStrategy deferred (residue)

Conflict Class

C_shared_module_coord — same shared modules as #100 (WhisperKitEngine.swift, TranscribeOptions, CLI); sequenced after #100 on the same branch.

Complexity

Simple — three optional pass-through fields with an existing injectable spy seam (#9) to test against.

Risks

• Silent-ignore on non-WhisperKit backends could confuse users A/B-ing backends — mitigated by "(WhisperKit only)" in help text and README.
• Setting aggressive thresholds interacts with --decode-deterministic (fallbackCount=0): thresholds that would normally trigger a fallback retry instead mark/skip segments — behavior documented in the flag help.

Residue

chunkingStrategy exposure (the issue's "possibly") — deferred: different value domain, unclear user need; revisit if hallucination reports persist after #100+#101 land.

[kiki830621]

✅ Verify — #101 decode-param knobs (opus adversarial pass, cluster with #100)

Verdict: SHIP WITH FIX (applied in 01e90c8) — one HIGH, one LOW-MEDIUM, one LOW; all addressed. Build green; 352 tests / 75 suites.

Findings

#	Severity	Finding	Status
1	HIGH	--logprob-threshold -1.0 (space form) failed to parse — ArgumentParser's default strategy rejects leading-dash values, and the log-prob domain is all-negative (WhisperKit's own default is -1.0), so the flag was unusable across its entire meaningful range via the documented syntax.	✅ fixed — parsing: .unconditional on the flag; regression test parses the real Transcribe command with the space form (the test target now links the executable target); empirically re-run: the space form now reaches the audio-file check.
2	LOW-MEDIUM	Doc-promise drift: the diagnosis promised the --decode-deterministic interaction (threshold trips mark/skip instead of triggering a fallback retry) would be documented in the flag help — it wasn't.	✅ fixed — noted in the flag help and README.
3	LOW	Scope honesty: knobs are CLI-only (MCP tool / GUI don't expose them) but nothing said so.	✅ fixed — README notes "CLI-only for now"; recorded here for the issue trail. (Contrast: #100's full mode IS reachable via MCP's hallucination_filter string automatically.)

Attacked and confirmed clean

• WhisperKit 0.18 DecodingOptions fields are Float? with stock defaults 0.6 / 2.4 / -1.0; the Float(Double) conversion is precision-safe; the nil path never touches the fields, so the unset == stock defaults test is meaningful.
• Positive-domain flags (--no-speech-threshold, --compression-ratio-threshold) parse normally on the default strategy (also regression-tested).
• Commit discipline: Refs #100/Refs #101 only, no auto-close keywords.

Stopping at verified — cluster PR (with #100) follows; merge + manual close are yours.

Refs #101

[kiki830621]

Closing Summary

Problem

All hallucination handling was post-decode (#98 denylist, #100 confidence gate); WhisperKit's decode-time thresholds (noSpeechThreshold, compressionRatioThreshold, logProbThreshold) rode hard defaults with no way to tune them — no knob to suppress hallucinations at the source (#101).

Root Cause

Feature gap: makeDecodeOptions set language/prompt/deterministic only; the three DecodingOptions thresholds were never exposed on TranscribeOptions or the CLI.

Solution

• TranscribeOptions carries three optional thresholds (nil = WhisperKit's own defaults, byte-for-byte pre-轉錄幻覺過濾 Phase 3：decode-param knobs (WhisperKit) #101 behavior — verified against stock DecodingOptions); makeDecodeOptions applies them only when set.
• CLI: --no-speech-threshold / --compression-ratio-threshold / --logprob-threshold, help-marked "(WhisperKit only)"; other backends never read the fields. README documents the knobs, the --decode-deterministic interaction (threshold trips mark/skip instead of triggering a fallback retry), and the CLI-only scope (MCP/GUI don't expose them yet).
• chunkingStrategy deliberately deferred per the issue's own "possibly" (recorded as residue in the Diagnosis).

Verification

• Opus adversarial verify (cluster with 轉錄幻覺過濾 Phase 2：confidence-gated (full) 模式 #100): SHIP WITH FIX, applied — the HIGH was real and would have shipped a dead flag: ArgumentParser's default strategy rejects leading-dash values, and the log-prob domain is all-negative, so the documented --logprob-threshold -1.0 failed with "Missing value" across the flag's entire meaningful range. Fixed with parsing: .unconditional + a regression test that parses the real Transcribe command in space form (the test target now links the executable target); empirically re-run to the audio-file check. Also fixed: the promised deterministic-interaction documentation (drift) and the CLI-only scope note. Report: 轉錄幻覺過濾 Phase 3：decode-param knobs (WhisperKit) #101 (comment)
• Type-level checks confirmed (Float? fields, precision-safe conversion, nil path untouched); positive-domain flags parse on the default strategy (also tested). Full suite 352/75 green; PR Hallucination filtering Phases 2+3 — confidence-gated full mode + WhisperKit decode knobs #102 CI green.

Changes

• 8ba9bbd feat: WhisperKit decode-param knobs — no-speech / compression-ratio / logprob thresholds
• 01e90c8 fix: negative logprob CLI value parses in space form + interaction/scope docs (verify)
• PR Hallucination filtering Phases 2+3 — confidence-gated full mode + WhisperKit decode knobs #102 (squash-merged, cluster with 轉錄幻覺過濾 Phase 2：confidence-gated (full) 模式 #100)

Residue

chunkingStrategy exposure (the issue's "possibly") — deferred; revisit if hallucination reports persist now that #100+#101 are both live. MCP/GUI knob exposure is a separate surface decision if agents/humans ask for it.

Related

• 轉錄後過濾 Whisper 常見幻覺（no-speech 段的罐頭字幕 / 重複殘影） #98 (Phase A), 轉錄幻覺過濾 Phase 2：confidence-gated (full) 模式 #100 (Phase 2 — post-decode complement to these decode-side knobs).