版本：2.9.0

TORQ-Toolkit Python API 参考

概述

TORQ-Toolkit 是一款面向开发者的专业开发套件，用户可通过它在 PC 平台上实现模型转换、推理以及性能评估等功能。

本文对 TORQ-Toolkit 的各个 API 功能、参数以及返回值定义进行说明。

支持硬件平台

TORQ-Toolkit 当前版本支持芯片的型号如下。

支持硬件平台
A200
A210

系统依赖说明

使用 TORQ-Toolkit 时需要满足以下运行环境要求。

运行环境	要求
操作系统版本	Ubuntu 24.04 (x64)
Python 版本	3.12

适用深度学习框架

TORQ-Toolkit 支持的深度学习框架包括 Caffe、 TensorFlow、 TensorFlow Lite (TF Lite) 和 ONNX。版本对应关系如下：

深度学习框架	支持版本
Caffe	1.0
TensorFlow	1.15
TensorFlow Lite (TF Lite)	2.4
ONNX	1.7.0~ 1.12.0

说明

由于 TensorFlow 版本兼容特性，TORQ-Toolkit 理论上也可以支持 TensorFlow V1.12.0 之前版本导出的 pb 文件。关于 TensorFlow 版本兼容性的更多信息，可参考 TensorFlow 版本兼容性指南

构建 TF Lite 模型前，需确认 schema 版本与 TORQ-Toolkit 相同。不同版本的 schema 可能导致加载失败。

TORQ-Toolkit 采用的 Caffe protocol 是以 Berkeley 官方版本扩展而来，新增了若干自定义算子。

ONNX 版本体系中，Release Version和Opset Version/IR Version 的关联关系参考 onnxruntime 官网说明。

TORQ-Toolkit 调用流程

关于 TORQ-Toolkit 调用流程，参考 TORQ SDK 介绍。

API 详细说明

TORQ

功能描述

初始化 TORQ 对象。在使用 TORQ-Toolkit 的所有 API 接口时，都需要先调用 TORQ() 方法初始化 TORQ 对象。

参数

参数	含义
verbose	控制是否打印详细日志（布尔值，默认 False）。
verbose_file	日志输出文件路径（仅当 verbose=True 时生效，日志将写入指定文件）。

示例代码

# 打印详细的日志信息

torq = TORQ(verbose=True, verbose_file="torq.log")

config

功能描述

配置模型，设置模型转换参数。

在构建 TORQ 模型之前，需对模型进行通道均值、量化类型等配置。

参数

参数	含义
mean_values	输入的均值。参数格式设置为列表格式，列表中包含一个或多个均值子列表。多输入模型应配置多个子列表，每个子列表的长度与该输入的通道数一致。例如 `[[128,128,128]]` ，表示一个输入的三个通道的值减去 128。默认值为 `None`，表示所有的 mean 值为 0。
std_values	输入的归一化值。参数格式设置为列表格式，列表中包含一个或多个归一化值子列表。多输入模型应配置多个子列表，每个子列表的长度与该输入的通道数一致。例如 `[[128,128,128]]` ，表示设置一个输入的三个通道的值减去均值后再除以 128。默认值为 `None` ，表示所有的 std 值为 1。
quantized_dtype	量化类型。默认值为 `w8a8`。a200 支持量化类型：`w8a8 (int8)`，`w16a16_int16 (int16)`。 a210 支持量化类型： `w4a16 (int4)`，`w5a16`，`w6a16`，`w7a16`，`w8a8 (int8)`，`w8a16`，`w16a16_int16 (int16)`，`w16a16_fp16 (fp16)`，`w16a16_bf16 (bf16)`。
quantized_method	目前支持 `layer` 或者 `channel` 。
target_platform	指定 TORQ 模型运行的目标芯片平台。目前支持参数为 `a200`、`a210` 和 `x86_ref`。该参数对大小写不敏感，默认值为 `None`。
dynamic_input	根据用户指定的多组输入 shape，来模拟动态输入。转换 TORQ 模型后推理时，需传入对应 shape 的输入数据。格式为 `[[input0_shapeA,input1_shapeA, ...],[input0_shapeB,input1_shapeB,...],...]`。默认值为 `None`，实验性功能。假设原始模型只有一个输入（如 shape=`[1,3,224,224]`）或原始模型的为动态输入 shape（如 shape=`[1,3,height,width]` 或 `[1,3,-1,-1]`）。部署时该模型需要支持多种不同的输入shape （如 `[1,3,224,224]`,`[1,3,192,192]`和`[1,3,160,160]`）。此时dynamic_input= `[[[1,3,224,224]],[[1,3,192,192]],[[1,3,160,160]]]`。
enable_flash_attention	是否启用 Flash Attention。默认值为 False。

