TorchScript 与 ONNX：端侧模型交付格式怎么选

训练出的权重不能直接交给客户，要先固化为可部署格式。TorchScript 与 ONNX 是最常见的两种，选型的核心依据只有一个：消费方的运行环境。本文把两者讲透，再给决策方法。

TorchScript：Python 生态即插即用

TorchScript 是 PyTorch 官方的中间表示，由 torch.jit.load 直接加载，不需要训练时的模型定义代码——这正是它相对"裸权重"的本质优势：裸权重的 pickle 里存的是类引用，推理环境缺少训练时的类定义或版本不一致就会加载崩溃（历史上著名的 "'Conv' object has no attribute 'bn'" 事故即由此而来）。TorchScript 把网络结构固化下来，消费方只需要装 PyTorch。适合消费方是 Python 服务、且能接受 PyTorch 运行时依赖的场景。

ONNX：跨语言通用底座

ONNX 是开放模型交换格式，推理用 ONNX Runtime——支持 Go、Java、Android、C#、Rust 等几乎所有主流语言与平台。消费方不需要安装 PyTorch，SDK 里带一个推理运行时即可。跨技术栈交付、端侧部署（安卓平板、边缘盒子）默认选 ONNX。注意 opset 版本：导出时锁定（我们用 opset 17），并确认消费方 Runtime 版本支持该 opset。

四个常见的坑

1. softmax 固化：某些导出路径会把分类头的 softmax 一并固化，而消费方契约要求 logits（概率由系统侧计算）。二次 softmax 会让全部判别方向失真。导出后必须验证输出是否为 logits；
2. 动态尺寸陷阱：导出时开了动态 batch/尺寸，消费端引擎却按固定尺寸优化，轻则性能劣化重则直接报错。端侧交付建议固定尺寸；
3. 预处理漂移：归一化方式（ImageNet 均值方差 vs 简单 /255）、颜色通道顺序（RGB/BGR）、插值方式，任何一项与训练时不一致都会显著掉精度。预处理契约必须写进交付元数据；
4. 版本错配：导出工具链与训练工具链版本不一致，或消费端 Runtime 版本过旧不支持新算子。导出环境要锁版本，交付报告里写明。

选型三问

1. 消费方什么技术栈？Python 优先 TorchScript；多语言、跨平台、无 PyTorch 依赖诉求，选 ONNX；
2. 输出契约是什么？logits 还是概率、类别顺序如何排列、阈值多少——白纸黑字写进元数据并随包验证；
3. 有没有验证门禁？同一批图在训练基准与消费端格式上的输出必须一致，通过才交付。没有门禁的导出等于盲发。

一次训练、双格式交付

两种格式并不互斥。我们的默认交付流程是：一份训练产物同时导出 TorchScript 与 ONNX，各自走一致性验证门禁，元数据共享同一套类别顺序与预处理契约——Python 系统拿 TorchScript，跨端系统拿 ONNX，两边行为完全一致。对集成商客户，这还提供了"以后换技术栈也不用重训"的灵活性。

延伸阅读：模型交付的三道关。