C++ API¶
CreatePaddlePredictor¶
#include <paddle_api.h>
template <typename ConfigT>
std::shared_ptr<PaddlePredictor> CreatePaddlePredictor(const ConfigT&);
CreatePaddlePredictor
用来根据 MobileConfig
构建预测器。
示例:
// 设置 MobileConfig
MobileConfig config;
config.set_model_dir(FLAGS_model_dir);
// 根据 MobileConfig 创建 PaddlePredictor
std::shared_ptr<PaddlePredictor> predictor = CreatePaddlePredictor<MobileConfig>(config);
参数
config
: 用于构建 Predictor 的配置信息。
返回值
PaddlePredictor
指针
CxxConfig¶
#include <paddle_api.h>
class CxxConfig;
CxxConfig
用来配置构建 CxxPredictor 的配置信息,如 protobuf 格式的模型地址、能耗模式、工作线程数、place 信息等等。
示例:
config = CxxConfig()
# 设置模型目录,加载非 combined 模型时使用
config.set_model_dir(<your_model_dir_path>)
# 设置工作线程数
config.set_threads(4);
# 设置能耗模式
config.set_power_mode(PowerMode.LITE_POWER_NO_BIND)
# 设置 valid places
places = [Place(TargetType.ARM, PrecisionType.FP32)]
config.set_valid_places(places)
# 根据 CxxConfig 创建 CxxPredictor
predictor = create_paddle_predictor(config)
公有成员函数¶
set_model_dir
¶
void set_model_dir(const std::string& x);
设置模型文件夹路径,当需要从磁盘加载非 combined 模型时使用。
参数
x
:模型文件夹路径
set_model_file
¶
void set_model_file(const std::string& path);
设置模型文件路径,加载 combined 形式模型时使用。
参数
path
:模型文件路径
set_param_file
¶
void set_param_file(const std::string& path);
设置模型参数文件路径,加载 combined 形式模型时使用。
参数
path
: 模型参数文件路径
set_valid_places
¶
void set_valid_places(const std::vector<Place>& x);
设置可用的 places 列表。
参数
x
:可用 place 列表。
示例:
config = CxxConfig()
# 设置模型目录,加载非 combined 模型时使用
config.set_model_dir(<your_model_dir_path>)
# 设置 valid places
# 注意,valid_places 列表中 Place 的排序表明了用户对 Place 的偏好程度,如用户想优先使用 ARM 上 Int8 精度的
# kernel,则应把 Place(TargetType.ARM, PrecisionType.INT8) 置于 valid_places 列表的首位。
places = [Place(TargetType.ARM, PrecisionType.INT8),
Place(TargetType.ARM, PrecisionType.FP32)]
config.set_valid_places(places)
# 根据 CxxConfig 创建 CxxPredictor
predictor = create_paddle_predictor(config)
set_power_mode
¶
void set_power_mode(PowerMode mode);
设置 CPU 能耗模式。若不设置,则默认使用 PowerMode.LITE_POWER_HIGH
。
注意:只在开启 OpenMP
时生效,否则系统自动调度。此函数只在使用 LITE_WITH_ARM
编译选项下生效。
参数
mode(PowerMode)
:CPU 能耗模式
power_mode
¶
PowerMode power_mode() const;
获取设置的 CPU 能耗模式。
注意:此函数只在使用 LITE_WITH_ARM
编译选项下生效。
返回值
设置的 CPU 能耗模式
set_threads
¶
void set_threads(int threads);
设置工作线程数。若不设置,则默认使用单线程。
注意:只在开启 OpenMP
的模式下生效,否则只使用单线程。此函数只在使用 LITE_WITH_ARM
编译选项下生效。
参数
threads
:工作线程数
set_x86_math_num_threads
¶
void set_x86_math_num_threads(int threads);
设置 CPU Math 库线程数,CPU 核心数支持情况下可加速预测。默认为 1,并且仅在 x86 下有效。
参数
threads
:CPU Math 库线程数
x86_math_num_threads
¶
int x86_math_num_threads() const;
返回 CPU Math 库线程数,CPU 核心数支持情况下可加速预测。仅在 x86 下有效。
返回值
CPU Math 库线程数
MobileConfig¶
#include <paddle_api.h>
class MobileConfig;
MobileConfig
用来配置构建轻量级 PaddlePredictor 的配置信息,如 NaiveBuffer 格式的模型地址、模型的内存地址(从内存加载模型时使用)、能耗模式、工作线程数等等。
注意:输入的模型需要使用 Model Optimize Tool 转化为 NaiveBuffer 格式的优化模型。
示例:
MobileConfig config;
// 判断设备是否支持 FP16 指令集(或者是否是 armv8.2 架构的 arm 设备)
bool suppor_fp16 = config.check_fp16_valid();
// 设置 NaiveBuffer 格式模型目录,从文件加载模型时使用
config.set_model_from_file(<your_model_path>);
// 设置工作线程数
config.set_threads(4);
// 设置能耗模式
config.set_power_mode(LITE_POWER_HIGH);
// 根据 MobileConfig 创建 PaddlePredictor
std::shared_ptr<PaddlePredictor> predictor = CreatePaddlePredictor<MobileConfig>(config);
check_fp16_valid
¶
bool check_fp16_valid();
判断当前设备是否支持FP16 指令集(或者是否是 armv8.2 架构的 arm 设备),且该方法仅对 arm CPU 有效
set_model_from_file
¶
void set_model_from_file(const std::string& x);
设置模型文件,当需要从磁盘加载模型时使用。
参数
x
: 模型文件路径
set_model_dir
¶
void set_model_dir(const std::string& x);
注意:Lite 模型格式在 release/v2.3.0 之后修改,本接口为加载老格式模型的接口,将在 release/v3.0.0 废弃。建议替换为 set_model_from_file
接口。
设置模型文件夹路径,当需要从磁盘加载模型时使用。
参数
x
: 模型文件夹路径
set_model_from_buffer
¶
void set_model_from_buffer(const std::string& x);
设置模型的内存数据,当需要从内存加载模型时使用。
参数
x
: 内存中的模型数据
set_model_buffer
¶
void set_model_buffer(const char* model_buffer,
size_t model_buffer_size,
const char* param_buffer,
size_t param_buffer_size);
注意:Lite 模型格式在 release/v2.3.0 之后修改,本接口为加载老格式模型的接口,将在 release/v3.0.0 废弃。建议替换为 set_model_from_buffer
接口。
设置模型、参数的内存地址,当需要从内存加载模型时使用。
示例:
// 读取模型文件到内存
std::string model_buffer = ReadFile(FLAGS_model_path);
std::string params_buffer = lite::ReadFile(FLAGS_params_path);
// 设置 MobileConfig
lite_api::MobileConfig config;
config.set_model_buffer(model_buffer.c_str(), model_buffer.size(),
params_buffer.c_str(), params_buffer.size());
// 根据 MobileConfig 创建 PaddlePredictor
std::shared_ptr<PaddlePredictor> predictor = CreatePaddlePredictor<MobileConfig>(config);
参数
model_buffer
: 内存中模型结构数据。model_buffer
: 内存中模型结构数据的大小。param_buffer
: 内存中模型参数数据。param_buffer
: 内存中模型参数数据的大小。
is_model_from_memory
¶
bool is_model_from_memory() const;
是否从内存中加载模型,当使用 set_model_buffer
接口时返回 true
。
返回值
是否从内存加载模型
set_power_mode
¶
void set_power_mode(PowerMode mode);
设置 CPU 能耗模式。若不设置,则默认使用 LITE_POWER_HIGH
。
注意:只在开启 OpenMP
时生效,否则系统自动调度。
参数
PowerMode
: CPU 能耗模式
set_threads
¶
void set_threads(int threads);
设置工作线程数。若不设置,则默认使用单线程。
注意:只在开启 OpenMP
的模式下生效,否则只使用单线程。
参数
threads
: 工作线程数
set_metal_lib_path
¶
void set_metal_lib_path(const std::string& path);
用于 iOS 设备上使用 Metal 进行 GPU 预测时,配置 metallib 加载路径。
参数
str
:metallib 库文件路径
set_metal_use_mps
¶
void set_metal_use_mps(bool flag);
设置 iOS 设备上使用 Metal 进行 GPU 预测时,是否启用 Metal Performance Shaders。若不设置,默认不使用(建议启用)。
参数
flag
:是否使用 MPS
PaddlePredictor¶
#include <paddle_api.h>
class PaddlePredictor;
PaddlePredictor
是 Paddle Lite 的预测器,由 CreatePaddlePredictor
根据 MobileConfig
进行创建。用户可以根据 PaddlePredictor 提供的接口设置输入数据、执行模型预测、获取输出以及获得当前使用 lib 的版本信息等。
示例:
int64_t ShapeProduction(const shape_t& shape) {
int64_t res = 1;
for (auto i : shape) res *= i;
return res;
}
// 设置 MobileConfig
MobileConfig config;
config.set_model_dir(FLAGS_model_dir);
// 根据 MobileConfig 创建 PaddlePredictor
std::shared_ptr<PaddlePredictor> predictor = CreatePaddlePredictor<MobileConfig>(config);
// 获得模型的输入和输出名称
std::vector<std::string> input_names = predictor->GetInputNames();
for (int i = 0; i < input_names.size(); i ++) {
printf("Input name[%d]: %s\n", i, input_names[i].c_str());
}
std::vector<std::string> output_names = predictor->GetOutputNames();
for (int i = 0; i < output_names.size(); i ++) {
printf("Output name[%d]: %s\n", i, output_names[i].c_str());
}
// 准备输入数据
// (1) 根据 index 获取输入 Tensor
std::unique_ptr<Tensor> input_tensor(std::move(predictor->GetInput(0)));
// (2) 根据名称获取输入 Tensor
// std::unique_ptr<Tensor> input_tensor(std::move(predictor->GetInputByName(input_names[0])));
input_tensor->Resize({1, 3, 224, 224});
auto* data = input_tensor->mutable_data<float>();
for (int i = 0; i < ShapeProduction(input_tensor->shape()); ++i) {
data[i] = 1;
}
// 执行预测
predictor->Run();
// 获取输出
// (1) 根据 index 获取输出 Tensor
std::unique_ptr<const Tensor> output_tensor(std::move(predictor->GetOutput(0)));
// (2) 根据名称获取输出 Tensor
// std::unique_ptr<const Tensor> output_tensor(std::move(predictor->GetOutput(output_names[0])));
printf("Output dim: %d\n", output_tensor->shape()[1]);
for (int i = 0; i < ShapeProduction(output_tensor->shape()); i += 100) {
printf("Output[%d]: %f\n", i, output_tensor->data<float>()[i]);
}
GetInput
¶
virtual std::unique_ptr<Tensor> GetInput(int i) = 0;
获取输入 Tensor 指针,用来设置模型的输入数据。
参数
i
: 输入Tensor
的索引
返回值
第
i
个输入Tensor
的指针
GetOutput
¶
virtual std::unique_ptr<const Tensor> GetOutput(int i) const = 0;
获取输出 Tensor 的指针,用来获取模型的输出结果。
参数
i
: 输出 Tensor 的索引
返回值
第
i
个输出Tensor
的指针
GetInputNames
¶
virtual std::vector<std::string> GetInputNames() = 0;
获取所有输入 Tensor 的名称。
返回值
所有输入 Tensor 的名称
GetOutputNames
¶
virtual std::vector<std::string> GetOutputNames() = 0;
获取所有输出 Tensor 的名称。
返回值
所有输出 Tensor 的名称
GetInputByName
¶
virtual std::unique_ptr<Tensor> GetInputByName(const std::string& name) = 0;
根据名称获取输出 Tensor 的指针,用来获取模型的输出结果。
参数
name
: 输入 Tensor 的名称
返回值
输入
Tensor
的指针
GetTensor
¶
virtual std::unique_ptr<const Tensor> GetTensor(const std::string& name) const = 0;
根据名称获取输出Tensor的指针。
注意:GetTensor
接口是为开发者设计的调试接口,可以输出转化后模型中的任一节点。如果出现 GetTensor(InputName)
返回值为空 Tensor
,可能原因是以该 InputName
命名的 Tensor 在模型转化的子图融合过程被融合替换了。
参数
name
: Tensor 的名称
返回值
指向
const Tensor
的指针
GetVersion
¶
virtual std::string GetVersion() const = 0;
用于获取当前库使用的代码版本。若代码有相应 tag 则返回 tag 信息,如 v2.0-beta
;否则返回代码的 branch(commitid)
,如 develop(7e44619)
。
返回值
当前库使用的代码版本信息
TargetType¶
#include <paddle_place.h>
class TargetType;
TargetType
为目标设备硬件类型,用户可以根据应用场景选择硬件平台类型。
枚举型变量 TargetType
的所有可能取值包括:{kX86, kCUDA, kARM, kOpenCL, kFPGA, kNPU}
PrecisionType¶
#include <paddle_place.h>
class PrecisionType;
PrecisionType
为模型中 Tensor 的数据精度,默认值为 FP32 (float32)。
枚举型变量 PrecisionType
的所有可能取值包括: {kFloat, kInt8, kInt32, kFP16, kBool, kInt64, kInt16, kUInt8, kFP64, kAny}
DataLayoutType¶
#include <paddle_place.h>
class DataLayoutType;
DataLayoutType
为 Tensor 的数据格式,默认值为 NCHW(number, channel, height, weigth)。
枚举型变量 DataLayoutType
的所有可能取值包括:{kNCHW, kNHWC, kImageDefault, kImageFolder, kImageNW, kMetalTexture2DArray, kMetalTexture2D, kAny}
Place¶
#include <paddle_place.h>
struct Place;
Place
是 TargetType
、PrecisionType
和 DataLayoutType
的集合,说明运行时的设备类型、数据精度和数据格式。
示例:
Place{TargetType(ARM), PrecisionType(FP32), DataLayoutType(NCHW)}
PowerMode¶
#include <paddle_place.h>
enum PowerMode;
PowerMode
为 ARM CPU 能耗模式,用户可以根据应用场景设置能耗模式获得最优的能效比。
示例:
MobileConfig config;
// 设置 NaiveBuffer 格式模型目录
config.set_model_dir(FLAGS_model_dir);
// 设置能耗模式
config.set_power_mode(LITE_POWER_HIGH);
// 根据 MobileConfig 创建 PaddlePredictor
std::shared_ptr<PaddlePredictor> predictor = CreatePaddlePredictor<MobileConfig>(config);
PowerMode详细说明如下:
选项 | 说明 |
---|---|
LITE_POWER_HIGH | 绑定大核运行模式。如果 ARM CPU 支持 big.LITTLE,则优先使用并绑定 Big cluster,如果设置的线程数大于大核数量,则会将线程数自动缩放到大核数量。如果系统不存在大核或者在一些手机的低电量情况下会出现绑核失败,如果失败则进入不绑核模式。 |
LITE_POWER_LOW | 绑定小核运行模式。如果 ARM CPU 支持 big.LITTLE,则优先使用并绑定 Little cluster,如果设置的线程数大于小核数量,则会将线程数自动缩放到小核数量。如果找不到小核,则自动进入不绑核模式。 |
LITE_POWER_FULL | 大小核混用模式。线程数可以大于大核数量,当线程数大于核心数量时,则会自动将线程数缩放到核心数量。 |
LITE_POWER_NO_BIND | 不绑核运行模式(推荐)。系统根据负载自动调度任务到空闲的 CPU 核心上。 |
LITE_POWER_RAND_HIGH | 轮流绑定大核模式。如果 Big cluster 有多个核心,则每预测 10 次后切换绑定到下一个核心。 |
LITE_POWER_RAND_LOW | 轮流绑定小核模式。如果 Little cluster 有多个核心,则每预测 10 次后切换绑定到下一个核心。 |
Tensor¶
#include <paddle_api.h>
struct Tensor
Tensor 是 Paddle Lite 的数据组织形式,用于对底层数据进行封装并提供接口对数据进行操作,包括设置 Shape、数据、LoD 信息等。
注意:用户应使用 PaddlePredictor
的 GetInput
和 GetOuput
接口获取输入 / 输出的 Tensor
。
示例:
int64_t ShapeProduction(const shape_t& shape) {
int64_t res = 1;
for (auto i : shape) res *= i;
return res;
}
// 设置 MobileConfig
MobileConfig config;
config.set_model_dir(FLAGS_model_dir);
// 根据 MobileConfig 创建 PaddlePredictor
std::shared_ptr<PaddlePredictor> predictor = CreatePaddlePredictor<MobileConfig>(config);
// 准备输入数据, 获取输入 Tensor
std::unique_ptr<Tensor> input_tensor(std::move(predictor->GetInput(0)));
// 设置输入 Tensor 维度信息
input_tensor->Resize({1, 3, 224, 224});
// 设置输入数据
auto* data = input_tensor->mutable_data<float>();
for (int i = 0; i < ShapeProduction(input_tensor->shape()); ++i) {
data[i] = 1;
}
// 执行预测
predictor->Run();
// 获取输出 Tensor
std::unique_ptr<const Tensor> output_tensor(std::move(predictor->GetOutput(0)));
// 获取输出 Tensor 维度
printf("Output dim: %d\n", output_tensor->shape()[1]);
// 获取输出 Tensor 数据
for (int i = 0; i < ShapeProduction(output_tensor->shape()); i += 100) {
printf("Output[%d]: %f\n", i, output_tensor->data<float>()[i]);
}
data
¶
template <typename T> const T* data() const;
获取 Tensor 的底层数据的常量指针,根据传入的不同模型类型获取相应数据。用于读取 Tensor 数据。
示例:
std::unique_ptr<const Tensor> output_tensor(std::move(predictor->GetOutput(0)));
// 如果模型中输出为 float 类型
output_tensor->data<float>()
返回值
Tensor
底层数据常量指针
mutable_data
¶
template <typename T> T* mutable_data() const;
获取 Tensor 的底层数据的指针,根据传入的不同模型类型获取相应数据。用于设置 Tensor 数据。
示例:
std::unique_ptr<Tensor> input_tensor(std::move(predictor->GetInput(0)));
// 如果模型中输出为 float 类型
auto* data = input_tensor->mutable_data<float>();
// 设置 Tensor 数据
for (int i = 0; i < ShapeProduction(input_tensor->shape()); ++i) {
data[i] = 1;
}
返回值
Tensor
底层数据指针
SetLoD
¶
void SetLoD(const lod_t& lod);
设置 Tensor 的 LoD 信息。
参数
lod
: Tensor 的 LoD 信息, 类型为std::vector<std::vector<uint64_t>>
precision
¶
PrecisionType precision() const;
获取Tensor的精度信息
返回值
Tensor
的 precision 信息, 类型为PrecisionType
SetPrecision
¶
void SetPrecision(PrecisionType precision);
设置Tensor的精度信息
参数
precision
: Tensor 的 precision 信息