[文章]HarmonyOS：Neural Network Runtime对接AI推理框架开发指导

场景介绍

Neural Network Runtime 作为 AI 推理引擎和加速芯片的桥梁，为 AI 推理引擎提供精简的 Native 接口，满足推理引擎通过加速芯片执行端到端推理的需求。

本文以图 1 展示的 Add 单算子模型为例，介绍 Neural Network Runtime 的开发流程。Add 算子包含两个输入、一个参数和一个输出，其中的 activation 参数用于指定 Add 算子中激活函数的类型。

**图 1 **Add 单算子网络示意图

环境准备

环境要求

Neural Network Runtime 部件的环境要求如下：

● 开发环境：Ubuntu 18.04 及以上。

● 接入设备：HarmonyOS 定义的标准设备，并且系统中内置的硬件加速器驱动，已通过 HDI 接口对接 Neural Network Runtime。

由于 Neural Network Runtime 通过 Native API 对外开放，需要通过 Native 开发套件编译 Neural Network Runtime 应用。

环境搭建

1. 打开 Ubuntu 编译服务器的终端。
2. 把下载好的 Native 开发套件压缩包拷贝至当前用户根目录下。
3. 执行以下命令解压 Native 开发套件的压缩包。

unzip native-linux-{版本号}.zip

解压缩后的内容如下（随版本迭代，目录下的内容可能发生变化，请以最新版本的 Native API 为准）：

native/
├── build // 交叉编译工具链
├── build-tools // 编译构建工具
├── docs
├── llvm
├── nativeapi_syscap_config.json
├── ndk_system_capability.json
├── NOTICE.txt
├── oh-uni-package.json
└── sysroot // Native API头文件和库

接口说明

这里给出 Neural Network Runtime 开发流程中通用的接口，具体请见下列表格。

结构体

模型构造相关接口

模型编译相关接口

执行推理相关接口

设备管理相关接口

开发步骤

Neural Network Runtime 的开发流程主要包含模型构造、模型编译和推理执行三个阶段。以下开发步骤以 Add 单算子模型为例，介绍调用 Neural Network Runtime 接口，开发应用的过程。

1. 创建应用样例文件。

首先，创建 Neural Network Runtime 应用样例的源文件。在项目目录下执行以下命令，创建 nnrt_example/目录，在目录下创建 nnrt_example.cpp 源文件。

mkdir ~/nnrt_example && cd ~/nnrt_example
touch nnrt_example.cpp

2. 导入 Neural Network Runtime。

在 nnrt_example.cpp 文件的开头添加以下代码，引入 Neural Network Runtime 模块。

#include <cstdint>
#include <iostream>
#include <vector>


#include "neural_network_runtime/neural_network_runtime.h"


// 常量，用于指定输入、输出数据的字节长度
const size_t DATA_LENGTH = 4 * 12;

3. 构造模型。

使用 Neural Network Runtime 接口，构造 Add 单算子样例模型。

