From 70782e6379e580a64257a91a489ae89ea31032cd Mon Sep 17 00:00:00 2001 From: Zhaolong Xing Date: Fri, 3 Apr 2020 23:25:29 +0800 Subject: [PATCH] [Inference doc]: refine paddle_api.h doc (#23354) * refine paddle api doc test=develop * fix comments test=develop --- paddle/fluid/inference/api/paddle_api.h | 143 ++++++++++++++---------- 1 file changed, 82 insertions(+), 61 deletions(-) diff --git a/paddle/fluid/inference/api/paddle_api.h b/paddle/fluid/inference/api/paddle_api.h index b0f86c6d7c8..50141e57a0a 100644 --- a/paddle/fluid/inference/api/paddle_api.h +++ b/paddle/fluid/inference/api/paddle_api.h @@ -143,42 +143,69 @@ struct PaddleTensor { enum class PaddlePlace { kUNK = -1, kCPU, kGPU }; -/** Tensor without copy, currently only supports `AnalysisPredictor`. - */ +/// \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. class ZeroCopyTensor { public: + /// \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. void Reshape(const std::vector& shape); - /** Get the memory in CPU or GPU with specific data type, should Reshape first - * to tell the data size. - * One can directly call this data to feed the data. - * This is for writing the input tensor. - */ + /// \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. template T* mutable_data(PaddlePlace place); - /** Get the memory directly, will return the place and element size by - * pointer. - * This is for reading the output tensor. - */ + + /// \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. template T* data(PaddlePlace* place, int* size) const; + /// \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. template void copy_from_cpu(const T* data); + /// \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. template void copy_to_cpu(T* data); + /// \brief Return the shape of the Tensor. std::vector shape() const; + /// \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. void SetLoD(const std::vector>& x); + /// \brief Return the lod info of the tensor. std::vector> lod() const; + /// \brief Return the name of the tensor. const std::string& name() const { return name_; } void SetPlace(PaddlePlace place, int device = -1) { place_ = place; device_ = device; } + /// \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. PaddleDType type() const; protected: @@ -199,8 +226,8 @@ class ZeroCopyTensor { int device_; }; -/** A simple Inference API for Paddle. - */ +/// \brief A Predictor for executing inference on a model. +/// Base class for AnalysisPredictor and NativePaddlePredictor. class PaddlePredictor { public: struct Config; @@ -208,85 +235,79 @@ class PaddlePredictor { PaddlePredictor(const PaddlePredictor&) = delete; PaddlePredictor& operator=(const PaddlePredictor&) = delete; - /** Predict an record. - * The caller should be responsible for allocating and releasing the memory of - * `inputs`. `inputs` should be available until Run returns. Caller should be - * responsible for the output tensor's buffer, either allocated or passed from - * outside. - */ + /// \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 virtual bool Run(const std::vector& inputs, std::vector* output_data, int batch_size = -1) = 0; - /** \brief Get input names of the model - */ + /// \brief Used to get the name of the network input. + /// Be inherited by AnalysisPredictor, Only used in ZeroCopy scenarios. + /// \return Input tensor names. virtual std::vector GetInputNames() { return {}; } - /** \brief Get input shapes of the model - */ + /// \brief Get the input shape of the model. + /// \return A map contains all the input names and shape defined in the model. virtual std::map> GetInputTensorShape() { return {}; } - /** \brief Get output names of the model - */ + /// \brief Used to get the name of the network output. + /// Be inherited by AnalysisPredictor, Only used in ZeroCopy scenarios. + /// \return Output tensor names. virtual std::vector GetOutputNames() { return {}; } - /** \brief Get a mutable tensor directly. - * - * NOTE Only works in AnalysisPredictor. - * - * One can also use this to modify any temporary variable related tensors in - * the predictor. - * - */ + /// \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. virtual std::unique_ptr GetInputTensor( const std::string& name) { return nullptr; } - /** - * \brief Get an immutable tensor without copy. - * - * NOTE Only works in AnalysisPredictor. - * One can use this API to get any temporary tensors in the predictor and - * read it. - */ + + /// \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. virtual std::unique_ptr GetOutputTensor( const std::string& name) { return nullptr; } - /** - * \brief Run the predictor with zero-copied inputs and outputs. - * - * NOTE Only works in AnalysisPredictor. - * - * 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. - */ + /// \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 virtual bool ZeroCopyRun() { return false; } - /** Clone a predictor that share the model weights, the Cloned predictor - * should be thread-safe. - */ + /// \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 virtual std::unique_ptr Clone() = 0; - /** Destroy the Predictor. - */ + /// \brief Destroy the Predictor. virtual ~PaddlePredictor() = default; - /** \brief Get the serialized model program that executes in inference phase. - * Its data type is ProgramDesc, which is a protobuf message. - */ virtual std::string GetSerializedProgram() const { assert(false); // Force raise error. return "NotImplemented"; } - /** The common configs for all the predictors. - */ + /// \brief Base class for NativeConfig and AnalysisConfig. struct Config { std::string model_dir; /*!< path to the model directory. */ }; -- GitLab