Qualcomm® AI Engine Direct 使用手册（19）

---

6.4.3 qnn-accuracy-debugger（实验）

依赖关系

精度调试器取决于设置中概述的设置。具体来说，需要满足以下条件：首先，需要根据平台依赖关系满足平台依赖关系。需要安装所需的 ML 框架。还必须遵循环境设置中的环境设置说明。

应使用安装程序中提到的 check-python-dependency 脚本来满足 Python 依赖关系。此外，还需要以下软件包：

absl==0.0
flatbuffers==23.3.3
onnxruntime==1.14.1
protobuf==4.22.4
xlsxwriter==3.1.9

本指南中使用了以下环境变量（用户可以根据需要更改以下路径）：

1. RESOURCESPATH = {所有模型和输入文件所在目录的路径}

2. PROJECTREPOPATH = {准确性调试器项目目录的路径}

概述

准确性调试器工具可以发现层级神经网络中的不准确性。该工具将通过特定机器学习框架（即 Tensorflow、Onnx、TFlite）运行模型所产生的黄金输出与通过高通 QNN 推理引擎运行相同模型所产生的结果进行比较。推理引擎可以在多种计算介质上运行，包括GPU、CPU和DSP。

Accuracy Debugger 提供以下功能。每个功能都可以使用相应的选项来运行；例如，。qnn-accuracy-debugger --{option}

1. qnn-accuracy-debugger -–framework_diagnosis此功能使用机器学习框架（例如tensorflow、tflite 或onnx）来运行模型以获得中间输出。

2. qnn-accuracy-debugger –-inference_engine此功能使用 QNN 引擎运行模型以检索中间输出。

3. qnn-accuracy-debugger –-verification此功能使用 CosineSimilarity、RtolAtol 等验证器来比较框架诊断和推理引擎功能生成的输出。

4. qnn-accuracy-debugger –compare_encodings此功能从给定的 QNN net JSON 文件中提取编码，将它们与给定的 AIMET 编码进行比较，并输出突出显示不匹配的 Excel 工作表。

5. qnn-accuracy-debugger –tensor_inspection此功能将给定的目标输出与参考输出进行比较。

提示：

• 您可以在 bin 命令后使用 –help 来查看可以添加哪些其他选项（必需或可选）。

• 如果未提供选项，Accuracy Debugger 将依次运行framework_diagnosis、inference_engine 和verification。

以下是运行 Accuracy Debugger 的说明：

框架诊断
框架诊断功能旨在运行具有不同机器学习框架（例如Tensorflow等）的模型。选定的模型使用特定的 ML 框架运行。生成黄金输出以供将来与推理引擎步骤的推理结果进行比较。

用法

usage: ./qnn-accuracy-debugger --framework_diagnosis [-h]
                                   -f FRAMEWORK [FRAMEWORK ...]
                                   -m MODEL_PATH
                                   -i INPUT_TENSOR [INPUT_TENSOR ...]
                                   -o OUTPUT_TENSOR
                                   [-w WORKING_DIR]
                                   [--output_dirname OUTPUT_DIRNAME]
                                   [-v]

Script to generate intermediate tensors from an ML Framework.

optional arguments:
     -h, --help            show this help message and exit

required arguments:
     -f FRAMEWORK [FRAMEWORK ...], --framework FRAMEWORK [FRAMEWORK ...]
                             Framework type and version, version is optional. Currently
                             supported frameworks are ["tensorflow","onnx","tflite"] case
                             insensitive but spelling sensitive
     -m MODEL_PATH, --model_path MODEL_PATH
                             Path to the model file(s).
     -i INPUT_TENSOR [INPUT_TENSOR ...], --input_tensor INPUT_TENSOR [INPUT_TENSOR ...]
                             The name, dimensions, raw data, and optionally data
                             type of the network input tensor(s) specifiedin the
                             format "input_name" comma-separated-dimensions path-
                             to-raw-file, for example: "data" 1,224,224,3 data.raw
                             float32. Note that the quotes should always be
                             included in order to handle special characters,
                             spaces, etc. For multiple inputs specify multiple
                             --input_tensor on the command line like:
                             --input_tensor "data1" 1,224,224,3 data1.raw
                             --input_tensor "data2" 1,50,100,3 data2.raw float32.
     -o OUTPUT_TENSOR, --output_tensor OUTPUT_TENSOR
                             Name of the graph's specified output tensor(s).

     optional arguments:
     -w WORKING_DIR, --working_dir WORKING_DIR
                             Working directory for the framework_diagnosis to store
                             temporary files. Creates a new directory if the
                             specified working directory does not exist
     --output_dirname OUTPUT_DIRNAME
                             output directory name for the framework_diagnosis to
                             store temporary files under
                             <working_dir>/framework_diagnosis. Creates a new
                             directory if the specified working directory does not
                             exist
     -v, --verbose         Verbose printing

Please note: All the command line arguments should either be provided through command line or through the config file. They will not override those in the config file if there is overlap.

命令示例

./qnn-accuracy-debugger \
    --framework_diagnosis \
    --framework tensorflow \
    --model_path $RESOURCESPATH/samples/InceptionV3Model/inception_v3_2016_08_28_frozen.pb \
    --input_tensor "input:0" 1,299,299,3 $RESOURCESPATH/samples/InceptionV3Model/data/chairs.raw \
    --output_tensor InceptionV3/Predictions/Reshape_1:0

./qnn-accuracy-debugger \
    --framework_diagnosis \
    --framework onnx \
    --model_path $RESOURCESPATH/samples/dlv3onnx/dlv3plus_mbnet_513-513_op9_mod_basic.onnx \
    --input_tensor Input 1,3,513,513 $RESOURCESPATH/samples/dlv3onnx/data/00000_1_3_513_513.raw \
    --output_tensor Output

提示：

• 如果没有另外指定，则工作目录是从您调用脚本的位置生成的；建议从同一目录调用所有脚本，以便所有输出和结果都存储在同一目录下，而不会到处都有输出

• 对于tensorflow，有时需要在输入和输出节点名称后面添加:0以表示节点的索引。请注意，onnx 型号中删除了 :0。

输出

该程序还在working_directory/framework_diagnosis中创建一个名为latest的目录，该目录以符号方式链接到最近生成的目录。在下面的示例中，最新的数据将符号链接到最新目录YYYY-MM-DD_HH:mm:ss中的数据。用户可以选择通过将目录名称传递给 –output_dirname（即 –output_dirname myTest1Ouput）来覆盖目录名称。

框架诊断步骤生成的浮动数据为验证组件提供精确的参考资料，以诊断推理引擎生成的网络的准确性。除非另外指定路径，否则 Accuracy Debugger 将在当前工作目录中找到的working_directory/framework_diagnosis目录中创建目录。这些目录将以程序执行的日期和时间命名，并包含张量数据。根据模型的张量命名约定，新目录中可能有许多子目录。当张量名称包含斜杠“/”时，就会发生这种情况。例如，对于张量名称“inception_3a/1x1/bn/sc”、“inception_3a/1x1/bn/sc_internal”和“inception_3a/1x1/bn”，将生成子目录。

上图显示了 Framework_diagnosis 运行的示例输出。InceptionV3 和 Logits 包含最后一层之前每一层的输出。每个输出目录包含与每个节点对应的.raw 文件。每个可见的原始文件都是操作的输出。最后一层的输出保存在 Predictions 目录中。文件framework_diagnosis_options.json包含用于运行此功能的所有选项。

推理机
推理引擎功能旨在查找 QNN 模型的输出。该步骤产生的输出可以与框架诊断步骤产生的黄金输出进行比较。

用法

