paddle_api.h 15.1 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
// Copyright (c) 2018 PaddlePaddle Authors. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
#pragma once

16 17 18
/*! \file paddle_api.h
 */

Y
Yan Chunwei 已提交
19 20 21 22 23 24
/*! \mainpage Paddle Inference APIs
 * \section intro_sec Introduction
 * The Paddle inference library aims to offer an high performance inference SDK
 * for Paddle users.
 */

25
#include <cassert>
26
#include <map>
27 28 29
#include <memory>
#include <string>
#include <vector>
M
MRXLT 已提交
30
#include "crypto/cipher.h"
31
#include "paddle_infer_declare.h"  // NOLINT
M
MRXLT 已提交
32 33
                                   /*! \namespace paddle
                                    */
34 35
namespace paddle {

36
/// \brief Paddle data type.
37 38 39
enum PaddleDType {
  FLOAT32,
  INT64,
40
  INT32,
41
  UINT8,
42 43 44
  // TODO(Superjomn) support more data types if needed.
};

45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89
/// \brief Memory manager for PaddleTensor.
///
/// The PaddleBuf holds a buffer for data input or output. The memory can be
/// allocated by user or by PaddleBuf itself, but in any case, the PaddleBuf
/// should be reused for better performance.
///
/// For user allocated memory, the following API can be used:
/// - PaddleBuf(void* data, size_t length) to set an external memory by
/// specifying the memory address and length.
/// - Reset(void* data, size_t length) to reset the PaddleBuf with an external
/// memory.
/// ATTENTION, for user allocated memory, deallocation should be done by users
/// externally after the program finished. The PaddleBuf won't do any allocation
/// or deallocation.
///
/// To have the PaddleBuf allocate and manage the memory:
/// - PaddleBuf(size_t length) will allocate a memory of size `length`.
/// - Resize(size_t length) resize the memory to no less than `length`,
/// ATTENTION
///  if the allocated memory is larger than `length`, nothing will done.
///
/// Usage:
///
/// Let PaddleBuf manage the memory internally.
/// \code{cpp}
/// const int num_elements = 128;
/// PaddleBuf buf(num_elements/// sizeof(float));
/// \endcode
///
/// Or
/// \code{cpp}
/// PaddleBuf buf;
/// buf.Resize(num_elements/// sizeof(float));
/// \endcode
/// Works the exactly the same.
///
/// One can also make the `PaddleBuf` use the external memory.
/// \code{cpp}
/// PaddleBuf buf;
/// void* external_memory = new float[num_elements];
/// buf.Reset(external_memory, num_elements*sizeof(float));
/// ...
/// delete[] external_memory; // manage the memory lifetime outside.
/// \endcode
///
90
class PD_INFER_DECL PaddleBuf {
91
 public:
92 93 94 95 96
  ///
  /// \brief PaddleBuf allocate memory internally, and manage it.
  ///
  /// \param[in] length The length of data.
  ///
97 98
  explicit PaddleBuf(size_t length)
      : data_(new char[length]), length_(length), memory_owned_(true) {}
99 100 101 102 103 104
  ///
  /// \brief Set external memory, the PaddleBuf won't manage it.
  ///
  /// \param[in] data The start address of the external memory.
  /// \param[in] length The length of data.
  ///
105 106
  PaddleBuf(void* data, size_t length)
      : data_(data), length_(length), memory_owned_{false} {}
107 108 109 110 111 112 113 114 115 116 117
  ///
  /// \brief Copy only available when memory is managed externally.
  ///
  /// \param[in] other another `PaddleBuf`
  ///
  explicit PaddleBuf(const PaddleBuf& other);
  ///
  /// \brief Resize the memory.
  ///
  /// \param[in] length The length of data.
  ///
118
  void Resize(size_t length);
119 120 121 122 123 124
  ///
  /// \brief Reset to external memory, with address and length set.
  ///
  /// \param[in] data The start address of the external memory.
  /// \param[in] length The length of data.
  ///
125
  void Reset(void* data, size_t length);
126 127 128
  ///
  /// \brief Tell whether the buffer is empty.
  ///
129
  bool empty() const { return length_ == 0; }
130 131 132
  ///
  /// \brief Get the data's memory address.
  ///
133
  void* data() const { return data_; }
134 135 136
  ///
  /// \brief Get the memory length.
  ///
137 138 139 140 141 142 143 144 145 146
  size_t length() const { return length_; }

