TNN API说明文档
TNN API說(shuō)明文檔
TNN：https://github.com/Tencent/TNN
說(shuō)明文檔：https://github.com/Tencent/TNN/blob/master/doc/cn/user/api.md
目錄
TNN API說(shuō)明文檔
一、API兼容性
二、API調(diào)用
簡(jiǎn)介
步驟1. 模型解析
步驟2. 網(wǎng)絡(luò)構(gòu)建
步驟3. 輸入設(shè)定
步驟4. 輸出獲取
二、API詳解
API目錄結(jié)構(gòu)
1. core/macro.h
2. core/common.h
3. core/status.h
4. core/blob.h
5. core/instance.h
6. core/tnn.h
7. utils/bfp16_utils.h
8. utils/blob_convert.h
9. utils/cpu_utils.h
10. utils/data_type_utils.h
11. utils/dims_vector_utils.h
12. utils/half_utils.h
一、API兼容性
TNN所有對(duì)外暴露接口均通過(guò)PUBLIC宏顯示聲明，非暴露接口符號(hào)均不可見(jiàn)。
#if defined _WIN32 || defined __CYGWIN__#ifdef BUILDING_DLL#ifdef __GNUC__#define PUBLIC __attribute__ ((dllexport))#else#define PUBLIC __declspec(dllexport)#endif#else#ifdef __GNUC__#define PUBLIC __attribute__ ((dllimport))#else#define PUBLIC __declspec(dllimport)#endif#endif#define LOCAL #else#if __GNUC__ >= 4#define PUBLIC __attribute__ ((visibility ("default")))#define LOCAL __attribute__ ((visibility ("hidden")))#else#define PUBLIC#define LOCAL#endif #endif不同版本API 兼容性遵守語(yǔ)義化版本 2.0.0規(guī)則。
二、API調(diào)用
簡(jiǎn)介
API調(diào)用主要對(duì)模型解析，網(wǎng)絡(luò)構(gòu)建，輸入設(shè)定，輸出獲取四個(gè)步驟進(jìn)行簡(jiǎn)要介紹，詳細(xì)說(shuō)明參見(jiàn)API詳解部分。
步驟1. 模型解析
TNN tnn; TNN_NS::ModelConfig model_config; //proto文件內(nèi)容存入proto_buffer model_config.params.push_back(proto_buffer); //model文件內(nèi)容存入model_buffer model_config.params.push_back(model_buffer);TNN模型解析需配置ModelConfig params參數(shù)，傳入proto和model文件內(nèi)容，并調(diào)用TNN Init接口即可完成模型解析。
步驟2. 網(wǎng)絡(luò)構(gòu)建
TNN_NS::NetworkConfig config; config.device_type = TNN_NS::DEVICE_ARM; TNN_NS::Status error; auto net_instance = tnn.CreateInst(config, error);TNN網(wǎng)絡(luò)構(gòu)建需配置NetworkConfig，device_type可配置ARM， OPENCL， METAL等多種加速方式，通過(guò)CreateInst接口完成網(wǎng)絡(luò)的構(gòu)建。 華為NPU需要特殊指定network類(lèi)型以及一個(gè)可選的cache路徑。cache路徑為存om文件的path,如("/data/local/tmp/")，空則表示不存om文件，每次運(yùn)行都使用IR翻譯并從內(nèi)存讀入模型。
config.network_type = TNN_NS::NETWORK_TYPE_HUAWEI_NPU; //Huawei_NPU可選：存om的Cache路徑 //add for cache; When using NPU, it is the path to store the om i.e. config.cache_path = "/data/local/tmp/npu_test/"; config.cache_path = "";步驟3. 輸入設(shè)定
auto status = instance->SetInputMat(input_mat, input_cvt_param);TNN輸入設(shè)定通過(guò)調(diào)用SetInputMat接口完成，需要傳入的數(shù)據(jù)保存在input_mat中，input_cvt_param可設(shè)置scale和bias相關(guān)轉(zhuǎn)換參數(shù)。
步驟4. 輸出獲取
auto status = instance->GetOutputMat(output_mat);TNN輸出獲取通過(guò)調(diào)用GetOutputMat接口完成，輸出結(jié)果將按照特定格式保存在output_mat中。
二、API詳解
API目錄結(jié)構(gòu)
. └── tnn├── core│?? ├── macro.h # 常用宏定義│?? ├── common.h # 定義常用結(jié)構(gòu)│?? ├── status.h # 接口狀態(tài)│?? ├── blob.h # 負(fù)責(zé)數(shù)據(jù)傳遞│?? ├── instance.h # 網(wǎng)絡(luò)實(shí)例│?? └── tnn.h # 模型解析├── utils│?? ├── bfp16_utils.h # bfp16轉(zhuǎn)換工具│ ├── blob_converter.h # blob輸入輸出數(shù)據(jù)工具│ ├── cpu_utils.h # CPU性能特定優(yōu)化工具│?? ├── data_type_utils.h # 網(wǎng)絡(luò)數(shù)據(jù)類(lèi)型解析工具│?? ├── dims_vector_utils.h # blob尺寸計(jì)算工具│?? └── half_utils.h # fp16轉(zhuǎn)換工具└── version.h # 編譯構(gòu)建信息1. core/macro.h
提供不同平臺(tái)Log宏，不同數(shù)據(jù)類(lèi)型最大最小值宏，PUBLIC宏定義，以及部分?jǐn)?shù)據(jù)pack轉(zhuǎn)換等宏定義。
2. core/common.h
DataType：定義不同數(shù)據(jù)類(lèi)型枚舉值。
DataFormat：定義Blob Data不同數(shù)據(jù)排布方式。
NetworkType：定義不同網(wǎng)絡(luò)構(gòu)建類(lèi)型，默認(rèn)構(gòu)建TNN網(wǎng)絡(luò)，支持第三方庫(kù)網(wǎng)絡(luò)構(gòu)建。
DeviceType：用于指定網(wǎng)絡(luò)運(yùn)行設(shè)備及加速方式。
ModelType：定義模型類(lèi)型，TNN默認(rèn)解析模型為T(mén)NN模型，同時(shí)支持其他第三方庫(kù)模型格式傳入。
SHARED_MEMORY_MODE_DEFAULT: 僅支持同一instance不同blob間內(nèi)存共享?SHARE_MEMORY_MODE_SHARE_ONE_THREAD: 支持同一線程的不同Instance內(nèi)存共享?SHARE_MEMORY_MODE_SET_FROM_EXTERNAL: 支持instance內(nèi)存由外部傳入，共享方式由調(diào)用側(cè)決定，線程間共享需處理同步問(wèn)題，內(nèi)存分配釋放均需調(diào)用側(cè)維護(hù)。
struct PUBLIC NetworkConfig {// device type default cpu DeviceType device_type = DEVICE_NAIVE;// device id default 0int device_id = 0;// blob data format decided by deviceDataFormat data_format = DATA_FORMAT_AUTO;// network type default internalNetworkType network_type = NETWORK_TYPE_DEFAULT;// raidnet instances not share memory with othersShareMemoryMode share_memory_mode = SHARE_MEMORY_MODE_DEFAULT;// dependent library pathstd::vector<std::string> library_path = {}; // compute precisionPrecision precision = PRECISION_AUTO; };NetworkConfig參數(shù)說(shuō)明：
- device_type: 默認(rèn)為DEVICE_NAIVE, 不包含特定平臺(tái)加速指令實(shí)現(xiàn)。
- Android使用DEVICE_ARM、DEVICE_OPENCL加速。
- iOS使用DEVICE_ARM,?DEVICE_METAL加速。
- device_id: 默認(rèn)為0，多個(gè)設(shè)備支持通過(guò)device_id選擇，移動(dòng)端可不配置。
- data_format: 默認(rèn)為tnn自動(dòng)選擇blob數(shù)據(jù)排布方式進(jìn)行加速，可通過(guò)此參數(shù)設(shè)定特定blob數(shù)據(jù)排布進(jìn)行加速。
- network_type: 支持構(gòu)建tnn自定義網(wǎng)絡(luò)以及第三方網(wǎng)絡(luò)，當(dāng)前開(kāi)源版本僅支持構(gòu)建tnn網(wǎng)絡(luò)。
- share_memory_mode: tnn instance內(nèi)存共享方式。
- library_path: 支持外部依賴(lài)庫(kù)加載，iOS metal kernel庫(kù)放在app非默認(rèn)路徑需配置此參數(shù)。
ModelConfig參數(shù)說(shuō)明：
- model_type: TNN當(dāng)前開(kāi)源版本僅支持傳入MODEL_TYPE_TNN，?MODEL_TYPE_NCNN兩種模型格式。
- params: TNN模型需傳入proto文件內(nèi)容以及model文件路徑。NCNN模型需傳入param文件內(nèi)容以及bin文件路徑。
3. core/status.h
Status定義于status.h頭文件中。
enum StatusCode {TNN_OK = 0x0,// param errcodeTNNERR_PARAM_ERR = 0x1000,TNNERR_INVALID_NETCFG = 0x1002,... }class PUBLIC Status { public:Status(int code = TNN_OK, std::string message = "OK");Status &operator=(int code);bool operator==(int code_);bool operator!=(int code_);operator int();operator bool();std::string description();private:int code_;std::string message_; }當(dāng)Status code不為T(mén)NN_OK，通過(guò)description接口可返回錯(cuò)誤描述信息。
4. core/blob.h
// @brief BlobDesc blob data info struct PUBLIC BlobDesc {// deivce_type describes devie cpu, gpu, ...DeviceType device_type = DEVICE_NAIVE;// data_type describes data precion fp32, in8, ...DataType data_type = DATA_TYPE_FLOAT;// data_format describes data order nchw, nhwc, ...DataFormat data_format = DATA_FORMAT_AUTO;// DimsVector describes data dimsDimsVector dims;// name describes the blob namestd::string name; };struct PUBLIC BlobHandle {void *base = NULL;uint64_t bytes_offset = 0; };// @brief Blob tnn data store and transfer interface. class PUBLIC Blob { public:...//@brief create Blob with blob descript and data handleBlob(BlobDesc desc, BlobHandle handle);... };Blob當(dāng)前主要由BlobDesc以及BlobHandle構(gòu)成，其中BlobDesc描述Blob相關(guān)結(jié)構(gòu)信息，BlobHandle用于讀取和存儲(chǔ)Blob數(shù)據(jù)。
BlobDesc用于描述device_type,?data_type,?data_format,?dims,?name信息。
dims描述blob維度信息，dims存儲(chǔ)尺寸與data_format無(wú)關(guān)：
- dims尺寸為4，存儲(chǔ)尺寸對(duì)應(yīng)N，C，H，W。
- dims尺寸為5，存儲(chǔ)尺寸對(duì)應(yīng)N，C，D，H，W。
當(dāng)前不同平臺(tái)blob輸入輸出數(shù)據(jù)類(lèi)型及排布如下：
- ARM：CPU內(nèi)存， NC4HW4.
- OPENCL: GPU顯存（clImage）， NHC4W4. 其中NH為clImage高，C4W4為clImage寬。
- METAL: GPU顯存（metal)， NC4HW4.
- `HUAWEI_NPU: CPU內(nèi)存, NCHW.
其中最后4代表pack 4, C4代表最后1位4由4個(gè)C進(jìn)行pack。
5. core/instance.h
class PUBLIC Instance { public:Instance(NetworkConfig& net_config, ModelConfig& model_config);~Instance();// init with model interpeter and inputs shape.Status Init(std::shared_ptr<AbstractModelInterpreter> interpreter, InputShapesMap inputs_shape);// deinit, release networkStatus DeInit();// return memory bytes required for forwardStatus GetForwardMemorySize(int& memory_size);// set memory to tnn instance. if success, return status code zero.// only instance created with SHARE_MEMORY_MODE_SET_FROM_EXTERNAL can be set from external.// the memory size need >= GetForwardMemorySize().// releasing or otherwise using the memory for other purposes during the tnn network run // will result in undefined behavior.Status SetForwardMemory(void* memory);// reshape instance with new input shapesStatus Reshape(const InputShapesMap& inputs);// get tnn command queueStatus GetCommandQueue(void** command_queue);// @brief tnn instance network infer, it will wait until all layer infer complete.Status Forward();...// tnn instance network infer async.// device gpu, all layer infer complete will call Callback.Status ForwardAsync(Callback call_back);// get all input blobsStatus GetAllInputBlobs(BlobMap& blobs);// get all output blobsStatus GetAllOutputBlobs(BlobMap& blobs);// set threads run on cpu virtual Status SetCpuNumThreads(int num_threads);...// set input Mat, if input_name is not set, take the first input as defaultStatus SetInputMat(std::shared_ptr<Mat> mat,MatConvertParam param,std::string input_name = "");// get output Mat, if output_name is not set, take the first output as defaultStatus GetOutputMat(std::shared_ptr<Mat>& mat,MatConvertParam param = MatConvertParam(),std::string output_name = "", DeviceType device = DEVICE_ARM, MatType mat_type = NCHW_FLOAT);};Instance接口說(shuō)明：
- Instance和Init接口正常均有TNN CreateInst接口實(shí)現(xiàn)調(diào)用，用于生成Instance網(wǎng)絡(luò)實(shí)例。
- GetForwardMemorySize可獲取Instance所有Blob所需內(nèi)存大小，SetForwardMemory用于傳入外部?jī)?nèi)存。對(duì)于SHARE_MEMORY_MODE_SET_FROM_EXTERNAL內(nèi)存模式構(gòu)建的Instance，內(nèi)存需由外部傳入， 傳入內(nèi)存實(shí)際大小不得小于GetForwardMemorySize返回值大小。
- Reshape接口支持重新設(shè)定網(wǎng)絡(luò)輸入輸出，當(dāng)前實(shí)現(xiàn)Reshape并不會(huì)重新分配內(nèi)存，所以Reshape傳入尺寸不得大于初始化網(wǎng)絡(luò)尺寸。
- GetCommandQueue接口支持獲取網(wǎng)絡(luò)運(yùn)行對(duì)應(yīng)的command queue，同一command queue消息順序執(zhí)行。
- GetAllInputBlobs和?GetAllOutputBlobs分別用于獲取輸入輸出blob。
- SetCpuNumThreads可設(shè)置CPU線程并行數(shù)。
- Forward為網(wǎng)絡(luò)運(yùn)行同步接口，ForwardAsync為網(wǎng)絡(luò)運(yùn)行異步接口。
- SetInputMat用于設(shè)定輸入Mat，其中MatConvertParam可設(shè)定轉(zhuǎn)換參數(shù)，對(duì)于多輸入網(wǎng)絡(luò)，可用input_name區(qū)分。
- GetOutputMat用于獲取輸出結(jié)果并保存在輸出Mat中，其中MatConvertParam可設(shè)定轉(zhuǎn)換參數(shù)，對(duì)于多輸出網(wǎng)絡(luò)，可用output_name區(qū)分，DeviceType可指定輸出Mat Memory構(gòu)建在CPU還是GPU，MatType可用于設(shè)定輸出Mat數(shù)據(jù)排列方式。
6. core/tnn.h
class PUBLIC TNN { public:...Status Init(ModelConfig& config);// denit tnn implement, release model interpreter.Status DeInit();// add output to the model.// if output_name of blob not found, then search output_index of layer.Status AddOutput(const std::string& output_name, int output_index = 0);// create tnn network instance with network config and inputs shape.// if inputs shape not set, use default from model.std::shared_ptr<Instance> CreateInst(NetworkConfig& config, Status& status,InputShapesMap inputs_shape = InputShapesMap());... };TNN接口說(shuō)明：
- Init接口：負(fù)責(zé)模型數(shù)據(jù)傳入并解析，需配置并傳入ModelConfig。
- DeInit接口: 負(fù)責(zé)tnn implement釋放，默認(rèn)析構(gòu)函數(shù)可自動(dòng)釋放。
- AddOutput接口：支持增加模型輸出，可將網(wǎng)絡(luò)任意一層輸出定義為模型輸出。
- CreateInst接口：負(fù)責(zé)網(wǎng)絡(luò)實(shí)例Instance構(gòu)建。
7. utils/bfp16_utils.h
接口提供了cpu內(nèi)存fp32和bfp16轉(zhuǎn)換工具。
8. utils/blob_convert.h
class PUBLIC BlobConverter { public:explicit BlobConverter(Blob* blob);virtual Status ConvertToMat(Mat& image, MatConvertParam param, void* command_queue);virtual Status ConvertFromMat(Mat& image, MatConvertParam param, void* command_queue);virtual Status ConvertToMatAsync(Mat& image, MatConvertParam param, void* command_queue);virtual Status ConvertFromMatAsync(Mat& image, MatConvertParam param, void* command_queue);private:Blob* blob_;std::shared_ptr<BlobConverterAcc> impl_ = nullptr; };通過(guò)ConvertToMat可將blob數(shù)據(jù)按照Mat格式傳入Mat，ConvertFromMat可將Mat數(shù)據(jù)按照blob格式傳入blob, 接口對(duì)應(yīng)的command_queue可通過(guò) Instance?GetCommandQueue接口獲取。
Mat定義于blob_converter.h中，
class PUBLIC Mat { public:...Mat(DeviceType device_type, MatType mat_type, DimsVector shape_dims, void* data);Mat(DeviceType device_type, MatType mat_type, DimsVector shape_dims);... };其中MatType支持常用的CV輸入輸出布局，且DeviceType可設(shè)定為CPU，GPU。
typedef enum {INVALID = -1,N8UC3 = 0x00,N8UC4 = 0x01,NGRAY = 0x10,NNV21 = 0x11,NNV12 = 0x12,NCHW_FLOAT = 0x20, } PUBLIC MatType;同時(shí)提供常用預(yù)處理，后處理支持，支持設(shè)定scale, bias參數(shù)設(shè)定以及reverse channel適配bgr, rgb等場(chǎng)景。
struct PUBLIC MatConvertParam {std::vector<float> scale = {1.0f, 1.0f, 1.0f, 1.0f};std::vector<float> bias = {0.0f, 0.0f, 0.0f, 0.0f};bool reverse_channel = false; };9. utils/cpu_utils.h
提供CPU線程核綁定以及省電模式設(shè)定相關(guān)工具。
10. utils/data_type_utils.h
提供DataType尺寸和名稱(chēng)轉(zhuǎn)換相關(guān)工具。
11. utils/dims_vector_utils.h
提供常用blob dims計(jì)算比較工具。
12. utils/half_utils.h
接口提供了cpu內(nèi)存fp32和fp16轉(zhuǎn)換工具。
總結(jié)
以上是生活随笔為你收集整理的TNN API说明文档的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。
- 上一篇： TNN MatConvertParam参
- 下一篇： CMake学习笔记