北京
开源音频分离模型HT-Demucs FT有个尴尬现状：iOS跑不了，Android跑不了，浏览器也跑不了。PyTorch Mobile装完2GB还随时崩溃，MLX绑定Apple Silicon，而看起来最靠谱的ONNX路线——GitHub上四个相关issue挂了三年，没人解决。
我搞定了。这是首个能用的HT-Demucs FT ONNX导出版本，基于onnxruntime运行，CPU上比PyTorch快1.31倍，数值精度与原版完全一致（鼓点最大绝对误差0.000163，人声0.000008）。四个子模型已上传Hugging Face：StemSplitio/htdemucs-ft-onnx。
这篇写四个让之前所有尝试都失败的工程障碍，以及怎么逐一攻破。
为什么HT-Demucs默认导不出ONNX？
模型用了四个PyTorch特性，ONNX导出器全都不认：
1. STFT输出complex64复数张量
2. model.segment里用fractions.Fraction做算术
3. cross-transformer里嵌了random.randrange
4. 调用C++融合算子aten::_native_multi_head_attention
按顺序踩坑，每修一个才能看到下一个报错。
障碍一：complex64 STFT输出
HT-Demucs第一层是torch.stft，return_complex=True返回complex64。ONNX的STFT算子（opset 17+）不支持复数输出，后续所有切片转置全崩。
解法：用Conv1d配合sin/cos核函数，输出拆成两个实数通道。手写STFT核函数，hann窗归一化，角度计算用双精度保证精度，最后转单精度。实测往返误差5×10⁻⁶，可忽略。
障碍二：fractions.Fraction算术
model.segment方法里用Fraction处理音频分段边界。ONNX不支持Python标准库的分数运算，导出时直接抛异常。
解法：把Fraction换成浮点除法，配合int()截断。验证分段起点终点与原版差不超过1个采样点，对4096点FFT、1024点hop的设定无影响。
障碍三：random.randrange随机数
cross-transformer训练时用了随机掩码，推理代码没清干净，残留random.randrange。ONNX对Python随机库零支持。
解法：定位到transformer.py第847行，把randrange换成固定掩码模式。确认该随机性仅用于训练增广，推理时固定值不影响输出质量。
障碍四：aten::_native_multi_head_attention融合算子
PyTorch 2.4把这个attention实现换成C++融合版本，ONNX exporter不认识。torch.onnx.dynamo_export和torch.onnx.export全挂。
解法：用torch.nn.MultiheadAttention的原始Python实现替换，或者强制分解为Q/K/V线性投影+scaled dot-product+softmax的组合。损失约15%推理速度，但换来可移植性，后续ONNX Runtime的图优化能补回大部分。
验证：怎么确认没导坏
不能信目视检查，必须数值验证：
1. 同一首测试曲，PyTorch原版和ONNX版各跑一遍
2. 提取drums/vocals/bass/other四轨
3. 计算每轨最大绝对差、均方根误差、频谱相关性
4. 四轨全部通过4位小数一致性检查才发布
当前版本drums最大差0.000163，vocals仅0.000008，人耳不可辨。
纯推理环境：零PyTorch依赖
导出后的模型用numpy+onnxruntime即可推理，运行时不需要PyTorch。这对移动端部署是关键——2GB依赖砍到几十MB。
安装：pip install "torch>=2.4,<2.5" "torchaudio>=2.4,<2.5" demucs onnx onnxruntime numpy soundfile
无需GPU。已在Apple M4 Pro和Linux x86_64验证。
模型地址：Hugging Face搜索StemSplitio/htdemucs-ft-onnx。四个子模型对应不同训练配置，按需下载。
特别声明：以上内容(如有图片或视频亦包括在内)为自媒体平台“网易号”用户上传并发布，本平台仅提供信息存储服务。
Notice: The content above (including the pictures and videos if any) is uploaded and posted by a user of NetEase Hao, which is a social media platform and only provides information storage services.
