4、Reality AI SDK架构：SDK目录结构、核心库文件介绍、API接口概览

好，咱们进入第四章。这一章我打算带你拆开Reality AI SDK的“外壳”，看看里面到底装了些什么。说实话，我第一次拿到这个SDK的时候，第一反应也是——这么多文件夹，从哪下手？别急，我踩过的坑，你就不用再踩了。

4.1 SDK目录结构：先摸清“家底”

你解压SDK后，会看到一个类似下面的目录树。我习惯先看顶层，再逐层深入。

reality_ai_sdk/
├── docs/                  # 文档，必看
├── examples/              # 示例工程，我的最爱
├── include/               # 头文件，API全在这
├── lib/                   # 核心库文件（.a/.so）
├── tools/                 # 辅助工具链
├── scripts/               # 编译与部署脚本
└── README.md              # 快速入门指南

嗯，这里要注意：docs 目录下的 API_Reference.pdf 和 Porting_Guide.pdf 是你最先要啃的两份文档。我个人习惯先把 examples 跑通，再回头读文档，这样理解更快。

4.2 核心库文件介绍：.a 和 .so 的秘密

打开 lib/ 目录，你会看到一堆 .a 和 .so 文件。说白了，这些就是Reality AI的“发动机”。

文件名	类型	作用
libreality_ai_core.a	静态库	推理引擎核心，负责模型加载与执行
libreality_ai_utils.a	静态库	工具函数集，比如内存管理、日志打印
libreality_ai_hal.so	动态库	硬件抽象层，适配不同MCU/MPU
libreality_ai_math.a	静态库	优化后的数学运算库，比如矩阵乘、激活函数

我在项目中遇到过一个问题：链接时忘了加 -lm（数学库），结果编译通过但运行时直接崩了。你想想看，这种错误排查起来多浪费时间。所以，链接顺序一定要按文档来。

4.3 API接口概览：你只需要记住这几个

Reality AI的API设计得还算清爽。我把它分成三大类：初始化、推理、资源管理。你只要掌握这十几个函数，就能把模型跑起来。

4.3.1 初始化与配置

这部分负责“开张”。就像你开店前要打扫卫生、摆好货架一样。

// 创建推理引擎实例
reality_ai_handle_t handle = reality_ai_create();

// 加载模型文件（.rpmodel 格式）
reality_ai_status_t status = reality_ai_load_model(handle, "model.rpmodel");

// 配置运行时参数，比如内存池大小
reality_ai_config_t config = {
    .memory_pool_size = 1024 * 64,  // 64KB
    .log_level = REALITY_AI_LOG_INFO
};
reality_ai_configure(handle, &config);

为什么是 .rpmodel 格式？这是Reality AI专有的模型格式，说白了就是把训练好的模型做了量化、剪枝、加密。你从平台导出的就是这个文件。

4.3.2 推理执行

这部分是核心中的核心。模型加载好了，就该干活了。

// 准备输入数据（假设是单张图片，尺寸 32x32）
float input_data[32 * 32 * 3];
// ... 填充数据 ...

// 设置输入张量
reality_ai_tensor_t input_tensor = {
    .data = input_data,
    .shape = {1, 3, 32, 32},  // NCHW 格式
    .dtype = REALITY_AI_FLOAT32
};
reality_ai_set_input(handle, "input", &input_tensor);

// 执行推理
reality_ai_run(handle);

// 获取输出
reality_ai_tensor_t output_tensor;
reality_ai_get_output(handle, "output", &output_tensor);
// 此时 output_tensor.data 里就是推理结果

嗯，这里要注意：输入张量的形状必须和模型训练时一致。我见过有人把 NHWC 和 NCHW 搞混，结果推理结果全是错的。你想想看，这种低级错误排查起来多冤。

4.3.3 资源管理与清理

有始有终，用完要释放。嵌入式环境最忌讳内存泄漏。

// 释放模型
reality_ai_unload_model(handle);

// 销毁引擎实例
reality_ai_destroy(handle);

我曾经在一个循环里反复创建和销毁引擎，忘了释放旧实例，结果跑了几个小时就内存溢出了。从那以后，我每次写 create 都会立刻写对应的 destroy，就像括号一样成对出现。

4.4 核心逻辑框架图

下面这张图是我自己画的，帮你理清SDK的调用流程。从初始化到推理，再到清理，一目了然。

这张图里，步骤4是个循环体。实际项目中，你可能会在循环里做预处理、后处理，但核心的推理调用就这三步。我建议你把 set_input、run、get_output 封装成一个函数，这样代码更干净。

4.5 常见问题与避坑

• 链接错误： 确保链接顺序是 -lreality_ai_core -lreality_ai_math -lreality_ai_utils。我曾经因为顺序反了，报了一堆未定义引用。
• 内存不足： 默认内存池可能不够。我建议先设大一点（比如256KB），跑通后再优化。
• 模型版本不匹配： SDK 和模型文件有版本对应关系。升级SDK后，记得重新导出模型。

好了，这一章就到这里。你只要把目录结构摸清、核心库记住、API接口走一遍，后面移植具体平台时就会轻松很多。

---