ONNX Runtime C++ 推理入门与实战
ONNX Runtime 为 C++ 提供了完整的推理 API,集成它可以在现有项目中高效运行 ONNX 模型。本文将带你从环境搭建到代码实现,完整梳理 C++ 端的推理流程。
获取库文件
在 C++ 项目中使用 ONNX Runtime,主要有两种方式:
- 使用预编译库(推荐):这是最简单的入门方式。你可以从 ONNX Runtime 官方 GitHub Releases 页面下载适用于你平台(如 Windows、Linux、macOS)的 C/C++ 预编译库。这些库通常包含了核心的推理功能。
- 从源码编译:如果你有特殊需求,比如需要支持特定的硬件(如 GPU、OpenVINO、NNAPI),或希望定制库的大小(例如为移动端进行精简),则需要从源码编译。官方 GitHub 仓库提供了详细的构建指南。例如,在 Linux 下启用 CUDA 支持的基本步骤是:
git clone --recursive https://github.com/microsoft/onnxruntime.git
cd onnxruntime
./build.sh --config RelWithDebInfo --build_shared_lib --use_cuda
API 结构概览
ONNX Runtime 的 C++ API 是对底层 C API 的现代封装,设计符合 C++ 习惯。核心接口主要包含在两个头文件中:
onnxruntime_cxx_api.h:这是 C++ 开发主要使用的头文件。它定义了Ort::命名空间下的所有 C++ 类,如Env(环境)、Session(推理会话)、MemoryInfo(内存信息)、Value(张量)等。这些类利用 RAII(资源获取即初始化)机制自动管理内存,并通过抛出异常来处理错误,让代码更简洁安全。onnxruntime_c_api.h:这是底层的 C API,提供了OrtApi结构体,包含所有以Ort开头的函数(如OrtCreateSession)。C++ API 是基于此实现的。虽然可以直接使用 C API,但通常更推荐使用更方便的 C++ 封装。
基础推理流程
在 C++ 中使用 ONNX Runtime 进行模型推理,一般遵循以下几个典型步骤:
- 包含头文件:在你的代码中包含 ONNX Runtime 的头文件。
- 创建环境和会话选项:首先,创建一个
Ort::Env对象来管理推理环境的日志和全局状态。然后,创建Ort::SessionOptions对象来配置会话,例如设置优化级别、线程数等。 - 加载模型并创建会话:使用上一步创建的环境和选项,加载模型文件(
.onnx)并创建Ort::Session对象。会话是执行推理的核心对象。 - 准备输入数据:通过
session.GetInputCount()、session.GetInputName()等方法,动态获取模型期望的输入名称、维度(shape)和数据类型。将你的数据填充到std::vector中,然后使用Ort::Value::CreateTensor()创建一个 ONNX Runtime 张量。 - 运行推理:调用
session.Run()方法,传入输入张量的名称和值,以及你想要获取的输出张量名称。函数会返回一个std::vector<Ort::Value>,包含了推理结果。 - 处理输出:从返回的
Ort::Value对象中提取数据,并进行后续处理,例如解析分类结果或显示检测框。
完整示例
下面是一个完整的示例,涵盖了从环境创建到结果输出的全过程。请注意替换其中的模型路径为你的实际文件。