usage: ./qnn-accuracy-debugger --inference_engine [-h]
                                   [--stage {source,converted,compiled}] -r
                                   {cpu,gpu,dsp,dspv65,dspv66,dspv68,dspv69,dspv73,aic,htp}
                                   -p ENGINE_PATH -a
                                   {aarch64-android,x86_64-linux-clang}
                                   -l INPUT_LIST
                                   [-i INPUT_TENSOR [INPUT_TENSOR ...]]
                                   [-o OUTPUT_TENSOR] [-m MODEL_PATH]
                                   [-f FRAMEWORK [FRAMEWORK ...]]
                                   [-qmcpp QNN_MODEL_CPP_PATH]
                                   [-qmbin QNN_MODEL_BIN_PATH]
                                   [-qmb QNN_MODEL_BINARY_PATH]
                                   [--deviceId DEVICEID] [-v]
                                   [--host_device {x86}] [-w WORKING_DIR]
                                   [--output_dirname OUTPUT_DIRNAME]
                                   [--engine_version ENGINE_VERSION]
                                   [--debug_mode_off]
                                   [--print_version PRINT_VERSION]
                                   [--offline_prepare] [-bbw {8,32}]
                                   [-abw {8,16}]
                                   [--golden_dir_for_mapping GOLDEN_DIR_FOR_MAPPING]
                                   [-wbw {8}] [--lib_name LIB_NAME]
                                   [-bd BINARIES_DIR] [-qmn MODEL_NAME]
                                   [-pq {tf,enhanced,adjusted,symmetric}]
                                   [-qo QUANTIZATION_OVERRIDES]
                                   [--act_quantizer {tf,enhanced,adjusted,symmetric}]
                                   [--algorithms ALGORITHMS]
                                   [--ignore_encodings]
                                   [--per_channel_quantization]
                                   [-idt {float,native}]
                                   [-odt {float_only,native_only,float_and_native}]
                                   [--profiling_level {basic,detailed}]
                                   [--perf_profile {low_balanced,balanced,high_performance,sustained_high_performance,burst,low_power_saver,power_saver,high_power_saver,extreme_power_saver,system_settings}]
                                   [--log_level {error,warn,info,debug,verbose}]
                                   [--qnn_model_net_json QNN_MODEL_NET_JSON]
                                   [--qnn_netrun_config_file QNN_NETRUN_CONFIG_FILE]
                                   [--extra_converter_args EXTRA_CONVERTER_ARGS]
                                   [--extra_runtime_args EXTRA_RUNTIME_ARGS]
                                   [--compiler_config COMPILER_CONFIG]
                                   [--precision {int8,fp16}]

Script to run QNN inference engine.

optional arguments:
     -h, --help            show this help message and exit

Core Arguments:
     --stage {source,converted,compiled}
                             Specifies the starting stage in the Accuracy Debugger
                             pipeline.
                             Source: starting with source framework model [default].
                             Converted: starting with model.cpp and .bin files.
                             Compiled: starting with a model's .so binary.
     -r {cpu,gpu,dsp,dspv65,dspv66,dspv68,dspv69,dspv73,aic,htp}, --runtime {cpu,gpu,dsp,dspv65,dspv66,dspv68,dspv69,dspv73,aic,htp}
                             Runtime to be used.
                             Use HTP runtime for emulation on x86 host.
     -a {aarch64-android,x86_64-linux-clang}, --architecture {aarch64-android,x86_64-linux-clang}
                             Name of the architecture to use for inference engine.
     -l INPUT_LIST, --input_list INPUT_LIST
                             Path to the input list text.

Arguments required for SOURCE stage:
     -i INPUT_TENSOR [INPUT_TENSOR ...], --input_tensor INPUT_TENSOR [INPUT_TENSOR ...]
                             The name, dimension, and raw data of the network input
                             tensor(s) specified in the format "input_name" comma-
                             separated-dimensions path-to-raw-file, for example:
                             "data" 1,224,224,3 data.raw. Note that the quotes
                             should always be included in order to handle special
                             characters, spaces, etc. For multiple inputs specify
                             multiple --input_tensor on the command line like:
                             --input_tensor "data1" 1,224,224,3 data1.raw
                             --input_tensor "data2" 1,50,100,3 data2.raw.
     -o OUTPUT_TENSOR, --output_tensor OUTPUT_TENSOR
                             Name of the graph's output tensor(s).
     -m MODEL_PATH, --model_path MODEL_PATH
                             Path to the model file(s).
     -f FRAMEWORK [FRAMEWORK ...], --framework FRAMEWORK [FRAMEWORK ...]
                             Framework type to be used, followed optionally by
                             framework version.

Arguments required for CONVERTED stage:
     -qmcpp QNN_MODEL_CPP_PATH, --qnn_model_cpp_path QNN_MODEL_CPP_PATH
                             Path to the qnn model .cpp file
     -qmbin QNN_MODEL_BIN_PATH, --qnn_model_bin_path QNN_MODEL_BIN_PATH
                             Path to the qnn model .bin file

Arguments required for COMPILED stage:
     -qmb QNN_MODEL_BINARY_PATH, --qnn_model_binary_path QNN_MODEL_BINARY_PATH
                             Path to the qnn model .so binary.

