树莓派部署mobilenetv3需经pytorch→torchscript→onnx→onnx runtime量化推理全流程：必须用opset_version=12导出、手动校准量化、cpu provider配置及双文件部署。
直接在树莓派上跑原始 PyTorch MobileNetV3 模型，大概率会卡在 3–5 FPS、内存爆到 1.2GB、CPU 温度直冲 80℃。这不是模型不行，而是 PyTorch 的 Python 解释器开销 + FP32 计算 + 动态图机制，在 ARM 小核上根本扛不住。真正能落地的路径只有一条：**PyTorch 训练 → TorchScript 导出 → ONNX 转换 → ONNX Runtime 量化推理**。中间跳过任意一环，性能就断崖式下跌。
为什么不能直接用 torch.load() + model.eval() 在树莓派上推理？
因为树莓派不是训练机，它不需要反向传播、autograd、模块注册表这些重型设施。直接加载 .pt 文件会：
- 启动完整 PyTorch 运行时（含 CUDA 兼容层、分布式逻辑等冗余模块），即使你没用 GPU；
- 所有张量默认为 torch.float32，在 Cortex-A76 上做浮点乘加极慢，带宽吃紧；
- 每次 forward 都触发 Python 字节码解释，无法被 ARM NEON 指令流水线充分调度；
- model.eval() 并不关闭梯度追踪元信息，内存里仍残留大量未释放的 hook 和 buffer。
ONNX 转换时必须绕开的三个坑
很多教程直接用 torch.onnx.export() 一导了事，结果在树莓派上运行时报 RuntimeError: Unsupported opset version 或输出全零——问题出在导出参数上：
- 必须显式指定 opset_version=12（树莓派上 ONNX Runtime 1.14+ 稳定支持的最高版本，更高版本会触发 shape inference 失败）；
- dynamic_axes 要精简：只对输入图像的 batch 维设为动态（{'input': {0: 'batch'}}），别给 height/width 设动态，否则 ONNX Runtime 会拒绝优化；
- 输入必须是 torch.randn(1, 3, 224, 224) 这类固定 shape 张量，不能用 torch.jit.trace() 包裹后直接导出，trace 会固化 control flow，导致 ONNX 中出现非法 Loop 节点。
ONNX Runtime 量化必须手动校准，不能靠 auto
树莓派没有 GPU/NPU，ONNX Runtime 默认用 CPU provider，而它的 INT8 量化依赖校准数据生成 scale/zero_point。自动量化（quantize_static 不传 calibration_data_reader）会用随机噪声填充校准集，导致量化误差爆炸：
- 校准帧数建议取 100–200 帧，必须来自**真实部署场景的视频片段**（比如你摄像头拍的室内光照人脸、背光侧脸、运动模糊帧）；
- 图像预处理要和推理时完全一致：BGR→RGB、归一化（/255.0）、减均值除方差顺序不能错；
- 校准用的 DataLoader 必须禁用 shuffle，且 batch_size=1（ONNX Runtime 校准器不支持多 batch 合并统计）；
- 关键配置：启用 QuantFormat.QOperator（而非 QDQ），它把量化操作融合进算子内部，减少 ARM 上额外的 int8↔fp32 转换开销。
树莓派上 ONNX Runtime 推理的最小可行配置
装完 onnxruntime 后，别用默认 session。必须手动指定执行提供者和线程数：
- 用 providers=['CPUExecutionProvider']，别碰 CoreMLExecutionProvider（树莓派不支持）或 OpenVINOExecutionProvider（需额外编译）；
- intra_op_num_threads=2（树莓派5 四核，留 2 核给 OpenCV/摄像头采集）；
- 输入 tensor 必须用 numpy.uint8（非 float32）喂入，否则 ONNX Runtime 会在内部做隐式转换，多一次 memcpy；
- 输出后立刻调用 np.ascontiguousarray()，避免后续 OpenCV 绘图时因内存不连续触发 copy。
最易被忽略的一点：ONNX 模型文件本身不包含量化参数，它们存在单独的 .onnx_data 二进制中（由 quantize_static 生成）。部署时必须把这两个文件一起拷到树莓派，缺一不可——否则 runtime 会静默回退到 FP32，你以为量化成功了，其实啥也没变。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
