adam-s/car-diagnosis

来源：https://github.com/adam-s/car-diagnosis

cardiag — 通过声音诊断汽车故障

cardiag 是一个端到端的音频机器学习流水线。它从 YouTube/TikTok 抓取故障声音片段，清洗音频（将机械声从人声、音乐和噪声中分离出来），使用冻结的 CLAP 模型进行嵌入，并训练小型线性头来对故障进行分类。它通过命令行界面和实时 Web 应用提供服务。

https://github.com/user-attachments/assets/23dc48e7-5571-4890-9a6c-4552d907dd8a

这是一个概念验证，并且对其含义保持坦诚。通过手机录音诊断汽车故障确实很难，因此 cardiag 被构建为一个校准后的分诊辅助工具，而非诊断器：它告诉你是否有声音异常，大致在车的哪个位置，以及一个按可能性排序的部件短列表。当音频不足以支持判断时，它会返回“不确定”而不是胡乱猜测。

真正的贡献在于清洗+诚实训练方案，该方案可复用于其他音频数据集。 这里的适度准确率反映了从粗糙的手机音频中诊断问题的难度（我们达到了文献天花板）；同样的方法在干净的发动机音频上达到了 0.93 AUROC。请参阅 docs/DEFENSE.md。

交互式演示

两个页面可视化了流水线的前两个阶段：

• 分离发动机音频 (https://adamsohn.com/separate/) — 直观展示 clean() 级联如何从嘈杂的 YouTube 音频（人声、音乐、路噪）中提取出短促的机械声段。
• CLAP 可视化 (https://adamsohn.com/clap/) — 展示冻结的 CLAP 模型如何将这些声段转换为线性头进行分类所需的 512 维嵌入。

实际达到的效果

基于样本外的测量，泄漏安全（按视频分组的交叉验证，共 1,031 个视频组；置换检验 p = 0.0005）。这些是实诚的数字，而非排行榜。

完整详情，以及我们因样本外测试失败而降级的一个头部（敲击声），请参阅 docs/MODEL_CARD.md。

快速入门：从克隆到推理

一个全新的克隆即可立即使用。预训练的小型模型随附在 models/ 中，并附带一个合成演示片段，因此无需下载或抓取任何内容。

git clone && cd car-diagnosis
uv venv && source .venv/bin/activate
uv pip install -e ".[scrape,web,dev,viz]"   # Python 3.11
cardiag doctor                                # 预检：已安装的内容
cardiag train --fixtures                      # 离线在约 2 秒内得到一个可用模型（无需抓取，无需 2 GB 下载）
cardiag diagnose                              # 判决 + 位置 + 排序的部件
cardiag serve --model models                  # 实时 Web 应用：拖入片段 / 粘贴链接，“解释原因”

在隔离的工作树中验证整个端到端流程：bash scripts/clone_verify.sh。

工作原理

音频 ──► clean() 级联 ──► CLAP 嵌入 ──► 线性头 ──► 诊断
        (分离声段)          (冻结，512维)  (故障/区域/      (已校准，
                                         部件/敲击)       支持 UNCERTAIN)

采用单一分割路径。抓取的片段、你自己的录音（cardiag ingest，任意长度）以及推理时的上传均通过相同的 clean() 级联，该级联隔离出短促的机械声段。超过约 10 秒的声段会被拆分为窗口，以避免 CLAP 静默截断。训练与推理共享同一嵌入契约，因此不存在训练/推理偏差。

用法

cardiag diagnose clip.wav                    # 完整模型：判决 + 区域 + 排序的部件
cardiag triage clip.wav                      # 校准后的发动机 vs 运行机构
cardiag clean clip.wav                       # 隔离机械声（无需模型）
cardiag inspect clip.wav -o r.html           # 查看/听取流水线：声段、频谱图、分数
cardiag ingest ./my_audio --kind fault --cause wheel_bearing   # 带上你自己的音频
cardiag scrape youtube|tiktok                # 构建语料库（Reddit 已弃用——噪声太大）
cardiag train                                # 在你的语料库上训练

在任何推理命令后添加 --json 以获取机器可读输出。

文档

• docs/DEFENSE.md — 坦诚说明为何一种故意粗糙的方法仍能带来真实的分诊结果。
• docs/MODEL_CARD.md — 每个头部的指标、预期用途和局限性。
• docs/architecture.md — 流水线图解。
• docs/scraping-guide.md — 从零开始构建语料库的指南。

范围与坦诚

适用于社交风格/定向上传的音频（YouTube、TikTok 或用户特意录制的手机片段）。非安全关键或独立诊断工具。它是一种分诊辅助工具，缩小检查范围，并诚实反映不确定性。

模型文件是 joblib 工件：只加载你信任的文件。

许可协议：参见 LICENSE。