  ~PaddleBuf() { Free(); }
  PaddleBuf& operator=(const PaddleBuf&);
  PaddleBuf& operator=(PaddleBuf&&);
  PaddleBuf() = default;
  PaddleBuf(PaddleBuf&& other);

 private:
  void Free();
147 148
  void* data_{nullptr};  ///< pointer to the data memory.
  size_t length_{0};     ///< number of memory bytes.
149 150 151
  bool memory_owned_{true};
};

152 153 154
///
/// \brief Basic input and output data structure for PaddlePredictor.
///
155
struct PD_INFER_DECL PaddleTensor {
156
  PaddleTensor() = default;
157
  std::string name;  ///<  variable name.
158
  std::vector<int> shape;
159
  PaddleBuf data;  ///<  blob of data.
160
  PaddleDType dtype;
161
  std::vector<std::vector<size_t>> lod;  ///<  Tensor+LoD equals LoDTensor
162 163 164
};

enum class PaddlePlace { kUNK = -1, kCPU, kGPU };
Y
Yan Chunwei 已提交
165

166 167 168 169 170 171 172 173
/// \brief Represents an n-dimensional array of values.
/// The ZeroCopyTensor is used to store the input or output of the network.
/// Zero copy means that the tensor supports direct copy of host or device data
/// to device,
/// eliminating additional CPU copy. ZeroCopyTensor is only used in the
/// AnalysisPredictor.
/// It is obtained through PaddlePredictor::GetinputTensor()
/// and PaddlePredictor::GetOutputTensor() interface.
174
class PD_INFER_DECL ZeroCopyTensor {
175
 public:
176 177 178 179
  /// \brief Reset the shape of the tensor.
  /// Generally it's only used for the input tensor.
  /// Reshape must be called before calling mutable_data() or copy_from_cpu()
  /// \param shape The shape to set.
180 181
  void Reshape(const std::vector<int>& shape);

182 183 184 185
  /// \brief Get the memory pointer in CPU or GPU with specific data type.
  /// Please Reshape the tensor first before call this.
  /// It's usually used to get input data pointer.
  /// \param place The place of the tensor.
186 187
  template <typename T>
  T* mutable_data(PaddlePlace place);
188 189 190 191 192 193

  /// \brief Get the memory pointer directly.
  /// It's usually used to get the output data pointer.
  /// \param[out] place To get the device type of the tensor.
  /// \param[out] size To get the data size of the tensor.
  /// \return The tensor data buffer pointer.
194 195 196
  template <typename T>
  T* data(PaddlePlace* place, int* size) const;

197 198 199
  /// \brief Copy the host memory to tensor data.
  /// It's usually used to set the input tensor data.
  /// \param data The pointer of the data, from which the tensor will copy.
N
nhzlx 已提交
200 201 202
  template <typename T>
  void copy_from_cpu(const T* data);

203 204 205
  /// \brief Copy the tensor data to the host memory.
  /// It's usually used to get the output tensor data.
  /// \param[out] data The tensor will copy the data to the address.
N
nhzlx 已提交
206 207 208
  template <typename T>
  void copy_to_cpu(T* data);

209
  /// \brief Return the shape of the Tensor.
N
nhzlx 已提交
210
  std::vector<int> shape() const;
211

212 213 214 215
  /// \brief Set lod info of the tensor.
  /// More about LOD can be seen here:
  ///  https://www.paddlepaddle.org.cn/documentation/docs/zh/beginners_guide/basic_concept/lod_tensor.html#lodtensor
  /// \param x the lod info.
216
  void SetLoD(const std::vector<std::vector<size_t>>& x);
217
  /// \brief Return the lod info of the tensor.
218
  std::vector<std::vector<size_t>> lod() const;
219
  /// \brief Return the name of the tensor.
220
  const std::string& name() const { return name_; }
N
nhzlx 已提交
221 222 223 224
  void SetPlace(PaddlePlace place, int device = -1) {
    place_ = place;
    device_ = device;
  }
225

226 227 228
  /// \brief Return the data type of the tensor.
  /// It's usually used to get the output tensor data type.
  /// \return The data type of the tensor.
N
nhzlx 已提交
229
  PaddleDType type() const;
230

231 232 233 234 235 236 237 238 239 240
 protected:
  explicit ZeroCopyTensor(void* scope) : scope_{scope} {}
  void SetName(const std::string& name) { name_ = name; }
  void* FindTensor() const;

