C 预测 API介绍

Fluid提供了高度优化的C++预测库，为了方便使用，我们也提供了封装C++预测库对应的C接口。C接口的使用方式，首先是需要#include c_api.h，头文件c_api.h可以在Paddle的仓库中的paddle/fluid/inference/capi/c_api.h找到。另外需要加入相关的编译的包(Linux下)libpaddle_fluid_c.so/(Windows下)paddle_fluid_c.lib的位置。下面是详细的使用说明。

C预测相关数据结构

使用C预测API与C++预测API不完全一样，C预测主要包括PD_Tensor, PD_DataType, PD_AnalysisConfig和PD_PaddleBuf，分别对应于C++ API中的PaddleTensor，PaddleDType，AnalysisConfig和PaddleBuf。接下来将会进一步介绍。本次的Release的C-API目前暂时只支持单输入单输出的模型，后续我们将会继续提供更多的支持。

PD_Tensor

PD_Tensor是预测库输入和输出的数据结构，包括以下函数:

  • PD_Tensor* PD_NewPaddleTensor(): 新建一个PD_Tensor的指针。
  • void PD_DeletePaddleTensor(PD_Tensor* tensor): 删除一个PD_Tensor的指针。
  • void PD_SetPaddleTensorName(PD_Tensor* tensor, char* name): 指定输入的名称，name是一个char的指针用于指定名称。
  • void PD_SetPaddleTensorShape(PD_Tensor* tensor, int* shape, int size): 设置Tensor的shape。
  • void PD_SetPaddleTensorData(PD_Tensor* tensor, PD_PaddleBuf* buf): 设置Tensor的数据。是作为PD_PaddleBuf传入的。PD_PaddleBuf的接口后文将会介绍。
  • void PD_SetPaddleTensorDType(PD_Tensor* tensor, PD_DataType dtype): 设置Tensor的类型。输入是一个枚举类型PD_DataType。PD_DataType后文将会详细介绍。

同时，提供了读取PD_Tensor中以上属性的方法。

  • char* PD_GetPaddleTensorName(const PD_Tensor* tensor): 获取PD_Tensor的名称name。
  • int* PD_GetPaddleTensorShape(const PD_Tensor* tensor, int** size): 获取PD_Tensor的shape。返回是一个int的指针，另外，通过传参的方式可以得到int指针的大小，即size。
  • PD_PaddleBuf* PD_GetPaddleTensorData(const PD_Tensor* tensor): 获取PD_Tensor的数据。返回值是作为PD_PaddleBuf的指针存储的。
  • PD_DataType PD_GetPaddleTensorDType(const PD_Tensor* tensor): 获取PD_Tensor的类型。返回的是一个枚举类型PD_DataType。

PD_PaddleBuf

PD_PaddleBuf存储了上文提到的PD_Tensor的数据，包括以下函数:

  • PD_PaddleBuf* PD_NewPaddleBuf(): 新建一个PD_PaddleBuf的指针。
  • void PD_DeletePaddleTensor(PD_Tensor* tensor): 删除一个PD_PaddleBuf的指针。
  • void PD_PaddleBufResize(PD_PaddleBuf* buf, size_t length): 重新设置PD_PaddleBuf指针指向的数据的长度大小。
  • void PD_PaddleBufReset(PD_PaddleBuf* buf, void* data, size_t length): 重新设置PD_PaddleBuf指针指向的数据的数据本身，也可以用作PD_PaddleBuf指针数据的初始化赋值。
  • bool PD_PaddleBufEmpty(PD_PaddleBuf* buf): 判断一个PD_PaddleBuf的指针指向的数据是否为空。
  • void* PD_PaddleBufData(PD_PaddleBuf* buf): 返回一个PD_PaddleBuf的指针指向的数据的结果，用void*表示，返回之后，用户可以自行转换成相应的数据类型。
  • size_t PD_PaddleBufLength(PD_PaddleBuf* buf): 返回一个PD_PaddleBuf的指针指向的数据的字节长度。如果需要得到数组的长度大小需要除以sizeof(float)（此处是以float的数据类型为例）。

PD_DataType

PD_DataType是一个提供给用户的枚举，用于设定存有用户数据的PD_Tensor的数据类型。包括以下成员：

  • PD_FLOAT32: 32位浮点型
  • PD_INT32: 32位整型
  • PD_INT64: 64位整型
  • PD_UINT8: 8位无符号整型

代码示例

