TNN API說明文檔

TNN：https://github.com/Tencent/TNN

說明文檔：https://github.com/Tencent/TNN/blob/master/doc/cn/user/api.md

---

目錄

TNN API說明文檔

一、API兼容性

二、API調用

簡介

步驟1. 模型解析

步驟2. 網絡構建

步驟3. 輸入設定

步驟4. 輸出獲取

二、API詳解

API目錄結構

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所有對外暴露接口均通過PUBLIC宏顯示聲明，非暴露接口符號均不可見。

#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 兼容性遵守語義化版本 2.0.0規則。

二、API調用

簡介

API調用主要對模型解析，網絡構建，輸入設定，輸出獲取四個步驟進行簡要介紹，詳細說明參見API詳解部分。

步驟1. 模型解析

TNN tnn; TNN_NS::ModelConfig model_config; //proto文件內容存入proto_buffer model_config.params.push_back(proto_buffer); //model文件內容存入model_buffer model_config.params.push_back(model_buffer);

TNN模型解析需配置ModelConfig params參數，傳入proto和model文件內容，并調用TNN Init接口即可完成模型解析。

步驟2. 網絡構建

TNN_NS::NetworkConfig config; config.device_type = TNN_NS::DEVICE_ARM; TNN_NS::Status error; auto net_instance = tnn.CreateInst(config, error);

TNN網絡構建需配置NetworkConfig，device_type可配置ARM， OPENCL， METAL等多種加速方式，通過CreateInst接口完成網絡的構建。 華為NPU需要特殊指定network類型以及一個可選的cache路徑。cache路徑為存om文件的path,如("/data/local/tmp/")，空則表示不存om文件，每次運行都使用IR翻譯并從內存讀入模型。

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. 輸入設定

auto status = instance->SetInputMat(input_mat, input_cvt_param);

TNN輸入設定通過調用SetInputMat接口完成，需要傳入的數據保存在input_mat中，input_cvt_param可設置scale和bias相關轉換參數。

步驟4. 輸出獲取

auto status = instance->GetOutputMat(output_mat);

TNN輸出獲取通過調用GetOutputMat接口完成，輸出結果將按照特定格式保存在output_mat中。

二、API詳解

API目錄結構

. └── tnn├── core│?? ├── macro.h # 常用宏定義│?? ├── common.h # 定義常用結構│?? ├── status.h # 接口狀態│?? ├── blob.h # 負責數據傳遞│?? ├── instance.h # 網絡實例│?? └── tnn.h # 模型解析├── utils│?? ├── bfp16_utils.h # bfp16轉換工具│ ├── blob_converter.h # blob輸入輸出數據工具│ ├── cpu_utils.h # CPU性能特定優化工具│?? ├── data_type_utils.h # 網絡數據類型解析工具│?? ├── dims_vector_utils.h # blob尺寸計算工具│?? └── half_utils.h # fp16轉換工具└── version.h # 編譯構建信息

1. core/macro.h

提供不同平臺Log宏，不同數據類型最大最小值宏，PUBLIC宏定義，以及部分數據pack轉換等宏定義。

2. core/common.h

DataType：定義不同數據類型枚舉值。
DataFormat：定義Blob Data不同數據排布方式。
NetworkType：定義不同網絡構建類型，默認構建TNN網絡，支持第三方庫網絡構建。
DeviceType：用于指定網絡運行設備及加速方式。
ModelType：定義模型類型，TNN默認解析模型為TNN模型，同時支持其他第三方庫模型格式傳入。