返回值

0：配置正确。
-1：配置错误。

示例代码

# model config
torq.config(mean_values=[[103.94, 116.78, 123.68]], std_values=[[58.82, 58.82, 58.82]], target_platform='a210')  

模型加载

TORQ-Toolkit 目前支持 ONNX、Huggingface、Caffe、 TensorFlow、 TensorFlow Lite 等模型的加载转换。用户可以根据不同框架的模型选择合适的接口进行加载，下面是各种框架的模型加载接口的简要介绍。

load_onnx

功能描述

加载 ONNX 模型。

参数

参数	含义
model	ONNX 模型文件（文件后缀为.onnx）路径。
inputs	模型输入节点（tensor 名），支持多个输入节点，所有输入节点名放在一个列表中。默认值为`None`，表示从模型里获取。
input_size_list	每个输入节点对应的 shape，所有输入 shape 放在一个列表中。如设置了`inputs`，则也需要设置`input_size_list`。默认值为`None`。
outputs	模型的输出节点（tensor 名），支持多个输出节点，所有输出节点名放在一个列表中。默认值为`None`，表示从模型里获取。

返回值

0：加载成功。
-1：加载失败。

示例代码

# 从当前目录加载arcface模型

ret = torq.load_onnx(model='./arcface.onnx')  

load_huggingface

功能描述

加载 Huggingface 模型。

参数

参数	含义
model	Huggingface 模型目录的路径。

返回值

0：加载成功。
-1：加载失败。

示例代码

# 从当前目录加载qwen0.5模型

ret = torq.load_huggingface(model='./qwen0.5')  

load_caffe

功能描述

加载 Caffe 模型。

参数

参数	含义
model	Caffe 模型文件（文件后缀为.prototxt）路径。
blobs	Caffe 模型的二进制数据文件（文件后缀为.caffemodel）路径。
input_name	Caffe 模型存在多输入时，可以通过该参数指定输入层名的顺序。如`['input1','input2','input3']`，注意名字需要与模型输入名一致；默认值为`None`，表示按 Caffe 模型文件（文件后缀为.prototxt）自动确定。

返回值

0：加载成功。
-1：加载失败。

示例代码

# 从当前路径加载mobilenet_v2模型
ret = torq.load_caffe(model='./mobilenet_v2.prototxt', blobs='./mobilenet_v2.caffemodel')  

load_tensorflow

功能描述

加载 TensorFlow 模型。

参数

参数	含义
tf_pb	TensorFlow 模型文件（文件后缀为.pb）路径。
inputs	模型的输入节点（tensor 名），支持多个输入节点。所有输入节点名放在一个列表中。
input_size_list	每个输入节点对应的 shape，所有输入 shape 放在一个列表中。如示例中的 `mobilenetv2-12` 模型，其输入节点对应的输入 shape 是 [[1, 3, 224, 224]]。
outputs	模型的输出节点（tensor 名），支持多个输出节点。所有输出节点名放在一个列表中。

返回值

0：加载成功。
-1：加载失败。

示例代码

# 从当前目录加载ssd_mobilenet_v1_coco_2017_11_17模型

ret = torq.load_tensorflow(tf_pb='./ssd_mobilenet_v1_coco_2017_11_17.pb', inputs=['Preprocessor/sub'], outputs=['concat', 'concat_1'], input_size_list=[[300, 300, 3]])  

load_tflite

功能描述

加载 TensorFlow Lite 模型。

参数

参数	含义
model	TensorFlow Lite 模型文件（文件后缀为.tflite）路径。
input_is_nchw	模型的输入的 layout 是否已经是 NCHW 格式。默认值为 `False`，即默认输入 layout 为 NHWC 格式。
inputs	模型的输入节点（tensor 名），支持多个输入节点。所有输入节点名放在一个列表中。
input_size_list	每个输入节点对应的 shape，所有输入 shape 放在一个列表中。如示例中的`mobilenetv2-12`模型，其输入节点对应的输入 shape 是 [[1, 3, 224, 224]]。
outputs	模型的输出节点（tensor 名），支持多个输出节点。所有输出节点名放在一个列表中。

