Qualcomm AI Hub-API介绍

Qualcomm® AI Hub极大的简化了AI 模型部署到边缘设备的过程。本文主要介绍了Qualcomm® AI Hub使用的各种API接口，还有各个模型配置的参数数据，具体可以参考API documentation

API介绍：

Core API

API的核心功能，可直接通过qai_hub获得。

upload_dataset	上传dataset，将于30天内过期
upload_model	上传模型
get_dataset	返回给定ID的dataset
get_datasets	返回你可见的dataset列表
get_devices	返回device列表
get_device_attributes	返回可用设备属性的超级集合
get_job	返回给定ID的任务job
get_jobs	返回你可见的任务列表
get_model	返回给定ID的模型
get_models	返回模型列表
set_verbose	如果为true，API调用将进度打印到标准输出
submit_compile_job	提交编译任务
submit_profile_job	提交评测任务
submit_inference_job	提交推理任务
submit_compile_and_profile_jobs	提交编译和评测任务

管理对象

由API返回的类。这些对象由API管理，不应直接实例化。例如，要构建一个Model实例，请调用upload_Model（）或get_mode（）。

Dataset	Dataset不应该直接创建
Device	创建目标设备.
Model	神经网络模型对象.
Job	模型和设备的任务.
CompileJob	为一个模型，一组输入规范和一组设备编译任务.
ProfileJob	为一个模型，一组输入规范和一组设备评测任务.
InferenceJob	为一个模型，一组输入规范和一组设备推理任务.
CompileJobResult	编译任务结果的结构体
ProfileJobResult	评测任务结果的结构体.
InferenceJobResult	推理任务结果的结构体.
JobStatus	任务状态.
SourceModelType	输入模型类型.

异常

API引发的异常：

Error	API抛出的基础类异常.
UserError	用户输入过程中某些内容的异常导致故障，可能需要调整输入.
InternalError	内部API异常，你可以联系ai-hub-support@qti.qualcomm.com 寻求帮助.

常用选项

submit_compile_job(), submit_profile_job(), submit_inference_job():

Option	Description
--compute_unit <units>	指定目标计算单位。当在编译任务中使用时，这可以优化各个层的代码生成。当在配置文件或推理作业中使用时，它以指定的计算单元为目标。隐性回退CPU将由 target_runtime决定; TfLite和ONNX运行时始终包括CPU回退。Options for <units> (逗号分隔的值是无序的): all 以所有可用的计算单元为目标，先是NPU, then GPU, then CPU. npu Target NPU. gpu Target GPU. cpu Target CPU. Default: npu 当目标运行时为qnn_lib_aarch64_android all 对于任何其他目标运行时 Example: --compute_unit npu,cpu

Option

Description

--compute_unit <units>

指定目标计算单位。当在编译任务中使用时，这可以优化各个层的代码生成。当在配置文件或推理作业中使用时，它以指定的计算单元为目标。

隐性回退CPU将由 target_runtime决定; TfLite和ONNX运行时始终包括CPU回退。Options for <units> (逗号分隔的值是无序的):

all
- 以所有可用的计算单元为目标，先是NPU, then GPU, then CPU.
npu
- Target NPU.
gpu
- Target GPU.
cpu
- Target CPU.

Default:

npu 当目标运行时为qnn_lib_aarch64_android
all 对于任何其他目标运行时

Example:

--compute_unit npu,cpu

编译选项

submit_compile_job():

