输入 512 维、输出 248 帧:react-native-executorch-fsmn-vad 的 forward 输入输出契约与结果解读
输入 512 维、输出 248 帧:react-native-executorch-fsmn-vad 的 forward 输入输出契约与结果解读
react-native-executorch-fsmn-vad 仓库发布了语音活动检测(Voice Activity Detection, VAD)模型 fsmn-vad 的 ExecuTorch .pte 端侧模型,可以直接在 React Native 应用中离线运行。本文带你读懂它 forward 的输入输出契约:输入是 [1000, 512] 的特征张量,输出是 [1, 1000, 248] 的结果张量——每个数字都对应明确的物理含义。
📦 这个仓库是做什么的?
仓库托管的是 FunASR 项目 上游 fsmn-vad 模型导出后的产物,专为 react-native-executorch 库准备,即"导出即运行"的端侧推理程序。目前仅发布了一个可用变体:
| 路径 | 后端 | 精度 |
|---|---|---|
| xnnpack/fsmn_vad_xnnpack_fp32.pte | xnnpack | fp32 |
模型文件约 1.7 MB(1,827,808 字节),非常轻量。根目录的 config.json 只声明了 modelName: "fsmn-vad",真正的技术细节都在各后端目录的配置里。
📋 forward 输入输出契约一览
契约完整定义在 xnnpack/config.json 的 methods.forward 字段中:
| 项目 | 形状 (shape) | 数据类型 (dtype) | 说明 |
|---|---|---|---|
| 输入 | [1000, 512] |
float32 | 1000 个音频帧,每帧 512 维特征 |
| 输出 | [1, 1000, 248] |
float32 | 批次维 1,保留 1000 帧,每帧 248 维输出 |
两边都是 float32,与文件名中的 fp32 精度一致;配置中还声明了能力标签 voice-activity-detection(见 xnnpack/config.json)。
🎵 输入端解读:[1000, 512] 是什么
注意输入是一个二维张量,没有显式批次维:
- 512 是特征维度:每一行代表一个音频帧经过前端特征提取后得到的 512 维特征向量(具体的特征类型由上游前端管线决定,模型只认这个维度约定)。
- 1000 是帧数:一次
forward调用处理 1000 个连续帧。在常见前端配置(帧移约 10 ms)下,1000 帧大约对应 10 秒左右的音频,因此这个模型适合按"秒级窗口"逐段喂入。
调用时若帧数不是 1000 或特征维不是 512,与契约不符,运行结果不可靠——这正是契约声明的意义:它把"喂什么"写得明明白白。
🧮 输出端解读:[1, 1000, 248] 是什么
输出是三维张量,逐维拆解:
- 1(批次维):显式补上了 batch 维,表示一次推理只处理一个样本。
- 1000(帧维):与输入帧数一一对应,每进 1 帧、每出 1 帧,时间轴不丢失。
- 248(状态维):每一帧对应一个 248 维的输出向量,它承载了模型对该帧的 VAD 解码状态信息,是后续聚合成"语音 / 非语音"逐帧判定的原始依据。
也就是说,标题里"输出 248"更准确的读法是:帧数保持 1000 不变,248 是每帧的输出状态维。拿到这个张量后,端上层(如 react-native-executorch 的 voice-activity-detection 任务管线)会进一步消费它,得到每个时间位置是否有人声的结论。
⚙️ 如何在 React Native 中使用
按 README.md 的说明,把这些文件接入 React Native ExecuTorch 时,将库的模型注册表中对应的 model constant 传给 voice-activity-detection 任务管线即可。仓库自身不包含业务代码——它提供的是契约 + 模型文件,上层管线负责把音频变成 [1000, 512] 输入,再把 [1, 1000, 248] 输出翻译成最终决策。
🔌 运行时兼容性与后端选择
- 运行时版本:这些文件面向 ExecuTorch v1.4.1 运行时发布,官方不提供向前兼容保证,更旧的运行时可能无法加载(见 README.md)。
- 为什么只有 xnnpack:仓库曾尝试另外两个后端,均被实测否决,原因记录在各自的 NOTES 中:
- coreml/NOTES.md:Core ML 在
CPU_AND_NE下执行报错0x1(fp16/fp32 均复现),CPU_ONLY虽可运行但相对 XNNPACK 无加速优势,故不发布。 - mlx/NOTES.md:同一台 iPhone 16、同一输入下,xnnpack fp32 以 1.5 ms 中位耗时产出有限输出,而 MLX 构建体积大 57%(2.87 MB)且执行失败(
Method 'forward' failed),故同样不发布。
- coreml/NOTES.md:Core ML 在
这个对照实验恰好证明了契约的价值:两份配置声明了完全相同的 forward I/O 契约,同一输入同时喂给两者,差异完全来自后端本身,而非输入或测试方法。
📁 关键文件索引
- 输入输出契约:xnnpack/config.json
- 端侧模型文件:xnnpack/fsmn_vad_xnnpack_fp32.pte
- 变体与兼容性说明:README.md
- 模型名声明:config.json
- 未发布后端的原因:coreml/NOTES.md、mlx/NOTES.md
一句话总结:向 forward 喂入 1000 帧 × 512 维的 float32 特征,就会拿到 1 × 1000 帧 × 248 维的 float32 结果——帧数原样保留,248 维承载逐帧 VAD 状态,交给上层管线即可落地成语音活动检测结论。