---

Libonnx

一个轻量级、可移植的纯 C99 ONNX 推理引擎，适用于支持硬件加速的嵌入式设备。

快速入门

将库中的 .c 和 .h 文件直接放入项目中，并与项目一起编译即可。在使用前，需要分配一个 struct onnx_context_t *，并且可以传入一个 struct resolver_t * 数组以实现硬件加速。

filename 是 ONNX 模型文件的路径。

struct onnx_context_t * ctx = onnx_context_alloc_from_file(filename, NULL, 0);

然后，可以使用 onnx_tensor_search 函数获取输入和输出张量。

struct onnx_tensor_t * input = onnx_tensor_search(ctx, "input-tensor-name");
struct onnx_tensor_t * output = onnx_tensor_search(ctx, "output-tensor-name");

设置好输入张量后，可以使用 onnx_run 函数运行推理引擎，结果会存储到输出张量中。

onnx_run(ctx);

最后，必须使用 onnx_context_free 函数释放 struct onnx_context_t *。

onnx_context_free(ctx);

编译说明

只需在根目录下输入 make，即可生成静态库以及一些用于演示和测试的二进制文件。

cd libonnx
make

要编译 mnist 示例，需要安装 SDL2 和 SDL2 GFX。在 Ubuntu 等系统上，运行以下命令来安装所需的 Simple DirectMedia Layer 库，以便运行 GUI：

    apt-get install libsdl2-dev libsdl2-gfx-dev

交叉编译示例（针对 arm64）

在根目录下运行 make CROSS_COMPILE=path/to/toolchains/aarch64-linux-gnu-，即可为指定平台编译所有库、测试和示例。

请将 CROSS_COMPILE 替换为你计划使用的工具链路径。

如何运行示例

编译完成后，可以通过以下命令运行示例：

cd libonnx/examples/hello/output
./hello

截图

• MNIST 手写数字预测

运行测试

要运行测试，例如 tests/model 文件夹中的测试，可以使用以下命令：

cd libonnx/tests/output
./tests ../model

以下是输出结果：

[mnist_8](test_data_set_0)                                                              [OKAY]
[mnist_8](test_data_set_1)                                                              [OKAY]
[mnist_8](test_data_set_2)                                                              [OKAY]
[mobilenet_v2_7](test_data_set_0)                                                       [OKAY]
[mobilenet_v2_7](test_data_set_1)                                                       [OKAY]
[mobilenet_v2_7](test_data_set_2)                                                       [OKAY]
[shufflenet_v1_9](test_data_set_0)                                                      [OKAY]
[shufflenet_v1_9](test_data_set_1)                                                      [OKAY]
[shufflenet_v1_9](test_data_set_2)                                                      [OKAY]
[squeezenet_v11_7](test_data_set_0)                                                     [OKAY]
[squeezenet_v11_7](test_data_set_1)                                                     [OKAY]
[squeezenet_v11_7](test_data_set_2)                                                     [OKAY]
[super_resolution_10](test_data_set_0)                                                  [OKAY]
[tinyyolo_v2_8](test_data_set_0)                                                        [OKAY]
[tinyyolo_v2_8](test_data_set_1)                                                        [OKAY]
[tinyyolo_v2_8](test_data_set_2)                                                        [OKAY]

请注意，在其他文件夹中运行测试可能无法成功。部分算子尚未实现，更多信息请参阅注释部分。

注释

• 本库基于 ONNX 版本 v1.17.0，并支持最新的 opset 24。支持的算子表位于 documents 目录下的 [the-supported-operator-table.md] 文件中。
• 可以查看 tools 文件夹，获取有关 ONNX 模型文件的帮助。
• 在 Linux 上，可以使用 xxd -i <filename.onnx> 将 ONNX 模型转换为 unsigned char 数组，然后使用 onnx_context_alloc 函数加载模型。示例中的 hello 和 mnist 就是这样加载模型的。

链接

• 中文讨论帖
• ONNX 官方文档
• ONNX 算子文档
• 创建 ONNX 模型的教程
• 预训练的 ONNX 模型

许可证

本库为自由软件，可在 MIT 许可证条款下重新分发或修改。详细信息请参阅 MIT License。

Libonnx 快速上手指南

Libonnx 是一个轻量级、可移植的纯 C99 ONNX 推理引擎，专为嵌入式设备设计，并支持硬件加速。

环境准备

系统要求

• 支持标准 C99 编译器的任意平台（Linux, macOS, Windows, 嵌入式系统等）
• 构建工具：make, gcc/clang

前置依赖

若需编译并运行示例程序（如 MNIST 手写数字识别），需安装 SDL2 图形库：

Ubuntu/Debian:

apt-get install libsdl2-dev libsdl2-gfx-dev

其他发行版: 请使用对应的包管理器安装 libsdl2-dev 和 libsdl2-gfx-dev。

提示：若仅需将库集成到自己的项目中用于推理，无需安装上述图形库依赖。

安装步骤

Libonnx 无需复杂的安装过程，只需克隆源码并编译即可。

1. 克隆仓库并进入目录

   git clone https://github.com/libonnx/libonnx.git
   cd libonnx
   

2. 编译库与示例 在根目录下执行 make，将生成静态库文件以及示例和测试程序的可执行文件。

   make
   

3. 交叉编译（可选） 针对嵌入式平台（如 ARM64），指定交叉编译工具链前缀：

   make CROSS_COMPILE=path/to/toolchains/aarch64-linux-gnu-
   

   请将 path/to/toolchains/aarch64-linux-gnu- 替换为你实际的工具链路径。

基本使用

Libonnx 的设计哲学是“即插即用”。你可以直接将 .c 和 .h 源文件复制到你的工程中进行编译。

1. 代码集成示例

以下是最小化的 C 语言调用流程：

#include "onnx.h"

// 1. 从文件加载 ONNX 模型并分配上下文
// filename: .onnx 模型文件路径
// resolvers: 硬件加速解析器数组（若无特殊加速需求可传 NULL）
struct onnx_context_t * ctx = onnx_context_alloc_from_file("model.onnx", NULL, 0);

if (ctx) {
    // 2. 获取输入和输出张量
    struct onnx_tensor_t * input = onnx_tensor_search(ctx, "input-tensor-name");
    struct onnx_tensor_t * output = onnx_tensor_search(ctx, "output-tensor-name");

    if (input && output) {
        // 3. 填充输入数据到 input->data ...
        
        // 4. 执行推理
        onnx_run(ctx);
        
        // 5. 从 output->data 读取结果
    }

    // 6. 释放资源
    onnx_context_free(ctx);
}

2. 运行内置示例

编译完成后，可直接运行官方提供的示例来验证环境：

运行 Hello World 示例：

cd libonnx/examples/hello/output
./hello

运行 MNIST 手写数字识别示例：

cd libonnx/examples/mnist/output
./mnist

3. 运行测试套件

验证算子支持情况，确保模型兼容性：

cd libonnx/tests/output
./tests ../model

预期输出应显示各测试用例状态为 [OKAY]。

注意：Libonnx 基于 ONNX v1.17.0 (opset 24)。部分算子可能尚未实现，详细支持的算子列表请参阅项目文档中的 the-supported-operator-table.md。