Tricoder/doc/平台设计/算法链分层设计.md

算法链分层设计

版本号：v0.1.0 最后更新：2026-04-04

1. 目的

本文档用于定义本项目中算法链的组织方式、分层原则、分类维度和第一版链模板目录。

本文件的目标不是描述单个算法实现细节，而是建立一套可供 AI分析员调用、组合、评估和迭代的算法链体系。

2. 核心原则

2.1 算法链是一等对象

算法链不能被视为临时拼接的内部实现细节。

在本项目中，算法链应被视为正式的实验方法单元，具备：

• 明确目的
• 明确输入输出
• 明确适用条件
• 明确可调参数
• 明确证据产出
• 明确评分方式
• 明确失败模式

2.2 算法链必须分层

不同分析阶段要解决的问题不同，因此不能用一条统一 pipeline 覆盖全部分析任务。

系统必须允许：

• 不同阶段使用不同算法
• 不同信号类型使用不同链模板
• 不同任务目标使用不同验证路径

2.3 算法链必须服务于 AI分析员

算法链体系的设计目标不是让人手动操作更方便，而是让 AI分析员能够：

• 识别有哪些可用工具
• 理解这些工具适合什么场景
• 在不同链之间切换
• 调整参数并比较结果
• 根据失败原因重新规划实验

3. 三个分类维度

算法链体系建议按三个维度组织：

1. 阶段
2. 信号画像
3. 分析目标

4. 按阶段分层

4.1 预处理阶段

目的：

• 统一输入质量
• 去除明显干扰
• 为后续分析建立稳定输入

典型模块：

• audio_normalize
• mono_convert
• resample_16k
• denoise_basic
• bandpass_filter

4.2 探测阶段

目的：

• 判断输入中是否存在值得进一步分析的结构
• 对信号进行快速初判

典型模块：

• energy_probe
• spectral_probe
• onset_probe
• periodicity_probe
• harmonicity_probe

4.3 分段阶段

目的：

• 将连续音频切分为可分析的事件或片段
• 为局部验证和重复模式分析提供单位

典型模块：

• segment_energy_based
• segment_vad_based
• segment_onset_based
• segment_repeat_based

4.4 特征提取阶段

目的：

• 生成更稳定、更可比较的结构表征

典型模块：

• spectrogram_extract
• mfcc_extract
• cepstrum_extract
• embedding_extract
• temporal_stats_extract

4.5 假设验证阶段

目的：

• 对特定模式假设进行针对性验证
• 不是泛泛分析，而是回答明确问题

典型模块：

• autocorrelation_period_check
• cepstrum_period_check
• f0_tracking
• harmonicity_check
• transient_density_check
• source_separation_basic
• template_repeat_match

4.6 归因与识别阶段

目的：

• 在结构证据基础上进行候选解释和标签归因

典型模块：

• baseline_sound_classifier
• alt_sound_classifier
• similarity_search
• anomaly_distance_check

4.7 解释与决策阶段

目的：

• 汇总证据
• 形成结论
• 决定下一步

说明：

该阶段通常由 AI分析员主导，不作为普通信号处理模块实现。

5. 按信号画像分类

第一版建议先定义以下信号画像，用于帮助 AI分析员选择链模板。

5.1 连续稳态信号

特点：

• 持续时间较长
• 频谱相对稳定
• 可能存在稳定窄带成分或谐波结构

典型例子：

• 空调声
• 电机稳态声
• 风扇声
• 蜂鸣器持续音

5.2 瞬态事件信号

特点：

• 短时爆发
• onset 明显
• 时域包络变化快

典型例子：

• 敲击
• 关门
• 点击
• 瞬时碰撞

5.3 周期重复信号

特点：

• 事件或音型重复出现
• 重复间隔可能稳定或近似稳定

典型例子：

• 报警器
• 机械节拍
• 周期提示音

5.4 多事件组合信号

特点：

• 由多个相似或不同事件组成
• 需要做局部分段和聚类

典型例子：

• 脚步
• 连续鸟叫
• 机械异响序列

5.5 混合声源信号

特点：

• 存在多个重叠声源
• 背景噪声或其他主体干扰明显

典型例子：

• 人声背景中的设备声
• 室外环境中的目标提示音

5.6 未知或异常信号

特点：

• 不适合直接分类
• 更适合先做结构分析和异常距离分析

典型例子：

• 未知设备声
• 与已知样本差异显著的片段

6. 按分析目标分类

AI分析员在不同目标下应选择不同链模板。

6.1 模式发现

目的：

• 先回答“这里面有没有值得注意的结构”

