4.10. Engine

Engine可以实现bmodel的加载与管理，是实现模型推理的主要模块。

4.10.1. 构造函数

初始化Engine

接口形式1:

创建Engine实例，并不加载bmodel

Engine(int tpu_id);

Engine(const Handle&   handle);

参数说明1:

tpu_id: int

指定Engine实例使用的智能视觉深度学习处理器的id

handle: Handle

指定Engine实例使用的设备标识Handle

接口形式2:

创建Engine实例并加载bmodel，需指定bmodel路径或内存中的位置。

Engine(
   const std::string& bmodel_path,
   int                tpu_id,
   IOMode             mode);

Engine(
   const std::string& bmodel_path,
   const Handle&      handle,
   IOMode             mode);

Engine(
    const void* bmodel_ptr,
    size_t      bmodel_size,
    int         tpu_id,
    IOMode      mode);

Engine(
   const void*        bmodel_ptr,
   size_t             bmodel_size,
   const Handle&      handle,
   IOMode             mode);

参数说明2:

bmodel_path: string

指定bmodel文件的路径

tpu_id: int

指定Engine实例使用的智能视觉深度学习处理器的id

mode: IOMode

指定输入/输出Tensor所在的内存位置：系统内存或设备内存。

bmodel_ptr: void*

bmodel在系统内存中的起始地址。

bmodel_size: size_t

bmodel在内存中的字节数

4.10.2. get_handle

获取Engine中使用的设备句柄sail.Handle

接口形式:

Handle get_handle();

返回值说明:

handle: Handle

返回Engine中的设备句柄。

4.10.3. load

将bmodel载入Engine中。

接口形式1:

指定bmodel路径，从文件中载入bmodel。

bool load(const std::string& bmodel_path);

参数说明1:

bmodel_path: string

bmodel的文件路径

接口形式2:

从系统内存中载入bmodel。

bool load(const void* bmodel_ptr, size_t bmodel_size);

参数说明2:

bmodel_ptr: void*

bmodel在系统内存中的起始地址。

bmodel_size: size_t

bmodel在内存中的字节数。

4.10.4. get_graph_names

获取Engine中所有载入的计算图的名称。

接口形式:

std::vector<std::string> get_graph_names();

返回值说明:

graph_names: std::vector<std::string>

Engine中所有计算图的name的数组。

4.10.5. set_io_mode

设置Engine的输入/输出Tensor所在的内存位置：系统内存或设备内存。

接口形式:

void set_io_mode(
    const std::string& graph_name,
    IOMode             mode);

参数说明:

graph_name: string

需要配置的计算图的name。

mode: IOMode

设置Engine的输入/输出Tensor所在的内存位置：系统内存或设备内存。

4.10.6. get_input_names

获取选定计算图中所有输入Tensor的name

接口形式:

std::vector<std::string> get_input_names(const std::string& graph_name);

参数说明:

graph_name: string

设定需要查询的计算图的name。

返回值说明:

input_names: std::vector<std::string>

返回选定计算图中所有输入Tensor的name的列表。

4.10.7. get_output_names

获取选定计算图中所有输出Tensor的name。

接口形式:

std::vector<std::string> get_output_names(const std::string& graph_name);

参数说明:

graph_name: string

设定需要查询的计算图的name。

返回值说明:

output_names: std::vector<std::string>

返回选定计算图中所有输出Tensor的name的列表。

4.10.8. get_max_input_shapes

查询选定计算图中所有输入Tensor对应的最大shape。

在静态模型中，输入Tensor的shape是固定的，应等于最大shape。

在动态模型中，输入Tensor的shape应小于等于最大shape。

接口形式:

std::map<std::string, std::vector<int>> get_max_input_shapes(
    const std::string& graph_name);

参数说明:

graph_name: string

设定需要查询的计算图的name。

返回值说明:

max_shapes: std::map<std::string, std::vector<int> >

返回输入Tensor中的最大shape。

4.10.9. get_input_shape

查询选定计算图中特定输入Tensor的shape。

接口形式:

std::vector<int> get_input_shape(
    const std::string& graph_name,
    const std::string& tensor_name);

参数说明:

graph_name: string

设定需要查询的计算图的name。

tensor_name: string

需要查询的Tensor的name。

返回值说明:

tensor_shape: std::vector<int>

该name下的输入Tensor中的最大维度的shape。

4.10.10. get_max_output_shapes

查询选定计算图中所有输出Tensor对应的最大shape。

在静态模型中，输出Tensor的shape是固定的，应等于最大shape。

在动态模型中，输出Tensor的shape应小于等于最大shape。

接口形式:

std::map<std::string, std::vector<int>> get_max_output_shapes(
    const std::string& graph_name);

参数说明:

graph_name: string

设定需要查询的计算图的name。

返回值说明:

std::map<std::string, std::vector<int> >

返回输出Tensor中的最大shape。

4.10.11. get_output_shape

查询选定计算图中特定输出Tensor的shape。

接口形式:

std::vector<int> get_output_shape(
    const std::string& graph_name,
    const std::string& tensor_name);

参数说明:

graph_name: string

设定需要查询的计算图的name。

tensor_name: string

需要查询的Tensor的name。

返回值说明:

tensor_shape: std::vector<int>

该name下的输出Tensor的shape。

4.10.12. get_input_dtype

获取特定计算图的特定输入Tensor的数据类型。

接口形式:

