llmfit 音频模型支持实现指南：为 Whisper 自动语音识别构建 RTF 感知的硬件适配与推荐

本文基于仓库根目录下的 AUDIO_SUPPORT.md（实现计划文档）展开，并对照当前仓库源码与数据逐一核实：哪些内容已落地、哪些仍处于提案阶段。文档的核心命题是——语音转写模型与 LLM 的适配逻辑并不相同，llmfit 需要一套以 RTF（Real-Time Factor，实时率） 与 VRAM/内存占用 为度量的独立分析路径，才能回答"我的硬件该跑哪个 Whisper"。读完本文，你将掌握 ASR 音频元数据的字段语义、Capability::Audio/UseCase::Audio 的分类边界、AudioFit 评分模型，以及 MLX / faster-whisper 本地 Whisper 服务端的探测方案。

背景：为什么"选择 Whisper 模型"和"选择 LLM"一样困难

llmfit 的既有能力是"一条命令找出能在你硬件上运行的模型"（数百个模型与提供方），但它的分析管线围绕 LLM 的两个核心量纲展开：token/s（吞吐）与 KV cache 随上下文增长带来的内存估算。以 fit.rs 中的 ModelFit 结构体（fit.rs）为例，其核心输出包括 estimated_tps、prefill_tps、ttft_ms、usable_context、score 及 memory_required_gb——这些字段对文本生成模型是精确的，但对自动语音识别（ASR）模型基本无效：Whisper 不"生成"连续文本 token 流，而是对一段定长音频做编码-解码转写，其速度由 处理时长与音频时长的比值 决定，与 token/s 是两套坐标系。

更现实的问题在于硬件差异的悬殊：同一转写模型在 NVIDIA GTX 1660 Ti 与 Apple M3 Pro 上的 RTF 可能差出一个数量级。AUDIO_SUPPORT.md 将这种"选错模型的困惑"与选 LLM 类比，提出把 llmfit 的硬件感知推荐能力延伸到音频域。文档将其落地拆成两个阶段：

1. 数据层变更（本分支已完成）：在 llmfit-core/data/hf_models.json 中新增带音频扩展字段的 ASR 模型条目；
2. Rust 集成（下一步，开放讨论）：models.rs、fit.rs、providers.rs 与 CLI 四处改动，让推荐引擎真正"理解"音频模型。

一、数据层：4 条 Whisper 条目的音频元数据 Schema

1.1 扩展字段及其语义

AUDIO_SUPPORT.md 规定，4 条新增模型条目需携带 pipeline_tag: "automatic-speech-recognition"、capabilities: ["audio"]，以及 4 个自定义下划线字段。经核实，这 4 个字段已实际存在于 hf_models.json 中：

字段	类型	语义
_audio_rtf_gpu	f64	GPU 上的实时率 RTF；数值含义为"处理时间 / 音频时长"，越低越快
_audio_rtf_cpu	f64	CPU 上的 RTF
_audio_vram_gb	f64	F16 精度下所需的显存（GB）
_audio_backends	[str]	该模型受支持的服务端/推理后端列表

之所以使用带下划线前缀的自定义字段名，文档给出的理由很明确：这些字段是 llmfit 私有扩展，不破坏既有 Rust 反序列化。这依赖两条 serde 惯例：其一，LlmModel（models.rs 起）对大量可选字段已统一使用 #[serde(default)] 声明；其二，serde 默认忽略 JSON 中未声明的键。因此即使当前 Rust 侧尚未声明 _audio_* 字段，老版本二进制也能平滑读取含这些键的新数据文件——这正是"数据先行、Rust 跟进"能成立的前提。若后续要类型化访问，文档建议为 LlmModel（或其伴生 AudioMeta 结构）增加：

#[serde(default)]
pub audio_rtf_gpu: Option<f64>,
#[serde(default)]
pub audio_rtf_cpu: Option<f64>,
#[serde(default)]
pub audio_vram_gb: Option<f64>,
#[serde(default)]
pub audio_backends: Vec<String>,