返回值

0：加载成功。
-1：加载失败。

示例代码

# 从当前目录加载mobilenet_v1模型

ret = torq.load_tflite(model='./mobilenet_v1_1.0_224.tflite', inputs=['input'], input_size_list=[[1, 224, 224, 3]], outputs=['MobilenetV1/Predictions/Reshape_1'])  

build

功能描述

构建 TORQ 模型。构建模型时，用户可以选择是否进行量化，量化可以减小模型的大小和提高在 UCA 上的性能。

参数

参数	含义
do_quantization	是否对模型进行量化。默认值为 `True`。
dataset	量化校正的数据集。目前支持文本文件格式（文件名后缀为 .txt）。用于校正的图片（jpg 或 png 格式）或 npy 文件路径需放到一个.txt 文件中。文本文件里的每一行代表一条路径信息。暂不支持对多个输入的模型做量化。

返回值

0：构建成功。
-1：构建失败。

示例代码

# 构建TORQ模型， 并且做量化

ret = torq.build(do_quantization=True, dataset='./dataset.txt')  

export_torq

功能描述

导出并保存 TORQ 模型文件到指定目录中（后缀为.torq），用于模型部署。

参数

参数	含义
export_path	导出模型文件的路径。

返回值

0：导出成功。
-1：导出失败。

示例代码

# 将构建好的TORQ模型保存到当前路径的 mobilenet_v1.torq 目录中

ret = torq.export_torq(export_path='./mobilenet_v1.torq')  

load_torq

功能描述

加载 TORQ 模型。

说明

加载后的模型仅可用于连接 NPU 硬件时的推理或获取性能数据，运行平台为模拟器或进行量化精度分析不适用。

参数

参数	含义
path	TORQ 模型文件路径。

返回值

0：加载成功。
-1：加载失败。

示例代码

# 从当前路径加载mobilenet_v1.torq模型

ret = torq.load_torq(path='./mobilenet_v1.torq')  

accuracy_analysis

功能描述

量化精度损失分析。

对模型进行逐层输出结果的精度损失分析，指标为 cos 余弦相似度和 L2 相对欧式距离。

参数

参数	含义
inputs	精度损失分析的参考输入，格式为 [input_name: np.ndarray]
output_dir	分析结果输出目录。默认值为 `./snapshot`
target	目标硬件平台，支持`a200`、 `a210`。默认值为模拟器，即在 PC 使用工具时，模型在软件模拟器上运行。

返回值

0：加载成功。
-1：加载失败。

示例代码

# 加载参考输入
input_tensor = np.load("input.npy")

inputs = {"images": input_tensor}
torq.accuracy_analysis(inputs=inputs, target="a210")

init_runtime

功能描述

初始化运行时环境。

在模型推理或性能评估之前，必须先初始化运行时环境，明确模型的运行平台。运行平台可为具体的目标硬件平台或软件模拟器。

参数

参数	含义
target	目标硬件平台，支持`a200`、 `a210`。默认值为模拟器，即在 PC 使用工具时，模型在软件模拟器上运行。
perf_debug	进行性能评估时是否开启 debug 模式。在 debug 模式下，可以获取到每一层的运行时间，否则只能获取模型运行的总时间。默认值为 `False`。
eval_mem	是否进入内存评估模式。进入内存评估模式后，可以调用`eval_memory`接口获取模型运行时的内存使用情况。默认值为 `False`。

返回值

0：初始化成功。
-1：初始化失败。

示例代码

# 初始化运行时环境

ret = torq.init_runtime(target='a210') 

inference

功能描述

对当前模型进行推理，并返回推理结果。根据初始化运行环境时设置 target 的设备平台，得到的是模型在硬件平台或者模拟器上的推理结果。

说明

模型推理前，需先构建或加载一个 TORQ 模型。

参数

参数	含义
inputs	待推理的输入列表，格式为 ndarray。
data_format	输入数据的 layout 列表， `nchw` 或 `nhwc`，只对 4 维的输入有效。默认值为 `None`，表示所有输入的 layout 都为 NHWC。
inputs_pass_through	输入的透传列表。默认值为 `None`，表示所有输入都不透传。该参数的值是一个列表，每个元素代表对应输入是否透传。1代表透传，0代表不透传。比如要透传 input0，不透传 input1，则该参数的值为[1,0]。

返回值

推理结果，类型是 ndarray list。

示例代码