6.2 周期验证

目的：

• 验证是否存在周期性、重复间隔和重复模板

6.3 谐波结构验证

目的：

• 验证是否存在明显主频、谐波和稳态音调结构

6.4 事件结构分析

目的：

• 分析事件边界、事件密度和事件序列模式

6.5 声源分离与重分析

目的：

• 在复杂输入中剥离可疑成分后重新判断

6.6 候选归因

目的：

• 形成“更像什么、不像什么”的解释结果

6.7 异常判断

目的：

• 解释为什么当前样本不像既有类别或已知模式

7. 第一版链模板目录

第一版建议至少建设以下链模板。

7.1 通用探针链

用途：

• 所有输入的默认第一步
• 快速建立初始证据

模板：

audio_normalize
-> mono_convert
-> resample_16k
-> energy_probe
-> spectral_probe
-> onset_probe
-> periodicity_probe

主要产出：

• 能量分布
• 频谱统计
• onset 密度
• 周期性候选指标

7.2 周期模式验证链

用途：

• 验证信号中是否存在稳定重复结构

模板：

segment_repeat_based
-> autocorrelation_period_check
-> cepstrum_period_check
-> repeat_interval_estimate

主要产出：

• 重复间隔估计
• 周期稳定度
• 重复模式置信度

7.3 谐波结构验证链

用途：

• 验证稳态窄带和谐波结构

模板：

spectrogram_extract
-> f0_tracking
-> harmonicity_check
-> tonal_stability_check

主要产出：

• 基频轨迹
• 谐波比
• 音调稳定性

7.4 瞬态事件分析链

用途：

• 分析短促事件和冲击型结构

模板：

segment_onset_based
-> transient_density_check
-> event_cluster
-> template_repeat_match

主要产出：

• 事件数
• 事件密度
• 重复事件模板

7.5 混合声源分析链

用途：

• 处理分类失败或明显混合输入

模板：

denoise_basic
-> source_separation_basic
-> embedding_extract
-> reclassify_with_alt_window

主要产出：

• 声源分离结果
• 分离后候选标签
• 混合程度估计

7.6 异常判断链

用途：

• 当常规分类无法给出稳定结果时，解释异常程度

模板：

embedding_extract
-> anomaly_distance_check
-> similarity_search

主要产出：

• 与已知样本距离
• 最近邻样本
• 异常分数

8. 算法链的元数据要求

为了支持 AI分析员调度，每条链或每个模块至少应暴露以下元数据：

• 标识符
• 名称
• 所属阶段
• 适用信号画像
• 适用目标
• 输入格式
• 输出格式
• 参数说明
• 主要证据产出类型
• 常见失败模式
• 成本估计

建议结构如下：

type ModuleSpec = {
  id: string
  stage: string
  signalProfiles: string[]
  goals: string[]
  inputFormat: string
  outputFormat: string
  params: Record<string, unknown>
  evidenceKinds: string[]
  failureModes: string[]
  cost: {
    cpu?: number
    latency?: number
    memory?: number
  }
}

9. 参数管理原则

AI 并不应该对所有参数无限制搜索。

第一版建议把参数分为三类：

9.1 固定参数

• 由系统或模块作者固定
• 第一版不开放给 AI 调整

9.2 可调参数

• 允许 AI 在已定义范围内调整
• 应有默认值、上下界和推荐步长

9.3 高风险参数

• 过度变化可能导致结果失真或成本失控
• 需要更严格的策略或更高权限才能调整

10. 评分与失败归因要求

每条链执行完成后，不能只输出结果，还应输出：

• Evidence
• ScoreCard
• failureReasons

示例失败原因：

• no_clear_event_boundary
• weak_periodicity_signal
• unstable_f0_track
• classifier_confidence_collapsed
• separation_not_improved
• unknown_pattern_out_of_catalog

AI分析员后续的调参与换链决策，应建立在这些结构化结果上。

11. 第一版建设优先级

第一版不应追求链模板过多，而应优先保证每类代表链可跑通。

建议优先顺序：

1. 通用探针链
2. 周期模式验证链
3. 谐波结构验证链
4. 瞬态事件分析链
5. 异常判断链
6. 混合声源分析链

12. 结论

本项目的算法链体系不是普通的数据处理流水线，而是 AI分析员可调用的实验方法库。

算法链必须：

• 按阶段分层
• 按信号画像分类
• 按分析目标分类
• 暴露足够元数据
• 支持评分和失败归因

只有在这个前提下，AI 才能真正替代专业使用者完成“选择、验证、分析、评估、结论”这整套流程。