Option<f64> + #[serde(default)] 的组合保证：JSON 中缺省时反序列化为 None（而非报错），与既有模型字段的兼容策略保持一致。

1.2 已入库的 4 个 ASR 条目

AUDIO_SUPPORT.md 所称的 4 条新增条目，在数据文件中均有迹可查（均标注 pipeline_tag: "automatic-speech-recognition"、capabilities: ["audio"]、architecture: "whisper"、format: "safetensors"、quantization: "F16"）：

模型	参数量	_audio_rtf_gpu	_audio_rtf_cpu	_audio_vram_gb	_audio_backends
openai/whisper-medium（hf_models.json）	307M	0.003	0.05	0.6	faster-whisper、whisper.cpp、huggingface、mlx-openai-server
distil-whisper/distil-large-v3（hf_models.json）	756M	0.004	0.08	1.2	faster-whisper、huggingface
openai/whisper-large-v3-turbo（hf_models.json）	809M	0.007	0.12	1.5	mlx-openai-server、faster-whisper、whisper.cpp、huggingface
openai/whisper-large-v3（hf_models.json）	1.5B	0.04	0.6	2.5	mlx-openai-server、faster-whisper、whisper.cpp、huggingface

以 openai/whisper-medium 条目为例，其 JSON 结构（hf_models.json）为：

{
  "name": "openai/whisper-medium",
  "provider": "OpenAI",
  "parameter_count": "307M",
  "min_ram_gb": 1.0,
  "recommended_ram_gb": 1.5,
  "min_vram_gb": 1.0,
  "quantization": "F16",
  "format": "safetensors",
  "context_length": 448,
  "use_case": "Audio transcription (balanced accuracy/speed, multi-language)",
  "capabilities": ["audio"],
  "pipeline_tag": "automatic-speech-recognition",
  "architecture": "whisper",
  "_audio_rtf_gpu": 0.003,
  "_audio_rtf_cpu": 0.05,
  "_audio_vram_gb": 0.6,
  "_audio_backends": ["faster-whisper", "whisper.cpp", "huggingface", "mlx-openai-server"]
}

值得注意的数据分层：whisper-medium（0.003）与 distil-large-v3（0.004）在 GPU 上极快、显存占用小，适合入门级显卡与纯 CPU 场景（CPU RTF 0.05，意味着远快于实时）；whisper-large-v3-turbo 在精度与速度间取平衡（GPU 0.007 / CPU 0.12）；whisper-large-v3 面向最高精度诉求（GPU 0.04 / CPU 0.6，CPU 上已接近实时上限）。这正是"同样叫 Whisper，硬件选型天差地别"的量化证据。

1.3 数据文件中的一处分类陷阱

数据中其实还有第 5 个带 pipeline_tag: "automatic-speech-recognition" 的条目：microsoft/Phi-4-multimodal-instruct（hf_models.json）。但它的 architecture 是 phi4mm、format 是 gguf、use_case 是 "Instruction following, chat"，且不带 _audio_* 字段。这说明：pipeline_tag 标签本身不足以精确判定"这是一个 ASR 专用模型"——若后续 UseCase::from_model 只按 pipeline_tag 判断，会把这类多模态指令模型误划入纯 Audio 用例（详见下文第二节的注意事项）。

二、Rust 模型层：Capability / UseCase / LlmModel 的改动

2.1 Capability 枚举：当前源码已包含 Audio

AUDIO_SUPPORT.md 提案的第一步是给 Capability 枚举增加 Audio 变体。核实当前源码发现这一步已经完成（models.rs），且枚举现为四态：

pub enum Capability {
    Vision,
    ToolUse,
    Audio,
    Tts,
}

配套的 Capability::label() 为 Audio 提供 "Audio" 展示名（Tts 为 "Text-to-Speech"），Capability::all() 亦包含二者（models.rs）。

更有价值的是 Capability::infer()（models.rs）——当 JSON 未显式声明 capabilities 时，它会按与 Vision/ToolUse 相同的启发式自动推断 Audio 能力：

