必须安装匹配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 - 别信“自动识别硬件”——
onnxruntimeCPU 版永远不调用 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 多条命令，用于安全分析和代码质量...
立即学习“Python免费学习笔记（深入）”；
-
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 再快也白搭。