Compile option	Description
--target_runtime <runtime>	覆盖默认的目标运行时。默认的目标运行时是从源模型派生的。Options for <runtime>: tflite: TensorFlow Lite (.tflite) qnn_lib_aarch64_android: Qualcomm® AI Engine Direct model library (.so) targeting AArch64 Android onnx: ONNX Runtime (.ort) Default: 源模型指定默认目标. .pt : tflite .aimet_pt : qnn_lib_aarch64_android .aimet_onnx : qnn_lib_aarch64_android .onnx : tflite Examples: --target_runtime tflite --target_runtime qnn_lib_aarch64_android
--output_names "<name>[,name]..."	覆盖默认输出名称。默认情况下，模型的输出名称为output_0, output_1 …. Options: 输出名称的逗号分隔列表 Requirements: 此选项适用当目标运行时为TensorFlow Lite时。必须为每个模型输出指定一个名称. Default: 输出模型名称 output_0, output_1 …. Examples: --output_names "new_name_0,new_name_1"
--force_channel_last_input "<name>[,name]..." --force_channel_last_output "<name>[,name]..."	覆盖通道布局。默认情况下，编译器将维护模型的输入和输出张量的布局。这通常会在最终模型中产生额外的转置层，最常见的是在开始和结束处。这些选项指示编译器以这样一种方式生成代码，即生成的模型可以使用最后一个通道布局中的输入和或在最后一个信道布局中产生输出。Options：输入张量名称的逗号分隔列表 Requirements: 当目标运行时为ONNX运行时时，此选项不适用。请注意 --force_channel_last_output 采用默认名称或 --output_names 选项中的名称. Default: 编译器将维护模型的输入和输出张量的布局. Examples: --force_channel_last_input "image,indices" --force_channel_last_output "output_0,output_1"
--quantize_full_type <type>	将未量化的模型量化为指定的类型。它使用一个有代表性的数据集来量化激活和权重。如果没有提供这样的数据集，则使用随机生成的数据集。在这种情况下，生成的模型只能用作可实现性能的代理，因为该模型将无法产生准确的结果。Options： int8: quantize to int8 int16: quantize to int16 float16: quantize to float16 Default: 无伪量化. Examples: --quantize_full_type int8
--quantize_io [true\|false]	量化模型时量化输入和输出 . Options: true false Default: 输入和输出未量化. Examples: --quantize_io

评测和推断选项

submit_profile_job():, submit_inference_job():

Profile option	Description
--dequantize_outputs [true\|false]	对输出进行去量化。默认为true. Options: true false Default: 输出被去量化 Examples: --dequantize_outputs
--tflite_delegates <delegate>[,<delegate>]...	指定要加载和作为目标的TensorFlow Lite代理。可以指定多个代理。它们将按照指定的顺序使用。指定设备在所需计算单元上运行的最佳代理。 Options: qnn qnn-gpu nnapi nnapi-gpu gpu xnnpack Default: 代表的选择由指定的计算单位决定 Examples: --tflite_delegates qnn,qnn-gpu
--tflite_options <option>[;<option>]...	指定TensorFlow Lite代理的行为。此选项指定为以分号分隔的子选项列表。全套子选项位于TensorFlow Lite Options, TensorFlow Lite Delegate Options for Qualcomm® AI Engine Direct, TensorFlow Lite Delegate Options for GPUv2, and TensorFlow Lite Delegate Options for NNAPI . Examples: --tflite_options number_of_threads=4;qnn_htp_precision=kHtpQuantized
--qnn_options <option>[;<option>]...	指定针对Qualcomm® AI Engine Direct模型库时的行为. 此选项指定为以分号分隔的子选项列表. 以下 Qualcomm® AI Engine Direct Options 表中提供了全套子选项. Requirements: --qnn_options 仅适用--target_runtime qnn_lib_aarch64_android. Examples: --target_runtime qnn_lib_aarch64_android --qnn_options context_priority=HIGH;context_htp_performance_mode=BALANCED

Profile Options

submit_profile_job():

Profile option	Description
--max_profiler_iterations=<num>	指定配置文件迭代的最大次数。如果预测迭代的累积运行时间将超过--max_inference_time. 定义的执行超时，则可能会运行更少的迭代。 Options: <num> 要运行的最大迭代次数. Default: 100 – 100 iterations Examples: --max_profiler_iterations=50
--max_profiler_time=<seconds>	指定执行推理所花费的最大时间。在运行时，迭代次数大致在这个限制内完成，永远不会超过--max_profiler_iterations指定的值。例如，假设提交一个概要文件作业时--max_profiler_iterations=100 --max_profiler_time=10. 这表明在循环分析推理中花费的时间不应超过10秒，如果可以在这段时间内完成，则最多可以进行100次迭代。如果推理时间的运行平均值预测另一次迭代将导致超时，则循环终止。 <seconds> 在设备上执行推理所需时间的软限制. Requirements: 该值必须严格为正，且不超过600。 Default: 600 – 10 minutes Examples: --max_profiler_time=30

Profile option

Description

--max_profiler_iterations=<num>

指定配置文件迭代的最大次数。如果预测迭代的累积运行时间将超过--max_inference_time. 定义的执行超时，则可能会运行更少的迭代。 Options:

<num> 要运行的最大迭代次数.

Default:

100 – 100 iterations

Examples:

--max_profiler_iterations=50

--max_profiler_time=<seconds>

指定执行推理所花费的最大时间。在运行时，迭代次数大致在这个限制内完成，永远不会超过--max_profiler_iterations指定的值。例如，假设提交一个概要文件作业时--max_profiler_iterations=100 --max_profiler_time=10. 这表明在循环分析推理中花费的时间不应超过10秒，如果可以在这段时间内完成，则最多可以进行100次迭代。如果推理时间的运行平均值预测另一次迭代将导致超时，则循环终止。

<seconds> 在设备上执行推理所需时间的软限制.

Requirements:

该值必须严格为正，且不超过600。

Default:

600 – 10 minutes

Examples:

--max_profiler_time=30

TensorFlow Lite选项

适用于所有代理的--tflite_options的子选项。

TensorFlow Lite option	Description
enable_fallback=[true\|false]	当没有做好准备时，回退到优先级较低的代理。如果此选项为false，则任何委派失败都将使整个作业失败。默认值为true.
invoke_interpreter_on_cold_load=[true\|false]	在冷加载期间运行解释器。这将验证委托是否可以成功执行。如果发生错误，将删除失败的委托，并重新加载模型，直到找到工作配置为止。后续加载不会重新运行程序。默认值为 false.
allow_fp32_as_fp16=[true\|false]	允许代表在fp32操作中使用降低的fp16精度。委派选项可能会覆盖此项。默认为 true.
force_opengl=[true\|false]	尽可能强制使用OpenGL。这是为了调试目的而存在的。默认为false.
number_of_threads=<num>	要使用的线程数。默认值：为-1, 然后使用 std::thread::hardware_concurrency() / 2.
release_dynamic_tensors=[true\|false]	一旦模型不使用所有中间动态张量，就强制释放它们。请谨慎使用此配置，因为它可能会以较慢的推理速度为代价降低模型的峰值内存使用量。默认为 false.

Qualcomm® AI Engine Direct的TensorFlow Lite代表选项

特定于QNN代理的--tflite_options的子选项。有关QNN选项的更多信息，请参阅高通®AI引擎直接文档中的QNN GPU后端和QNN HTP后端页面。请注意，并非所有选项都可用于所有后端。

fLite option (QNN)	Description
qnn_log_level=<option>	设置qnn的日志级别. Default: kLogLevelWarn. Options: kLogOff kLogLevelError kLogLevelWarn kLogLevelInfo kLogLevelVerbose kLogLevelDebug
qnn_graph_priority=<option>	设置基础图形优先级. Default: kQnnPriorityDefault. Options: kQnnPriorityDefault kQnnPriorityLow kQnnPriorityNormal kQnnPriorityNormalHigh kQnnPriorityHigh kQnnPriorityUndefined
qnn_gpu_precision=<option>	设置GPU后端的精度，该后端定义了图形张量（既不是输入张量也不是输出张量）的优化级别。默认为kGpuFp16. Options: kGpuUserProvided kGpuFp32 kGpuFp16 kGpuHybrid
qnn_gpu_performance_mode=<option>	GPU的性能模式。更高的性能消耗更多的功率。默认为kGpuHigh. Options: kGpuDefault kGpuHigh kGpuNormal kGpuLow
qnn_dsp_performance_mode=<option>	DSP performance mode. Default is kDspBurst. Options: kDspLowPowerSaver kDspPowerSaver kDspHighPowerSaver kDspLowBalanced kDspBalanced kDspHighPerformance kDspSustainedHighPerformance kDspBurst