// Audio (speech-to-text) detection — Whisper / distil-whisper family.
let architecture = model.architecture.as_deref().unwrap_or("").to_lowercase();
if !caps.contains(&Capability::Audio)
    && (architecture.contains("whisper")
        || name.contains("whisper")
        || use_case.contains("text-to-speech")
        || use_case.contains("transcription")
        || use_case.contains("speech")
        || use_case.contains("audio"))
{
    caps.push(Capability::Audio);
}

源码注释揭示了一个关键现实（models.rs）：HF 抓取器并不会为新的 ASR 模型自动设置 capabilities=["audio"]，因此需要从 architecture/name/use_case 推断。换句话说，即使抓取器持续接入新的 Whisper 变体，infer 也能兜底赋予其 Capability::Audio。与此呼应，数据抓取侧的 infer_capabilities 也把 text-to-speech pipeline 映射为 [Capability::Audio, Capability::Tts]（update.rs）——注意这里 TTS 也被授予宽泛的 Audio 能力。

2.2 UseCase::Audio：仍是提案，且有分类精度隐患

文档要求新增 UseCase::Audio，并让 from_model 在命中 pipeline_tag == "automatic-speech-recognition" 或 capabilities 含 Capability::Audio 时返回 UseCase::Audio：

pub enum UseCase {
    General, Coding, Reasoning, Chat, Multimodal, Embedding,
    Audio,  // ← 提案新增
}

impl UseCase {
    pub fn from_model(model: &LlmModel) -> Self {
        if model.pipeline_tag.as_deref() == Some("automatic-speech-recognition")
            || model.capabilities.contains(&Capability::Audio)
        {
            UseCase::Audio
        } else { /* existing logic */ }
    }
}

这是文档所述 Rust 改动中尚未在主线落地的部分：当前源码的 UseCase 枚举仍止于 General/Coding/Reasoning/Chat/Multimodal/Embedding 六个变体（models.rs），from_model 的逻辑只覆盖 embedding/code/vision/reason/chat 五类（models.rs），尚无音频分支。UseCase 之所以重要，是因为 fit.rs 的分值计算按用例选择权重（models.rs 的注释即点明"use-case category for scoring weights"），只有为 Audio 建立独立用例，才能在后续分析中切入 RTF 评分而非 token/s 评分。

结合 1.3 节的数据事实，实现 from_model 时需要比文档示例更谨慎：直接把 pipeline_tag == "automatic-speech-recognition" 或 capabilities.contains(&Capability::Audio) 判为 Audio，会把 microsoft/Phi-4-multimodal-instruct 这类"带语音输入的多模态指令模型"整体划入 ASR 用例，而其真实定位是 chat 文本生成。更稳妥的判据是与 architecture == "whisper"（或存在 _audio_* 字段）做组合判断。仓库测试也印证了"架构/用例 vs 能力"需要分开对待：models.rs 内既有针对 Whisper 条目必须携带 Capability::Audio 的断言（models.rs），也有要求 TTS 条目携带宽泛 Capability::Audio 的断言（models.rs）。

三、适配层：AudioFit 与 RTF 评分模型

3.1 为什么不能复用 ModelFit

AUDIO_SUPPORT.md 明确提出：ASR 模型不用 tok/s，而用 RTF。当前 ModelFit（fit.rs）的整个估值体系都建立在文本生成假设上：estimated_tps 估算基线吞吐、usable_context 估算上下文窗口内能装多少 token、estimate_basis 记录估算方法与带宽效率。这些概念对"转写一段 30 秒语音"几乎没有意义。因此文档建议新增独立结构体：

pub struct AudioFit {
    pub model: LlmModel,
    pub rtf_gpu: Option<f64>,
    pub rtf_cpu: f64,
    pub fits_vram: bool,
    pub fits_ram: bool,
    pub recommended_backend: String,
}