typedef enum {// defaultSHARE_MEMORY_MODE_DEFAULT = 0,// same thread tnn instance share blob memorySHARE_MEMORY_MODE_SHARE_ONE_THREAD = 1,// set blob memory from external, different thread share blob memory need// synchronizeSHARE_MEMORY_MODE_SET_FROM_EXTERNAL = 2 } ShareMemoryMode;

SHARED_MEMORY_MODE_DEFAULT: 僅支持同一instance不同blob間內存共享?SHARE_MEMORY_MODE_SHARE_ONE_THREAD: 支持同一線程的不同Instance內存共享?SHARE_MEMORY_MODE_SET_FROM_EXTERNAL: 支持instance內存由外部傳入，共享方式由調用側決定，線程間共享需處理同步問題，內存分配釋放均需調用側維護。

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參數說明：

• device_type: 默認為DEVICE_NAIVE, 不包含特定平臺加速指令實現。
  • Android使用DEVICE_ARM、DEVICE_OPENCL加速。
  • iOS使用DEVICE_ARM,?DEVICE_METAL加速。
• device_id: 默認為0，多個設備支持通過device_id選擇，移動端可不配置。
• data_format: 默認為tnn自動選擇blob數據排布方式進行加速，可通過此參數設定特定blob數據排布進行加速。
• network_type: 支持構建tnn自定義網絡以及第三方網絡，當前開源版本僅支持構建tnn網絡。
• share_memory_mode: tnn instance內存共享方式。
• library_path: 支持外部依賴庫加載，iOS metal kernel庫放在app非默認路徑需配置此參數。

struct PUBLIC ModelConfig {ModelType model_type = MODEL_TYPE_TNN;// tnn model need two params: order is proto content, model content.// ncnn need two: params: order is param content, bin content.// openvino model need two params: order is xml content, model path.// coreml model need one param: coreml model directory path.// snpe model need one param: dlc model directory path.// hiai model need two params: order is model name, model file path.// atlas model need one param: config string.std::vector<std::string> params; };

ModelConfig參數說明：

• model_type: TNN當前開源版本僅支持傳入MODEL_TYPE_TNN，?MODEL_TYPE_NCNN兩種模型格式。
• params: TNN模型需傳入proto文件內容以及model文件路徑。NCNN模型需傳入param文件內容以及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_; }

當Status code不為TNN_OK，通過description接口可返回錯誤描述信息。

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當前主要由BlobDesc以及BlobHandle構成，其中BlobDesc描述Blob相關結構信息，BlobHandle用于讀取和存儲Blob數據。

BlobDesc用于描述device_type,?data_type,?data_format,?dims,?name信息。

dims描述blob維度信息，dims存儲尺寸與data_format無關：

• dims尺寸為4，存儲尺寸對應N，C，H，W。
• dims尺寸為5，存儲尺寸對應N，C，D，H，W。

當前不同平臺blob輸入輸出數據類型及排布如下：

• ARM：CPU內存， NC4HW4.
• OPENCL: GPU顯存（clImage）， NHC4W4. 其中NH為clImage高，C4W4為clImage寬。
• METAL: GPU顯存（metal)， NC4HW4.
• `HUAWEI_NPU: CPU內存, NCHW.

其中最后4代表pack 4, C4代表最后1位4由4個C進行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接口說明：

• Instance和Init接口正常均有TNN CreateInst接口實現調用，用于生成Instance網絡實例。
• GetForwardMemorySize可獲取Instance所有Blob所需內存大小，SetForwardMemory用于傳入外部內存。對于SHARE_MEMORY_MODE_SET_FROM_EXTERNAL內存模式構建的Instance，內存需由外部傳入， 傳入內存實際大小不得小于GetForwardMemorySize返回值大小。
• Reshape接口支持重新設定網絡輸入輸出，當前實現Reshape并不會重新分配內存，所以Reshape傳入尺寸不得大于初始化網絡尺寸。
• GetCommandQueue接口支持獲取網絡運行對應的command queue，同一command queue消息順序執行。
• GetAllInputBlobs和?GetAllOutputBlobs分別用于獲取輸入輸出blob。
• SetCpuNumThreads可設置CPU線程并行數。
• Forward為網絡運行同步接口，ForwardAsync為網絡運行異步接口。
• SetInputMat用于設定輸入Mat，其中MatConvertParam可設定轉換參數，對于多輸入網絡，可用input_name區分。
• GetOutputMat用于獲取輸出結果并保存在輸出Mat中，其中MatConvertParam可設定轉換參數，對于多輸出網絡，可用output_name區分，DeviceType可指定輸出Mat Memory構建在CPU還是GPU，MatType可用于設定輸出Mat數據排列方式。

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接口說明：

• Init接口：負責模型數據傳入并解析，需配置并傳入ModelConfig。
• DeInit接口: 負責tnn implement釋放，默認析構函數可自動釋放。
• AddOutput接口：支持增加模型輸出，可將網絡任意一層輸出定義為模型輸出。
• CreateInst接口：負責網絡實例Instance構建。

7. utils/bfp16_utils.h

接口提供了cpu內存fp32和bfp16轉換工具。

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; };

通過ConvertToMat可將blob數據按照Mat格式傳入Mat，ConvertFromMat可將Mat數據按照blob格式傳入blob, 接口對應的command_queue可通過 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可設定為CPU，GPU。

typedef enum {INVALID = -1,N8UC3 = 0x00,N8UC4 = 0x01,NGRAY = 0x10,NNV21 = 0x11,NNV12 = 0x12,NCHW_FLOAT = 0x20, } PUBLIC MatType;

同時提供常用預處理，后處理支持，支持設定scale, bias參數設定以及reverse channel適配bgr, rgb等場景。

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線程核綁定以及省電模式設定相關工具。

10. utils/data_type_utils.h

提供DataType尺寸和名稱轉換相關工具。

11. utils/dims_vector_utils.h

提供常用blob dims計算比較工具。

12. utils/half_utils.h

接口提供了cpu內存fp32和fp16轉換工具。

總結

以上是生活随笔為你收集整理的TNN API说明文档的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。