首先可以新建一个PD_Tensor和一个PD_PaddleBuf的指针。

  1. PD_Tensor* input = PD_NewPaddleTensor();
  2. PD_PaddleBuf* buf = PD_NewPaddleBuf();

调用设置PD_PaddleBuf的函数调用如下:

  1. int batch = 1;
  2. int channel = 3;
  3. int height = 318;
  4. int width = 318;
  5. int shape[4] = {batch, channel, height, width};
  6. int shape_size = 4;
  7. float* data = (float *) malloc(sizeof(float) * (batch * channel * height * width));
  8. if (PD_PaddleBufEmpty(buf))
  9.   PD_PaddleBufReset(buf, (void *)(data),
  10.                   sizeof(float) * (batch * channel * height * width));
  11. float* data__ = (float *) PD_PaddleBufData(buf);
  12. size_t size__ = PD_PaddleBufLength(buf) / sizeof(float);

设置了PD_PaddleBuf之后，就可以顺利完成对PD_Tensor的设置。

  1. char* name = "image";
  2. PD_SetPaddleTensorName(input, name);
  3. PD_SetPaddleTensorDType(input, PD_DataType::PD_FLOAT32);
  4. PD_SetPaddleTensorShape(input, shape, shape_size);
  5. PD_SetPaddleTensorData(input, buf);

PD_AnalysisConfig

PD_AnalysisConfig是创建预测引擎的配置，提供了模型路径设置、预测引擎运行设备选择以及多种优化预测流程的选项，主要包括以下方法

  • PD_AnalysisConfig* PD_NewAnalysisConfig(): 新建一个PD_AnalysisConfig的指针。
  • void PD_DeleteAnalysisConfig(PD_AnalysisConfig* config): 删除一个PD_AnalysisConfig的指针。
  • void PD_SetModel(PD_AnalysisConfig* config, const char* model_dir, const char* params_path = NULL): 设置模型的路径，输入的参数包括PD_AnalysisConfig，model_dir，params_path，其中model_dir是指的是模型保存位置的路径，一般不用包括文件名，params_path为可选参数，注意:
    • 如果不给定params_path，则认为该模型的参数存储路径与model_dir一致，且模型文件和参数文件是按照默认的文件名存储的，此时参数文件可能有多个。
    • 如果提供了params_path，为了方便用户的自定义，则在指明model_dir路径最后需要加上模型文件的文件名传入。
  • const char* PD_ModelDir(const PD_AnalysisConfig* config): 如果未指明PD_SetModel()的params_path，则可以返回模型文件夹路径。
  • const char* PD_ProgFile(const PD_AnalysisConfig* config): 如果是指明PD_SetModel()的params_path，则可以返回模型文件路径。
  • const char* PD_ParamsFile(const PD_AnalysisConfig* config): 如果是指明PD_SetModel()的params_path，则可以返回参数文件路径。
  • void PD_EnableUseGpu(PD_AnalysisConfig* config, uint64_t memory_pool_init_size_mb, int device_id = 0): 设置开启GPU，并且设定GPU显存(单位M)和设备的Device ID。
  • void PD_DisableGpu(PD_AnalysisConfig* config): 禁用GPU。
  • int PD_GpuDeviceId(const PD_AnalysisConfig* config): 返回使用的GPU设备的ID。
  • void PD_SwitchIrOptim(PD_AnalysisConfig* config, bool x = true): IR优化(默认开启)。
  • void PD_EnableTensorRtEngine(PD_AnalysisConfig* config, int workspace_size = 1 << 20, int max_batch_size = 1, int min_subgraph_size = 3, Precision precision = Precision::kFloat32, bool use_static = false, bool use_calib_mode = false): 开启TensorRT。关于参数的解释，详见使用Paddle-TensorRT库预测。
  • void PD_EnableMKLDNN(PD_AnalysisConfig* config): 开启MKLDNN。

代码示例

首先，新建一个PD_AnalysisConfig的指针。

  1. PD_AnalysisConfig* config = PD_NewAnalysisConfig();

如前文所述，设置模型和参数路径有两种形式：

  • 当模型文件夹下存在一个以默认文件名保存的模型文件和多个参数文件时，传入模型文件夹路径，模型文件名默认为__model__ 
  1. const char* model_dir = "./model";
  2. PD_SetModel(config, model_dir);
  • 当模型文件夹下只有一个模型文件和一个参数文件，传入模型文件和参数文件 
  1. const char* model_path = "./model/model";
  2. const char* params_path = "./params/params";
  3. PD_SetModel(config, model_path, params_path);