qnn_dsp_encoding=<option>	指定量化参数的原点。默认为 kDspStatic. Options: kDspStatic: 使用模型中的量化参数。 kDspDynamic: 使用来自模型输入的量化参数。
qnn_htp_performance_mode=<option>	HTP performance mode. Default is kHtpBurst. Options: kHtpLowPowerSaver kHtpPowerSaver kHtpHighPowerSaver kHtpLowBalanced kHtpBalanced kHtpHighPerformance kHtpSustainedHighPerformance kHtpBurst
qnn_htp_precision=<option>	HTP精度模式。仅适用于8gen1及更新版本。默认值：为kHtpFp16. Options: kHtpQuantized kHtpFp16
qnn_htp_optimization_strategy=<option>	优化加载时间或推理时间。默认为 kHtpOptimizeForInference. kHtpOptimizeForInference kHtpOptimizeForPrepare
qnn_htp_use_conv_hmx=[true\|false]	使用短的conv hmx可能会带来更好的性能。然而，具有短深度和/或非对称权重的卷积可能表现出不准确的结果。默认值为true.
qnn_htp_use_fold_relu=[true\|false]	使用fold-relu可能会带来更好的性能。卷积的量化范围应该相等，或者是Relu运算的子集，以获得正确的结果。默认值为false.
qnn_htp_vtcm_size=<size>	设置VTCM大小（MB）。如果未设置VTCM大小，将使用默认VTCM大小。VTCM大小必须大于0，如果VTCM大小设置为大于可用于此设备的VTCM大小，则它将被设置为可用于该设备的VTCM大小。
qnn_htp_num_hvx_threads=<num>	设置HVX线程数。如果num超过HVX线程的最大数量，则该数量将被剪裁为支持的最大线程数量。num必须大于0。

适用于GPUv2的TensorFlow Lite代表选项

特定于GPUv2委托的--tflite_options的子选项。使用--tflite_delegates gpu选择GPUv2委托。有关TensorFlow Lite GPU选项的更多信息，请参阅delegate_options.h。

TfLite option (GPUv2)	Description
gpu_inference_preference=<option>	指定编译/运行时权衡。默认值为TFLITE_GPU_INFERENCE_PREFERENCE_SUSTAINED_SPEED. Options: TFLITE_GPU_INFERENCE_PREFERENCE_FAST_SINGLE_ANSWER: 委托将只使用一次，因此应考虑引导/初始化时间。 TFLITE_GPU_INFERENCE_PREFERENCE_SUSTAINED_SPEED: 更倾向于最大限度地提高吞吐量。同一个委托将在多个输入上重复使用。 TFLITE_GPU_INFERENCE_PREFERENCE_BALANCED: 平衡初始化延迟和吞吐量。此选项将导致比 TFLITE_GPU_INFERENCE_PREFERENCE_FAST_SINGLE_ANSWER 稍高的初始化延迟，但其推理延迟应更接近TFLITE_GPU_INFERENCE_PREFERENCE_SUSTAINED_SPEED.
gpu_inference_priority1=<option> gpu_inference_priority2=<option> gpu_inference_priority3=<option>	设置最高优先级. 优先级1的默认值为TFLITE_GPU_INFERENCE_PRIORITY_MIN_LATENCY. 优先级2的默认值为 TFLITE_GPU_INFERENCE_PRIORITY_MIN_MEMORY_USAGE. 优先级3的默认值为 TFLITE_GPU_INFERENCE_PRIORITY_MAX_PRECISION. 要指定最大精度，请使用以下优先级级1-优先级3: TFLITE_GPU_INFERENCE_PRIORITY_MAX_PRECISION, TFLITE_GPU_INFERENCE_PRIORITY_AUTO, TFLITE_GPU_INFERENCE_PRIORITY_AUTO. Options: TFLITE_GPU_INFERENCE_PRIORITY_AUTO TFLITE_GPU_INFERENCE_PRIORITY_MAX_PRECISION TFLITE_GPU_INFERENCE_PRIORITY_MIN_LATENCY TFLITE_GPU_INFERENCE_PRIORITY_MIN_MEMORY_USAGE
gpu_max_delegated_partitions=<num>	可以有多个可以委派的分区。这限制了要委派的最大分区数。默认为1.

NNAPI的TensorFlow Lite代表选项

特定于NNAPI委托的--tflite_options的子选项。有关NNAPI特定选项的其他信息，请参见 nnapi_delegate_c_api.h。

TensorFlow Lite option (NNAPI)	Description
nnapi_execution_preference=<option>	功率/性能权衡。默认值为 kSustainedSpeed. Options: kLowPower kFastSingleAnswer kSustainedSpeed
nnapi_max_number_delegated_partitions=<max>	设置最大分区数。小于或等于零的值表示没有限制。如果受支持的节点的完整集合的委派将生成大于此参数的分区数，那么实际上只有<max>的分区会被加速。当前的选择是按照节点数量的递减顺序对分区进行排序，然后选择它们，直到达到限制为止。默认值为 3.
nnapi_allow_fp16=[true\|false]	允许fp32作为fp16运行。默认为true.