OH_NN_ReturnCode BuildModel(OH_NNModel** pModel)
{
    // 创建模型实例，进行模型构造
    OH_NNModel* model = OH_NNModel_Construct();
    if (model == nullptr) {
        std::cout << "Create model failed." << std::endl;
        return OH_NN_MEMORY_ERROR;
    }


    // 添加Add算子的第一个输入Tensor，类型为float32，张量形状为[1, 2, 2, 3]
    int32_t inputDims[4] = {1, 2, 2, 3};
    OH_NN_Tensor input1 = {OH_NN_FLOAT32, 4, inputDims, nullptr, OH_NN_TENSOR};
    OH_NN_ReturnCode ret = OH_NNModel_AddTensor(model, &input1);
    if (ret != OH_NN_SUCCESS) {
        std::cout << "BuildModel failed, add Tensor of first input failed." << std::endl;
        return ret;
    }


    // 添加Add算子的第二个输入Tensor，类型为float32，张量形状为[1, 2, 2, 3]
    OH_NN_Tensor input2 = {OH_NN_FLOAT32, 4, inputDims, nullptr, OH_NN_TENSOR};
    ret = OH_NNModel_AddTensor(model, &input2);
    if (ret != OH_NN_SUCCESS) {
        std::cout << "BuildModel failed, add Tensor of second input failed." << std::endl;
        return ret;
    }


    // 添加Add算子的参数Tensor，该参数Tensor用于指定激活函数的类型，Tensor的数据类型为int8。
    int32_t activationDims = 1;
    int8_t activationValue = OH_NN_FUSED_NONE;
    OH_NN_Tensor activation = {OH_NN_INT8, 1, &activationDims, nullptr, OH_NN_ADD_ACTIVATIONTYPE};
    ret = OH_NNModel_AddTensor(model, &activation);
    if (ret != OH_NN_SUCCESS) {
        std::cout << "BuildModel failed, add Tensor of activation failed." << std::endl;
        return ret;
    }


    // 将激活函数类型设置为OH_NN_FUSED_NONE，表示该算子不添加激活函数。
    ret = OH_NNModel_SetTensorData(model, 2, &activationValue, sizeof(int8_t));
    if (ret != OH_NN_SUCCESS) {
        std::cout << "BuildModel failed, set value of activation failed." << std::endl;
        return ret;
    }


    // 设置Add算子的输出，类型为float32，张量形状为[1, 2, 2, 3]
    OH_NN_Tensor output = {OH_NN_FLOAT32, 4, inputDims, nullptr, OH_NN_TENSOR};
    ret = OH_NNModel_AddTensor(model, &output);
    if (ret != OH_NN_SUCCESS) {
        std::cout << "BuildModel failed, add Tensor of output failed." << std::endl;
        return ret;
    }


    // 指定Add算子的输入、参数和输出索引
    uint32_t inputIndicesValues[2] = {0, 1};
    uint32_t paramIndicesValues = 2;
    uint32_t outputIndicesValues = 3;
    OH_NN_UInt32Array paramIndices = {&paramIndicesValues, 1};
    OH_NN_UInt32Array inputIndices = {inputIndicesValues, 2};
    OH_NN_UInt32Array outputIndices = {&outputIndicesValues, 1};


    // 向模型实例添加Add算子
    ret = OH_NNModel_AddOperation(model, OH_NN_OPS_ADD, &paramIndices, &inputIndices, &outputIndices);
    if (ret != OH_NN_SUCCESS) {
        std::cout << "BuildModel failed, add operation failed." << std::endl;
        return ret;
    }


    // 设置模型实例的输入、输出索引
    ret = OH_NNModel_SpecifyInputsAndOutputs(model, &inputIndices, &outputIndices);
    if (ret != OH_NN_SUCCESS) {
        std::cout << "BuildModel failed, specify inputs and outputs failed." << std::endl;
        return ret;
    }


    // 完成模型实例的构建
    ret = OH_NNModel_Finish(model);
    if (ret != OH_NN_SUCCESS) {
        std::cout << "BuildModel failed, error happened when finishing model construction." << std::endl;
        return ret;
    }


    *pModel = model;
    return OH_NN_SUCCESS;
}

4. 查询 Neural Network Runtime 已经对接的加速芯片。

Neural Network Runtime 支持通过 HDI 接口，对接多种加速芯片。在执行模型编译前，需要查询当前设备下，Neural Network Runtime 已经对接的加速芯片。每个加速芯片对应唯一的 ID 值，在编译阶段需要通过设备 ID，指定模型编译的芯片。

void GetAvailableDevices(std::vector<size_t>& availableDevice)
{
    availableDevice.clear();


    // 获取可用的硬件ID
    const size_t* devices = nullptr;
    uint32_t deviceCount = 0;
    OH_NN_ReturnCode ret = OH_NNDevice_GetAllDevicesID(&devices, &deviceCount);
    if (ret != OH_NN_SUCCESS) {
        std::cout << "GetAllDevicesID failed, get no available device." << std::endl;
        return;
    }


    for (uint32_t i = 0; i < deviceCount; i++) {
        availableDevice.emplace_back(devices[i]);
    }
}

5. 在指定的设备上编译模型。

Neural Network Runtime 使用抽象的模型表达描述 AI 模型的拓扑结构，在加速芯片上执行前，需要通过 Neural Network Runtime 提供的编译模块，将抽象的模型表达下发至芯片驱动层，转换成可以直接推理计算的格式。