Optional Arguments:
     --deviceId DEVICEID   The serial number of the device to use. If not
                             available, the first in a list of queried devices will
                             be used for validation.
     -v, --verbose         Verbose printing
     --host_device {x86}   The device that will be running conversion. Set to x86
                             by default.
     -w WORKING_DIR, --working_dir WORKING_DIR
                             Working directory for the inference_engine to store
                             temporary files. Creates a new directory if the
                             specified working directory does not exist
     --output_dirname OUTPUT_DIRNAME
                             output directory name for the inference_engine to
                             store temporary files under
                             <working_dir>/inference_engine .Creates a new
                             directory if the specified working directory does not
                             exist
     -p ENGINE_PATH, --engine_path ENGINE_PATH
                             Path to the inference engine.
     --debug_mode_off      Specifies if wish to turn off debug_mode mode.
     --print_version PRINT_VERSION
                             Print the QNN SDK version alongside the output.
     --offline_prepare     Use offline prepare to run qnn model.
     -bbw {8,32}, --bias_bitwidth {8,32}
                             option to select the bitwidth to use when quantizing
                             the bias. default 8
     -abw {8,16}, --act_bitwidth {8,16}
                             option to select the bitwidth to use when quantizing
                             the activations. default 8
     --golden_output_reference_directory GOLDEN_OUTPUT_REFERENCE_DIRECTORY, --golden_dir_for_mapping GOLDEN_DIR_FOR_MAPPING
                             Optional parameter to indicate the directory of the
                             goldens, it's used for tensor mapping without
                             framework.
     -wbw {8}, --weights_bitwidth {8}
                             option to select the bitwidth to use when quantizing
                             the weights. Only support 8 atm
     --float_bitwidth {32,16}
                             option to select the bitwidth to use when using float
                             for parameters(weights/bias) and activations for all
                             ops or specific Op (via encodings) selected through
                             encoding; either 32 (default) or 16
     -nif, --use_native_input_files
                             Specifies that the input files will be parsed in the
                             data type native to the graph. If not specified, input
                             files will be parsed in floating point.
     -nof, --use_native_output_files
                             Specifies that the output files will be generated in
                             the data type native to the graph. If not specified,
                             output files will be generated in floating point.
     --lib_name LIB_NAME   Name to use for model library (.so file)
     -bd BINARIES_DIR, --binaries_dir BINARIES_DIR
                             Directory to which to save model binaries, if they
                             don't yet exist.
     -mn MODEL_NAME, --model_name MODEL_NAME
                             Name of the desired output qnn model
     -pq {tf,enhanced,adjusted,symmetric}, --param_quantizer {tf,enhanced,adjusted,symmetric}
                             Param quantizer algorithm used.
     -qo QUANTIZATION_OVERRIDES, --quantization_overrides QUANTIZATION_OVERRIDES
                             Path to quantization overrides json file.
     --act_quantizer {tf,enhanced,adjusted,symmetric}
                             Optional parameter to indicate the activation
                             quantizer to use
     -fbw {16,32}, --float_bias_bitwidth {16,32}
                             option to select the bitwidth to use when biases are in float; default is 32
     -rqs RESTRICT_QUANTIZATION_STEPS, --restrict_quantization_steps RESTRICT_QUANTIZATION_STEPS
                             ENCODING_MIN, ENCODING_MAX
                             Specifies the number of steps to use to compute quantization encodings such that
                             scale = (max - min) / number of quantization steps.
                             The option should be passed as a space separated pair of hexadecimal string minimum and maximum values,
                             i.e. --restrict_quantization_steps 'MIN MAX'. Note that this is a hexadecimal string
                             literal and not a signed integer. To supply a negative value an explicit minus sign is required.
                             e.g.: 8-bit range: --restrict_quantization_steps '-0x80 0x7F'
                             16-bit range: --restrict_quantization_steps '-0x8000 0x7F7F'
     --algorithms ALGORITHMS
                             Use this option to enable new optimization algorithms.
                             Usage is: --algorithms <algo_name1> ... The available
                             optimization algorithms are: 'cle ' - Cross layer
                             equalization includes a number of methods for
                             equalizing weights and biases across layers in order
                             to rectify imbalances that cause quantization errors.
     --ignore_encodings    Use only quantizer generated encodings, ignoring any
                             user or model provided encodings.
     --per_channel_quantization
                             Use per-channel quantization for convolution-based op
                             weights.
     -idt {float,native}, --input_data_type {float,native}
                             the input data type, must match with the supplied
                             inputs
     -odt {float_only,native_only,float_and_native}, --output_data_type {float_only,native_only,float_and_native}
                             the desired output data type
     --profiling_level {basic,detailed,backend}
                             Enables profiling and sets its level.
     --perf_profile {low_balanced,balanced,high_performance,sustained_high_performance,burst,low_power_saver,power_saver,high_power_saver,extreme_power_saver,system_settings}
     --log_level {error,warn,info,debug,verbose}
                             Enable verbose logging.
     --qnn_model_net_json QNN_MODEL_NET_JSON
                             Path to the qnn model net json. Only necessary if its being run from the converted stage. It has information about what structure the data is in within framework_diagnosis and inference_engine steps.
                             This file is required to generate model_graph_struct.json file which is good to have in the verification step.
     --qnn_netrun_config_file QNN_NETRUN_CONFIG_FILE
                             allow backend_extention features to be applied during
                             qnn-net-run
     --extra_converter_args EXTRA_CONVERTER_ARGS
                             additional convereter arguments in a string. example:
                             --extra_converter_args input_dtype=data
                             float;input_layout=data1 NCHW
     --extra_contextbin_args EXTRA_CONTEXTBIN_ARGS
                             additional context binary generator arguments in a quoted string.
                             example: --extra_contextbin_args 'arg1=value1;arg2=value2'
     --extra_runtime_args EXTRA_RUNTIME_ARGS
                             additional convereter arguments in a quoted string.
                             example: --extra_runtime_args
                             profiling_level=basic;log_level=debug
     --compiler_config COMPILER_CONFIG
                             Path to the compiler config file.
     --precision {int8,fp16}
                             select precision
     --intermediate_output_tensors INTERMEDIATE_OUTPUT_TENSORS
                             Output tensor names to be dumped. example:1579,232
Please note: All the command line arguments should either be provided through command line or through the config file. They will not override those in the config file if there is overlap.

推理引擎配置文件位于{accuracy_debugger 工具根目录}/python/qti/aisw/accuracy_debugger/lib/inference_engine/configs/config_files中，是一个JSON文件。此配置文件存储的信息可帮助推理引擎确定要读入的工具和参数。

命令示例

./qnn-accuracy-debugger \
    --inference_engine \
    --framework tensorflow \
    --runtime dspv73 \
    --model_path $RESOURCESPATH/samples/InceptionV3Model/inception_v3_2016_08_28_frozen.pb \
    --input_tensor "input:0" 1,299,299,3 $RESOURCESPATH/samples/InceptionV3Model/data/chairs.raw \
    --output_tensor InceptionV3/Predictions/Reshape_1 \
    --architecture x86_64-linux-clang \
    --input_list $RESOURCESPATH/samples/InceptionV3Model/data/image_list.txt \
    --verbose

命令示例

./qnn-accuracy-debugger \
    --inference_engine \
    --deviceId 357415c4 \
    --framework tensorflow \
    --runtime dspv73 \
    --architecture aarch64-android \
    --model_path $RESOURCESPATH/samples/InceptionV3Model/inception_v3_2016_08_28_frozen.pb \
    --input_tensor "input:0" 1,299,299,3 $RESOURCESPATH/samples/InceptionV3Model/data/chairs.raw \
    --output_tensor InceptionV3/Predictions/Reshape_1 \
    --input_list $RESOURCESPATH/samples/InceptionV3Model/data/image_list.txt \
    --verbose

提示：

• 对于运行时（从“cpu”、“gpu”、“dsp”、“dspv65”、“dspv66”、“dspv68”、“dspv69”、“dspv73”、“aic”、“htp”中选择）。确保 kailua 的运行时为 73，waiipio 的运行时为 69，等等。选择 HTP 运行时在 x86 主机上进行模拟。

• 输入张量 (-i) 和输出张量 (-o) 不需要像运行张量流框架诊断时那样的 :0 索引

• 生成两个文件，即tensor_mapping.json和qnn_model_graph_struct.json用于验证，请务必在working_directory/inference_engine/latest中找到这2个文件

从不同阶段运行的更多示例命令：

命令示例

source file stage: same as example from above section (stage default is "source")

running from converted stage (x86):
./qnn-accuracy-debugger \
    --inference_engine \
    --stage converted \
    -qmcpp $RESOURCESPATH/samples/InceptionV3Model/inception_v3_2016_08_28_frozen_qnn_model.cpp \
    -qmbin $RESOURCESPATH/samples/InceptionV3Model/inception_v3_2016_08_28_frozen_qnn_model.bin \
    --runtime dspv73 \
    --architecture x86_64-linux-clang \
    --input_list $RESOURCESPATH/samples/InceptionV3Model/data/image_list.txt \
    --qnn_model_net_json $RESOURCESPATH/samples/InceptionV3Model/inception_v3_2016_08_28_frozen_qnn_model_net.json \
    --verbose \
    --framework tensorflow \
    --golden_output_reference_directory $RESOURCESPATH/samples/InceptionV3Model/golden_from_framework_diagnosis/

Android Devices (ie. MTP):
./qnn-accuracy-debugger \
    --inference_engine \
    --stage converted \
    -qmcpp $RESOURCESPATH/samples/InceptionV3Model/inception_v3_2016_08_28_frozen_qnn_model.cpp \
    -qmbin $RESOURCESPATH/samples/InceptionV3Model/inception_v3_2016_08_28_frozen_qnn_model.bin \
    --deviceId f366ce60 \
    --runtime dspv73 \
    --architecture aarch64-android \
    --input_list $RESOURCESPATH/samples/InceptionV3Model/data/image_list.txt \
    --qnn_model_net_json $RESOURCESPATH/samples/InceptionV3Model/inception_v3_2016_08_28_frozen_qnn_model_net.json \
    --verbose \
    --framework tensorflow \
    --golden_output_reference_directory $RESOURCESPATH/samples/InceptionV3Model/golden_from_framework_diagnosis/


running in compiled stage (x86):

