必须安装匹配cuda版本的onnxruntime-gpu而非仅onnx，否则因版本不兼容导致静默失败或ort_invalid_argument；需显式启用cudaexecutionprovider并验证nvidia-smi内存变化确认gpu实际参与推理。

onnxruntime 是实际部署环节最常接触的库，不是 onnx 本身。后者只负责读写模型结构、校验格式，真正做推理的是前者。

怎么选对 onnxruntime 安装包？

装错包是部署失败的第一高发原因。你不能同时装 onnxruntime 和 onnxruntime-gpu，它们互斥，后装的会覆盖前装的。

• 没 GPU 或只跑测试：用 pip install onnxruntime
• 有 NVIDIA GPU 且想用 CUDA 加速：必须用 pip install onnxruntime-gpu
• 别信“自动识别硬件”——onnxruntime CPU 版永远不调用 GPU，哪怕你机器上有 T4

版本匹配比安装更重要。比如 onnxruntime-gpu==1.15.1 要求 CUDA 11.8 + cuDNN 8.6；用错版本会导致 ORT_INVALID_ARGUMENT 或加载时静默失败。

torch.onnx.export 导出时最容易漏掉的参数

导出模型不是“保存一下就行”，很多线上报错（比如输入 shape 不匹配、动态 batch 失效）都源于导出配置不完整。

Claw Code Suite (Python-Only Edition)

仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...

下载

• opset_version 必须显式指定，建议 ≥13（旧版 opset 对某些算子支持不全）
• dynamic_axes 要提前声明可变维度，例如 {'input': {0: 'batch_size'}, 'output': {0: 'batch_size'}}，否则固定 shape 模型无法处理不同 batch 的请求
• do_constant_folding=True 能简化计算图，提升推理速度，但某些自定义算子可能因此出错，需实测验证
• input_names 和 output_names 建议设为明确字符串（如 'input_img'），避免后续用 session.get_inputs()[0].name 取名时依赖顺序

加载 ONNX 模型时怎么确认 GPU 真正在干活？

光装了 onnxruntime-gpu 不等于 GPU 就在跑。ONNX Runtime 默认仍走 CPU，必须手动启用执行提供者（Execution Provider）。

• 检查是否识别到 GPU：ort.get_available_providers() 应返回 ['CUDAExecutionProvider', 'CPUExecutionProvider']
• 显式启用 CUDA：session = ort.InferenceSession('model.onnx', providers=['CUDAExecutionProvider'])
• 如果报 No module named 'onnxruntime.capi._pybind_state'，大概率是 CUDA 版本不匹配，不是 Python 环境问题
• 用 nvidia-smi 观察 GPU memory usage，空载时应接近 0MB，推理时跳升才说明真在用

跨平台部署时最常被忽略的输入预处理细节

模型文件是跨平台的，但输入数据不是。同一份 .onnx 文件，在 Windows、Linux、Android 上运行结果不一致，90% 出在预处理环节。

• 图像通道顺序：PyTorch 默认 CHW，OpenCV 默认 HWC，务必统一转成模型期望的格式
• 归一化参数：训练时用的 mean/std 必须复现，不能靠 img / 255.0 一刀切；例如 ImageNet 模型要求 (img - [0.485,0.456,0.406]) / [0.229,0.224,0.225]
• 数据类型：np.float32 是硬性要求，传 float64 或 uint8 会直接报错或输出乱码
• 输入 name 必须严格匹配：用 session.get_inputs()[0].name 查，别凭经验写 'input'

真正麻烦的从来不是模型转换，而是把训练时那套隐式假设（尺寸、范围、顺序、dtype）完整、无歧义地搬到部署端。这点没对齐，GPU 再快也白搭。

Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！