其他预测引擎配置选项示例如下

  1. PD_EnableUseGpu(config, 100, 0); // 初始化100M显存，使用的gpu id为0
  2. PD_GpuDeviceId(config);          // 返回正在使用的gpu id
  3. PD_DisableGpu(config);           // 禁用gpu
  4. PD_SwitchIrOptim(config, true);  // 开启IR优化
  5. PD_EnableMKLDNN(config);         // 开启MKLDNN

PD_PredictorRun

  1. bool PD_PredictorRun(const PD_AnalysisConfig* config, PD_Tensor* inputs, int in_size, PD_Tensor** output_data, int* out_size, int batch_size);

PD_PredictorRun是运行预测的引擎。输入的参数解释如下：

  • config(PD_AnalysisConfig): 用于设置预测的配置变量。
  • inputs(PD_Tensor*): 输入的PD_Tensor的指针。如果有多个PD_Tensor作为输入，则inputs将指向第一个，其数组的大小由in_size决定。
  • in_size(int): 输入的PD_Tensor的个数。
  • output_data(PD_Tensor**): 输出的PD_Tensor的指针。
  • out_size(int*): 输出的PD_Tensor的个数。是指针的指针，需要新建后传值进入函数，函数执行完会得到赋值，即，获得输出的PD_Tensor的个数。
  • batch_size(int): batch_size的大小。

代码示例

如前文所述，当完成网络配置PD_AnalysisConfig以及input设置之后，只需要简单的几行代码就可以获得模型的输出。假设模型输入的个数是in_size = 1。

  1. int in_size = 1;
  2. int batch_size = 1;
  3.  
  4. PD_Tensor* output = PD_NewPaddleTensor();
  5. int output_size;
  6.  
  7. PD_PredictorRun(config, input, in_size, &output, &output_size, batch_size);

完整使用示例

下面是使用Fluid C API进行预测的一个完整示例，使用resnet50模型

下载resnet50模型并解压，运行如下命令将会调用预测引擎。

  1. #include "c_api.h"
  2.  
  3. /*
  4.  * The main procedures to run a predictor according to c-api:
  5.  * 1. Create config to set how to process the inference.
  6.  * 2. Prepare the input for the inference.
  7.  * 3. Call PD_PredictorRun() to start. 
  8.  * 4. Obtain the output, and transform the PD_PaddleBuf data to expected data type. 
  9.  * 5. According to the size of the PD_PaddleBuf's data's size, print all the output data. 
  10.  */
  11. int main() {
  12.     PD_AnalysisConfig* config = PD_NewAnalysisConfig();
  13.     PD_DisableGpu(config);
  14.     const char* model_path = "./model/model";
  15.     const char* params_path = "./params/params";
  16.     PD_SetModel(config, model_path, params_path);
  17.  
  18.     int in_size = 1;
  19.     PD_Tensor* input = PD_NewPaddleTensor();
  20.     PD_PaddleBuf* buf = PD_NewPaddleBuf();
  21.     int batch = 1;
  22.     int channel = 3;
  23.     int height = 318;
  24.     int width = 318;
  25.     int shape[4] = {batch, channel, height, width};
  26.     int shape_size = 4;
  27.     float* data = (float *) malloc(sizeof(float) * (batch * channel * height * width));
  28.     PD_PaddleBufReset(buf, (void *)(data),
  29.                     sizeof(float) * (batch * channel * height * width));
  30.  
  31.     char name[5] = {'d', 'a', 't', 'a', '\0'};
  32.     PD_SetPaddleTensorName(input, name);
  33.     PD_SetPaddleTensorDType(input, PD_DataType::PD_FLOAT32);
  34.     PD_SetPaddleTensorShape(input, shape, shape_size);
  35.     PD_SetPaddleTensorData(input, buf);
  36.  
  37.     PD_Tensor* output = PD_NewPaddleTensor();
  38.  
  39.     /* Mention that the the output_size and data_size is different. 
  40.      * output_size is the size of PD_Tensor, for this version is one. 
  41.      * data_size is for the specific one PD_Tensor, the data's size.
  42.      */
  43.     PD_PredictorRun(config, input, in_size, &output, &output_size, batch);
  44.  
  45.     const char* output_name = PD_GetPaddleTensorName(output);
  46.     PD_PaddleBuf* out_buf = PD_GetPaddleTensorData(output);
  47.     float* out_data = (float *) PD_PaddleBufData(out_buf);
  48.     int data_size = PD_PaddleBufLength(out_buf) / sizeof(float);
  49.     return 0;
  50. }