./qnn-accuracy-debugger \
    --inference_engine \
    --stage compiled \
    --qnn_model_binary $RESOURCESPATH/samples/InceptionV3Model/qnn_model_binaries/x86_64-linux-clang/libqnn_model.so \
    --runtime dspv73 \
    --architecture x86_64-linux-clang \
    --input_list $RESOURCESPATH/samples/InceptionV3Model/data/image_list.txt \
    --verbose \
    --qnn_model_net_json $RESOURCESPATH/samples/InceptionV3Model/inception_v3_2016_08_28_frozen_qnn_model_net.json \
    --golden_output_reference_directory $RESOURCESPATH/samples/InceptionV3Model/golden_from_framework_diagnosis/

Android devices (ie MTP):
./qnn-accuracy-debugger \
    --inference_engine \
    --stage compiled \
    --qnn_model_binary $RESOURCESPATH/samples/InceptionV3Model/qnn_model_binaries/aarch64-android/libqnn_model.so \
    --runtime dspv73 \
    --architecture aarch64-android \
    --input_list $RESOURCESPATH/samples/InceptionV3Model/data/image_list.txt \
    --verbose \
    --qnn_model_net_json $RESOURCESPATH/samples/InceptionV3Model/inception_v3_2016_08_28_frozen_qnn_model_net.json \
    --framework tensorflow \
    --golden_output_reference_directory $RESOURCESPATH/samples/InceptionV3Model/golden_from_framework_diagnosis/

提示：

• 运行此步骤不需要 qnn_model_net_json 文件。但是，需要构建 qnn_model_graph_struct.json，它可以在验证步骤中使用。model_net.json 文件是在原始模型转换为转换后模型时生成的。因此，如果您从转换后的模型阶段调试此模型，建议您请求此 model_net.json 文件。

• 框架和golden_dir_for_mapping，或者只是golden_dir_for_mapping本身是用于生成tensor_mapping.json的原始模型的替代方案。然而，仅提供golden_dir_for_mapping，get_tensor_mapping模块将尽力进行映射，但不能保证该映射100％准确。

输出
推理引擎运行完成后，会将输出存储在指定目录（默认为当前工作目录）中，并将文件存储在该目录中。默认情况下，它将把输出存储在当前工作目录的working_directory/inference_engine中。

上图显示了推理引擎步骤之一运行的示例输出。输出目录包含原始文件。每个原始文件都是网络中操作的输出。model.bin 和 model.cpp 文件由模型转换器创建。qnn_model_binaries 目录包含由 modellibgenerator 实用程序生成的 .so 文件。文件 image_list.txt 包含示例测试图像的路径。inference_engine_options.json 文件包含启动此运行时使用的所有选项。除了生成 .raw 文件之外，inference_engine 还在 .json 文件中生成模型的图结构。该文件的名称与protobuf模型文件的名称相同。model_graph_struct.json 有助于在验证步骤期间提供转换后的模型图的结构相关信息。具体来说，它有助于按顺序组织节点（即开始节点应该早于结束节点）。model_net.json 包含有关framework_diagnosis 和inference_engine 步骤中数据的结构的信息（数据可以采用不同的格式，例如通道在前与通道在后）。验证步骤使用此信息，以便可以正确转置和比较数据。它是一个可选参数，可以在推理引擎步骤中提供，用于生成 model_graph_struct.json 文件（仅在从转换阶段运行推理引擎时强制）。最后，tensor_mapping 文件包含框架诊断步骤和推理引擎步骤生成的各种中间输出文件名的映射。

创建的 .raw 文件的组织方式与 Framework_diagnosis 相同（见上文）。

确认
验证步骤将框架诊断步骤产生的输出（来自给定模型的中间张量）与推理引擎步骤产生的输出进行比较。比较完成后，验证结果将被编译并以用户可以轻松解释的格式直观地显示。

有不同类型的验证器，例如：CosineSimilarity、RtolAtol 等。要查看可用的验证器，请使用 –help 选项 (./qnn-accuracy-debugger –verification –help)。每个验证者使用错误度量来比较框架诊断和推理引擎输出。它还准备报告和/或可视化以帮助用户分析网络的错误数据。

用法

usage: ./qnn-accuracy-debugger --verification [-h]

Script to run verification.

required arguments:
     --default_verifier DEFAULT_VERIFIER [DEFAULT_VERIFIER ...]
                             Default verifier used for verification. The options
                             "RtolAtol", "AdjustedRtolAtol", "TopK", "L1Error",
                             "CosineSimilarity", "MSE", "MAE", "SQNR", "MeanIOU",
                             "ScaledDiff" are supported. An optional list of
                             hyperparameters can be appended. For example:
                             --default_verifier
                             rtolatol,rtolmargin,0.01,atolmargin,0,01. An optional
                             list of placeholders can be appended. For example:
                             --default_verifier CosineSimilarity param1 1 param2 2.
                             to use multiple verifiers, add additional
                             --default_verifier CosineSimilarity
     --golden_output_reference_directory GOLDEN_OUTPUT_REFERENCE_DIRECTORY, --framework_results FRAMEWORK_RESULTS
                             Path to root directory generated from framework
                             diagnosis. Paths may be absolute, or relative to the
                             working directory.
     --inference_results INFERENCE_RESULTS
                             Path to root directory generated from inference engine
                             diagnosis. Paths may be absolute, or relative to the
                             working directory.

optional arguments:
     --tensor_mapping TENSOR_MAPPING
                             Path to the file describing the tensor name mapping
                             between inference and golden tensors.can be generated
                             with in the inference engine step.
     --verifier_config VERIFIER_CONFIG
                             Path to the verifiers' config file
     --graph_struct GRAPH_STRUCT
                             Path to the inference graph structure .json file. This file
                             aids in providing the structure related information of the converted model graph during this step.
     -v, --verbose         Verbose printing
     -w WORKING_DIR, --working_dir WORKING_DIR
                             Working directory for the verification to store
                             temporary files. Creates a new directory if the
                             specified working directory does not exist
     --output_dirname OUTPUT_DIRNAME
                             output directory name for the verification to store
                             temporary files under <working_dir>/verification.
                             Creates a new directory if the specified working
                             directory does not exist
     --qnn_model_json_path QNN_MODEL_JSON_PATH
                             Path to the model json for transforming intermediate
                             tensors to spatial-first axis order.

arguments for generating a new tensor_mapping.json:
     -m MODEL_PATH, --model_path MODEL_PATH
                             path to original model for tensor_mapping uses here.
     -e ENGINE_NAME [ENGINE_VERSION ...], --engine ENGINE_NAME [ENGINE_VERSION ...]
                             Name of engine that will be running inference,
                             optionally followed by the engine version. Used here
                             for tensor_mapping.
     -f FRAMEWORK [FRAMEWORK ...], --framework FRAMEWORK [FRAMEWORK ...]
                             Framework type to be used, followed optionally by
                             framework version. Used here for tensor_mapping.

Please note: All the command line arguments should either be provided through command line or through the config file. They will not override those in the config file if there is overlap.

使用 ./qnn-accuracy-debugger 运行的主要验证过程 –verification 可以选择使用 –tensor_mapping 和 –graph_struct 来查找要比较的文件。这些文件由推理引擎步骤生成，应提供给验证以获得最佳结果。默认情况下，它们被命名为tensor_mapping.json和{模型名称}_graph_struct.json，可以在推理引擎结果的输出目录中找到。

命令示例

Compare output of framework diagnosis with inference engine:

./qnn-accuracy-debugger \
     --verification \
     --default_verifier CosineSimilarity param1 1 param2 2 \
     --default_verifier SQNR param1 5 param2 1 \
     --golden_output_reference_directory $PROJECTREPOPATH/working_directory/framework_diagnosis/2022-10-31_17-07-58/ \
     --inference_results $PROJECTREPOPATH/working_directory/inference_engine/latest/output/Result_0/ \
     --tensor_mapping $PROJECTREPOPATH/working_directory/inference_engine/latest/tensor_mapping.json \
     --graph_struct $PROJECTREPOPATH/working_directory/inference_engine/latest/qnn_model_graph_struct.json \
     --qnn_model_json_path $PROJECTREPOPATH/working_directory/inference_engine/latest/qnn_model_net.json

