1 /** 2 * Copyright 2021 Huawei Technologies Co., Ltd 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 /** 18 * @addtogroup MindSpore 19 * @{ 20 * 21 * @brief Provides APIs related to MindSpore Lite model inference. 22 * 23 * @Syscap SystemCapability.Ai.MindSpore 24 * @since 9 25 */ 26 27 /** 28 * @file model.h 29 * 30 * @brief Provides model-related APIs for model creation and inference. 31 * 32 * @since 9 33 */ 34 35 #ifndef MINDSPORE_INCLUDE_C_API_MODEL_C_H 36 #define MINDSPORE_INCLUDE_C_API_MODEL_C_H 37 38 #include "mindspore/tensor.h" 39 #include "mindspore/context.h" 40 #include "mindspore/status.h" 41 42 #ifdef __cplusplus 43 extern "C" 44 { 45 #endif 46 /** 47 * @brief Defines the pointer to a model object. 48 * 49 * @since 9 50 */ 51 typedef void *OH_AI_ModelHandle; 52 53 /** 54 * @brief Defines the tensor array structure, which is used to store the tensor array pointer and tensor array length. 55 * 56 * @since 9 57 */ 58 typedef struct OH_AI_TensorHandleArray 59 { 60 /** Tensor array length */ 61 size_t handle_num; 62 /** Tensor array pointer */ 63 OH_AI_TensorHandle *handle_list; 64 } OH_AI_TensorHandleArray; 65 66 /** 67 * @brief Defines dimension information. The maximum dimension is set by {@link MS_MAX_SHAPE_NUM}. 68 * 69 * @since 9 70 */ 71 #define OH_AI_MAX_SHAPE_NUM 32 72 typedef struct OH_AI_ShapeInfo 73 { 74 /** Dimension array length */ 75 size_t shape_num; 76 /** Dimension array */ 77 int64_t shape[OH_AI_MAX_SHAPE_NUM]; 78 } OH_AI_ShapeInfo; 79 80 /** 81 * @brief Defines the operator information passed in a callback. 82 * 83 * @since 9 84 */ 85 typedef struct OH_AI_CallBackParam 86 { 87 /** Operator name */ 88 char *node_name; 89 /** Operator type */ 90 char *node_type; 91 } OH_AI_CallBackParam; 92 93 /** 94 * @brief Defines the pointer to a callback. 95 * 96 * This pointer is used to set the two callback functions in {@link OH_AI_ModelPredict}. 97 * Each callback function must contain three parameters, where **inputs** and **outputs** indicate the input and output tensors of the operator, and **kernel_Info** indicates information about the current operator. 98 * You can use the callback functions to monitor the operator execution status, for example, operator execution time and the operator correctness. 99 * 100 * @since 9 101 */ 102 typedef bool (*OH_AI_KernelCallBack)(const OH_AI_TensorHandleArray inputs, const OH_AI_TensorHandleArray outputs, 103 const OH_AI_CallBackParam kernel_Info); 104 105 /** 106 * \brief Creates a model object. 107 * 108 * \return Pointer to the model object. 109 * @since 9 110 */ 111 OH_AI_API OH_AI_ModelHandle OH_AI_ModelCreate(); 112 113 /** 114 * \brief Destroys a model object. 115 * 116 * \param model Pointer to the model object. 117 * @since 9 118 */ 119 OH_AI_API void OH_AI_ModelDestroy(OH_AI_ModelHandle *model); 120 121 /** 122 * \brief Loads and builds a MindSpore model from the memory buffer. 123 * 124 * Note that the same {@Link OH_AI_ContextHandle} object can only be passed to {@Link OH_AI_ModelBuild} or {@Link OH_AI_ModelBuildFromFile} once. 125 * If you call this function multiple times, make sure that you create multiple {@Link OH_AI_ContextHandle} objects accordingly. 126 * 127 * \param model Pointer to the model object. 128 * \param model_data Address of the loaded model data in the memory. 129 * \param data_size Length of the model data. 130 * \param model_type Type of the model file. For details, see {@link OH_AI_ModelType}. 131 * \param model_context Context for model running. For details, see {@link OH_AI_ContextHandle}. 132 * \return Status code enumerated by {@link OH_AI_Status}. The value **MSStatus::kMSStatusSuccess** indicates that the operation is successful. 133 * @since 9 134 */ 135 OH_AI_API OH_AI_Status OH_AI_ModelBuild(OH_AI_ModelHandle model, const void *model_data, size_t data_size, 136 OH_AI_ModelType model_type, const OH_AI_ContextHandle model_context); 137 138 /** 139 * \brief Loads and builds a MindSpore model from a model file. 140 * 141 * Note that the same {@Link OH_AI_ContextHandle} object can only be passed to {@Link OH_AI_ModelBuild} or {@Link OH_AI_ModelBuildFromFile} once. 142 * If you call this function multiple times, make sure that you create multiple {@Link OH_AI_ContextHandle} objects accordingly. 143 * 144 * \param model Pointer to the model object. 145 * \param model_path Path of the model file. 146 * \param model_type Type of the model file. For details, see {@link OH_AI_ModelType}. 147 * \param model_context Context for model running. For details, see {@link OH_AI_ContextHandle}. 148 * \return Status code enumerated by {@link OH_AI_Status}. The value **MSStatus::kMSStatusSuccess** indicates that the operation is successful. 149 * @since 9 150 */ 151 OH_AI_API OH_AI_Status OH_AI_ModelBuildFromFile(OH_AI_ModelHandle model, const char *model_path, 152 OH_AI_ModelType model_type, const OH_AI_ContextHandle model_context); 153 154 /** 155 * \brief Adjusts the input tensor shapes of a built model. 156 * 157 * \param model Pointer to the model object. 158 * \param inputs Tensor array structure corresponding to the model input. 159 * \param shape_infos Input shape array, which consists of tensor shapes arranged in the model input sequence. The model adjusts the tensor shapes in sequence. 160 * \param shape_info_num Length of the input shape array. 161 * \return Status code enumerated by {@link OH_AI_Status}. The value **MSStatus::kMSStatusSuccess** indicates that the operation is successful. 162 * @since 9 163 */ 164 OH_AI_API OH_AI_Status OH_AI_ModelResize(OH_AI_ModelHandle model, const OH_AI_TensorHandleArray inputs, 165 OH_AI_ShapeInfo *shape_infos, size_t shape_info_num); 166 167 /** 168 * \brief Performs model inference. 169 * 170 * \param model Pointer to the model object. 171 * \param inputs Tensor array structure corresponding to the model input. 172 * \param outputs Pointer to the tensor array structure corresponding to the model output. 173 * \param before Callback function executed before model inference. 174 * \param after Callback function executed after model inference. 175 * \return Status code enumerated by {@link OH_AI_Status}. The value **MSStatus::kMSStatusSuccess** indicates that the operation is successful. 176 * @since 9 177 */ 178 OH_AI_API OH_AI_Status OH_AI_ModelPredict(OH_AI_ModelHandle model, const OH_AI_TensorHandleArray inputs, 179 OH_AI_TensorHandleArray *outputs, const OH_AI_KernelCallBack before, 180 const OH_AI_KernelCallBack after); 181 182 /** 183 * \brief Obtains the input tensor array structure of a model. 184 * 185 * \param model Pointer to the model object. 186 * \return Tensor array structure corresponding to the model input. 187 * @since 9 188 */ 189 OH_AI_API OH_AI_TensorHandleArray OH_AI_ModelGetInputs(const OH_AI_ModelHandle model); 190 191 /** 192 * \brief Obtains the output tensor array structure of a model. 193 * 194 * \param model Pointer to the model object. 195 * \return Tensor array structure corresponding to the model output. 196 * @since 9 197 */ 198 OH_AI_API OH_AI_TensorHandleArray OH_AI_ModelGetOutputs(const OH_AI_ModelHandle model); 199 200 /** 201 * \brief Obtains the input tensor of a model by tensor name. 202 * 203 * \param model Pointer to the model object. 204 * \param tensor_name Tensor name. 205 * \return Pointer to the input tensor indicated by **tensor_name**. If the tensor does not exist in the input, **null** will be returned. 206 * @since 9 207 */ 208 OH_AI_API OH_AI_TensorHandle OH_AI_ModelGetInputByTensorName(const OH_AI_ModelHandle model, const char *tensor_name); 209 210 /** 211 * \brief Obtains the output tensor of a model by tensor name. 212 * 213 * \param model Pointer to the model object. 214 * \param tensor_name Tensor name. 215 * \return Pointer to the output tensor indicated by **tensor_name**. If the tensor does not exist in the input, **null** will be returned. 216 * @since 9 217 */ 218 OH_AI_API OH_AI_TensorHandle OH_AI_ModelGetOutputByTensorName(const OH_AI_ModelHandle model, const char *tensor_name); 219 220 #ifdef __cplusplus 221 } 222 #endif 223 224 /** @} */ 225 #endif // MINDSPORE_INCLUDE_C_API_MODEL_C_H 226