bm_data_type_t get_input_dtype(
    const std::string& graph_name,
    const std::string& tensor_name);

参数说明:

graph_name: string

设定需要查询的计算图的name。

tensor_name: string

需要查询的Tensor的name。

返回值说明:

datatype: bm_data_type_t

返回Tensor中数据的数据类型。

4.10.13. get_output_dtype

获取特定计算图的特定输出Tensor的数据类型。

接口形式:

bm_data_type_t get_output_dtype(
    const std::string& graph_name,
    const std::string& tensor_name);

参数说明:

graph_name: string

设定需要查询的计算图的name。

tensor_name: string

需要查询的Tensor的name。

返回值说明:

datatype: bm_data_type_t

返回Tensor中数据的数据类型。

4.10.14. get_input_scale

获取特定计算图的特定输入Tensor的scale，只在int8模型中有效。

接口形式:

float get_input_scale(
    const std::string& graph_name,
    const std::string& tensor_name);

参数说明:

graph_name: string

设定需要查询的计算图的name。

tensor_name: string

需要查询的Tensor的name。

返回值说明:

scale: float32

返回Tensor数据的scale。

4.10.15. get_output_scale

获取特定计算图的特定输出Tensor的scale，只在int8模型中有效。

接口形式:

float get_output_scale(
    const std::string& graph_name,
    const std::string& tensor_name);

参数说明:

graph_name: string

设定需要查询的计算图的name。

tensor_name: string

需要查询的Tensor的name。

返回值说明:

scale: float32

返回Tensor数据的scale。

4.10.16. process

在特定的计算图上进行前向推理。

接口形式:

void process(
   const std::string&              graph_name,
   std::map<std::string, Tensor*>& input,
   std::map<std::string, Tensor*>& output);

void process(
   const std::string&                       graph_name,
   std::map<std::string, Tensor*>&          input,
   std::map<std::string, std::vector<int>>& input_shapes,
   std::map<std::string, Tensor*>&          output);

参数说明:

graph_name: string

输入参数。特定的计算图name。

input: std::map<std::string, Tensor*>

输入参数。所有的输入Tensor的数据。

input_shapes : std::map<std::string, std::vector<int> >

输入参数。所有传入Tensor的shape。

output: std::map<std::string, Tensor*>

输出参数。所有的输出Tensor的数据。

4.10.17. get_device_id

获取Engine中的设备id号

接口形式:

int get_device_id() const;

返回值说明:

tpu_id : int

返回Engine中的设备id号。

4.10.18. create_input_tensors_map

创建输入Tensor的映射

接口形式:

std::map<std::string, Tensor*> create_input_tensors_map(
    const std::string& graph_name,
    int create_mode = -1);

参数说明:

graph_name: string

特定的计算图name。

create_mode: int

创建Tensor分配内存的模式。为0时只分配系统内存，为1时只分配设备内存，其他时则根据Engine中IOMode的配置分配。

返回值说明:

input: std::map<std::string, Tensor*>

返回字符串到tensor的映射。

4.10.19. create_output_tensors_map

创建输入Tensor的映射，在python接口中为字典dict{string : Tensor}

接口形式:

std::map<std::string, Tensor*> create_output_tensors_map(
    const std::string& graph_name,
    int create_mode = -1);

参数说明:

graph_name: string

特定的计算图name。

create_mode: int

创建Tensor分配内存的模式。为0时只分配系统内存，为1时只分配设备内存，其他时则根据Engine中IOMode的配置分配。

返回值说明:

output: std::map<std::string, Tensor*>

返回字符串到tensor的映射。

示例代码:

#include <stdio.h>
#include <sail/cvwrapper.h>
#include <sail/engine.h>
#include <sail/tensor.h>
#include <iostream>
#include <string>

using namespace std;

int main() {
    int dev_id = 0;
    sail::Handle handle(dev_id);
    std::string bmodel_path = "../../../sophon-demo/sample/YOLOv5/models/BM1684X/yolov5s_v6.1_3output_int8_1b.bmodel";
    sail::Engine engine(bmodel_path, dev_id, sail::IOMode::SYSIO);
    std::string graph_name = engine.get_graph_names()[0];
    std::string input_name = engine.get_input_names(graph_name)[0];
    std::string output_name = engine.get_output_names(graph_name)[0];
    std::vector<int> input_shape = engine.get_input_shape(graph_name, input_name);
    std::vector<int> output_shape = engine.get_output_shape(graph_name, output_name);
    bm_data_type_t input_dtype = engine.get_input_dtype(graph_name, input_name);
    bm_data_type_t output_dtype = engine.get_output_dtype(graph_name, output_name);
    float input_scale = engine.get_input_scale(graph_name, input_name);
    float output_scale = engine.get_output_scale(graph_name, output_name);
    int device_id = engine.get_device_id();
    std::map<std::string, sail::Tensor> input_tensors_map = engine.create_input_tensors_map(graph_name);
    std::map<std::string, sail::Tensor> output_tensors_map = engine.create_output_tensors_map(graph_name);
    engine.process(graph_name, input_tensors_map, output_tensors_map);
    std::cout << input_name << ", " << input_shape << ", " << input_dtype << ", " << input_scale << ", " << device_id << std::endl;
    std::cout << output_name << ", " << output_shape << ", " << output_dtype << ", " << output_scale << ", " << device_id << std::endl;

    return 0;
}