语义对照清晰：fits_vram / fits_ram 对应 ModelFit 的内存适配检查（对照 _audio_vram_gb 与硬件 VRAM/RAM 池），recommended_backend 则从 _audio_backends 中选出与本地运行时可匹配的服务端（见第四节），而性能主轴从 estimated_tps 换成 rtf_gpu / rtf_cpu。

3.2 评分公式：accuracy_tier − latency_penalty − vram_penalty

文档给出的音频评分核心公式为：

score = accuracy_tier − latency_penalty − vram_penalty

要点是"RTF 越低 = 越快 = 得分越高"，即延迟惩罚项与 RTF 正相关——这与 ModelFit 的 0–100 加权综合分 score（含 score_components 明细）思路一致，只是把"吞吐+内存+用例权重"替换为"精度档位 − 延迟 − 显存压力"三个音频域指标。从数据层面看它的实际效果：distil-large-v3（English-only、0.004 GPU RTF）会在延迟维度胜过 whisper-large-v3（0.04 GPU RTF），但在 accuracy tier 上落于下风；whisper-medium 的多语言平衡定位则落在二者之间——最终排名完全取决于三条轴线的权重配比，这与仓库对 LLM 打分"加权综合"的设计哲学（见 fit.rs 对 score 与 score_components 的注释）保持了一致。

四、服务端探测：为本地运行的 Whisper 服务建立 Provider

4.1 两条服务端路径

AUDIO_SUPPORT.md 规划的检测逻辑面向两类真实的本地部署形态：

/// mlx-openai-server Whisper endpoint (Apple Silicon path).
pub struct MlxWhisperProvider;
impl ModelProvider for MlxWhisperProvider {
    fn check_running(&self) -> Option<ProviderInfo> {
        probe_http("http://localhost:18000/v1/audio/transcriptions")
            .map(|_| ProviderInfo { name: "mlx-openai-server", port: 18000 })
    }
}

/// faster-whisper-server (Docker, NVIDIA/CPU path).
pub struct FasterWhisperProvider;
impl ModelProvider for FasterWhisperProvider {
    fn check_running(&self) -> Option<ProviderInfo> {
        probe_http("http://localhost:8000/health")
            .map(|_| ProviderInfo { name: "faster-whisper-server", port: 8000 })
    }
}

两条路径各有侧重：

• mlx-openai-server（默认端口 18000）：Apple Silicon 路径，探测 http://localhost:18000/v1/audio/transcriptions。注意它暴露的是 OpenAI 兼容的音频转写端点——这正是"AI 页面/视频摘要"这类应用能以 OpenAI SDK 直连 Whisper 的接口形态。对照数据文件，_audio_backends 中含 mlx-openai-server 的正是 whisper-large-v3 与 whisper-large-v3-turbo 这两个大模型条目，与 MLX 生态在 Apple Silicon 上运行大 Whisper 的典型用法吻合。
• faster-whisper-server（默认端口 8000）：Docker 部署、面向 NVIDIA/CPU 的路径，探测 /health 健康端点。whisper-medium 与 distil-large-v3 的两个条目也声明了 faster-whisper 后端，whisper.cpp / huggingface 则作为跨平台轻量与参考后端同时被列出。

4.2 与既有 Provider 抽象的关系

需要澄清的是，当前仓库的 ModelProvider trait（providers.rs）定义的是模型生命周期管理接口——name()、is_available()、installed_models()、start_pull()/pull_progress()，面向 Ollama、llama.cpp、MLX、Docker Model Runner、LM Studio、vLLM 等"能列出本地已装模型并拉取新模型"的运行时（见 providers.rs）。文档中 MlxWhisperProvider / FasterWhisperProvider 所依赖的 probe_http + ProviderInfo { name, port } 是一套更轻量的"健康探测"抽象，属于提案内容。其价值在于：AudioFit.recommended_backend 可以据此从"模型理论上支持哪些后端"收敛为"你的机器此刻真正跑着哪个后端"，从而给出可立即执行的推荐，而非泛泛的兼容列表。