 private:
  std::string name_;
  bool input_or_output_;
  friend class AnalysisPredictor;
  void* scope_{nullptr};
241 242 243
  // The corresponding tensor pointer inside Paddle workspace is cached for
  // performance.
  mutable void* tensor_{nullptr};
N
nhzlx 已提交
244
  PaddlePlace place_;
245
  PaddleDType dtype_;
N
nhzlx 已提交
246
  int device_;
247 248
};

249 250
/// \brief A Predictor for executing inference on a model.
/// Base class for AnalysisPredictor and NativePaddlePredictor.
251
class PD_INFER_DECL PaddlePredictor {
252 253 254 255 256 257
 public:
  struct Config;
  PaddlePredictor() = default;
  PaddlePredictor(const PaddlePredictor&) = delete;
  PaddlePredictor& operator=(const PaddlePredictor&) = delete;

258 259 260 261 262 263 264 265
  /// \brief This interface takes input and runs the network.
  /// There are redundant copies of data between hosts in this operation,
  /// so it is more recommended to use the zecopyrun interface
  /// \param[in] inputs An list of PaddleTensor as the input to the network.
  /// \param[out] output_data Pointer to the tensor list, which holds the output
  /// paddletensor
  /// \param[in] batch_size This setting has been discarded and can be ignored.
  /// \return Whether the run is successful
266 267 268 269
  virtual bool Run(const std::vector<PaddleTensor>& inputs,
                   std::vector<PaddleTensor>* output_data,
                   int batch_size = -1) = 0;

270 271 272
  /// \brief  Used to get the name of the network input.
  /// Be inherited by AnalysisPredictor, Only used in ZeroCopy scenarios.
  /// \return Input tensor names.
N
nhzlx 已提交
273 274
  virtual std::vector<std::string> GetInputNames() { return {}; }

275 276
  /// \brief Get the input shape of the model.
  /// \return A map contains all the input names and shape defined in the model.
277 278 279 280
  virtual std::map<std::string, std::vector<int64_t>> GetInputTensorShape() {
    return {};
  }

281 282 283
  /// \brief Used to get the name of the network output.
  /// Be inherited by AnalysisPredictor, Only used in ZeroCopy scenarios.
  /// \return Output tensor names.
N
nhzlx 已提交
284 285
  virtual std::vector<std::string> GetOutputNames() { return {}; }

286 287 288 289 290
  /// \brief Get the input ZeroCopyTensor by name.
  /// Be inherited by AnalysisPredictor, Only used in ZeroCopy scenarios.
  /// The name is obtained from the GetInputNames() interface.
  /// \param name The input tensor name.
  /// \return Return the corresponding input ZeroCopyTensor.
291 292 293 294
  virtual std::unique_ptr<ZeroCopyTensor> GetInputTensor(
      const std::string& name) {
    return nullptr;
  }
295 296 297 298 299 300

  /// \brief Get the output ZeroCopyTensor by name.
  /// Be inherited by AnalysisPredictor, Only used in ZeroCopy scenarios.
  /// The name is obtained from the GetOutputNames() interface.
  /// \param name The output tensor name.
  /// \return Return the corresponding output ZeroCopyTensor.
301 302 303 304
  virtual std::unique_ptr<ZeroCopyTensor> GetOutputTensor(
      const std::string& name) {
    return nullptr;
  }
305 306 307 308 309 310 311 312 313
  /// \brief Run the network with zero-copied inputs and outputs.
  /// Be inherited by AnalysisPredictor and only used in ZeroCopy scenarios.
  /// This will save the IO copy for transfering inputs and outputs to predictor
  /// workspace
  /// and get some performance improvement.
  /// To use it, one should call the AnalysisConfig.SwitchUseFeedFetchOp(true)
  /// and then use the `GetInputTensor` and `GetOutputTensor`
  /// to directly write or read the input/output tensors.
  /// \return Whether the run is successful
314 315
  virtual bool ZeroCopyRun() { return false; }

316 317 318 319 320 321
  ///
  /// \brief Clear the intermediate tensors of the predictor
  ///
  ///
  virtual void ClearIntermediateTensor() {}

322 323 324 325
  /// \brief Clone an existing predictor
  /// When using clone, the same network will be created,
  /// and the parameters between them are shared.
  /// \return unique_ptr which contains the pointer of predictor
326 327
  virtual std::unique_ptr<PaddlePredictor> Clone() = 0;

328
  /// \brief Destroy the Predictor.
329 330
  virtual ~PaddlePredictor() = default;

331
  virtual std::string GetSerializedProgram() const {
Y
Yan Chunwei 已提交
332 333
    assert(false);  // Force raise error.
    return "NotImplemented";
334
  }
Y
Yan Chunwei 已提交
335

336
  /// \brief Base class for NativeConfig and AnalysisConfig.
337
  struct Config {
338
    std::string model_dir; /*!< path to the model directory. */
339 340 341
  };
};

342 343 344 345 346 347 348
///
/// \brief configuration manager for `NativePredictor`.
///
/// `AnalysisConfig` manages configurations of `NativePredictor`.
/// During inference procedure, there are many parameters(model/params path,
/// place of inference, etc.)
///
349
struct PD_INFER_DECL NativeConfig : public PaddlePredictor::Config {
350
  /// GPU related fields.
351 352
  bool use_gpu{false};
  int device{0};
353
  float fraction_of_gpu_memory{
354
      -1.f};  ///< Change to a float in (0,1] if needed.
355 356

