ONNX Runtime C++ API 初始化失败主因是动态库未正确链接或运行时找不到；需显式链接、配置环境变量、合理设置SessionOptions（含优化级、线程数、GPU支持）；输入输出张量须严格匹配模型签名，注意内存布局与类型；推理时避免频繁小batch调用，推荐零拷贝与预分配。
ONNX Runtime C++ API 初始化失败：环境与链接问题
直接跑不起来，八成是环境没配对或链接错了。ONNX Runtime 的 C++ 接口依赖动态库（onnxruntime.dll 或 libonnxruntime.so），不是头文件包含完就完事的。
常见错误现象：undefined reference to `Ort::Env::Env(...)`（链接缺失）、Failed to load library: ...（运行时找不到 so/dll）、ORT_NO_SUCHFILE（模型路径错或格式非 ONNX）。
- Linux/macOS 下必须显式链接
-lonnxruntime，且确保LD_LIBRARY_PATH（或DYLD_LIBRARY_PATH）包含库所在目录 - Windows 下需把
onnxruntime.dll放到可执行文件同目录，或系统 PATH 中；链接时加onnxruntime.lib（不是 dll） - CMake 中推荐用
find_package(onnxruntime REQUIRED)+target_link_libraries(... ${ONNXRUNTIME_LIBRARIES})，避免手写路径出错
加载模型和创建会话：别漏掉 Ort::SessionOptions 配置
默认构造的 Ort::SessionOptions 不启用优化、不设线程数、不支持 GPU——这会导致推理慢得离谱，甚至在某些硬件上 fallback 到 CPU 也不报错。
典型误操作：直接 Ort::Session(session_options) 加载模型，结果性能比 Python 版还差一倍。
立即学习“C++免费学习笔记（深入）”；
- 启用图优化：
session_options.SetGraphOptimizationLevel(ORT_ENABLE_ALL) - 控制线程：
session_options.SetIntraOpNumThreads(4)（CPU 场景下建议设为物理核数） - GPU 推理需额外初始化
Ort::SessionOptions并传入OrtCUDAProviderOptions，否则仍走 CPU - 模型路径必须是绝对路径或相对于当前工作目录的正确路径；相对路径出错时
Ort::Session构造会抛std::exception，务必 try-catch
输入输出张量：内存布局和类型必须严格匹配模型签名
ONNX 模型导出时固定了 input/output 的 shape、data_type 和 layout（通常是 NCHW 或 NHWC）。C++ 端手动构造 Ort::Value 时，只要有一个维度错、类型错（比如该用 ONNX_TENSOR_ELEMENT_DATA_TYPE_FLOAT 却传了 double），就会触发 InvalidArgument 错误，且提示极不友好。
调试关键点：先用 onnxruntime_test_all 或 Python 的 ort.InferenceSession(model).get_inputs() 查清模型期望的 name/shape/dtype。
- 输入数据必须是连续内存（
std::vector<float></float>而非 vector of vector），且按模型要求的 layout 排列（图像类模型多为 NCHW，别直接 memcpy cv::Mat.data） - 创建
Ort::Value用Ort::Value::CreateTensor(...)，传入的memory_info建议用Ort::MemoryInfo::CreateCpu(...)或对应 GPU info - 输出 tensor 的 shape 需预先分配足够空间；
GetTensorMutableData()返回的是裸指针，别让它被 vector 释放
推理调用与性能陷阱：同步阻塞、零拷贝与 batch 处理
session.Run(...) 是同步阻塞调用，但它的耗时不仅含计算，还含输入 copy-in、output copy-out。高频小 batch 推理时，频繁调用 Run 会让内存拷贝成为瓶颈。
容易被忽略的细节：默认情况下，ONNX Runtime 对输入输出做深拷贝；若数据已在 GPU 上，又没配好 provider，它可能先拷回 CPU 再送进 kernel。
- 启用 zero-copy 输入：用
Ort::Value::CreateTensor(..., Ort::MemType::MemTypeCPUInput)（仅限 CPU）或 GPU 对应 memory type，并确保 lifetime 覆盖整个Run过程 - batch 推理必须提前 reshape 输入 tensor（如模型输入是
[1,3,224,224]，想推 4 张图就得改第一维为 4，并确保数据内存连续排布） - 多线程并发推理需为每个线程创建独立
Ort::Session实例（Ort::Env可全局共享），否则可能触发内部锁竞争
模型输入 shape 动态变化、带 optional input、或用了 control flow op（如 Loop）时，C++ API 的 error 信息几乎不提供上下文，这时候得靠 onnx.checker.check_model() 和 onnx.shape_inference.infer_shapes() 在导出侧把模型验干净。