Qualcomm® AI Engine Direct选项

-qnn_options的子选项。当目标运行时为qnn_lib_aarch64_android时，这些选项适用。有关Qualcomm® AI Engine Direct选项的更多信息，请参阅Qualcomm® AI Engine Direct文档中的QNN GPU后端和QNN HTP后端页面。请注意，并非所有选项都可用于所有后端。

Qualcomm® AI Engine Direct option	Description
context_async_execution_queue_depth_numeric=<num>	指定异步执行队列深度.
context_enable_graphs=<name>[,<name>]...	要从上下文二进制文件反序列化的图的名称。默认情况下，所有图形都处于启用状态。如果提供了无效的图形名称，则会生成错误。
context_error_reporting_options_level=<option>	设置错误报告级别. Options: BRIEF DETAILED
context_error_reporting_options_storage_limit=<kb>	为错误信息保留的内存量。以KB为单位指定。
context_memory_limit_hint=<mb>	设置反序列化上下文的峰值内存限制提示（MB）。
context_priority=<option>	设置此上下文中图形的默认优先级。Options: LOW NORMAL NORMAL_HIGH HIGH
context_gpu_performance_hint=<option>	设置GPU性能提示。默认为HIGH. Options: HIGH: 最大化GPU时钟频率。. NORMAL: 平衡性能取决于电源管理. LOW: 以牺牲推理延迟为代价使用最低功耗.
context_gpu_use_gl_buffers=[true\|false]	如果设置为true，将使用OpenGL缓冲区。
context_htp_performance_mode=<option>	设置HTP performance mode. 默认为 BURST. Options: EXTREME_POWER_SAVER LOW_POWER_SAVER POWER_SAVER HIGH_POWER_SAVER LOW_BALANCED BALANCED HIGH_PERFORMANCE SUSTAINED_HIGH_PERFORMANCE BURST
default_graph_priority=<option>	Options: LOW NORMAL NORMAL_HIGH HIGH
default_graph_gpu_precision=<option>	指定要使用的精度模式。默认为USER_PROVIDED. Options: FLOAT32: 将张量数据类型转换为FP32，并选择使用FP32累加器的内核. FLOAT16: 将张量数据类型转换为FP16，并尽可能选择使用FP16累加器的内核. HYBRID: 将张量数据类型转换为FP16，并选择使用FP32累加器的内核. USER_PROVIDED: 不优化张量数据类型.
default_graph_gpu_disable_memory_optimizations=[true\|false]	当为true时，模型中的每个张量都将被分配唯一的内存，并且共享被禁用。
default_graph_gpu_disable_node_optimizations=[true\|false]	当为true时，操作将不会融合，而是保持独立.
default_graph_gpu_disable_queue_recording=[true\|false]	QNN GPU后端将使用队列记录来提高性能。如果为true，则禁用队列记录。
default_graph_htp_disable_fold_relu_activation_into_conv=[true\|false]	对于卷积或类卷积运算后面跟着Relu或ReluMinMax的任何图，Relu被折叠到卷积运算中。默认值为false。
default_graph_htp_num_hvx_threads=<num>	定义要为特定图形保留和使用的HVX线程数。默认值为4。
default_graph_htp_optimization_type=<option>	设置优化级别以平衡准备和执行。 Options: FINALIZE_OPTIMIZATION_FLAG
default_graph_htp_optimization_value=<num>	结合指定default_graph_htp_optimization_type. Options for <num>: 1: 准备时间更快，图形优化程度更低。. 2: 准备时间更长，图形更优化 3: 最长的准备时间，最有可能是更优化的图形.
default_graph_htp_precision=<option>	如果没有设置精度值，QNN HTP后端会假设客户端希望运行量化网络。当精度值设置为FLOAT16时，QNN HTTPP后端会将用户提供的float32输入转换为FLOAT16，并使用FLOAT16数学执行图形. Options: FLOAT16
default_graph_htp_disable_short_depth_conv_on_hmx=[true\|false]	使用HMX指令运行所有卷积运算。默认为false.
default_graph_htp_vtcm_size=<mb>	设置要保留和使用的VTCM内存量（MB）。指定0以使用最大值。默认为4.