OH_NN_ReturnCode CreateCompilation(OH_NNModel* model, const std::vector<size_t>& availableDevice, OH_NNCompilation** pCompilation)
{
    // 创建编译实例，用于将模型传递至底层硬件编译
    OH_NNCompilation* compilation = OH_NNCompilation_Construct(model);
    if (compilation == nullptr) {
        std::cout << "CreateCompilation failed, error happened when creating compilation." << std::endl;
        return OH_NN_MEMORY_ERROR;
    }


    // 设置编译的硬件、缓存路径、性能模式、计算优先级、是否开启float16低精度计算等选项


    // 选择在第一个设备上编译模型
    OH_NN_ReturnCode ret = OH_NNCompilation_SetDevice(compilation, availableDevice[0]);
    if (ret != OH_NN_SUCCESS) {
        std::cout << "CreateCompilation failed, error happened when setting device." << std::endl;
        return ret;
    }


    // 将模型编译结果缓存在/data/local/tmp目录下，版本号指定为1
    ret = OH_NNCompilation_SetCache(compilation, "/data/local/tmp", 1);
    if (ret != OH_NN_SUCCESS) {
        std::cout << "CreateCompilation failed, error happened when setting cache path." << std::endl;
        return ret;
    }


    // 完成编译设置，进行模型编译
    ret = OH_NNCompilation_Build(compilation);
    if (ret != OH_NN_SUCCESS) {
        std::cout << "CreateCompilation failed, error happened when building compilation." << std::endl;
        return ret;
    }


    *pCompilation = compilation;
    return OH_NN_SUCCESS;
}

6. 创建执行器。

完成模型编译后，需要调用 Neural Network Runtime 的执行模块，创建推理执行器。执行阶段，设置模型输入、获取模型输出和触发推理计算的操作均围绕执行器完成。

OH_NNExecutor* CreateExecutor(OH_NNCompilation* compilation)
{
    // 创建执行实例
    OH_NNExecutor* executor = OH_NNExecutor_Construct(compilation);
    return executor;
}

7. 执行推理计算，并打印计算结果。

通过执行模块提供的接口，将推理计算所需要的输入数据传递给执行器，触发执行器完成一次推理计算，获取模型的推理计算结果。

OH_NN_ReturnCode Run(OH_NNExecutor* executor)
{
    // 构造示例数据
    float input1[12] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11};
    float input2[12] = {11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22};


    int32_t inputDims[4] = {1, 2, 2, 3};
    OH_NN_Tensor inputTensor1 = {OH_NN_FLOAT32, 4, inputDims, nullptr, OH_NN_TENSOR};
    OH_NN_Tensor inputTensor2 = {OH_NN_FLOAT32, 4, inputDims, nullptr, OH_NN_TENSOR};


    // 设置执行的输入


    // 设置执行的第一个输入，输入数据由input1指定
    OH_NN_ReturnCode ret = OH_NNExecutor_SetInput(executor, 0, &inputTensor1, input1, DATA_LENGTH);
    if (ret != OH_NN_SUCCESS) {
        std::cout << "Run failed, error happened when setting first input." << std::endl;
        return ret;
    }


    // 设置执行的第二个输入，输入数据由input2指定
    ret = OH_NNExecutor_SetInput(executor, 1, &inputTensor2, input2, DATA_LENGTH);
    if (ret != OH_NN_SUCCESS) {
        std::cout << "Run failed, error happened when setting second input." << std::endl;
        return ret;
    }


    // 设置输出的数据缓冲区，OH_NNExecutor_Run执行计算后，输出结果将保留在output中
    float output[12];
    ret = OH_NNExecutor_SetOutput(executor, 0, output, DATA_LENGTH);
    if (ret != OH_NN_SUCCESS) {
        std::cout << "Run failed, error happened when setting output buffer." << std::endl;
        return ret;
    }


    // 执行计算
    ret = OH_NNExecutor_Run(executor);
    if (ret != OH_NN_SUCCESS) {
        std::cout << "Run failed, error doing execution." << std::endl;
        return ret;
    }


    // 打印输出结果
    for (uint32_t i = 0; i < 12; i++) {
        std::cout << "Output index: " << i << ", value is: " << output[i] << "." << std::endl;
    }


    return OH_NN_SUCCESS;
}

8. 构建端到端模型构造-编译-执行流程。

步骤 3-步骤 7 实现了模型的模型构造、编译和执行流程，并封装成 4 个函数，便于模块化开发。以下示例代码将 4 个函数串联成完整的 Neural Network Runtime 开发流程。