对于分类模型，如 mobilenet_v1，代码如下（完整代码参考 example/tflite/mobilenet_v1）：

# 使用模型对图片进行推理， 得到TOP5结果

outputs = torq.inference(inputs=[img])
show_outputs(outputs)  

输出的 TOP5 结果如下：

----TOP 5-----

[ 156] score:0.928223 class:"Shih-Tzu"
[ 155] score:0.063171 class:"Pekinese, Pekingese, Peke" 
[ 205] score:0.004299 class:"Lhasa, Lhasa apso"
[ 284] score:0.003096 class:"Persian cat"
[ 285] score:0.000171 class:"Siamese cat, Siamese"  

generate

功能描述

LLM 模型推理。对当前 LLM 进行推理，并返回推理结果。根据初始化运行环境时设置 target 的设备平台，得到的是模型在硬件平台或者模拟器上的推理结果。

说明

模型推理前，需先构建或加载一个 TORQ 模型。

参数

参数	含义
input_ids	输入 token 列表。

返回值

output_tokens：推理结果，类型是 token list。

示例代码

对于 LLM（如 qwen）代码如下（完整代码参考 example/qwen3/python/qwen3.py）：

# 使用模型对输入 token 进行推理， 得到 token 结果

outputs = torq.generate(input_ids=input_ids)
show_outputs(outputs)  

eval_perf

功能描述

评估模型性能。

说明

只有模型运行在模拟器上，才可以评估模型性能。

模型运行在模拟器上。

初始化运行时环境时，init_runtime接口中perf_debug为False，系统将返回为模型在硬件端运行的理论执行总时长。
初始化运行时环境时，init_runtime接口中perf_debug为True，除了返回总时间外，还将同时返回理论和板端实际的每一层的耗时情况。

参数

参数	含义
is_print	是否打印性能信息，默认值为 True。

返回值

perf_result：性能信息（字符串）。

示例代码

# 对模型性能进行评估

perf_detail = torq.eval_perf()  

eval_memory

功能描述

获取模型在硬件平台运行时的内存使用情况。

参数

参数	含义
is_print	是否以规范格式打印内存使用情况，默认值为`True`。

返回值

memory_detail：内存使用情况，类型为字典。内存使用情况按照下面的格式封装在字典中：

{
'weight_memory': 3698688, 
'internal_memory': 1756160, 
'other_memory': 484352, 
'total_memory': 5939200,
}

weight_memory 表示运行时模型权重的内存占用。
internal_memory 表示运行时模型中间 tensor 内存占用。
other_memory 表示运行时其他的内存占用。
total_memory 运行总内存占用，即权重、中间 tensor 和其他的内存占用之和。

示例代码

# 对模型内存使用情况进行评估
memory_detail = torq.eval_memory()    

如examples/caffe/mobilenet_v2，它在 A210 上运行时内存占用情况如下：

Total calculation amount: macc=300774272, flops=601827648
Total memory(float): params=13947264 bytes, output=54308672 bytes.
Total ddr: accum_ddr=0 bytes, coeff_ddr=0 bytes,
           input_ddr=0 bytes, output_ddr=0 bytes.

get_sdk_version

功能描述

获取 SDK API 和驱动的版本号。

返回值

sdk_version： API 和驱动版本信息，类型为字符串。

示例代码

# 获取SDK版本信息

sdk_version = torq.get_sdk_version() 
print(sdk_version)    

返回的 SDK 信息类似如下：

1.0.1

release

功能描述

不再使用TORQ 对象时，通过调用该对象的release() 方法释放 TORQ 对象占用的资源。

示例代码

torq.release()  

概述​

支持硬件平台​

系统依赖说明​

适用深度学习框架​

TORQ-Toolkit 调用流程​

API 详细说明​

TORQ​

config​

模型加载​

load_onnx​

load_huggingface​

load_caffe​

load_tensorflow​

load_tflite​

build​

export_torq​

load_torq​

accuracy_analysis​

init_runtime​

inference​

generate​

eval_perf​

eval_memory​

get_sdk_version​

release​

概述

支持硬件平台

系统依赖说明

适用深度学习框架

TORQ-Toolkit 调用流程

API 详细说明

TORQ

config

模型加载

load_onnx

load_huggingface

load_caffe

load_tensorflow

load_tflite

build

export_torq

load_torq

accuracy_analysis

init_runtime

inference

generate

eval_perf

eval_memory

get_sdk_version

release