1# Neural Network Runtime对接AI推理框架开发指导
2
3## 场景介绍
4
5Neural Network Runtime作为AI推理引擎和加速芯片的桥梁，为AI推理引擎提供精简的Native接口，满足推理引擎通过加速芯片执行端到端推理的需求。
6
7本文以图1展示的`Add`单算子模型为例，介绍Neural Network Runtime的开发流程。`Add`算子包含两个输入、一个参数和一个输出，其中的`activation`参数用于指定`Add`算子中激活函数的类型。
8
9**图1** Add单算子网络示意图
10!["Add单算子网络示意图"](figures/neural_network_runtime_add_op_model.png)
11
12## 环境准备
13
14### 环境要求
15
16Neural Network Runtime部件的环境要求如下：
17
18- 开发环境：Ubuntu 18.04及以上。
19- 接入设备：系统定义的标准设备，系统中内置AI硬件驱动并已接入Neural Network Runtime。
20
21由于Neural Network Runtime通过OpenHarmony Native API对外开放，需要通过OpenHarmony的Native开发套件编译Neural Network Runtime应用。在社区的每日构建中下载对应系统版本的ohos-sdk压缩包，从压缩包中提取对应平台的Native开发套件。以Linux为例，Native开发套件的压缩包命名为`native-linux-{版本号}.zip`。
22
23### 环境搭建
24
251. 打开Ubuntu编译服务器的终端。
262. 把下载好的Native开发套件压缩包拷贝至当前用户根目录下。
273. 执行以下命令解压Native开发套件的压缩包。
28    ```shell
29    unzip native-linux-{版本号}.zip
30    ```
31
32    解压缩后的内容如下（随版本迭代，目录下的内容可能发生变化，请以最新版本的Native API为准）：
33    ```text
34    native/
35    ├── build // 交叉编译工具链
36    ├── build-tools // 编译构建工具
37    ├── docs
38    ├── llvm
39    ├── nativeapi_syscap_config.json
40    ├── ndk_system_capability.json
41    ├── NOTICE.txt
42    ├── oh-uni-package.json
43    └── sysroot // Native API头文件和库
44    ```
45## 接口说明
46
47这里给出Neural Network Runtime开发流程中通用的接口，具体请见下列表格。
48
49### 结构体
50
51| 结构体名称 | 描述 |
52| --------- | ---- |
53| typedef struct OH_NNModel OH_NNModel | Neural Network Runtime的模型句柄，用于构造模型。 |
54| typedef struct OH_NNCompilation OH_NNCompilation | Neural Network Runtime的编译器句柄，用于编译AI模型。 |
55| typedef struct OH_NNExecutor OH_NNExecutor | Neural Network Runtime的执行器句柄，用于在指定设备上执行推理计算。 |
56| typedef struct NN_QuantParam NN_QuantParam | Neural Network Runtime的量化参数句柄，用于在构造模型时指定张量的量化参数。 |
57| typedef struct NN_TensorDesc NN_TensorDesc | Neural Network Runtime的张量描述句柄，用于描述张量的各类属性，例如数据布局、数据类型、形状等。 |
58| typedef struct NN_Tensor NN_Tensor | Neural Network Runtime的张量句柄，用于设置执行器的推理输入和输出张量。 |
59
60### 模型构造接口
61
62| 接口名称 | 描述 |
63| ------- | --- |
64| OH_NNModel_Construct() | 创建OH_NNModel类型的模型实例。 |
65| OH_NN_ReturnCode OH_NNModel_AddTensorToModel(OH_NNModel *model, const NN_TensorDesc *tensorDesc) | 向模型实例中添加张量。 |
66| OH_NN_ReturnCode OH_NNModel_SetTensorData(OH_NNModel *model, uint32_t index, const void *dataBuffer, size_t length) | 设置张量的数值。 |
67| OH_NN_ReturnCode OH_NNModel_AddOperation(OH_NNModel *model, OH_NN_OperationType op, const OH_NN_UInt32Array *paramIndices, const OH_NN_UInt32Array *inputIndices, const OH_NN_UInt32Array *outputIndices) | 向模型实例中添加算子。 |
68| OH_NN_ReturnCode OH_NNModel_SpecifyInputsAndOutputs(OH_NNModel *model, const OH_NN_UInt32Array *inputIndices, const OH_NN_UInt32Array *outputIndices) | 指定模型的输入和输出张量的索引值。 |
69| OH_NN_ReturnCode OH_NNModel_Finish(OH_NNModel *model) | 完成模型构图。|
70| void OH_NNModel_Destroy(OH_NNModel **model) | 销毁模型实例。 |
71
72
73### 模型编译接口
74
75| 接口名称 | 描述 |
76| ------- | --- |
77| OH_NNCompilation *OH_NNCompilation_Construct(const OH_NNModel *model) | 基于模型实例创建OH_NNCompilation类型的编译实例。 |
78| OH_NNCompilation *OH_NNCompilation_ConstructWithOfflineModelFile(const char *modelPath) | 基于离线模型文件路径创建OH_NNCompilation类型的编译实例。 |
79| OH_NNCompilation *OH_NNCompilation_ConstructWithOfflineModelBuffer(const void *modelBuffer, size_t modelSize) | 基于离线模型文件内存创建OH_NNCompilation类型的编译实例。 |
80| OH_NNCompilation *OH_NNCompilation_ConstructForCache() | 创建一个空的编译实例，以便稍后从模型缓存中恢复。 |
81| OH_NN_ReturnCode OH_NNCompilation_ExportCacheToBuffer(OH_NNCompilation *compilation, const void *buffer, size_t length, size_t *modelSize) | 将模型缓存写入到指定内存区域。 |
82| OH_NN_ReturnCode OH_NNCompilation_ImportCacheFromBuffer(OH_NNCompilation *compilation, const void *buffer, size_t modelSize) | 从指定内存区域读取模型缓存。 |
83| OH_NN_ReturnCode OH_NNCompilation_AddExtensionConfig(OH_NNCompilation *compilation, const char *configName, const void *configValue, const size_t configValueSize) | 为自定义硬件属性添加扩展配置，具体硬件的扩展属性名称和属性值需要从硬件厂商的文档中获取。 |
84| OH_NN_ReturnCode OH_NNCompilation_SetDevice(OH_NNCompilation *compilation, size_t deviceID) | 指定模型编译和计算的硬件，可通过设备管理接口获取。 |
85| OH_NN_ReturnCode OH_NNCompilation_SetCache(OH_NNCompilation *compilation, const char *cachePath, uint32_t version) | 设置编译模型的缓存目录和版本。 |
86| OH_NN_ReturnCode OH_NNCompilation_SetPerformanceMode(OH_NNCompilation *compilation, OH_NN_PerformanceMode performanceMode) | 设置模型计算的性能模式。 |
87| OH_NN_ReturnCode OH_NNCompilation_SetPriority(OH_NNCompilation *compilation, OH_NN_Priority priority) | 设置模型计算的优先级。 |
88| OH_NN_ReturnCode OH_NNCompilation_EnableFloat16(OH_NNCompilation *compilation, bool enableFloat16) | 是否以float16的浮点数精度计算。 |
89| OH_NN_ReturnCode OH_NNCompilation_Build(OH_NNCompilation *compilation) | 执行模型编译。 |
90| void OH_NNCompilation_Destroy(OH_NNCompilation **compilation) | 销毁编译实例。 |
91
92### 张量描述接口
93
94| 接口名称 | 描述 |
95| ------- | --- |
96| NN_TensorDesc *OH_NNTensorDesc_Create() | 创建一个张量描述实例，用于后续创建张量。 |
97| OH_NN_ReturnCode OH_NNTensorDesc_SetName(NN_TensorDesc *tensorDesc, const char *name) | 设置张量描述的名称。 |
98| OH_NN_ReturnCode OH_NNTensorDesc_GetName(const NN_TensorDesc *tensorDesc, const char **name) | 获取张量描述的名称。 |
99| OH_NN_ReturnCode OH_NNTensorDesc_SetDataType(NN_TensorDesc *tensorDesc, OH_NN_DataType dataType) | 设置张量描述的数据类型。 |
100| OH_NN_ReturnCode OH_NNTensorDesc_GetDataType(const NN_TensorDesc *tensorDesc, OH_NN_DataType *dataType) | 获取张量描述的数据类型。 |
101| OH_NN_ReturnCode OH_NNTensorDesc_SetShape(NN_TensorDesc *tensorDesc, const int32_t *shape, size_t shapeLength) | 设置张量描述的形状。 |
102| OH_NN_ReturnCode OH_NNTensorDesc_GetShape(const NN_TensorDesc *tensorDesc, int32_t **shape, size_t *shapeLength) | 获取张量描述的形状。 |
103| OH_NN_ReturnCode OH_NNTensorDesc_SetFormat(NN_TensorDesc *tensorDesc, OH_NN_Format format) | 设置张量描述的数据布局。 |
104| OH_NN_ReturnCode OH_NNTensorDesc_GetFormat(const NN_TensorDesc *tensorDesc, OH_NN_Format *format) | 获取张量描述的数据布局。 |
105| OH_NN_ReturnCode OH_NNTensorDesc_GetElementCount(const NN_TensorDesc *tensorDesc, size_t *elementCount) | 获取张量描述的元素个数。 |
106| OH_NN_ReturnCode OH_NNTensorDesc_GetByteSize(const NN_TensorDesc *tensorDesc, size_t *byteSize) | 获取基于张量描述的形状和数据类型计算的数据占用字节数。 |
107| OH_NN_ReturnCode OH_NNTensorDesc_Destroy(NN_TensorDesc **tensorDesc) | 销毁张量描述实例。 |
108
109### 张量接口
110
111| 接口名称 | 描述 |
112| ------- | --- |
113| NN_Tensor* OH_NNTensor_Create(size_t deviceID, NN_TensorDesc *tensorDesc) | 从张量描述创建张量实例，会申请设备共享内存。 |
114| NN_Tensor* OH_NNTensor_CreateWithSize(size_t deviceID, NN_TensorDesc *tensorDesc, size_t size) | 按照指定内存大小和张量描述创建张量实例，会申请设备共享内存。 |
115| NN_Tensor* OH_NNTensor_CreateWithFd(size_t deviceID, NN_TensorDesc *tensorDesc, int fd, size_t size, size_t offset) | 按照指定共享内存的文件描述符和张量描述创建张量实例，从而可以复用其他张量的设备共享内存。 |
116| NN_TensorDesc* OH_NNTensor_GetTensorDesc(const NN_Tensor *tensor) | 获取张量内部的张量描述实例指针，从而可读取张量的属性，例如数据类型、形状等。 |
117| void* OH_NNTensor_GetDataBuffer(const NN_Tensor *tensor) | 获取张量数据的内存地址，可以读写张量数据。 |
118| OH_NN_ReturnCode OH_NNTensor_GetFd(const NN_Tensor *tensor, int *fd) | 获取张量数据所在共享内存的文件描述符，文件描述符fd对应了一块设备共享内存。 |
119| OH_NN_ReturnCode OH_NNTensor_GetSize(const NN_Tensor *tensor, size_t *size) | 获取张量数据所在共享内存的大小。 |
120| OH_NN_ReturnCode OH_NNTensor_GetOffset(const NN_Tensor *tensor, size_t *offset) | 获取张量数据所在共享内存上的偏移量，张量数据可使用的大小为所在共享内存的大小减去偏移量。 |
121| OH_NN_ReturnCode OH_NNTensor_Destroy(NN_Tensor **tensor) | 销毁张量实例。 |
122
123### 执行推理接口
124
125| 接口名称 | 描述 |
126| ------- | --- |
127| OH_NNExecutor *OH_NNExecutor_Construct(OH_NNCompilation *compilation) | 创建OH_NNExecutor类型的执行器实例。 |
128| OH_NN_ReturnCode OH_NNExecutor_GetOutputShape(OH_NNExecutor *executor, uint32_t outputIndex, int32_t **shape, uint32_t *shapeLength) | 获取输出张量的维度信息，用于输出张量具有动态形状的情况。 |
129| OH_NN_ReturnCode OH_NNExecutor_GetInputCount(const OH_NNExecutor *executor, size_t *inputCount) | 获取输入张量的数量。 |
130| OH_NN_ReturnCode OH_NNExecutor_GetOutputCount(const OH_NNExecutor *executor, size_t *outputCount) | 获取输出张量的数量。 |
131| NN_TensorDesc* OH_NNExecutor_CreateInputTensorDesc(const OH_NNExecutor *executor, size_t index) | 由指定索引值创建一个输入张量的描述，用于读取张量的属性或创建张量实例。 |
132| NN_TensorDesc* OH_NNExecutor_CreateOutputTensorDesc(const OH_NNExecutor *executor, size_t index) | 由指定索引值创建一个输出张量的描述，用于读取张量的属性或创建张量实例。 |
133| OH_NN_ReturnCode OH_NNExecutor_GetInputDimRange(const OH_NNExecutor *executor, size_t index, size_t **minInputDims, size_t **maxInputDims, size_t *shapeLength) |获取所有输入张量的维度范围。当输入张量具有动态形状时，不同设备可能支持不同的维度范围。 |
134| OH_NN_ReturnCode OH_NNExecutor_SetOnRunDone(OH_NNExecutor *executor, NN_OnRunDone onRunDone) | 设置异步推理结束后的回调处理函数，回调函数定义详见接口文档。 |
135| OH_NN_ReturnCode OH_NNExecutor_SetOnServiceDied(OH_NNExecutor *executor, NN_OnServiceDied onServiceDied) | 设置异步推理执行期间设备驱动服务突然死亡时的回调处理函数，回调函数定义详见接口文档。 |
136| OH_NN_ReturnCode OH_NNExecutor_RunSync(OH_NNExecutor *executor, NN_Tensor *inputTensor[], size_t inputCount, NN_Tensor *outputTensor[], size_t outputCount) | 执行同步推理。 |
137| OH_NN_ReturnCode OH_NNExecutor_RunAsync(OH_NNExecutor *executor, NN_Tensor *inputTensor[], size_t inputCount, NN_Tensor *outputTensor[], size_t outputCount, int32_t timeout, void *userData) | 执行异步推理。 |
138| void OH_NNExecutor_Destroy(OH_NNExecutor **executor) | 销毁执行器实例。 |
139
140### 设备管理接口
141
142| 接口名称 | 描述 |
143| ------- | --- |
144| OH_NN_ReturnCode OH_NNDevice_GetAllDevicesID(const size_t **allDevicesID, uint32_t *deviceCount) | 获取对接到Neural Network Runtime的所有硬件ID。 |
145| OH_NN_ReturnCode OH_NNDevice_GetName(size_t deviceID, const char **name) | 获取指定硬件的名称。 |
146| OH_NN_ReturnCode OH_NNDevice_GetType(size_t deviceID, OH_NN_DeviceType *deviceType) | 获取指定硬件的类别信息。 |
147
148
149## 开发步骤
150
151Neural Network Runtime的开发流程主要包含**模型构造**、**模型编译**和**推理执行**三个阶段。以下开发步骤以`Add`单算子模型为例，介绍调用Neural Network Runtime接口，开发应用的过程。
152
1531. 创建应用样例文件。
154
155    首先，创建Neural Network Runtime应用样例的源文件。在项目目录下执行以下命令，创建`nnrt_example/`目录，并在目录下创建 `nnrt_example.cpp` 源文件。
156
157    ```shell
158    mkdir ~/nnrt_example && cd ~/nnrt_example
159    touch nnrt_example.cpp
160    ```
161
1622. 导入Neural Network Runtime。
163
164    在 `nnrt_example.cpp` 文件的开头添加以下代码，引入Neural Network Runtime。
165
166    ```cpp
167    #include <iostream>
168    #include <cstdarg>
169    #include "hilog/log.h"
170    #include "neural_network_runtime/neural_network_runtime.h"
171    ```
172
1733. 定义日志打印、设置输入数据、数据打印等辅助函数。
174
175    ```cpp
176    #define LOG_DOMAIN 0xD002101
177    #define LOG_TAG "NNRt"
178    #define LOGD(...) OH_LOG_DEBUG(LOG_APP, __VA_ARGS__)
179    #define LOGI(...) OH_LOG_INFO(LOG_APP, __VA_ARGS__)
180    #define LOGW(...) OH_LOG_WARN(LOG_APP, __VA_ARGS__)
181    #define LOGE(...) OH_LOG_ERROR(LOG_APP, __VA_ARGS__)
182    #define LOGF(...) OH_LOG_FATAL(LOG_APP, __VA_ARGS__)
183
184    // 返回值检查宏
185    #define CHECKNEQ(realRet, expectRet, retValue, ...) \
186        do { \
187            if ((realRet) != (expectRet)) { \
188                printf(__VA_ARGS__); \
189                return (retValue); \
190            } \
191        } while (0)
192
193    #define CHECKEQ(realRet, expectRet, retValue, ...) \
194        do { \
195            if ((realRet) == (expectRet)) { \
196                printf(__VA_ARGS__); \
197                return (retValue); \
198            } \
199        } while (0)
200
201    // 设置输入数据用于推理
202    OH_NN_ReturnCode SetInputData(NN_Tensor* inputTensor[], size_t inputSize)
203    {
204        OH_NN_DataType dataType(OH_NN_FLOAT32);
205        OH_NN_ReturnCode ret{OH_NN_FAILED};
206        size_t elementCount = 0;
207        for (size_t i = 0; i < inputSize; ++i) {
208            // 获取张量的数据内存
209            auto data = OH_NNTensor_GetDataBuffer(inputTensor[i]);
210            CHECKEQ(data, nullptr, OH_NN_FAILED, "Failed to get data buffer.");
211            // 获取张量的描述
212            auto desc = OH_NNTensor_GetTensorDesc(inputTensor[i]);
213            CHECKEQ(desc, nullptr, OH_NN_FAILED, "Failed to get desc.");
214            // 获取张量的数据类型
215            ret = OH_NNTensorDesc_GetDataType(desc, &dataType);
216            CHECKNEQ(ret, OH_NN_SUCCESS, OH_NN_FAILED, "Failed to get data type.");
217            // 获取张量的元素个数
218            ret = OH_NNTensorDesc_GetElementCount(desc, &elementCount);
219            CHECKNEQ(ret, OH_NN_SUCCESS, OH_NN_FAILED, "Failed to get element count.");
220            switch(dataType) {
221                case OH_NN_FLOAT32: {
222                    float* floatValue = reinterpret_cast<float*>(data);
223                    for (size_t j = 0; j < elementCount; ++j) {
224                        floatValue[j] = static_cast<float>(j);
225                    }
226                    break;
227                }
228                case OH_NN_INT32: {
229                    int* intValue = reinterpret_cast<int*>(data);
230                    for (size_t j = 0; j < elementCount; ++j) {
231                        intValue[j] = static_cast<int>(j);
232                    }
233                    break;
234                }
235                default:
236                    return OH_NN_FAILED;
237            }
238        }
239        return OH_NN_SUCCESS;
240    }
241
242    OH_NN_ReturnCode Print(NN_Tensor* outputTensor[], size_t outputSize)
243    {
244        OH_NN_DataType dataType(OH_NN_FLOAT32);
245        OH_NN_ReturnCode ret{OH_NN_FAILED};
246        size_t elementCount = 0;
247        for (size_t i = 0; i < outputSize; ++i) {
248            auto data = OH_NNTensor_GetDataBuffer(outputTensor[i]);
249            CHECKEQ(data, nullptr, OH_NN_FAILED, "Failed to get data buffer.");
250            auto desc = OH_NNTensor_GetTensorDesc(outputTensor[i]);
251            CHECKEQ(desc, nullptr, OH_NN_FAILED, "Failed to get desc.");
252            ret = OH_NNTensorDesc_GetDataType(desc, &dataType);
253            CHECKNEQ(ret, OH_NN_SUCCESS, OH_NN_FAILED, "Failed to get data type.");
254            ret = OH_NNTensorDesc_GetElementCount(desc, &elementCount);
255            CHECKNEQ(ret, OH_NN_SUCCESS, OH_NN_FAILED, "Failed to get element count.");
256            switch(dataType) {
257                case OH_NN_FLOAT32: {
258                    float* floatValue = reinterpret_cast<float*>(data);
259                    for (size_t j = 0; j < elementCount; ++j) {
260                        std::cout << "Output index: " << j << ", value is: " << floatValue[j] << "." << std::endl;
261                    }
262                    break;
263                }
264                case OH_NN_INT32: {
265                    int* intValue = reinterpret_cast<int*>(data);
266                    for (size_t j = 0; j < elementCount; ++j) {
267                        std::cout << "Output index: " << j << ", value is: " << intValue[j] << "." << std::endl;
268                    }
269                    break;
270                }
271                default:
272                    return OH_NN_FAILED;
273            }
274        }
275
276        return OH_NN_SUCCESS;
277    }
278    ```
279
2804. 构造模型。
281
282    使用Neural Network Runtime的模型构造接口，构造`Add`单算子样例模型。
283
284    ```cpp
285    OH_NN_ReturnCode BuildModel(OH_NNModel** pmodel)
286    {
287        // 创建模型实例model，进行模型构造
288        OH_NNModel* model = OH_NNModel_Construct();
289        CHECKEQ(model, nullptr, -1, "Create model failed.");
290
291        // 添加Add算子的第一个输入张量，类型为float32，张量形状为[1, 2, 2, 3]
292        NN_TensorDesc* tensorDesc = OH_NNTensorDesc_Create();
293        CHECKEQ(tensorDesc, nullptr, -1, "Create TensorDesc failed.");
294
295        int32_t inputDims[4] = {1, 2, 2, 3};
296        returnCode = OH_NNTensorDesc_SetShape(tensorDesc, inputDims, 4);
297        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "Set TensorDesc shape failed.");
298
299        returnCode = OH_NNTensorDesc_SetDataType(tensorDesc, OH_NN_FLOAT32);
300        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "Set TensorDesc data type failed.");
301
302        returnCode = OH_NNTensorDesc_SetFormat(tensorDesc, OH_NN_FORMAT_NONE);
303        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "Set TensorDesc format failed.");
304
305        returnCode = OH_NNModel_AddTensorToModel(model, tensorDesc);
306        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "Add first TensorDesc to model failed.");
307
308        returnCode = OH_NNModel_SetTensorType(model, 0, OH_NN_TENSOR);
309        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "Set model tensor type failed.");
310
311        // 添加Add算子的第二个输入张量，类型为float32，张量形状为[1, 2, 2, 3]
312        tensorDesc = OH_NNTensorDesc_Create();
313        CHECKEQ(tensorDesc, nullptr, -1, "Create TensorDesc failed.");
314
315        returnCode = OH_NNTensorDesc_SetShape(tensorDesc, inputDims, 4);
316        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "Set TensorDesc shape failed.");
317
318        returnCode = OH_NNTensorDesc_SetDataType(tensorDesc, OH_NN_FLOAT32);
319        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "Set TensorDesc data type failed.");
320
321        returnCode = OH_NNTensorDesc_SetFormat(tensorDesc, OH_NN_FORMAT_NONE);
322        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "Set TensorDesc format failed.");
323
324        returnCode = OH_NNModel_AddTensorToModel(model, tensorDesc);
325        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "Add second TensorDesc to model failed.");
326
327        returnCode = OH_NNModel_SetTensorType(model, 1, OH_NN_TENSOR);
328        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "Set model tensor type failed.");
329
330        // 添加Add算子的参数张量，该参数张量用于指定激活函数的类型，张量的数据类型为int8。
331        tensorDesc = OH_NNTensorDesc_Create();
332        CHECKEQ(tensorDesc, nullptr, -1, "Create TensorDesc failed.");
333
334        int32_t activationDims = 1;
335        returnCode = OH_NNTensorDesc_SetShape(tensorDesc, &activationDims, 1);
336        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "Set TensorDesc shape failed.");
337
338        returnCode = OH_NNTensorDesc_SetDataType(tensorDesc, OH_NN_INT8);
339        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "Set TensorDesc data type failed.");
340
341        returnCode = OH_NNTensorDesc_SetFormat(tensorDesc, OH_NN_FORMAT_NONE);
342        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "Set TensorDesc format failed.");
343
344        returnCode = OH_NNModel_AddTensorToModel(model, tensorDesc);
345        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "Add second TensorDesc to model failed.");
346
347        returnCode = OH_NNModel_SetTensorType(model, 2, OH_NN_ADD_ACTIVATIONTYPE);
348        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "Set model tensor type failed.");
349
350        // 将激活函数类型设置为OH_NNBACKEND_FUSED_NONE，表示该算子不添加激活函数。
351        int8_t activationValue = OH_NN_FUSED_NONE;
352        returnCode = OH_NNModel_SetTensorData(model, 2, &activationValue, sizeof(int8_t));
353        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "Set model tensor data failed.");
354
355        // 设置Add算子的输出张量，类型为float32，张量形状为[1, 2, 2, 3]
356        tensorDesc = OH_NNTensorDesc_Create();
357        CHECKEQ(tensorDesc, nullptr, -1, "Create TensorDesc failed.");
358
359        returnCode = OH_NNTensorDesc_SetShape(tensorDesc, inputDims, 4);
360        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "Set TensorDesc shape failed.");
361
362        returnCode = OH_NNTensorDesc_SetDataType(tensorDesc, OH_NN_FLOAT32);
363        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "Set TensorDesc data type failed.");
364
365        returnCode = OH_NNTensorDesc_SetFormat(tensorDesc, OH_NN_FORMAT_NONE);
366        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "Set TensorDesc format failed.");
367
368        returnCode = OH_NNModel_AddTensorToModel(model, tensorDesc);
369        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "Add forth TensorDesc to model failed.");
370
371        returnCode = OH_NNModel_SetTensorType(model, 3, OH_NN_TENSOR);
372        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "Set model tensor type failed.");
373
374        // 指定Add算子的输入张量、参数张量和输出张量的索引
375        uint32_t inputIndicesValues[2] = {0, 1};
376        uint32_t paramIndicesValues = 2;
377        uint32_t outputIndicesValues = 3;
378        OH_NN_UInt32Array paramIndices = {&paramIndicesValues, 1 * 4};
379        OH_NN_UInt32Array inputIndices = {inputIndicesValues, 2 * 4};
380        OH_NN_UInt32Array outputIndices = {&outputIndicesValues, 1 * 4};
381
382        // 向模型实例添加Add算子
383        returnCode = OH_NNModel_AddOperation(model, OH_NN_OPS_ADD, &paramIndices, &inputIndices, &outputIndices);
384        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "Add operation to model failed.");
385
386        // 设置模型实例的输入张量、输出张量的索引
387        returnCode = OH_NNModel_SpecifyInputsAndOutputs(model, &inputIndices, &outputIndices);
388        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "Specify model inputs and outputs failed.");
389
390        // 完成模型实例的构建
391        returnCode = OH_NNModel_Finish(model);
392        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "Build model failed.");
393
394        // 返回模型实例
395        *pmodel = model;
396        return OH_NN_SUCCESS;
397    }
398    ```
399
4005. 查询Neural Network Runtime已经对接的AI加速芯片。
401
402    Neural Network Runtime支持通过HDI接口，对接多种AI加速芯片。在执行模型编译前，需要查询当前设备下，Neural Network Runtime已经对接的AI加速芯片。每个AI加速芯片对应唯一的ID值，在编译阶段需要通过设备ID，指定模型编译的芯片。
403    ```cpp
404    void GetAvailableDevices(std::vector<size_t>& availableDevice)
405    {
406        availableDevice.clear();
407
408        // 获取可用的硬件ID
409        const size_t* devices = nullptr;
410        uint32_t deviceCount = 0;
411        OH_NN_ReturnCode ret = OH_NNDevice_GetAllDevicesID(&devices, &deviceCount);
412        if (ret != OH_NN_SUCCESS) {
413            std::cout << "GetAllDevicesID failed, get no available device." << std::endl;
414            return;
415        }
416
417        for (uint32_t i = 0; i < deviceCount; i++) {
418            availableDevice.emplace_back(devices[i]);
419        }
420    }
421    ```
422
4236. 在指定的设备上编译模型。
424
425    Neural Network Runtime使用抽象的模型表达描述AI模型的拓扑结构。在AI加速芯片上执行前，需要通过Neural Network Runtime提供的编译模块来创建编译实例，并由编译实例将抽象的模型表达下发至芯片驱动层，转换成可以直接推理计算的格式，即模型编译。
426    ```cpp
427    OH_NN_ReturnCode CreateCompilation(OH_NNModel* model, const std::vector<size_t>& availableDevice,
428                                       OH_NNCompilation** pCompilation)
429    {
430        // 创建编译实例compilation，将构图的模型实例或MSLite传下来的模型实例传入
431        OH_NNCompilation* compilation = OH_NNCompilation_Construct(model);
432        CHECKEQ(compilation, nullptr, -1, "OH_NNCore_ConstructCompilationWithNNModel failed.");
433
434        // 设置编译的硬件、缓存路径、性能模式、计算优先级、是否开启float16低精度计算等选项
435        // 选择在第一个设备上编译模型
436        returnCode = OH_NNCompilation_SetDevice(compilation, availableDevice[0]);
437        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "OH_NNCompilation_SetDevice failed.");
438
439        // 将模型编译结果缓存在/data/local/tmp目录下，版本号指定为1
440        returnCode = OH_NNCompilation_SetCache(compilation, "/data/local/tmp", 1);
441        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "OH_NNCompilation_SetCache failed.");
442
443        // 设置硬件性能模式
444        returnCode = OH_NNCompilation_SetPerformanceMode(compilation, OH_NN_PERFORMANCE_EXTREME);
445        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "OH_NNCompilation_SetPerformanceMode failed.");
446
447        // 设置推理执行优先级
448        returnCode = OH_NNCompilation_SetPriority(compilation, OH_NN_PRIORITY_HIGH);
449        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "OH_NNCompilation_SetPriority failed.");
450
451        // 是否开启FP16计算模式
452        returnCode = OH_NNCompilation_EnableFloat16(compilation, false);
453        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "OH_NNCompilation_EnableFloat16 failed.");
454
455        // 执行模型编译
456        returnCode = OH_NNCompilation_Build(compilation);
457        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "OH_NNCompilation_Build failed.");
458
459        *pCompilation = compilation;
460        return OH_NN_SUCCESS;
461    }
462    ```
463
4647. 创建执行器。
465
466    完成模型编译后，需要调用Neural Network Runtime的执行模块，通过编译实例创建执行器。模型推理阶段中的设置模型输入、触发推理计算以及获取模型输出等操作均需要围绕执行器完成。
467    ```cpp
468    OH_NNExecutor* CreateExecutor(OH_NNCompilation* compilation)
469    {
470        // 通过编译实例compilation创建执行器executor
471        OH_NNExecutor *executor = OH_NNExecutor_Construct(compilation);
472        CHECKEQ(executor, nullptr, -1, "OH_NNExecutor_Construct failed.");
473        return executor;
474    }
475    ```
476
4778. 执行推理计算，并打印推理结果。
478
479    通过执行模块提供的接口，将推理计算所需要的输入数据传递给执行器，触发执行器完成一次推理计算，获取模型的推理结果并打印。
480    ```cpp
481    OH_NN_ReturnCode Run(OH_NNExecutor* executor, const std::vector<size_t>& availableDevice)
482    {
483        // 从executor获取输入输出信息
484        // 获取输入张量的个数
485        size_t inputCount = 0;
486        returnCode = OH_NNExecutor_GetInputCount(executor, &inputCount);
487        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "OH_NNExecutor_GetInputCount failed.");
488        std::vector<NN_TensorDesc*> inputTensorDescs;
489        NN_TensorDesc* tensorDescTmp = nullptr;
490        for (size_t i = 0; i < inputCount; ++i) {
491            // 创建输入张量的描述
492            tensorDescTmp = OH_NNExecutor_CreateInputTensorDesc(executor, i);
493            CHECKEQ(tensorDescTmp, nullptr, -1, "OH_NNExecutor_CreateInputTensorDesc failed.");
494            inputTensorDescs.emplace_back(tensorDescTmp);
495        }
496        // 获取输出张量的个数
497        size_t outputCount = 0;
498        returnCode = OH_NNExecutor_GetOutputCount(executor, &outputCount);
499        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "OH_NNExecutor_GetOutputCount failed.");
500        std::vector<NN_TensorDesc*> outputTensorDescs;
501        for (size_t i = 0; i < outputCount; ++i) {
502            // 创建输出张量的描述
503            tensorDescTmp = OH_NNExecutor_CreateOutputTensorDesc(executor, i);
504            CHECKEQ(tensorDescTmp, nullptr, -1, "OH_NNExecutor_CreateOutputTensorDesc failed.");
505            outputTensorDescs.emplace_back(tensorDescTmp);
506        }
507
508        // 创建输入和输出张量
509        NN_Tensor* inputTensors[inputCount];
510        NN_Tensor* tensor = nullptr;
511        for (size_t i = 0; i < inputCount; ++i) {
512            tensor = nullptr;
513            tensor = OH_NNTensor_Create(availableDevice[0], inputTensorDescs[i]);
514            CHECKEQ(tensor, nullptr, -1, "OH_NNTensor_Create failed.");
515            inputTensors[i] = tensor;
516        }
517        NN_Tensor* outputTensors[outputCount];
518        for (size_t i = 0; i < outputCount; ++i) {
519            tensor = nullptr;
520            tensor = OH_NNTensor_Create(availableDevice[0], outputTensorDescs[i]);
521            CHECKEQ(tensor, nullptr, -1, "OH_NNTensor_Create failed.");
522            outputTensors[i] = tensor;
523        }
524
525        // 设置输入张量的数据
526        returnCode = SetInputData(inputTensors, inputCount);
527        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "SetInputData failed.");
528
529        // 执行推理
530        returnCode = OH_NNExecutor_RunSync(executor, inputTensors, inputCount, outputTensors, outputCount);
531        CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "OH_NNExecutor_RunSync failed.");
532
533        // 打印输出张量的数据
534        Print(outputTensors, outputCount);
535
536        // 清理输入和输出张量以及张量描述
537        for (size_t i = 0; i < inputCount; ++i) {
538            returnCode = OH_NNTensor_Destroy(&inputTensors[i]);
539            CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "OH_NNTensor_Destroy failed.");
540            returnCode = OH_NNTensorDesc_Destroy(&inputTensorDescs[i]);
541            CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "OH_NNTensorDesc_Destroy failed.");
542        }
543        for (size_t i = 0; i < outputCount; ++i) {
544            returnCode = OH_NNTensor_Destroy(&outputTensors[i]);
545            CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "OH_NNTensor_Destroy failed.");
546            returnCode = OH_NNTensorDesc_Destroy(&outputTensorDescs[i]);
547            CHECKNEQ(returnCode, OH_NN_SUCCESS, -1, "OH_NNTensorDesc_Destroy failed.");
548        }
549
550        return OH_NN_SUCCESS;
551    }
552    ```
553
5549. 构建端到端模型构造-编译-执行流程。
555
556    步骤4-步骤8实现了模型的模型构造、编译和执行流程，并封装成多个函数，便于模块化开发。以下示例代码将串联这些函数， 形成一个完整的Neural Network Runtime使用流程。
557    ```cpp
558    int main()
559    {
560        OH_NNModel* model = nullptr;
561        OH_NNCompilation* compilation = nullptr;
562        OH_NNExecutor* executor = nullptr;
563        std::vector<size_t> availableDevices;
564
565        // 模型构造
566        OH_NNModel* model = nullptr;
567        OH_NN_ReturnCode ret = BuildModel(&model);
568        if (ret != OH_NN_SUCCESS) {
569            std::cout << "BuildModel failed." << std::endl;
570            OH_NNModel_Destroy(&model);
571            return -1;
572        }
573
574        // 获取可执行的设备
575        GetAvailableDevices(availableDevices);
576        if (availableDevices.empty()) {
577            std::cout << "No available device." << std::endl;
578            OH_NNModel_Destroy(&model);
579            return -1;
580        }
581
582        // 模型编译
583        ret = CreateCompilation(model, availableDevices, &compilation);
584        if (ret != OH_NN_SUCCESS) {
585            std::cout << "CreateCompilation failed." << std::endl;
586            OH_NNModel_Destroy(&model);
587            OH_NNCompilation_Destroy(&compilation);
588            return -1;
589        }
590
591        // 销毁模型实例
592        OH_NNModel_Destroy(&model);
593
594        // 创建模型的推理执行器
595        executor = CreateExecutor(compilation);
596        if (executor == nullptr) {
597            std::cout << "CreateExecutor failed, no executor is created." << std::endl;
598            OH_NNCompilation_Destroy(&compilation);
599            return -1;
600        }
601
602        // 销毁编译实例
603        OH_NNCompilation_Destroy(&compilation);
604
605        // 使用上一步创建的执行器，执行推理计算
606        ret = Run(executor, availableDevices);
607        if (ret != OH_NN_SUCCESS) {
608            std::cout << "Run failed." << std::endl;
609            OH_NNExecutor_Destroy(&executor);
610            return -1;
611        }
612
613        // 销毁执行器实例
614        OH_NNExecutor_Destroy(&executor);
615
616        return 0;
617    }
618    ```
619
620## 调测验证
621
6221. 准备应用样例的编译配置文件。
623
624    新建一个 `CMakeLists.txt` 文件，为开发步骤中的应用样例文件 `nnrt_example.cpp` 添加编译配置。以下提供简单的 `CMakeLists.txt` 示例：
625    ```text
626    cmake_minimum_required(VERSION 3.16)
627    project(nnrt_example C CXX)
628
629    add_executable(nnrt_example
630        ./nnrt_example.cpp
631    )
632
633    target_link_libraries(nnrt_example
634        neural_network_runtime
635        neural_network_core
636    )
637    ```
638
6392. 编译应用样例。
640
641    执行以下命令，在当前目录下新建build/目录，在build/目录下编译 `nnrt_example.cpp`，得到二进制文件 `nnrt_example`。
642    ```shell
643    mkdir build && cd build
644    cmake -DCMAKE_TOOLCHAIN_FILE={交叉编译工具链的路径}/build/cmake/ohos.toolchain.cmake -DOHOS_ARCH=arm64-v8a -DOHOS_PLATFORM=OHOS -DOHOS_STL=c++_static ..
645    make
646    ```
647
6483. 执行以下代码，将样例推送到设备上执行。
649    ```shell
650    # 将编译得到的 `nnrt_example` 推送到设备上，执行样例。
651    hdc_std file send ./nnrt_example /data/local/tmp/.
652
653    # 给测试用例可执行文件加上权限。
654    hdc_std shell "chmod +x /data/local/tmp/nnrt_example"
655
656    # 执行测试用例
657    hdc_std shell "/data/local/tmp/nnrt_example"
658    ```
659
660    如果样例执行正常，应该得到以下输出。
661    ```text
662    Output index: 0, value is: 0.000000.
663    Output index: 1, value is: 2.000000.
664    Output index: 2, value is: 4.000000.
665    Output index: 3, value is: 6.000000.
666    Output index: 4, value is: 8.000000.
667    Output index: 5, value is: 10.000000.
668    Output index: 6, value is: 12.000000.
669    Output index: 7, value is: 14.000000.
670    Output index: 8, value is: 16.000000.
671    Output index: 9, value is: 18.000000.
672    Output index: 10, value is: 20.000000.
673    Output index: 11, value is: 22.000000.
674    ```
675
6764. 检查模型缓存（可选）。
677
678    如果在调测环境下，Neural Network Runtime对接的HDI服务支持模型缓存功能，执行完 `nnrt_example`, 可以在 `/data/local/tmp` 目录下找到生成的缓存文件。
679
680    > **说明：**
681    >
682    > 模型的IR需要传递到硬件驱动层，由HDI服务将统一的IR图，编译成硬件专用的计算图，编译的过程非常耗时。Neural Network Runtime支持计算图缓存的特性，可以将HDI服务编译生成的计算图，缓存到设备存储中。当下一次在同一个加速芯片上编译同一个模型时，通过指定缓存的路径，Neural Network Runtime可以直接加载缓存文件中的计算图，减少编译消耗的时间。
683
684    检查缓存目录下的缓存文件：
685    ```shell
686    ls /data/local/tmp
687    ```
688
689    以下为打印结果：
690    ```text
691    # 0.nncache 1.nncache 2.nncache cache_info.nncache
692    ```
693
694    如果缓存不再使用，需要手动删除缓存，可以参考以下命令，删除缓存文件。
695    ```shell
696    rm /data/local/tmp/*nncache
697    ```