int main()
{
    OH_NNModel* model = nullptr;
    OH_NNCompilation* compilation = nullptr;
    OH_NNExecutor* executor = nullptr;
    std::vector<size_t> availableDevices;


    // 模型构造阶段
    OH_NN_ReturnCode ret = BuildModel(&model);
    if (ret != OH_NN_SUCCESS) {
        std::cout << "BuildModel failed." << std::endl;
        OH_NNModel_Destroy(&model);
        return -1;
    }


    // 获取可执行的设备
    GetAvailableDevices(availableDevices);
    if (availableDevices.empty()) {
        std::cout << "No available device." << std::endl;
        OH_NNModel_Destroy(&model);
        return -1;
    }


    // 模型编译阶段
    ret = CreateCompilation(model, availableDevices, &compilation);
    if (ret != OH_NN_SUCCESS) {
        std::cout << "CreateCompilation failed." << std::endl;
        OH_NNModel_Destroy(&model);
        OH_NNCompilation_Destroy(&compilation);
        return -1;
    }


    // 创建模型的推理执行器
    executor = CreateExecutor(compilation);
    if (executor == nullptr) {
        std::cout << "CreateExecutor failed, no executor is created." << std::endl;
        OH_NNModel_Destroy(&model);
        OH_NNCompilation_Destroy(&compilation);
        return -1;
    }


    // 使用上一步创建的执行器，执行单步推理计算
    ret = Run(executor);
    if (ret != OH_NN_SUCCESS) {
        std::cout << "Run failed." << std::endl;
        OH_NNModel_Destroy(&model);
        OH_NNCompilation_Destroy(&compilation);
        OH_NNExecutor_Destroy(&executor);
        return -1;
    }


    // 释放申请的资源
    OH_NNModel_Destroy(&model);
    OH_NNCompilation_Destroy(&compilation);
    OH_NNExecutor_Destroy(&executor);


    return 0;
}

调测验证

1. 准备应用样例的编译配置文件。

新建一个 CMakeLists.txt 文件，为开发步骤中的应用样例文件 nnrt_example.cpp 添加编译配置。以下提供简单的 CMakeLists.txt 示例：

cmake_minimum_required(VERSION 3.16)
project(nnrt_example C CXX)


add_executable(nnrt_example
    ./nnrt_example.cpp
)


target_link_libraries(nnrt_example
    neural_network_runtime.z
)

2. 编译应用样例。

执行以下命令，在当前目录下新建 build/目录，在 build/目录下编译 nnrt_example.cpp，得到二进制文件 nnrt_example。

mkdir build && cd build
cmake -DCMAKE_TOOLCHAIN_FILE={交叉编译工具链的路径}/build/cmake/ohos.toolchain.cmake -DOHOS_ARCH=arm64-v8a -DOHOS_PLATFORM=OHOS -DOHOS_STL=c++_static ..
make

3. 执行以下代码，将样例推送到设备上执行。

# 将编译得到的 `nnrt_example` 推送到设备上，执行样例。
hdc_std file send ./nnrt_example /data/local/tmp/.


# 给测试用例可执行文件加上权限。
hdc_std shell "chmod +x /data/local/tmp/nnrt_example"


# 执行测试用例
hdc_std shell "/data/local/tmp/nnrt_example"

如果样例执行正常，应该得到以下输出。

Output index: 0, value is: 11.000000.
Output index: 1, value is: 13.000000.
Output index: 2, value is: 15.000000.
Output index: 3, value is: 17.000000.
Output index: 4, value is: 19.000000.
Output index: 5, value is: 21.000000.
Output index: 6, value is: 23.000000.
Output index: 7, value is: 25.000000.
Output index: 8, value is: 27.000000.
Output index: 9, value is: 29.000000.
Output index: 10, value is: 31.000000.
Output index: 11, value is: 33.000000.

4. 检查模型缓存（可选）。

如果在调测环境下，Neural Network Runtime 对接的 HDI 服务支持模型缓存功能，执行完 nnrt_example, 可以在 /data/local/tmp 目录下找到生成的缓存文件。

说明

模型的 IR 需要传递到硬件驱动层，由 HDI 服务将统一的 IR 图，编译成硬件专用的计算图，编译的过程非常耗时。Neural Network Runtime 支持计算图缓存的特性，可以将 HDI 服务编译生成的计算图，缓存到设备存储中。当下一次在同一个加速芯片上编译同一个模型时，通过指定缓存的路径，Neural Network Runtime 可以直接加载缓存文件中的计算图，减少编译消耗的时间。

检查缓存目录下的缓存文件：

ls /data/local/tmp

以下为打印结果：

# 0.nncache  cache_info.nncache

如果缓存不再使用，需要手动删除缓存，可以参考以下命令，删除缓存文件。

rm /data/local/tmp/*nncache