  std::string prog_file;
357 358
  std::string
      param_file;  ///< Specify the exact path of program and parameter files.
359

360 361 362 363
  bool specify_input_name{false};  ///< Specify the variable's name of each
                                   ///< input if input tensors don't follow the
                                   ///< `feeds` and `fetches` of the phase
                                   ///< `save_inference_model`.
L
luotao1 已提交
364

365
  /// Set and get the number of cpu math library threads.
L
luotao1 已提交
366 367 368 369 370
  void SetCpuMathLibraryNumThreads(int cpu_math_library_num_threads) {
    cpu_math_library_num_threads_ = cpu_math_library_num_threads;
  }
  int cpu_math_library_num_threads() const {
    return cpu_math_library_num_threads_;
L
luotao1 已提交
371 372 373
  }

 protected:
374 375 376
  int cpu_math_library_num_threads_{1};  ///< number of cpu math library (such
                                         ///< as MKL, OpenBlas) threads for each
                                         ///< instance.
377 378
};

379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394
///
/// \brief A factory to help create different predictors.
///
/// Usage:
///
/// \code{.cpp}
/// NativeConfig config;
/// ... // change the configs.
/// auto native_predictor = CreatePaddlePredictor(config);
/// \endcode
///
/// FOR EXTENSION DEVELOPER:
/// Different predictors are designated by config type. Similar configs can be
/// merged, but there shouldn't be a huge config containing different fields for
/// more than one kind of predictors.
////
395 396 397
template <typename ConfigT>
std::unique_ptr<PaddlePredictor> CreatePaddlePredictor(const ConfigT& config);

398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413
struct AnalysisConfig;
struct NativeConfig;
struct DemoConfig;

template <>
PD_INFER_DECL std::unique_ptr<PaddlePredictor>
CreatePaddlePredictor<AnalysisConfig>(const AnalysisConfig& config);

template <>
PD_INFER_DECL std::unique_ptr<PaddlePredictor>
CreatePaddlePredictor<NativeConfig>(const NativeConfig& config);

template <>
PD_INFER_DECL std::unique_ptr<PaddlePredictor>
CreatePaddlePredictor<DemoConfig>(const DemoConfig& config);

414 415 416
/// NOTE The following APIs are too trivial, we will discard it in the following
/// versions.
///
417
enum class PaddleEngineKind {
418 419 420
  kNative = 0,         ///< Use the native Fluid facility.
  kAutoMixedTensorRT,  ///< Automatically mix Fluid with TensorRT.
  kAnalysis,           ///< More optimization.
421 422 423 424 425
};

template <typename ConfigT, PaddleEngineKind engine>
std::unique_ptr<PaddlePredictor> CreatePaddlePredictor(const ConfigT& config);

426 427 428 429 430 431 432 433 434 435 436
template <>
PD_INFER_DECL std::unique_ptr<PaddlePredictor> CreatePaddlePredictor<
    NativeConfig, PaddleEngineKind::kNative>(const NativeConfig& config);

template <>
PD_INFER_DECL std::unique_ptr<PaddlePredictor> CreatePaddlePredictor<
    AnalysisConfig, PaddleEngineKind::kAnalysis>(const AnalysisConfig& config);

PD_INFER_DECL int PaddleDtypeSize(PaddleDType dtype);

PD_INFER_DECL std::string get_version();
437

438
PD_INFER_DECL std::string UpdateDllFlag(const char* name, const char* value);
Y
Yan Chunwei 已提交
439

M
MRXLT 已提交
440 441
PD_INFER_DECL std::shared_ptr<framework::Cipher> MakeCipher(
    const std::string& config_file);
442
}  // namespace paddle