提示：

• 如果您从运行推理引擎诊断中传递了 image_list.txt 中的多个图像，您将收到多个输出/Result_x，选择与您用于框架诊断的输入相匹配的结果进行比较（即，在框架中您使用了 chair.raw 和 inference chair.raw 是 image_list.txt 中的第一项，然后选择 output/Result_0，如果 chair.raw 是 image_list.txt 中的第二项，则选择 output/Result_1)。

• 建议始终向命令提供“graph_struct”和“tensor_mapping”，因为它用于排列报告并查找相应的文件进行比较。如果前面的步骤没有生成tensor_mapping，您可以补充’model_path’，‘engine’，‘framework’以使模块在运行时生成’tensor_mapping’。

• 您还可以通过将 inference_engine 输出的 /output 传递到“framework_results”来将 inference_engine 输出与 inference_engine 输出进行比较。如果您希望输出完全名称匹配，则不需要提供tensor_mapping 文件。

• 请注意，如果您需要生成张量映射而不是提供现有张量映射文件的路径。您可以提供“model_path”选项。

验证程序使用两个可选的配置文件。第一个文件用于设置特定验证器的参数，以及在哪些张量上使用这些验证器。第二个文件用于将张量名称从framework_diagnosis映射到inference_engine，因为framework_diagnosis生成的某些张量可能与inference_engine生成的张量具有不同的名称。

验证器配置：

验证器配置文件是一个 JSON 文件，它告诉验证要使用哪些验证器（默认验证器除外）、使用哪些参数以及在哪些特定张量上。如果未提供配置文件，该工具将仅在所有张量上使用从命令行指定的默认验证器及其默认参数。JSON 文件以验证者名称为键，每个验证者都是自己的字典，以“参数”和“张量”为键。

配置文件

