纯浏览器端跑AI模型：三个实战工具带给我的血泪教训
如果你打算做端侧AI部署，尤其是涉及大模型量化或复杂算子时，下面这几个坑建议提前避开，能帮你省掉至少一周的调试时间。
一、 不要盲信第三方ONNX模型，物理常识是最好的Debug工具
在做人声分离（Stem Splitter）时，我使用了 Meta 的 HTDemucs。为了加载速度，我直接找了一个第三方的 ONNX 导出版本，配合 onnxruntime-web 使用。结果出来的音频全是电音噪音，人声几乎原封不动地留在伴奏轨里。
我当时的第一反应是精度问题，因为我把模型转成了 fp16 来减小体积。但实测发现，fp16 和 fp32 在前四位有效数字上是完全一致的，排除了精度丢失。接着我检查了采样率，确认进入模型的确实是 44.1kHz 立体声，也没问题。
为了死磕，我直接把 PyTorch 源码里的 _spec() 和 _ispec()（短时傅里叶变换及其逆变换）用 JS 重新实现了一遍，对比输入输出，结果小数点后八位全部对齐。这意味着我的代码 pipeline 是完美的。
直到我把官方 PyTorch 权重和这个 ONNX 模型放在一起对比数据，才发现了离谱的事情：
- 低频段（20–60Hz）的人声能量： 官方版本 4.8%，ONNX版本 69.3%
- 次低频段的贝斯能量： ONNX版本竟然达到了原混音能量的 145.2%
- 次低频段的其他能量： ONNX版本达到了 174.7%
从物理学角度看，分离出来的分轨能量不可能超过原始混音的总能量。145% 这个数字直接证明了模型文件本身就是损坏的，而不是我的配置问题。
解决方案： 放弃第三方转换，直接从官方预训练权重自行导出 ONNX。由于 STFT 算子在导出时非常挑剔，必须进行自定义处理。重新导出后，相关相关性回升至 0.987/0.999，工具才真正可用。
二、 ONNX Runtime 的隐形 Bug：权重绑定导致的崩溃
在实现 Speech-to-text 时，我使用了 transformers.js 跑 Whisper 模型。结果在创建 Session 时直接抛出异常：
TransposeDQWeightsForMatMulNBits Missing required scale ... model.decoder.embed_tokens.weight_transposed_DequantizeLinear这个报错非常具有误导性。MatMulNBits 是 4-bit 量化算子，但我下载的是标准的 uint8 版本，二进制文件中根本没有这个字符串。
经过排查发现，这是一个典型的上游库 Bug：ONNX Runtime 的图优化器（Graph Optimizer）在 Session 创建阶段，会自动尝试对权重绑定（Tied Embeddings）进行优化，在这个过程中它错误地生成了一个 4-bit 算子，导致随后找不到对应的 scale 参数而崩溃。
实操避坑指南：
如果你遇到类似的量化算子缺失报错，但确定自己没用量化模型，可以尝试在初始化 InferenceSession 时禁用部分优化选项。例如，通过配置 graph_optimization_level 来降低优化等级，强制它跳过那个有问题的优化步骤。
三、 浏览器内存天花板：长文件的隐形杀手
端侧AI最头疼的就是内存管理。在处理短音频时一切正常，但一旦文件长度增加，浏览器就会直接崩溃或触发 OOM（Out of Memory）。
这是因为浏览器对单个 Tab 的内存限制非常严格。在使用 onnxruntime-web 时，如果模型输入张量过大，内存峰值会瞬间飙升。
我的优化方案：
1. 分片处理（Chunking）： 不要一次性把整个音频丢进模型，必须实现滑动窗口处理，每次只处理 30 秒的片段，并处理好边缘重叠（Overlap）以避免拼接处的爆音。
2. 显式释放： 在 JS 中，确保所有的 Tensor 在使用完后立即调用 .dispose()（如果是使用 tfjs 兼容层）或将其设为 null 触发 GC。
总结下来，做浏览器端 AI 部署，最核心的能力不是写 Prompt，而是对模型算子、内存占用以及底层运行时（Runtime）行为的精准掌控。
