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 提供MindSpore Lite的模型推理相关接口。 22 * 23 * @Syscap SystemCapability.Ai.MindSpore 24 * @since 9 25 */ 26 27 /** 28 * @file model.h 29 * 30 * @brief 提供了模型相关接口，可以用于模型创建、模型推理等。 31 * 32 * @library libmindspore_lite_ndk.so 33 * @since 9 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 #endif 45 46 typedef void *OH_AI_ModelHandle; 47 48 typedef void *OH_AI_TrainCfgHandle; 49 50 typedef struct OH_AI_TensorHandleArray { 51 size_t handle_num; 52 OH_AI_TensorHandle *handle_list; 53 } OH_AI_TensorHandleArray; 54 55 #define OH_AI_MAX_SHAPE_NUM 32 56 typedef struct OH_AI_ShapeInfo { 57 size_t shape_num; 58 int64_t shape[OH_AI_MAX_SHAPE_NUM]; 59 } OH_AI_ShapeInfo; 60 61 typedef struct OH_AI_CallBackParam { 62 char *node_name; 63 char *node_type; 64 } OH_AI_CallBackParam; 65 66 typedef bool (*OH_AI_KernelCallBack)(const OH_AI_TensorHandleArray inputs, const OH_AI_TensorHandleArray outputs, 67 const OH_AI_CallBackParam kernel_Info); 68 69 /** 70 * @brief Create a model object. 71 * @return Model object handle. 72 * @since 9 73 */ 74 OH_AI_API OH_AI_ModelHandle OH_AI_ModelCreate(); 75 76 /** 77 * @brief Destroy the model object. 78 * @param model Model object handle address. 79 * @since 9 80 */ 81 OH_AI_API void OH_AI_ModelDestroy(OH_AI_ModelHandle *model); 82 83 /** 84 * @brief Build the model from model file buffer so that it can run on a device. 85 * @param model Model object handle. 86 * @param model_data Define the buffer read from a model file. 87 * @param data_size Define bytes number of model file buffer. 88 * @param model_type Define The type of model file. 89 * @param model_context Define the context used to store options during execution. 90 * @return OH_AI_Status. 91 * @since 9 92 */ 93 OH_AI_API OH_AI_Status OH_AI_ModelBuild(OH_AI_ModelHandle model, const void *model_data, size_t data_size, 94 OH_AI_ModelType model_type, const OH_AI_ContextHandle model_context); 95 96 /** 97 * @brief Load and build the model from model path so that it can run on a device. 98 * @param model Model object handle. 99 * @param model_path Define the model file path. 100 * @param model_type Define The type of model file. 101 * @param model_context Define the context used to store options during execution. 102 * @return OH_AI_Status. 103 * @since 9 104 */ 105 OH_AI_API OH_AI_Status OH_AI_ModelBuildFromFile(OH_AI_ModelHandle model, const char *model_path, 106 OH_AI_ModelType model_type, const OH_AI_ContextHandle model_context); 107 108 /** 109 * @brief Resizes the shapes of inputs. 110 * @param model Model object handle. 111 * @param inputs The array that includes all input tensor handles. 112 * @param shape_infos Defines the new shapes of inputs, should be consistent with inputs. 113 * @param shape_info_num The num of shape_infos. 114 * @return OH_AI_Status. 115 * @since 9 116 */ 117 OH_AI_API OH_AI_Status OH_AI_ModelResize(OH_AI_ModelHandle model, const OH_AI_TensorHandleArray inputs, 118 OH_AI_ShapeInfo *shape_infos, size_t shape_info_num); 119 120 /** 121 * @brief Inference model. 122 * @param model Model object handle. 123 * @param inputs The array that includes all input tensor handles. 124 * @param outputs The array that includes all output tensor handles. 125 * @param before CallBack before predict. 126 * @param after CallBack after predict. 127 * @return OH_AI_Status. 128 * @since 9 129 */ 130 OH_AI_API OH_AI_Status OH_AI_ModelPredict(OH_AI_ModelHandle model, const OH_AI_TensorHandleArray inputs, 131 OH_AI_TensorHandleArray *outputs, const OH_AI_KernelCallBack before, 132 const OH_AI_KernelCallBack after); 133 134 /** 135 * @brief Obtains all input tensor handles of the model. 136 * @param model Model object handle. 137 * @return The array that includes all input tensor handles. 138 * @since 9 139 */ 140 OH_AI_API OH_AI_TensorHandleArray OH_AI_ModelGetInputs(const OH_AI_ModelHandle model); 141 142 /** 143 * @brief Obtains all output tensor handles of the model. 144 * @param model Model object handle. 145 * @return The array that includes all output tensor handles. 146 * @since 9 147 */ 148 OH_AI_API OH_AI_TensorHandleArray OH_AI_ModelGetOutputs(const OH_AI_ModelHandle model); 149 150 /** 151 * @brief Obtains the input tensor handle of the model by name. 152 * @param model Model object handle. 153 * @param tensor_name The name of tensor. 154 * @return The input tensor handle with the given name, if the name is not found, an NULL is returned. 155 * @since 9 156 */ 157 OH_AI_API OH_AI_TensorHandle OH_AI_ModelGetInputByTensorName(const OH_AI_ModelHandle model, const char *tensor_name); 158 159 /** 160 * @brief Obtains the output tensor handle of the model by name. 161 * @param model Model object handle. 162 * @param tensor_name The name of tensor. 163 * @return The output tensor handle with the given name, if the name is not found, an NULL is returned. 164 * @since 9 165 */ 166 OH_AI_API OH_AI_TensorHandle OH_AI_ModelGetOutputByTensorName(const OH_AI_ModelHandle model, const char *tensor_name); 167 168 /** 169 * @brief Create a TrainCfg object. Only valid for Lite Train. 170 * @return TrainCfg object handle. 171 * @since 11 172 */ 173 OH_AI_API OH_AI_TrainCfgHandle OH_AI_TrainCfgCreate(); 174 175 /** 176 * @brief Destroy the train_cfg object. Only valid for Lite Train. 177 * @param train_cfg TrainCfg object handle. 178 * @since 11 179 */ 180 OH_AI_API void OH_AI_TrainCfgDestroy(OH_AI_TrainCfgHandle *train_cfg); 181 182 /** 183 * @brief Obtains part of the name that identify a loss kernel. Only valid for Lite Train. 184 * @param train_cfg TrainCfg object handle. 185 * @param num The num of loss_name. 186 * @return loss_name. 187 * @since 11 188 */ 189 OH_AI_API char **OH_AI_TrainCfgGetLossName(OH_AI_TrainCfgHandle train_cfg, size_t *num); 190 191 /** 192 * @brief Set part of the name that identify a loss kernel. Only valid for Lite Train. 193 * @param train_cfg TrainCfg object handle. 194 * @param loss_name Define part of the name that identify a loss kernel. 195 * @param num The num of loss_name. 196 * @since 11 197 */ 198 OH_AI_API void OH_AI_TrainCfgSetLossName(OH_AI_TrainCfgHandle train_cfg, const char **loss_name, size_t num); 199 200 /** 201 * @brief Obtains optimization level of the train_cfg. Only valid for Lite Train. 202 * @param train_cfg TrainCfg object handle. 203 * @return OH_AI_OptimizationLevel. 204 * @since 11 205 */ 206 OH_AI_API OH_AI_OptimizationLevel OH_AI_TrainCfgGetOptimizationLevel(OH_AI_TrainCfgHandle train_cfg); 207 208 /** 209 * @brief Set optimization level of the train_cfg. Only valid for Lite Train. 210 * @param train_cfg TrainCfg object handle. 211 * @param level The optimization level of train_cfg. 212 * @since 11 213 */ 214 OH_AI_API void OH_AI_TrainCfgSetOptimizationLevel(OH_AI_TrainCfgHandle train_cfg, OH_AI_OptimizationLevel level); 215 216 /** 217 * @brief Build the train model from model buffer so that it can run on a device. Only valid for Lite Train. 218 * @param model Model object handle. 219 * @param model_data Define the buffer read from a model file. 220 * @param data_size Define bytes number of model file buffer. 221 * @param model_type Define The type of model file. 222 * @param model_context Define the context used to store options during execution. 223 * @param train_cfg Define the config used by training. 224 * @return OH_AI_Status. 225 * @since 11 226 */ 227 OH_AI_API OH_AI_Status OH_AI_TrainModelBuild(OH_AI_ModelHandle model, const void *model_data, size_t data_size, 228 OH_AI_ModelType model_type, const OH_AI_ContextHandle model_context, 229 const OH_AI_TrainCfgHandle train_cfg); 230 231 /** 232 * @brief Build the train model from model file buffer so that it can run on a device. Only valid for Lite Train. 233 * @param model Model object handle. 234 * @param model_path Define the model path. 235 * @param model_type Define The type of model file. 236 * @param model_context Define the context used to store options during execution. 237 * @param train_cfg Define the config used by training. 238 * @return OH_AI_Status. 239 * @since 11 240 */ 241 OH_AI_API OH_AI_Status OH_AI_TrainModelBuildFromFile(OH_AI_ModelHandle model, const char *model_path, 242 OH_AI_ModelType model_type, 243 const OH_AI_ContextHandle model_context, 244 const OH_AI_TrainCfgHandle train_cfg); 245 246 /** 247 * @brief Train model by step. Only valid for Lite Train. 248 * @param model Model object handle. 249 * @param before CallBack before predict. 250 * @param after CallBack after predict. 251 * @return OH_AI_Status. 252 * @since 11 253 */ 254 OH_AI_API OH_AI_Status OH_AI_RunStep(OH_AI_ModelHandle model, const OH_AI_KernelCallBack before, 255 const OH_AI_KernelCallBack after); 256 257 /** 258 * @brief Sets the Learning Rate of the training. Only valid for Lite Train. 259 * @param learning_rate to set. 260 * @return OH_AI_Status of operation. 261 * @since 11 262 */ 263 OH_AI_API OH_AI_Status OH_AI_ModelSetLearningRate(OH_AI_ModelHandle model, float learning_rate); 264 265 /** 266 * @brief Obtains the Learning Rate of the optimizer. Only valid for Lite Train. 267 * @param model Model object handle. 268 * @return Learning rate. 0.0 if no optimizer was found. 269 * @since 11 270 */ 271 OH_AI_API float OH_AI_ModelGetLearningRate(OH_AI_ModelHandle model); 272 273 /** 274 * @brief Obtains all weights tensors of the model. Only valid for Lite Train. 275 * @param model Model object handle. 276 * @return The vector that includes all gradient tensors. 277 * @since 11 278 */ 279 OH_AI_API OH_AI_TensorHandleArray OH_AI_ModelGetWeights(OH_AI_ModelHandle model); 280 281 /** 282 * @brief update weights tensors of the model. Only valid for Lite Train. 283 * @param new_weights A vector new weights. 284 * @return OH_AI_Status 285 * @since 11 286 */ 287 OH_AI_API OH_AI_Status OH_AI_ModelUpdateWeights(OH_AI_ModelHandle model, const OH_AI_TensorHandleArray new_weights); 288 289 /** 290 * @brief Get the model running mode. 291 * @param model Model object handle. 292 * @return Is Train Mode or not. 293 * @since 11 294 */ 295 OH_AI_API bool OH_AI_ModelGetTrainMode(OH_AI_ModelHandle model); 296 297 /** 298 * @brief Set the model running mode. Only valid for Lite Train. 299 * @param model Model object handle. 300 * @param train True means model runs in Train Mode, otherwise Eval Mode. 301 * @return OH_AI_Status. 302 * @since 11 303 */ 304 OH_AI_API OH_AI_Status OH_AI_ModelSetTrainMode(OH_AI_ModelHandle model, bool train); 305 306 /** 307 * @brief Setup training with virtual batches. Only valid for Lite Train. 308 * @param model Model object handle. 309 * @param virtual_batch_multiplier Virtual batch multiplier, use any number < 1 to disable. 310 * @param lr Learning rate to use for virtual batch, -1 for internal configuration. 311 * @param momentum Batch norm momentum to use for virtual batch, -1 for internal configuration. 312 * @return OH_AI_Status. 313 * @since 11 314 */ 315 OH_AI_API OH_AI_Status OH_AI_ModelSetupVirtualBatch(OH_AI_ModelHandle model, int virtual_batch_multiplier, float lr, 316 float momentum); 317 318 /** 319 * @brief Export training model from file. Only valid for Lite Train. 320 * @param model The model data. 321 * @param model_type The model file type. 322 * @param model_file The exported model file. 323 * @param quantization_type The quantification type. 324 * @param export_inference_only Whether to export a reasoning only model. 325 * @param output_tensor_name The set the name of the output tensor of the exported reasoning model, default as 326 * empty, and export the complete reasoning model. 327 * @param num The number of output_tensor_name. 328 * @return OH_AI_Status. 329 * @since 11 330 */ 331 OH_AI_API OH_AI_Status OH_AI_ExportModel(OH_AI_ModelHandle model, OH_AI_ModelType model_type, const char *model_file, 332 OH_AI_QuantizationType quantization_type, bool export_inference_only, 333 char **output_tensor_name, size_t num); 334 335 /** 336 * @brief Export training model from buffer. Only valid for Lite Train. 337 * @param model The model data. 338 * @param model_type The model file type. 339 * @param model_data The exported model buffer. 340 * @param data_size The exported model buffer size. 341 * @param quantization_type The quantification type. 342 * @param export_inference_only Whether to export a reasoning only model. 343 * @param output_tensor_name The set the name of the output tensor of the exported reasoning model, default as 344 * empty, and export the complete reasoning model. 345 * @param num The number of output_tensor_name. 346 * @return OH_AI_Status. 347 * @since 11 348 */ 349 OH_AI_API OH_AI_Status OH_AI_ExportModelBuffer(OH_AI_ModelHandle model, OH_AI_ModelType model_type, char **model_data, 350 size_t *data_size, OH_AI_QuantizationType quantization_type, 351 bool export_inference_only, char **output_tensor_name, size_t num); 352 353 /** 354 * @brief Export model's weights, which can be used in micro only. Only valid for Lite Train. 355 * @param model The model data. 356 * @param model_type The model file type. 357 * @param weight_file The path of exported weight file. 358 * @param is_inference Whether to export weights from a reasoning model. Currently, only support this is `true`. 359 * @param enable_fp16 Float-weight is whether to be saved in float16 format. 360 * @param changeable_weights_name The set the name of these weight tensors, whose shape is changeable. 361 * @param num The number of changeable_weights_name. 362 * @return OH_AI_Status. 363 * @since 11 364 */ 365 OH_AI_API OH_AI_Status OH_AI_ExportWeightsCollaborateWithMicro(OH_AI_ModelHandle model, OH_AI_ModelType model_type, 366 const char *weight_file, bool is_inference, 367 bool enable_fp16, char **changeable_weights_name, 368 size_t num); 369 370 #ifdef __cplusplus 371 } 372 #endif 373 #endif // MINDSPORE_INCLUDE_C_API_MODEL_C_H 374