```json
{
    "MeanIOU": {
        "parameters": {
            "background_classification": 1.0
        },
        "tensors": [["Postprocessor/BatchMultiClassNonMaxSuppression_boxes", "detection_classes:0"]]
    },
    "TopK": {
        "parameters": {
            "k": 5,
            "ordered": false
        },
        "tensors": [["Reshape_1:0"], ["detection_classes:0"]]
    }
}

请注意，“张量”字段是列表的列表。这样做是因为特定验证器（例如 MeanIOU）一次在两个张量上运行。因此，这两个张量被放置在一个列表中。否则，如果验证器仅在一个张量上运行，它将有一个列表列表，每个列表中只有一个张量名称。

张量映射：

张量映射是一个 JSON 文件，由框架张量名称的推理张量名称键入。如果未提供张量映射，该工具将假设推理和黄金张量名称相同。

张量映射文件

{
    "Postprocessor/BatchMultiClassNonMaxSuppression_boxes": "detection_boxes:0",
    "Postprocessor/BatchMultiClassNonMaxSuppression_scores": "detection_scores:0"
}

输出

验证的输出被分为不同的验证者。例如，如果同时使用RtolAtol和TopK验证器，则会有两个名为“RtolAtol”和“TopK”的子目录。可以通过发出 –help 选项找到可用的验证程序。

在每个子目录下，每个张量的验证分析的组织方式类似于framework_diagnosis（见上文）和inference_engine的组织方式。对于每个张量，都会生成一个 CSV 和 HTML 文件。除了特定于张量的分析之外，该工具还生成一个 CSV 和 HTML 摘要文件，其中汇总了所有验证者及其后续张量的数据。下图显示了验证步骤中生成的示例摘要的外观。此摘要中的每一行对应于由框架诊断和推理引擎步骤识别的一个张量名称。最后一列显示余弦相似度分数，可以在 0 到 1 之间变化（这个范围对于其他验证者可能不同）。较高的分数表示相似性，而较低的分数表示差异。然后，开发人员可以进一步研究这些特定的张量细节。开发人员应从上到下的顺序检查张量，这意味着如果张量在较早的节点处损坏，则在该节点正确修复之前生成的任何内容都是不可靠的。

比较编码
比较编码功能旨在比较 QNN 和 AIMET 编码。此功能将 QNN 模型网络和 AIMET 编码 JSON 文件作为输入。此功能按以下顺序执行。

1. 从给定的 QNN 模型网络 JSON 中提取编码。

2. 将提取的 QNN 编码与给定的 AIMET 编码进行比较。

3. 将结果写入突出显示不匹配的 Excel 文件。

4. 如果某些编码存在于 QNN 中但不存在于 AIMET 中，则会引发警告，反之亦然。

5. 写入提取的 QNN 编码 JSON 文件（供参考）。

用法

usage: qnn-accuracy-debugger --compare_encodings [-h]
                             --qnn_net_json QNN_NET_JSON
                             --aimet_encodings_json AIMET_ENCODINGS_JSON
                             [--precision PRECISION]
                             [--params_only]
                             [--activations_only]
                             [--specific_node SPECIFIC_NODE]
                             [--working_dir WORKING_DIR]
                             [--output_dirname OUTPUT_DIRNAME]
                             [-v]

Script to compare QNN encodings with AIMET encodings

optional arguments:
  -h, --help            Show this help message and exit

required arguments:
  --qnn_net_json QNN_NET_JSON
                        Path to QNN model net JSON file
  --aimet_encodings_json AIMET_ENCODINGS_JSON
                        Path to AIMET encodings JSON file
  --specific_node SPECIFIC_NODE
                        Display encoding difference for given node name

optional arguments:
  --precision PRECISION
                        Number of decimal places up to which comparison will be done (default: 17)
  --params_only         Compare only parameters in the encodings
  --activations_only    Compare only activations in the encodings
  --working_dir WORKING_DIR
                        Working directory for the compare_encodings to store temporary files.
                        Creates a new directory if the specified working directory does not exist.
  --output_dirname OUTPUT_DIRNAME
                        Output directory name for the compare_encodings to store temporary files
                        under <working_dir>/compare_encodings. Creates a new directory if the
                        specified working directory does not exist.
  -v, --verbose         Verbose printing

命令示例

# Compare both params and activations
./qnn-accuracy-debugger \
    --compare_encodings \
    --qnn_net_json QNN_model_net.json \
    --aimet_encodings_json aimet_encodings.json

# Compare only params
./qnn-accuracy-debugger \
    --compare_encodings \
    --qnn_net_json QNN_model_net.json \
    --aimet_encodings_json aimet_encodings.json \
    --params_only

# Compare only activations
./qnn-accuracy-debugger \
    --compare_encodings \
    --qnn_net_json QNN_model_net.json \
    --aimet_encodings_json aimet_encodings.json \
    --activations_only

# Compare only a specific encoding
./qnn-accuracy-debugger \
    --compare_encodings \
    --qnn_net_json QNN_model_net.json \
    --aimet_encodings_json aimet_encodings.json \
    --specific_node _2_22_Conv_output_0

提示

除非另有指定，否则从调用此脚本的任何位置都会生成工作目录。

输出

该程序在working_directory/compare_encodings中创建一个名为latest的目录，该目录以符号方式链接到最近生成的目录。在下面的示例中，最新的数据将符号链接到最新目录YYYY-MM-DD_HH:mm:ss中的数据。用户可以选择通过将目录名称传递给 –output_dirname 来覆盖目录名称，例如–output_dirname myTest。

上图显示了compare_encodings 运行的示例输出。以下详细说明每个文件包含的内容。

• Compare_encodings_options.json 包含用于运行此功能的所有选项

• codings_diff.xlsx 包含突出显示不匹配的比较结果

• log.txt 包含运行的日志语句

• qnn_encoding.json 包含提取的 QNN 编码

张量检查
张量检查器比较给定的参考输出和目标输出张量，并转储各种统计数据以表示它们之间的差异。

张量检查器工具可以：

• 绘制黄金张量和目标张量的直方图

• 绘制一个图表，指示黄金张量和目标张量之间的偏差

• 绘制黄金张量与目标张量的累积分布图 (CDF)

• 绘制目标张量的密度 (KDE) 图，突出显示目标最小/最大值和校准的最小/最大值

• 创建一个 CSV 文件，其中包含以下信息：目标最小值/最大值；校准最小值/最大值；黄金输出最小/最大；目标/校准的最小/最大差异；和计算指标（验证者）。

笔记
仅检查具有匹配目标/黄金文件名的数据；其他数据被忽略
校准的最小/最大值是从用户提供的编码文件中提取的。如果未提供编码文件，将跳过密度图，并且 CSV 摘要输出将不包括校准的最小/最大信息。

用法

usage: qnn-accuracy-debugger --tensor_inspection [-h]
                        --golden_data GOLDEN_DATA
                        --target_data TARGET_DATA
                        --verifier VERIFIER [VERIFIER ...]
                        [-w WORKING_DIR]
                        [--data_type {int8,uint8,int16,uint16,float32}]
                        [--target_encodings TARGET_ENCODINGS]
                        [-v]

Script to inspection tensor.

required arguments:
  --golden_data GOLDEN_DATA
                        Path to golden/framework outputs folder. Paths may be absolute or
                        relative to the working directory.
  --target_data TARGET_DATA
                        Path to target outputs folder. Paths may be absolute or relative to the
                        working directory.
  --verifier VERIFIER [VERIFIER ...]
                        Verifier used for verification. The options "RtolAtol",
                        "AdjustedRtolAtol", "TopK", "L1Error", "CosineSimilarity", "MSE", "MAE",
                        "SQNR", "MeanIOU", "ScaledDiff" are supported.
                        An optional list of hyperparameters can be appended, for example:
                        --verifier rtolatol,rtolmargin,0.01,atolmargin,0,01.
                        To use multiple verifiers, add additional --verifier CosineSimilarity

optional arguments:
  -w WORKING_DIR, --working_dir WORKING_DIR
                        Working directory to save results. Creates a new directory if the
                        specified working directory does not exist
  --data_type {int8,uint8,int16,uint16,float32}
                        DataType of the output tensor.
  --target_encodings TARGET_ENCODINGS
                        Path to target encodings json file.
  -v, --verbose         Verbose printing

命令示例

# Basic run
./tensor-inspector \
    --golden_data golden_tensors_dir \
    --target_data target_tensors_dir \
    --verifier sqnr

# Pass target encodings file and enable multiple verifiers
./tensor-inspector \
    --golden_data golden_tensors_dir \
    --target_data target_tensors_dir \
    --verifier mse \
    --verifier sqnr \
    --verifier rtolatol,rtolmargin,0.01,atolmargin,0.01 \
    --target_encodings qnn_encoding.json

提示

除非另有指定，否则从调用此脚本的任何位置都会生成工作目录。

上图显示了张量检查运行的示例输出。以下详细说明每个文件包含的内容。

• 每个张量都会有自己的目录；目录名称与张量名称匹配。

  • CDF_plots.png – 黄金与目标 CDF 图
  • Diff_plots.png – 黄金和目标偏差图
  • Distribution_min-max.png – 目标张量的密度图，突出显示目标与校准的最小/最大值
  • Histograms.png – 黄金直方图和目标直方图
  • Golden_data.csv – 黄金张量数据
  • target_data.csv – 目标张量数据

• log.txt – 整个运行过程中的日志语句

• Summary.csv – 目标最小值/最大值、校准最小值/最大值、黄金输出最小值/最大值、目标与校准最小值/最大值差异以及验证器输出

运行 QNN 精度调试器 E2E
此功能旨在通过单个命令顺序运行框架诊断、推理引擎和验证功能来调试模型。可以使用以下调试算法。

• 单次逐层（默认）：

  • 该算法旨在通过执行以下步骤一次调试模型的所有层

    • 执行框架诊断以收集 fp32 中的参考输出

    • 执行推理引擎以提供的目标精度收集后端输出。

    • 执行验证以比较上述 2 个步骤的中间输出

  • 它提供快速分析来识别导致精度偏差的模型层。

  • 用户可以选择累积分层（如下）来更深入地分析精度偏差。

• 逐层累积：

  • 该算法旨在通过执行以下步骤一次调试一层

    • 执行框架诊断以收集 fp32 中模型各层的参考输出。

    • 以迭代的方式执行推理引擎和验证来执行以下操作

      • 以目标精度收集每一层的后端输出，同时消除其前一层对最终输出的影响。

      • 比较框架诊断和推理引擎的中间输出

  • 它提供更深入的分析来识别导致精度偏差的模型的所有层。

  • 目前此选项仅支持 onnx 模型。

• 分层：

  • 该算法旨在通过执行以下步骤一次调试单层模型

    • 从外部工具获取每层输出的黄金参考，或者，如果未给出黄金参考，则运行框架诊断以收集中间层输出。

    • 迭代执行推理引擎和验证以：

      • 通过删除前面和后面的层，以目标精度收集每个单层模型的后端输出

      • 将黄金参考的中间输出与推理引擎单层模型输出进行比较

  • 分层侦听提供更深入的分析，以识别导致硬件相对于框架/模拟输出的精度偏差的所有模型层。

  • 分层侦听仅支持 ONNX 模型。

用法

usage: qnn-accuracy-debugger [--framework_diagnosis] [--inference_engine] [--verification] [-h]

Script that runs Framework Diagnosis, Inference Engine or Verification.

Arguments to select which component of the tool to run.  Arguments are mutually exclusive (at
most 1 can be selected).  If none are selected, then all components are run:
--framework_diagnosis Run framework
--inference_engine    Run inference engine
--verification        Run verification

optional arguments:
-h, --help              Show this help message. To show help for any of the components, run
                        script with --help and --<component>. For example, to show the help
                        for Framework Diagnosis, run script with the following: --help
                        --framework_diagnosis

usage: qnn-accuracy-debugger [-h] -f FRAMEWORK [FRAMEWORK ...] -m MODEL_PATH -i INPUT_TENSOR
                            [INPUT_TENSOR ...] -o OUTPUT_TENSOR -r RUNTIME -a
                            {aarch64-android,x86_64-linux-clang,aarch64-android-clang6.0}
                            -l INPUT_LIST --default_verifier DEFAULT_VERIFIER
                            [DEFAULT_VERIFIER ...] [-v] [-w WORKING_DIR]
                            [--output_dirname OUTPUT_DIRNAME]
                            [--deep_analyzer {modelDissectionAnalyzer}]
                            [--debugging_algorithm {layerwise,cumulative-layerwise,oneshot-layerwise}]

Options for running the Accuracy Debugger components

optional arguments:
-h, --help            show this help message and exit

Arguments required by both Framework Diagnosis and Inference Engine:
-f FRAMEWORK [FRAMEWORK ...], --framework FRAMEWORK [FRAMEWORK ...]
                        Framework type and version, version is optional. Currently supported
                        frameworks are [tensorflow, tflite, onnx]. For example, tensorflow
                        2.3.0
-m MODEL_PATH, --model_path MODEL_PATH
                        Path to the model file(s).
-i INPUT_TENSOR [INPUT_TENSOR ...], --input_tensor INPUT_TENSOR [INPUT_TENSOR ...]
                        The name, dimensions, raw data, and optionally data type of the
                        network input tensor(s) specifiedin the format "input_name" comma-
                        separated-dimensions path-to-raw-file, for example: "data"
                        1,224,224,3 data.raw float32. Note that the quotes should always be
                        included in order to handle special characters, spaces, etc. For
                        multiple inputs specify multiple --input_tensor on the command line
                        like: --input_tensor "data1" 1,224,224,3 data1.raw --input_tensor
                        "data2" 1,50,100,3 data2.raw float32.
-o OUTPUT_TENSOR, --output_tensor OUTPUT_TENSOR
                        Name of the graph's specified output tensor(s).

Arguments required by Inference Engine:
-r RUNTIME, --runtime RUNTIME
                        Runtime to be used for inference.
-a {aarch64-android,x86_64-linux-clang,aarch64-android-clang6.0}, --architecture {aarch64-an
droid,x86_64-linux-clang,aarch64-android-clang6.0}
                        Name of the architecture to use for inference engine.
-l INPUT_LIST, --input_list INPUT_LIST
                        Path to the input list text.
Arguments required by Verification:                                                    [3/467]
--default_verifier DEFAULT_VERIFIER [DEFAULT_VERIFIER ...]
                        Default verifier used for verification. The options "RtolAtol",
                        "AdjustedRtolAtol", "TopK", "L1Error", "CosineSimilarity", "MSE",
                        "MAE", "SQNR", "MeanIOU", "ScaledDiff" are supported. An optional
                        list of hyperparameters can be appended. For example:
                        --default_verifier rtolatol,rtolmargin,0.01,atolmargin,0,01. An
                        optional list of placeholders can be appended. For example:
                        --default_verifier CosineSimilarity param1 1 param2 2. to use
                        multiple verifiers, add additional --default_verifier
                        CosineSimilarity

optional arguments:
-v, --verbose           Verbose printing
-w WORKING_DIR, --working_dir WORKING_DIR
                        Working directory for the wrapper to store temporary files. Creates
                        a new directory if the specified working directory does not exitst.
--output_dirname OUTPUT_DIRNAME
                        output directory name for the wrapper to store temporary files under
                        <working_dir>/wrapper. Creates a new directory if the specified
                        working directory does not exist
--deep_analyzer {modelDissectionAnalyzer}
                        Deep Analyzer to perform deep analysis
--golden_output_reference_directory
                        Optional parameter to indicate the directory of the golden reference outputs.
                        When this option is provided, the framework diagnosis is stage skipped.
                        In inference stage, it's used for tensor mapping without a framework.
                        In verification stage, it's used as a reference to compare
                        outputs produced in the inference engine stage.
--debugging_algorithm {layerwise,cumulative-layerwise,oneshot-layerwise}
                        Performs model debugging layerwise, cumulative-layerwise or in oneshot-
                        layerwise based on choice.

(below options are allowed only for Layerwise and Cumulative layerwise run)
--start_layer START_LAYER
                        Extracts the given model from mentioned start layer
                        output name
--end_layer END_LAYER
                        Extracts the given model from mentioned end layer
                        output name

oneshot-layerwise 的示例命令

./qnn-accuracy-debugger \
    --framework tensorflow \
    --runtime dspv73 \
    --model_path $RESOURCESPATH/samples/InceptionV3Model/inception_v3_2016_08_28_frozen.pb \
    --input_tensor "input:0" 1,299,299,3 $PATHTOGOLDENI/samples/InceptionV3Model/data/chairs.raw \
    --output_tensor InceptionV3/Predictions/Reshape_1:0 \
    --architecture x86_64-linux-clang \
    --debugging_algorithm oneshot-layerwise
    --input_list $RESOURCESPATH/samples/InceptionV3Model/data/image_list.txt \
    --default_verifier CosineSimilarity \
    --framework_results $PROJECTREPOPATH/working_directory/framework_diagnosis/latest/ \
    --inference_results $PROJECTREPOPATH/working_directory/inference_engine/latest/output/Result_0/ \
    --tensor_mapping $PROJECTREPOPATH/working_directory/inference_engine/latest/tensor_mapping.json \
    --graph_struct $PROJECTREPOPATH/working_directory/inference_engine/latest/qnn_model_graph_struct.json \
    --qnn_model_json_path $PROJECTREPOPATH/working_directory/inference_engine/latest/qnn_model_net.json \
    --verbose

Command for Oneshot-layerwise using HTP emulation on x86 host:

./qnn-accuracy-debugger \
    --framework onnx \
    --runtime htp \
    --model_path /local/mnt/workspace/models/vit/vit_base_16_224.onnx \
    --input_tensor "input.1" 1,3,224,224 /local/mnt/workspace/models/vit/000000039769_1_3_224_224.raw \
    --output_tensor 1597 \
    --architecture x86_64-linux-clang \
    --input_list /local/mnt/workspace/models/vit/list.txt \
    --default_verifier CosineSimilarity \
    --offline_prepare \
    --debugging_algorithm oneshot-layerwise
    --engine QNN \
    --verbose

输出

该程序创建framework_diagnosis、inference_engine、verification和wrapper输出目录，如下所示：

• Framework_diagnosis – 包含带时间戳的目录，其中包含以 .raw 格式存储的中间层输出（框架），如框架诊断步骤中所述。

• inference_engine – 包含带时间戳的目录，其中包含以 .raw 格式存储的中间层输出（推理引擎），如推理引擎步骤中所述。

• 验证目录 – 包含带时间戳的目录，其中包含以下内容：

  • 运行 oneshot 时指定的每个验证程序的目录；它包含 CSV 和 HTML 文件，其中包含每层输出的指标详细信息

  • tensor_inspection – 每层输出的单独目录，包含以下内容：

    • CDF_plots.png – 黄金与目标 CDF 图
    • Diff_plots.png – 黄金和目标偏差图
    • Histograms.png – 黄金直方图和目标直方图
    • Golden_data.csv – 黄金张量数据
    • target_data.csv – 目标张量数据

  • summary.csv – 每层输出的验证结果报告

• 包含 log.txt 的包装器目录以及运行的整个日志。

注意：除了包装器目录之外，所有其他目录都会有一个名为“latest”的文件夹，它是指向最新运行的相应时间戳目录的符号链接。

Summary.csv 文件的快照：

了解一次性分层报告：

柱子	描述
姓名	当前图层的输出名称
图层类型	当前图层类型
尺寸	该层输出的大小
张量尺寸	该层输出的形状
<验证者姓名>	当前层输出与参考输出相比的验证器值
黄金分钟	当前层参考输出中的最小值
黄金最大	当前层参考输出中的最大值
目标最小值	当前层目标输出的最小值
目标最大	当前层目标输出的最大值

逐层累积命令示例

./qnn-accuracy-debugger \
    --framework onnx \
    --runtime dspv73 \
    --model_path /local/mnt/workspace/models/vit/vit_base_16_224.onnx \
    --input_tensor "input.1" 1,3,224,224 /local/mnt/workspace/models/vit/000000039769_1_3_224_224.raw \
    --output_tensor 1597 \
    --architecture x86_64-linux-clang \
    --input_list /local/mnt/workspace/models/vit/list.txt \
    --default_verifier CosineSimilarity \
    --offline_prepare \
    --debugging_algorithm cumulative-layerwise
    --engine QNN \
    --verbose

Command for Cumulative-layerwise using HTP emulation on x86 host:

./qnn-accuracy-debugger \
    --framework onnx \
    --runtime htp \
    --model_path /local/mnt/workspace/models/vit/vit_base_16_224.onnx \
    --input_tensor "input.1" 1,3,224,224 /local/mnt/workspace/models/vit/000000039769_1_3_224_224.raw \
    --output_tensor 1597 \
    --architecture x86_64-linux-clang \
    --input_list /local/mnt/workspace/models/vit/list.txt \
    --default_verifier CosineSimilarity \
    --offline_prepare \
    --debugging_algorithm cumulative-layerwise
    --engine QNN \
    --verbose

输出
该程序创建输出目录framework_diagnosis、cumulative_layerwise_snooping和wrapper目录如下

• Framework_diagnosis 目录包含带时间戳的目录，其中包含以 .raw 格式存储的中间层输出，正如框架诊断步骤中提到的那样。

• cumulative_layerwise_snooping 目录包含从推理引擎步骤获得的中间输出，存储在具有各自层名称的单独目录中。它还包含名为cumulative_layerwise.csv 的最终报告，其中包含每层的验证者分数。用户可以将得分偏差最大的层识别为有问题的节点。

• Wrapper 目录包含一个 log.txt，用户可以在其中引用整个运行的完整日志。
  
  了解累积分层报告

在累积分层运行结束时，该工具会生成 .csv，其中每层包含以下信息

Command for Layerwise:

./qnn-accuracy-debugger \
    --framework onnx \
    --runtime dspv73 \
    --model_path /local/mnt/workspace/models/vit/vit_base_16_224.onnx \
    --input_tensor "input.1" 1,3,224,224 /local/mnt/workspace/models/vit/000000039769_1_3_224_224.raw \
    --output_tensor 1597 \
    --architecture x86_64-linux-clang \
    --input_list /local/mnt/workspace/models/vit/list.txt \
    --default_verifier CosineSimilarity \
    --offline_prepare \
    --debugging_algorithm layerwise
    --golden_directory /local/mnt/workspace/aimet_layer_output_dump/outputs/layer_outputs_0/
    --quantization_overrides /local/mnt/workspace/layer_output_dump/vit_base_16_224.encodings
    --engine QNN \
    --verbose

输出

如果未提供黄金参考（如针对累积分层所描述的），程序将创建layerwise_snooping和包装器输出目录以及framework_diagnosis。

• Layerwise_snooping 目录 – 包含从存储在单独目录中的推理引擎阶段获得的每个单层模型输出以及名为 Layerwise.csv 的最终报告，其中包含每个层模型的验证器分数。用户可以将得分偏差最大的层识别为有问题的节点。

• 包装器目录 – 包含 log.txt，其中存储运行的完整日志。

• 输出 .csv 与累积分层输出类似，但原始输出列不会出现在分层监听中，因为我们不处理模型的最终输出。

使用累积分层侦听调试量化模型的准确性问题

• 对于量化模型，预计大多数数据密集层都会出现一些不匹配——这是由于量化误差而引起的。

• 调试器可用于识别具有高验证器分数的最敏感操作符，并以更高的精度运行这些操作符以提高整体准确性。

• 敏感性由在该层看到的关于参考平台（如 ONNXRT）的验证者分数决定。

• 请注意，累积分层调试需要相当长的时间，因为分区模型应在与参考不具有 100% 匹配的每一层进行量化和编译。

• 以下是调试较大模型的一种策略：

  • 在模型上逐层运行 Oneshot，这有助于识别模型中敏感度的起点。

  • 使用开始层和结束层选项在模型的不同部分运行累积分层（如果模型有 100 个节点，则在运行 1 的第 25 个节点处使用来自 Oneshot-layerwise 运行的开始节点处的开始层，开始对于运行 2，起始层位于第 26 个节点，结束层位于第 50 个节点；对于运行 3，起始层位于第 51 个节点，结束层位于第 75 个节点…依此类推）。所有运行的最终报告有助于识别模型中最敏感的层。假设节点 A、B、C 的验证者分数较高，这表明敏感度较高

    • 在 FP16 中运行具有这些特定层（A/B/C - 一次一个或组合）的原始模型，并观察准确性的提高。

模型的调试精度问题表现出黄金参考（例如 AIMET/框架运行时输出）与使用分层侦听的目标输出之间的精度差异

• 分层侦听的流行用例之一是调试 AIMET 与目标之间的准确度差异

  • 尽管我们正在使用 AIMET 等工具创建精确的硬件模拟，但由于环境差异，预计仍然会出现非常微小的不匹配。这可能是因为模拟在 GPU FP32 内核上执行，并且模拟噪声，而不是在硬件执行的情况下在整数内核上实际执行。

  • 如果我们在模拟和硬件之间有较高的偏差，则可以使用分层窥探来指出具有较高偏差的节点。根据layerwise.csv 显示较高偏差的节点可以被识别为错误节点。

• 其他用例包括调试框架运行时的 FP32 输出与目标 INT16 输出偏差。

6.4.4 qnn 平台验证器

qnn-platform-validator 检查设备的 QNN 兼容性/功能。输出以 csv 格式保存在“output”目录中的 CSV 文件中。基本日志也显示在控制台上。

DESCRIPTION:
------------
Helper script to set up the environment for and launch the qnn-platform-
validator executable.

REQUIRED ARGUMENTS:
-------------------
--backend            <BACKEND>          Specify the backend to validate: <gpu>, <dsp>
                                        <all>.

--directory          <DIR>              Path to the root of the unpacked SDK directory containing
                                        the executable and library files

--dsp_type           <DSP_VERSION>      Specify DSP variant: v66 or v68

OPTIONALS ARGUMENTS:
--------------------
--buildVariant       <TOOLCHAIN>        Specify the build variant
                                        aarch64-android or aarch64-windows-msvc to be validated.
                                        Default: aarch64-android

--testBackend                           Runs a small program on the runtime and Checks if QNN is supported for
                                        backend.

--deviceId           <DEVICE_ID>        Uses the device for running the adb command.
                                        Defaults to first device in the adb devices list..

--coreVersion                           Outputs the version of the runtime that is present on the target.

--libVersion                            Outputs the library version of the runtime that is present on the target.

--targetPath          <DIR>             The path to be used on the device.
                                        Defaults to /data/local/tmp/platformValidator

--remoteHost         <REMOTEHOST>       Run on remote host through remote adb server.
                                        Defaults to localhost.

--debug                                 Set to turn on Debug log

6.4.5 qnn-个人资料查看器

qnn-profile-viewer工具用于解析使用 qnn-net-run生成的分析数据。此外，相同的数据可以保存到 csv 文件中。

usage: qnn-profile-viewer --input_log PROFILING_LOG [--help] [--output=CSV_FILE] [--extract_opaque_objects] [--reader=CUSTOM_READER_SHARED_LIB] [--schematic=SCHEMATIC_BINARY]

Reads a profiling log and outputs the contents to stdout

Note: The IPS calculation takes the following into account: graph execute time, tensor file IO time, and misc. time for quantization, callbacks, etc.

required arguments:
  --input_log                     PROFILING_LOG
                                  Profiling log file.

optional arguments:
  --output                        PATH
                                  Output file with processed profiling data. File formats vary depending upon the reader used
                                  (see --reader). If not provided, not output is created.

  --help                          Displays this help message.

  --reader                        CUSTOM_READER_SHARED_LIB
                                  Path to a reader library. If not specified, the default reader outputs a CSV file.

  --schematic                     SCHEMATIC_BINARY
                                  Path to the schematic binary file.
                                  Please note that this option is specific to the QnnHtpOptraceProfilingReader library.

  --version                       Displays version information.

  --extract_opaque_objects        Specifies that the opaque objects will be dumped to output files

6.4.6 qnn-上下文-二进制-实用程序

qnn -context-binary-utility工具验证上下文二进制文件的元数据并将其序列化为 json 文件。然后，此 json 文件可用于检查上下文二进制文件，以帮助调试。可以使用 QNN API 或 qnn-context-binary-generator 工具将 QNN 上下文序列化为二进制。

usage: qnn-context-binary-utility --context_binary CONTEXT_BINARY_FILE --json_file JSON_FILE_NAME [--help] [--version]

Reads a serialized context binary and validates its metadata.
If --json_file is provided, it outputs the metadata to a json file

required arguments:
  --context_binary  CONTEXT_BINARY_FILE
                    Path to cached context binary from which the binary info will be extracted
                    and written to json.

  --json_file       JSON_FILE_NAME
                    Provide path along with the file name <DIR>/<FILE_NAME> to serialize
                    context binary info into json.
                    The directory path must exist. File with the FILE_NAME will be created at DIR.

optional arguments:
  --help          Displays this help message.

  --version       Displays version information.