• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /**
2  * Copyright 2020 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 #ifndef MINDSPORE_INCLUDE_API_MODEL_H
17 #define MINDSPORE_INCLUDE_API_MODEL_H
18 
19 #include <string>
20 #include <vector>
21 #include <map>
22 #include <memory>
23 #include <utility>
24 #include "include/api/status.h"
25 #include "include/api/types.h"
26 #include "include/api/graph.h"
27 #include "include/api/context.h"
28 #include "include/api/callback/callback.h"
29 #include "include/api/cell.h"
30 #include "include/api/cfg.h"
31 #include "include/api/dual_abi_helper.h"
32 
33 namespace mindspore {
34 class ModelImpl;
35 class Metrics;
36 
37 namespace dataset {
38 class Dataset;
39 }  // namespace dataset
40 /// \brief The Model class is used to define a MindSpore model, facilitating computational graph management.
41 class MS_API Model {
42  public:
43   Model();
44   ~Model();
45   Model(const Model &) = delete;
46   void operator=(const Model &) = delete;
47 
48   /// \brief Builds a model so that it can run on a device.
49   ///
50   /// \param[in] graph GraphCell is a derivative of Cell. Cell is not available currently. GraphCell can be constructed
51   /// from Graph, for example, model.Build(GraphCell(graph), context).
52   /// \param[in] model_context A context used to store options during execution.
53   /// \param[in] train_cfg A config used by training.
54   ///
55   /// \return Status.
56   Status Build(GraphCell graph, const std::shared_ptr<Context> &model_context = nullptr,
57                const std::shared_ptr<TrainCfg> &train_cfg = nullptr);
58 
59   /// \brief Resizes the shapes of inputs.
60   ///
61   /// \param[in] inputs A vector that includes all input tensors in order.
62   /// \param[in] dims Defines the new shapes of inputs, should be consistent with inputs.
63   ///
64   /// \return Status.
65   Status Resize(const std::vector<MSTensor> &inputs, const std::vector<std::vector<int64_t>> &dims);
66 
67   /// \brief Inference model.
68   ///
69   /// \param[in] inputs A vector where model inputs are arranged in sequence.
70   /// \param[out] outputs Which is a pointer to a vector. The model outputs are filled in the container in sequence.
71   /// \param[in] before CallBack before predict.
72   /// \param[in] after CallBack after predict.
73   ///
74   /// \return Status.
75   Status Predict(const std::vector<MSTensor> &inputs, std::vector<MSTensor> *outputs,
76                  const MSKernelCallBack &before = nullptr, const MSKernelCallBack &after = nullptr);
77 
78   /// \brief Inference model with preprocess in model.
79   ///
80   /// \param[in] inputs A vector where model inputs are arranged in sequence.
81   /// \param[out] outputs Which is a pointer to a vector. The model outputs are filled in the container in sequence.
82   /// \param[in] whether to use data preprocess in model.
83   /// \param[in] before CallBack before predict.
84   /// \param[in] after CallBack after predict.
85   ///
86   /// \return Status.
87   Status PredictWithPreprocess(const std::vector<MSTensor> &inputs, std::vector<MSTensor> *outputs,
88                                const MSKernelCallBack &before = nullptr, const MSKernelCallBack &after = nullptr);
89 
90   /// \brief Apply data preprocess if it exits in model.
91   ///
92   /// \param[in] inputs A vector where model inputs are arranged in sequence.
93   /// \param[out] outputs Which is a pointer to a vector. The model outputs are filled in the container in sequence.
94   ///
95   /// \return Status.
96   Status Preprocess(const std::vector<MSTensor> &inputs, std::vector<MSTensor> *outputs);
97 
98   /// \brief Check if data preprocess exists in model.
99   /// \return true if data preprocess exists.
100   bool HasPreprocess();
101 
102   /// \brief Load config file.
103   ///
104   /// \param[in] config_path config file path.
105   ///
106   /// \return Status.
107   Status LoadConfig(const std::string &config_path);
108 
109   /// \brief Obtains all input tensors of the model.
110   ///
111   /// \return The vector that includes all input tensors.
112   std::vector<MSTensor> GetInputs();
113 
114   /// \brief Obtains the input tensor of the model by name.
115   ///
116   /// \return The input tensor with the given name, if the name is not found, an invalid tensor is returned.
117   inline MSTensor GetInputByTensorName(const std::string &tensor_name);
118 
119   /// \brief Obtains all gradient tensors of the model.
120   ///
121   /// \return The vector that includes all gradient tensors.
122   std::vector<MSTensor> GetGradients() const;
123 
124   /// \brief update gradient tensors of the model.
125   ///
126   /// \param[in] inputs A vector new gradients.
127   /// \return Status of operation
128   Status ApplyGradients(const std::vector<MSTensor> &gradients);
129 
130   /// \brief Obtains optimizer params tensors of the model.
131   ///
132   /// \return The vector that includes all params tensors.
133   std::vector<MSTensor> GetOptimizerParams() const;
134 
135   /// \brief update the optimizer parameters
136   ///
137   /// \param[in] inputs A vector new optimizer params.
138   /// \return Status of operation
139   Status SetOptimizerParams(const std::vector<MSTensor> &params);
140 
141   Status InitMetrics(std::vector<Metrics *> metrics);
142   std::vector<Metrics *> GetMetrics();
143 
144   /// \brief Obtains all output tensors of the model.
145   ///
146   /// \return The vector that includes all output tensors.
147   std::vector<MSTensor> GetOutputs();
148 
149   /// \brief Obtains names of all output tensors of the model.
150   ///
151   /// \return A vector that includes names of all output tensors.
152   inline std::vector<std::string> GetOutputTensorNames();
153 
154   /// \brief Obtains the output tensor of the model by name.
155   ///
156   /// \return The output tensor with the given name, if the name is not found, an invalid tensor is returned.
157   inline MSTensor GetOutputByTensorName(const std::string &tensor_name);
158 
159   /// \brief Get output MSTensors of model by node name.
160   ///
161   /// \param[in] node_name Define node name.
162   ///
163   /// \note Deprecated, replace with GetOutputByTensorName
164   ///
165   /// \return The vector of output MSTensor.
166   inline std::vector<MSTensor> GetOutputsByNodeName(const std::string &node_name);
167 
168   /// \brief Inference model.
169   ///
170   /// \param[in] device_type Device type,options are kGPU, kAscend910, etc.
171   /// \param[in] model_type The type of model file, options are ModelType::kMindIR, ModelType::kOM.
172   ///
173   /// \return Is supported or not.
174   static bool CheckModelSupport(enum DeviceType device_type, ModelType model_type);
175 
176   Status SetTrainMode(bool train);
177   bool GetTrainMode() const;
178   Status Train(int epochs, std::shared_ptr<dataset::Dataset> ds, std::vector<TrainCallBack *> cbs);
179   Status Evaluate(std::shared_ptr<dataset::Dataset> ds, std::vector<TrainCallBack *> cbs);
180 
181   /// \brief Build a model from model buffer so that it can run on a device. Only valid for Lite.
182   ///
183   /// \param[in] model_data Define the buffer read from a model file.
184   /// \param[in] size Define bytes number of model buffer.
185   /// \param[in] model_type Define The type of model file. Options: ModelType::kMindIR, ModelType::kOM. Only
186   /// ModelType::kMindIR is valid for Lite.
187   /// \param[in] model_context Define the context used to store options during execution.
188   /// \param[in] dec_key Define the key used to decrypt the ciphertext model. The key length is 16, 24, or 32.
189   /// \param[in] dec_mode Define the decryption mode. Options: AES-GCM, AES-CBC.
190   ///
191   /// \return Status.
192   Status Build(const void *model_data, size_t data_size, ModelType model_type,
193                const std::shared_ptr<Context> &model_context = nullptr, const Key &dec_key = {},
194                const std::string &dec_mode = kDecModeAesGcm);
195 
196   /// \brief Load and build a model from model buffer so that it can run on a device. Only valid for Lite.
197   ///
198   /// \param[in] model_path Define the model path.
199   /// \param[in] model_type Define The type of model file. Options: ModelType::kMindIR, ModelType::kOM. Only
200   /// ModelType::kMindIR is valid for Lite.
201   /// \param[in] model_context Define the context used to store options during execution.
202   /// \param[in] dec_key Define the key used to decrypt the ciphertext model. The key length is 16, 24, or 32.
203   /// \param[in] dec_mode Define the decryption mode. Options: AES-GCM, AES-CBC.
204   ///
205   /// \return Status.
206   Status Build(const std::string &model_path, ModelType model_type,
207                const std::shared_ptr<Context> &model_context = nullptr, const Key &dec_key = {},
208                const std::string &dec_mode = kDecModeAesGcm);
209 
210  private:
211   friend class Serialization;
212   // api without std::string
213   MSTensor GetInputByTensorName(const std::vector<char> &tensor_name);
214   std::vector<std::vector<char>> GetOutputTensorNamesChar();
215   MSTensor GetOutputByTensorName(const std::vector<char> &tensor_name);
216   std::vector<MSTensor> GetOutputsByNodeName(const std::vector<char> &node_name);
217 
218   std::shared_ptr<ModelImpl> impl_;
219 };
220 
221 MSTensor Model::GetInputByTensorName(const std::string &tensor_name) {
222   return GetInputByTensorName(StringToChar(tensor_name));
223 }
224 
225 std::vector<std::string> Model::GetOutputTensorNames() { return VectorCharToString(GetOutputTensorNamesChar()); }
226 
227 MSTensor Model::GetOutputByTensorName(const std::string &tensor_name) {
228   return GetOutputByTensorName(StringToChar(tensor_name));
229 }
230 
231 std::vector<MSTensor> Model::GetOutputsByNodeName(const std::string &node_name) {
232   return GetOutputsByNodeName(StringToChar(node_name));
233 }
234 }  // namespace mindspore
235 #endif  // MINDSPORE_INCLUDE_API_MODEL_H
236