• AI 应用
• 机器学习
• 模型优化

本文基于 coremltools 仓库中的模型格式规范文档 SoundAnalysisPreprocessing.rst，完整讲解 Core ML 中声音分析预处理模型（SoundAnalysisPreprocessing）的 protobuf 格式定义、Vggish 预处理的四步算法流程及其输入输出约束。读完本文，你将能理解该模型在 Core ML 规格（Model.proto）中的注册方式、15600 样本输入到[1, 96, 64]特征张量的完整转换链条，并掌握仓库中与之对应的验证器与测试代码的校验口径。

一、模型定位：一个"格式即算法"的预处理模型

SoundAnalysisPreprocessing是 Core ML 提供的"其他模型"（Other Models）家族中的一员，在 Model.rst 的模型分类清单 中与TextClassifier、WordTagger、VisionFeaturePrint等并列。它的官方定义（见 SoundAnalysisPreprocessing.proto）是：

A model which takes audio signal samples as input and outputs an array of preprocessed samples according to the specified preprocessing types

即：接收音频信号采样作为输入，按照指定的预处理类型输出一组预处理后的样本。与一般的神经网络模型不同，这个模型本身不包含可训练参数，它的"计算逻辑"完全由格式（规格）中声明的预处理类型决定——格式文档即算法说明书。

在 Core ML 的整体模型规格中，该模型通过 Model.proto 中oneof Type的字段 2003 挂载：

// CoreML provided models CoreMLModels.TextClassifier textClassifier = 2000; CoreMLModels.WordTagger wordTagger = 2001; CoreMLModels.VisionFeaturePrint visionFeaturePrint = 2002; CoreMLModels.SoundAnalysisPreprocessing soundAnalysisPreprocessing = 2003; CoreMLModels.Gazetteer gazetteer = 2004; CoreMLModels.WordEmbedding wordEmbedding = 2005; CoreMLModels.AudioFeaturePrint audioFeaturePrint = 2006;

从源码结构可以推断，它是 Core ML 框架内置（framework-provided）的模型类型之一，位于TextClassifier（2000）与AudioFeaturePrint（2006）之间，编号区间属于 CoreML 提供模型专用段（2000–2999）。

二、Vggish 预处理类型：消息定义与功能定位

SoundAnalysisPreprocessing内部通过一个oneof SoundAnalysisPreprocessingType选择具体的预处理类型。当前格式中只定义了一种类型——Vggish，字段编号为 20（见 SoundAnalysisPreprocessing.proto）：

// Vision feature print type oneof SoundAnalysisPreprocessingType { Vggish vggish = 20; }

而Vggish消息本身是空消息，没有任何参数（见 SoundAnalysisPreprocessing.rst 及对应 proto）：