五、CLI 与 UI：按 ASR 用例过滤

5.1 提案中的命令形态

为支撑"智能安装器在浏览器里一键选 Whisper"这类场景，AUDIO_SUPPORT.md 提议为 fit / recommend 增加按用例过滤的选项：

llmfit --json fit --kind audio -n 3

--json 保证输出可被脚本/前端解析，--kind audio 将候选收窄到 ASR 模型，-n 3 截取前三名。

5.2 当前 CLI 的现状与差距

对照当前 main.rs：fit、recommend 已是现成的 Commands 子命令（main.rs，Recommend 帮助文本即写明"Recommend top models for your hardware (JSON-friendly)"，并给出 llmfit recommend --runtime mlx --capability vision 的示例）。CLI 层面已支持 --capability 参数（帮助文本明确列出 vision, tool_use, audio, tts），且过滤闭包中已包含 "audio" 分支——直接按 Capability::Audio 判断（main.rs）。

这意味着"按音频能力筛模型"的入口在 CLI 中其实已经存在，真正缺的是文档所提议的 --kind audio（按 UseCase::Audio 语义过滤） 以及后端适配后的 AudioFit 评分——两者恰好是当前 Rust 侧尚未合入的部分，与文档"Rust integration changes are the next step"的定位完全一致。落地顺序上，二者是递进关系：先有 UseCase::Audio 分类（第二节），才有 --kind audio 的精确语义；先有 AudioFit（第三节），recommend 的输出才有意义。

六、落地状态对照与后续验证

下表汇总本文在仓库中核实到的"已具备 / 提案中"边界，供后续开发与审阅者快速对齐：

内容	当前仓库状态	证据
4 条 Whisper ASR 数据条目（含 _audio_* 字段、capabilities: ["audio"]）	✅ 已落地	hf_models.json、L105066、L106479、L131634
Capability::Audio / Tts 枚举与 infer() 启发式	✅ 已落地	models.rs
TTS pipeline → 宽泛 Audio capability 映射	✅ 已落地	update.rs
Whisper/TTS 条目能力约束测试	✅ 已落地	models.rs、models.rs
LlmModel 的 audio_rtf_* / audio_backends 类型化字段	⏳ 提案中（现仅存在于 JSON）	AUDIO_SUPPORT.md
UseCase::Audio 变体与 from_model 音频分支	⏳ 提案中	models.rs
AudioFit 结构与 RTF 评分公式	⏳ 提案中	AUDIO_SUPPORT.md vs fit.rs
MlxWhisperProvider / FasterWhisperProvider 探测	⏳ 提案中	AUDIO_SUPPORT.md vs providers.rs
--kind audio（UseCase 级过滤）	⏳ 提案中（--capability audio 已有）	main.rs

这一对照关系本身也是本篇最值得工程团队注意的一点：文档所说的"数据就绪、Rust 未动"与仓库现状完全吻合——凡是需要数据参与的（条目、能力枚举、推断、约束测试）都已存在，凡是需要引入新分析语义的（类型化字段、Audio 用例、AudioFit、Whisper Provider、--kind audio）都仍是待讨论的实现计划。按文档的推进顺序，建议从"UseCase::Audio + 谨慎的 from_model 判据（结合 architecture/_audio_* 字段，规避 Phi-4-multimodal 这类误判）"入手，再接 AudioFit 与 Provider 探测，最后打通 CLI 的 --kind audio。

对于下游集成方，本文传递的实战结论是：Whisper 的硬件选型完全可以像 LLM 一样被结构化推荐——以 _audio_rtf_gpu/_audio_rtf_cpu 量化延迟、_audio_vram_gb 校验显存、_audio_backends 匹配本机运行的 mlx-openai-server（Apple Silicon）或 faster-whisper-server（NVIDIA/CPU），RTF 值越低排名越靠前。这正是 llmfit 把"数百模型一条命令适配硬件"的能力从文本域平滑延伸到语音转写域的关键一步。