message Vggish { // no specific parameter }

这说明了两个关键设计点：

1. 算法参数内置化：Vggish 预处理的所有超参数（帧长、步长、FFT 长度、mel 频带范围等）都硬编码在格式规范中，而不是作为模型参数暴露给开发者，因此空消息即可完整描述该预处理类型；
2. 可扩展性：oneof的语法为后续新增其他音频预处理类型（如其他特征提取前端）预留了格式空间。

三、核心算法流程：输入规格与四步预处理

格式文档对 Vggish 预处理给出了非常精确的规格描述，其输入输出与四步计算流程如下。

3.1 输入输出规格

• 输入：单声道（monophonic）音频采样，时长 975 毫秒，采样率 16KHz，即一个长度为15600 的一维 multiarray；
• 输出：预处理后的特征张量，形状为[1, 96, 64]，可直接馈送给 Vggish 特征提取器（Vggish feature extractor）。

参考：Vggish 特征提取器源自 Google 的 VGGish 音频嵌入模型（格式文档中引用了对应论文作为算法依据），本模型负责完成其输入端的声学特征前端（frontend）预处理，即把原始波形转换为对数 Mel 频谱图。

3.2 步骤一：重叠分帧（Framing）

将输入音频切分为相互重叠的帧：

• 每帧时长25 毫秒；
• 帧间向前跳跃（hop）10 毫秒；
• 末尾不足一帧的部分帧直接丢弃（partial frames at the end are dropped）。

在 16KHz 采样率下，可计算帧长与帧数：帧长 = 25ms × 16 samples/ms = 400 个采样点。文档中输出帧数维为 96（见验证器常量FRONTEND_PROCESSING_OUTPUT_NUM_FRAMES = 96，SoundAnalysisPreprocessingValidator.cpp），这与 975ms 信号按 10ms 步长滑动得到的帧数一致。

3.3 步骤二：周期 Hann 窗（Hann Window）

对每一帧施加周期 Hann 窗，窗长为 25 毫秒，对应 16KHz 采样率下的400 个采样点。窗函数定义如下：

w(n) = 0.5 - 0.5 * cos(2*pi*n/window_length_sample)

其中0 <= n <= window_length_samples - 1，且window_length_samples = 400。

加窗操作为逐点相乘：

windowed_frame(n) = frame(n) * w(n)

同样满足0 <= n <= window_length_samples - 1，window_length_samples = 400。

加窗的目的是抑制帧边缘的频谱泄漏（spectral leakage），是 STFT 分析的标准前置步骤。

3.4 步骤三：功率谱（Power Spectrum）

对加窗后的每帧计算短时傅里叶变换（STFT）的幅度（magnitude），其中：

• FFT 长度（FFT length）为 512。

由于帧长为 400 个采样点，FFT 长度 512 意味着在 400 个有效样本的基础上进行了补零（zero-padding）到 512 点再做变换，从而得到更高的频谱分辨率。

3.5 步骤四：Log Mel 滤波器组（Log Mel Filter Bank）

最后一步计算对数幅度 Mel 频率谱图（log magnitude mel-frequency spectrogram），参数如下：

输出频谱维度为 64（对应输出张量的第三维 64），将 512 点 FFT 的结果映射到 64 个 mel 频带上，并施加log(x + 0.01)形式的对数压缩（log_offset = 0.01用于避免对零取对数）。

至此，一帧 400 点波形转换为一个 64 维的 log-mel 特征向量；96 帧堆叠后，即得到输出张量[1, 96, 64]（1 为 batch 维度，96 为帧数，64 为 mel 频带数）。

四、输入输出校验：验证器源码的硬性约束

格式文档描述的是"期望规格"，而实际加载模型时的强制约束由仓库中的验证器实现。核心验证逻辑位于 SoundAnalysisPreprocessingValidator.cpp，其中定义了三个关键常量：

constexpr int FRONTEND_PROCESSING_INPUT_LENGTH = 15600; // 输入长度 constexpr int FRONTEND_PROCESSING_OUTPUT_NUM_FRAMES = 96; // 输出帧数维 constexpr int FRONTEND_PROCESSING_OUTPUT_NUM_BANDS = 64; // 输出频带维

validate<MLModelType_soundAnalysisPreprocessing>模板特化（第 37-112 行）依次执行以下校验，这些正是上文输入输出规格的"强制执行版本"：

1. 模型类型检查：模型必须确实包含soundanalysispreprocessing字段，否则返回INVALID_MODEL_PARAMETERS（"Model not a sound analysis preprocessing."）；
2. 输入特征检查：只允许1 个输入，且类型必须是multiarray（kMultiArrayType）；
3. 输出特征检查：只允许1 个输出，且类型必须是multiarray；
4. Vggish 输入形状：当类型为kVggish时，输入形状必须为一维且长度为 15600，否则返回UNSUPPORTED_FEATURE_TYPE_FOR_MODEL_TYPE，错误信息提示 "Incorrect input shape, should be 1-dimension, of length: 15600"；
5. 输入数据类型：必须是FLOAT32（ArrayFeatureType_ArrayDataType_FLOAT32），错误信息会打印实际类型与期望类型；
6. 输出形状：必须是三维且依次为 1 × 96 × 64，错误信息提示 "Incorrect output shape, should be 3-dimension, of size: 1x96x64"；
7. 输出数据类型：同样必须是FLOAT32；
8. 类型未设置检查：oneof未设置任何预处理类型时返回INVALID_MODEL_PARAMETERS（"Type for sound analysis preprocessing not set"）。

从验证器的逐项检查可以看出：该模型的输入输出完全被"钉死"在 Vggish 前端所要求的规格上，开发者构造模型时不能自由选择形状或数据类型。

五、测试验证：规格与实现的闭环印证

仓库中的测试用例 SoundAnalysisPreprocessingValidatorTests.cpp 的testVggishPreprocessingBasic完整走了一遍验证路径，与本文描述的规格一一对应：

• 构造输入 multiarray 形状为[15600]、输出 multiarray 形状为[1, 96, 64]的模型描述；
• 依次验证了：缺少预处理字段时失败、oneof 类型未设置时失败、输入长度改为 15599 时失败（少了 1 个样本都不行）、输入数据类型未设为 FLOAT32 时失败、输出帧数维改为 95 时失败、输出频带维改为 65 时失败、输出降为二维 [96, 64] 时失败；
• 全部约束满足后，ML_ASSERT_GOOD(result)断言校验通过。

该测试从反面印证了第四节列出的每一条约束都是强制性的：15600 样本、FLOAT32、1×96×64 输出，缺一不可。

六、生态关联：比较逻辑与可更新性检查

除验证器外，SoundAnalysisPreprocessing在仓库的其他组件中也有明确接入，可作为理解其生态位置的补充：

• 模型比较：Comparison.cpp 为该类型实现了相等性比较：仅需比对SoundAnalysisPreprocessingType_case()（即 oneof 选择的具体预处理类型）是否一致——因为Vggish为空消息，无参数可比，类型一致即视为模型相等；
• 可更新性检查：Utils.cpp 在walkModelAndPipeline的遍历逻辑中，将kSoundAnalysisPreprocessing与kNearestNeighborsClassifier、kLinkedModel、kItemSimilarityRecommender一并列为需要特殊处理的模型类型（可推断其参与了模型可更新性/兼容性检查的路径判定）；
• 模型类型分支：Model::kSoundAnalysisPreprocessing在 Comparison.cpp 第 106 行 的顶层类型分发中被支持；
• Python 绑定：仓库的coremltoolsPython 包中包含由该 proto 生成的 SoundAnalysisPreprocessing_pb2.py，说明该格式已随 protobuf 生成链进入 Python 侧模型读写工具链。

七、小结与使用要点

围绕SoundAnalysisPreprocessing模型，本文梳理出以下可直接用于实践的关键事实：

1. 格式即实现：该模型没有可训练权重，Vggish空消息 + 硬编码算法参数即构成其全部规格；
2. 输入约束：单声道、16KHz、975ms（15600 个 FLOAT32 采样点）的一维 multiarray，这是验证器的强制要求，任何长度偏差都会导致模型加载失败；
3. 输出契约：[1, 96, 64]的 FLOAT32 multiarray，其中 96 = 帧数、64 = mel 频带数；
4. 算法链条：25ms/10ms 重叠分帧 → 400 点周期 Hann 窗 → 512 点 FFT 功率谱 → 125Hz–7500Hz、64 频带、log_offset=0.01 的 Log Mel 滤波器组；
5. 仓库配套：验证器（SoundAnalysisPreprocessingValidator.cpp）与测试（SoundAnalysisPreprocessingValidatorTests.cpp）给出了规格的权威口径，构造或校验此类模型时可直接对照。

如需在 coremltools 中构建、读写或验证包含 Vggish 音频前端的模型，请以 SoundAnalysisPreprocessing.proto 与本文第三、四节的参数表为准；对于更深层的 Vggish 特征提取网络，可进一步参考格式文档中标注的 Vggish 原始论文（1609.09430）了解嵌入特征的设计背景。

• AI 应用
• 机器学习
• 模型优化