使用 QAIRT C++ API 开发 AI 应用

Qualcomm AI Runtime（QAIRT）SDK 提供用于示例应用开发的 C++ API。 Qualcomm AI Engine Direct（QNN）和 Qualcomm 神经处理引擎 SDK（SNPE）都提供了示例。这些示例可帮助您开始应用开发。以下说明介绍如何构建、运行和浏览源代码，并演示使用 QNN 或 SNPE API 运行模型的工作流程。

构建并运行 QNN 示例应用

qnn-sample-app 位于 ${QNN_SDK_ROOT}/examples/QNN/SampleApp，其中 QNN_SDK_ROOT 指 QNN SDK 解压后的路径。

设置 QAIRT SDK

要为 QNN 示例应用设置工具链，请完成以下步骤：

下载 Qualcomm AI Runtime SDK。

解压 SDK。

unzip v2.47.0.260601.zip

cd qairt/2.47.0.260601

export QNN_SDK_ROOT=`pwd`

安装 SDK。按照构建 QIM SDK 安装 SDK，其中包含所需的交叉编译工具链。
- 这些库使用 GCC-11.2 编译。
- 使用 SDK 安装路径设置 SDK_PATH 环境变量。后续步骤将使用该安装路径（/path/to/extracted/toolchain）进行编译。
export SDK_PATH="/path/to/extracted/toolchain"

构建 QNN 示例应用

完成以下步骤以构建 QNN 示例应用。

进入示例应用目录。

cd ${QNN_SDK_ROOT}/examples/QNN/SampleApp/SampleApp/

为 GCC 工具链设置环境变量。

export QNN_AARCH64_LINUX_OE_GCC_112=$SDK_PATH

构建应用。
make CXX="$SDK_PATH/sysroots/x86_64-qcomsdk-linux/usr/bin/aarch64-qcom-linux/aarch64-qcom-linux-g++ --sysroot=$SDK_PATH/sysroots/armv8a-qcom-linux/" all_linux_oe_aarch64_gcc112
此操作会创建两个文件夹。
- bin：包含各平台的 qnn-sample-app 二进制文件，分别位于各自的目录中。
- obj：包含构建和链接可执行文件所用的所有目标文件。

在 Linux（基于 Yocto）上运行 QNN 示例应用

构建好的 qnn-sample-app 可执行文件可以使用任意 QNN 后端运行模型。对于基于 Yocto scarthgap 的设备，可使用 aarch64-oe-linux-gcc11.2 的后端。

将产物推送到目标设备。

scp ${QNN_SDK_ROOT}/examples/QNN/SampleApp/SampleApp/bin/aarch64-oe-linux-gcc11.2/qnn-sample-app root@<IP_ADDRESS_OF_TARGET_DEVICE>:/etc/apps/qnn-sample-app

如果设备上尚不存在 /etc/apps/ 目录，请先创建它。

在主机上，使用 AI Hub 导出模型。例如，要导出 InceptionV3 QNN 模型，请运行以下命令：

pip3 install qai-hub-models

python -m qai_hub_models.models.inception_v3.export --quantize w8a8 --target-runtime=qnn_context_binary --device="Dragonwing RB3 Gen 2 Vision Kit" --compile-options="--qairt_version 2.45" --profile-options "--qairt_version 2.45"

请为目标设备上正在使用的相同 SDK 版本生成上下文二进制文件。

将导出的 InceptionV3 QNN 模型推送到目标设备。将模型保存到 export_assets/inception_v3-qnn_context_binary-w8a8-<CHIPSET>。以下示例使用 QCS6490 作为芯片组。
scp export_assets/inception_v3-qnn_context_binary-w8a8-qualcomm_qcs6490/inception_v3.bin root@<IP_ADDRESS_OF_TARGET_DEVICE>:/etc/apps
当提示输入密码时，输入 oelinux123。
在主机上生成用于推理的虚拟输入文件，并将其传输到目标设备。 a. 在 Python 环境中运行以下命令。
python3
import numpy as np np.random.random((1, 3, 299, 299)).astype(np.float32).tofile("input.raw")
b. 将 input.raw 文件传输到目标设备：
scp input.raw root@<IP_ADDRESS_OF_TARGET_DEVICE>:/etc/apps

从主机通过 SSH 连接到目标设备。

ssh root@<IP_ADDRESS_OF_TARGET_DEVICE>

cd /etc/apps

创建 input_list.txt。

echo "input.raw" > /etc/apps/input_list.txt

运行应用。

chmod +x qnn-sample-app

./qnn-sample-app --retrieve_context inception_v3.bin \
                --backend libQnnHtp.so \
                --input_list input_list.txt \
                --system_library libQnnSystem.so

请根据所选模型更新模型名称和 input_list。

要查看帮助信息，请运行：

./qnn-sample-app --help

命令行参数

必需参数

--model：QNN 网络模型的路径。与 --retrieve_context 互斥。
--retrieve_context：缓存二进制文件的路径，用于加载已保存的上下文和执行图。与 --model 互斥。
--backend：用于运行模型的 QNN 后端的路径。
--input_list：列出网络输入的文件路径。对于多个图，请提供以逗号分隔的输入文件列表。

可选参数

--debug：保存所有网络层的输出。
--output_dir：输出目录（默认：./output）。
--output_data_type：输出数据类型（float_only、native_only、float_and_native）。
--input_data_type：输入数据类型（float 或 native）。
--op_packages：以逗号分隔的算子包和接口提供者列表。
--profiling_level：性能分析级别（basic 或 detailed）。
--save_context：将后端上下文和图元数据保存到二进制文件。
--num_inferences：要执行的推理次数。
--log_level：最高日志级别（error、warn、info、verbose）。
--system_library：libQnnSystem.so 的路径，用于上下文加载期间的反射 API。
--version：打印 QNN SDK 版本。
--help：显示帮助信息。

工作流程与 API 使用

使用以下推荐模式来开发使用 QNN API 的 C++ 应用。

加载必备的共享库

QNN SDK 提供多种共享库以访问后端，应用需要按需加载它们才能运行网络。可通过以下方式之一在 QNN 中创建网络。

在应用中直接使用 QNN API 构建网络。
使用 QNN 转换器生成 QNN 网络的共享库。

qnn-sample-app 使用共享库方式。该网络可以使用 SDK 中提供的某个 QNN 转换器生成，并使用 qnn-model-lib-generator 编译为共享库。

对于 Windows 用户，在以下说明中请将所有 .so 文件替换为对应的 .dll 文件。有关更多详细信息，请参见平台差异。

加载后端

QNN SDK 中提供了包括 CPU、GPU、HTP 和 DSP 在内的各种后端的共享库。每个实现 QNN API 的后端都会公开所有必要的符号，这些符号可以通过动态加载机制访问。以名为 libQnnSampleBackend.so 的示例后端共享库为例，可按如下方式动态加载：

void* libBackendHandle = pal::dynamicloading::dlOpen(
  "libQnnSampleBackend.so", pal::dynamicloading::DL_NOW | pal::dynamicloading::DL_LOCAL);

if (nullptr == libBackendHandle) {
  QNN_ERROR("Unable to load backend. pal::dynamicloading::dlError(): %s",
            pal::dynamicloading::dlError());
  return StatusCode::FAIL_LOAD_BACKEND;

要以共享库形式加载模型，我们以名为 libQnnSampleModel.so 的示例模型共享库为例，可按如下方式动态加载：

void* libModelHandle = pal::dynamicloading::dlOpen(
    "libQnnSampleModel.so", pal::dynamicloading::DL_NOW | pal::dynamicloading::DL_LOCAL);

if (nullptr == libModelHandle) {
  QNN_ERROR("Unable to load model. pal::dynamicloading::dlError(): %s",
            pal::dynamicloading::dlError());
  return StatusCode::FAIL_LOAD_MODEL;
}

可选地，为了从缓存的二进制文件创建上下文并执行图，应用可以使用 QnnSystem API 来检索与上下文关联的元数据。QnnSystem API 可以通过加载 libQnnSystem.so 共享库来访问，如下所示：

void* systemLibraryHandle = pal::dynamicloading::dlOpen(
  "libQnnSystem.so", pal::dynamicloading::DL_NOW | pal::dynamicloading::DL_LOCAL);

if (nullptr == systemLibraryHandle) {
  QNN_ERROR("Unable to load system library. pal::dynamicloading::dlError(): %s",
            pal::dynamicloading::dlError());
  return StatusCode::FAIL_LOAD_SYSTEM_LIB;
}

解析共享库中的符号

共享库成功加载后，我们即可继续解析访问 QNN API 所需的全部符号。以下代码片段展示了在共享库中解析符号的模板：

// A generic function to resolve symbols in a library
template <class T>
static inline T resolveSymbol(void* libHandle, const char* symName) {
T ptr = (T)pal::dynamicloading::dlSym(libHandle, symName);
if (ptr == nullptr) {
  QNN_ERROR("Unable to access symbol [%s]. pal::dynamicloading::dlError(): %s", symName, pal::dynamicloading::dlError());
}
return ptr;
}
// Template for resolving a function of type SampleFnHandleType_t
typedef ReturnType_t (*SampleFnHandleType_t)(FunctionParameterTypes_t ...);
SampleFnHandleType_t sampleFn = nullptr;
sampleFnHandle = resolveSymbol<SampleFnHandleType_t>(libBackendHandle, "QnnSample_API");
if (nullptr == sampleFnHandle) {
// Error code indicating failure in symbol resolution
return StatusCode::FAIL_SYM_FUNCTION;
}

以下代码片段展示了如何解析实际 QNN API 的示例：

/* Resolve the symbol for Qnn_ErrorHandle_t QnnInterface_getProviders(const QnnInterface_t*** providerList,
                                                                    uint32_t* numProviders)
  API */

typedef Qnn_ErrorHandle_t (*QnnInterfaceGetProvidersFn_t)(const QnnInterface_t*** providerList,
                                                        uint32_t* numProviders);

QnnInterfaceGetProvidersFn_t getInterfaceProviders {nullptr};

getInterfaceProviders =
resolveSymbol<QnnInterfaceGetProvidersFn_t>(libBackendHandle, "QnnInterface_getProviders");
if (nullptr == getInterfaceProviders) {
return StatusCode::FAIL_SYM_FUNCTION;
}

在 qnn-sample-app 源代码中，所有必要的符号都被解析并存储在如下所示的 QnnFunctionPointers 类型的结构体中：

typedef struct QnnFunctionPointers {
  // APIs from model output from converters
  // QnnModel_composeGraphs
  ComposeGraphsFnHandleType_t composeGraphsFnHandle;
  // QnnModel_freeGraphsInfo
  FreeGraphInfoFnHandleType_t freeGraphInfoFnHandle;
  // QNN Interface function table containing pointers to all necessary QNN APIs
  // in a backend
  QNN_INTERFACE_VER_TYPE qnnInterface;
  // QNN System Interface function table containing pointers to all QNN System APIs
  QNN_SYSTEM_INTERFACE_VER_TYPE qnnSystemInterface;
} QnnFunctionPointers;

上述结构体可以在 ${QNN_SDK_ROOT}/examples/QNN/SampleApp/SampleApp/src/SampleApp.hpp 中找到。本教程的其余部分将假定存在一个名为 m_qnnFunctionPointers 的 QnnFunctionPointers 类型变量，其中包含有效的函数指针。

QNN API 的用法

本节演示在客户端应用中使用 QNN API。

使用 QNN Interface 获取函数指针

可以使用 QNN Interface 机制来建立指向后端中 QNN API 的函数指针表，而不必逐个手动解析每个 API 的符号，这使符号解析变得简单。QNN Interface 的使用方式如下：

QnnInterface_t** interfaceProviders{nullptr};
uint32_t numProviders{0};
// Query for al available interfaces
if (QNN_SUCCESS !=
  getInterfaceProviders((const QnnInterface_t***)&interfaceProviders, &numProviders)) {
QNN_ERROR("Failed to get interface providers.");
return StatusCode::FAIL_GET_INTERFACE_PROVIDERS;
}
// Check for validity of returned interfaces
if (nullptr == interfaceProviders) {
QNN_ERROR("Failed to get interface providers: null interface providers received.");
return StatusCode::FAIL_GET_INTERFACE_PROVIDERS;
}
if (0 == numProviders) {
QNN_ERROR("Failed to get interface providers: 0 interface providers.");
return StatusCode::FAIL_GET_INTERFACE_PROVIDERS;
}
bool foundValidInterface{false};
// Loop through all available interface providers and pick the one that suits the current API
// version
for (size_t pIdx = 0; pIdx < numProviders; pIdx++) {
if (QNN_API_VERSION_MAJOR == interfaceProviders[pIdx]->apiVersion.coreApiVersion.major &&
      QNN_API_VERSION_MINOR <= interfaceProviders[pIdx]->apiVersion.coreApiVersion.minor) {
  foundValidInterface                 = true;
  m_qnnFunctionPointers.qnnInterface = interfaceProviders[pIdx]->QNN_INTERFACE_VER_NAME;
  break;
}
}
if (!foundValidInterface) {
QNN_ERROR("Unable to find a valid interface.");
libBackendHandle = nullptr;
return StatusCode::FAIL_GET_INTERFACE_PROVIDERS;
}

可以使用 QNN System Interface 来解析与 QNN System API 相关的所有符号，如下所示：

typedef Qnn_ErrorHandle_t (*QnnSystemInterfaceGetProvidersFn_t)(
  const QnnSystemInterface_t*** providerList, uint32_t* numProviders);

QnnSystemInterfaceGetProvidersFn_t getSystemInterfaceProviders{nullptr};
getSystemInterfaceProviders = resolveSymbol<QnnSystemInterfaceGetProvidersFn_t>(
  systemLibraryHandle, "QnnSystemInterface_getProviders");
if (nullptr == getSystemInterfaceProviders) {
  return StatusCode::FAIL_SYM_FUNCTION;
}
QnnSystemInterface_t** systemInterfaceProviders{nullptr};
uint32_t numProviders{0};
if (QNN_SUCCESS != getSystemInterfaceProviders(
                    (const QnnSystemInterface_t***)&systemInterfaceProviders, &numProviders)) {
  QNN_ERROR("Failed to get system interface providers.");
  return StatusCode::FAIL_GET_INTERFACE_PROVIDERS;
}
if (nullptr == systemInterfaceProviders) {
  QNN_ERROR("Failed to get system interface providers: null interface providers received.");
  return StatusCode::FAIL_GET_INTERFACE_PROVIDERS;
}
if (0 == numProviders) {
  QNN_ERROR("Failed to get interface providers: 0 interface providers.");
  return StatusCode::FAIL_GET_INTERFACE_PROVIDERS;
}
bool foundValidSystemInterface{false};
for (size_t pIdx = 0; pIdx < numProviders; pIdx++) {
  if (QNN_SYSTEM_API_VERSION_MAJOR == systemInterfaceProviders[pIdx]->systemApiVersion.major &&
      QNN_SYSTEM_API_VERSION_MINOR <= systemInterfaceProviders[pIdx]->systemApiVersion.minor) {
  foundValidSystemInterface = true;
  m_qnnFunctionPointers->qnnSystemInterface =
      systemInterfaceProviders[pIdx]->QNN_SYSTEM_INTERFACE_VER_NAME;
  break;
  }
}

设置日志记录

日志记录可以在后端初始化之前、后端共享库动态加载完成之后进行设置。要初始化日志记录，必须定义一个 QnnLog_Callback_t 类型的回调。示例定义如下：

void logStdoutCallback(const char* fmt,
                        QnnLog_Level_t level,
                        uint64_t timestamp,
                        va_list argp) {
  const char* levelStr = "";
  switch (level) {
  case QNN_LOG_LEVEL_ERROR:
  levelStr = " ERROR ";
  break;
  case QNN_LOG_LEVEL_WARN:
  levelStr = "WARNING";
  break;
  case QNN_LOG_LEVEL_INFO:
  levelStr = "  INFO ";
  break;
  case QNN_LOG_LEVEL_DEBUG:
  levelStr = " DEBUG ";
  break;
  case QNN_LOG_LEVEL_VERBOSE:
  levelStr = "VERBOSE";
  break;
  case QNN_LOG_LEVEL_MAX:
  levelStr = "UNKNOWN";
  break;
  }
  fprintf(stdout, "%8.1fms [%-7s] ", ms, levelStr);
  vfprintf(stdout, fmt, argp);
  fprintf(stdout, "\n");
}

上述回调可以与最高日志级别一起注册到后端。以下是以 QNN_LOG_LEVEL_INFO 作为最高日志级别进行初始化的示例代码：

Qnn_LogHandle_t logHandle;
if (QNN_SUCCESS !=
      m_qnnFunctionPointers.qnnInterface.logCreate(logStdoutCallback, QNN_LOG_LEVEL_INFO, &logHandle)) {
QNN_ERROR("Unable to initialize logging in the backend.");
return StatusCode::FAILURE;
}

初始化后端

日志记录成功初始化后，即可按如下方式初始化后端：

Qnn_BackendHandle_t backendHandle;
const QnnBackend_Config_t* backendConfigs;
/* Set up any necessary backend configurations */
if (QNN_BACKEND_NO_ERROR != m_qnnFunctionPointers.qnnInterface.backendCreate(logHandle,
                                                                            &backendConfigs,
                                                                            &backendHandle)) {
  QNN_ERROR("Could not initialize backend");
  return StatusCode::FAILURE;
}

初始化性能分析

如果需要性能分析，在后端初始化后可以设置性能分析句柄。该性能分析句柄可在之后用于任何支持性能分析的 API。可以在后端以 basic 性能分析级别创建性能分析句柄，如下所示：

Qnn_ProfileHandle_t profileHandle;
if (QNN_PROFILE_NO_ERROR != m_qnnFunctionPointers.qnnInterface.profileCreate(
                                  backendHandle, QNN_PROFILE_LEVEL_BASIC, &profileHandle)) {
  QNN_WARN("Unable to create profile handle in the backend.");
  return StatusCode::FAILURE;
}

创建设备

可以按如下方式创建设备：

Qnn_DeviceHandle_t deviceHandle {nullptr};
const QnnDevice_Config_t* devConfigArray[] = {&devConfig, nullptr};
Qnn_ErrorHandle_t ret = m_qnnFunctionPointers.qnnInterface.deviceCreate(logHandle,
                                                                        devConfigArray,
                                                                        &deviceHandle);
if (QNN_SUCCESS != ret) {
  QNN_ERROR("Failed to create device: %u", qnnStatus);
  return StatusCode::FAILURE;
}

按照 QNN HTP Backend API 中的定义设置 devConfig

注册算子包

算子包（op package）是向后端提供包含算子的库的方式。它们可按如下方式注册：

uint32_t opPackageCount;
char* opPackagePath[opPackageCount];
char* opPackageInterfaceProvider[opPackageCount];
/* Set up required op package paths and interface providers as necessary */
for(uint32_t idx = 0; idx < opPackageCount; idx++) {
  if (QNN_BACKEND_NO_ERROR !=
        m_qnnFunctionPointers.qnnInterface.backendRegisterOpPackage(backendHandle,
                                                                    opPackagePath[idx],
                                                                    opPackageInterfaceProvider[idx])) {
    QNN_ERROR("Could not register Op Package: %s and interface provider: %s",
            opPackagePath[idx],
            opPackageInterfaceProvider[idx]);
    return StatusCode::FAILURE;
  }
}

创建上下文

可以按如下方式在后端中创建上下文：

Qnn_ContextHandle_t context;
Qnn_DeviceHandle_t deviceHandle {nullptr};
const QnnContext_Config_t* contextConfigs;
/* Set up any context configs that are necessary */
if (QNN_CONTEXT_NO_ERROR !=
      m_qnnFunctionPointers.qnnInterface.contextCreate(backendHandle,
                                                        deviceHandle,
                                                        &contextConfigs,
                                                        &context)) {
  QNN_ERROR("Could not create context");
  return StatusCode::FAILURE;
}

准备图

qnn-sample-app 依赖某个转换器的输出在后端创建 QNN 网络。composeGraphsFnHandle 映射到模型共享库中的 QnnModel_composeGraphs API，该 API 将 qnn_wrapper_api::GraphInfo_t*** 作为参数之一。函数 composeGraphsFnHandle 会对后端进行必要的调用以创建网络。它还会将执行图所需的所有必要信息（例如与图相关的输入和输出张量的信息）写入结构体 graphsInfo，如以下代码块所示：

/* Structure to retrieve information about graphs, like graph name,
  details about input and output tensors preset in libQnnSampleModel.so */
qnn_wrapper_api::GraphInfo_t** graphsInfo;
// No. of graphs present in libQnnSampleModel.so
uint32_t graphsCount;
// true to enable intermediate outputs, false for network outputs only
bool debug;
if (qnn_wrapper_api::ModelError_t::MODEL_NO_ERROR !=
        m_qnnFunctionPointers.composeGraphsFnHandle(backendHandle,
                                                    m_qnnFunctionPointers.qnnInterface,
                                                    context,
                                                    &graphsInfo,
                                                    &graphsCount,
                                                    debug)) {
  QNN_ERROR("Failed in composeGraphs()");
  return StatusCode::FAILURE;
}

此时，上下文将包含 libQnnSampleModel.so 中存在的所有图。

最终化图

可以按如下方式对上一步中添加的图进行最终化处理：

// information about graphs obtained in the previous step
qnn_wrapper_api::GraphInfo_t** graphsInfo;
// No. of graphs obtained in the previous step
uint32_t graphsCount;
/* A valid profile handle if profiling is desired,
  nullptr if profiling is not needed */
Qnn_ProfileHandle_t profileHandle;

for (size_t graphIdx = 0; graphIdx < m_graphsCount; graphIdx++) {
  if (QNN_GRAPH_NO_ERROR !=
    m_qnnFunctionPointers.qnnInterface.graphFinalize(
        (*graphsInfo)[graphIdx].graph, profileBackendHandle, nullptr)) {
    return StatusCode::FAILURE;
  }
  /* Extract profiling information if desired and if a valid handle was supplied to finalize
    graphs API */
}

将上下文保存为二进制文件

当上下文中的所有图都最终化后，用户应用可以选择将上下文保存为二进制文件以供将来使用。保存上下文的优势在于，将来可以直接检索该上下文来执行其中包含的图，而无需再次进行最终化处理。这将在执行网络时为初始化节省大量时间。可以按如下方式保存上下文：

// Get the expected size of the buffer from the backend in which the context can be saved
if (QNN_CONTEXT_NO_ERROR !=
  m_qnnFunctionPointers.qnnInterface.contextGetBinarySize(context, &requiredBufferSize)) {
  QNN_ERROR("Could not get the required binary size.");
  return StatusCode::FAILURE;
}

// Allocate a buffer of the required size
saveBuffer = (uint8_t*)malloc(requiredBufferSize * sizeof(uint8_t));
if (nullptr == saveBuffer) {
  QNN_ERROR("Could not allocate buffer to save binary.");
  return StatusCode::FAILURE;
}

auto status = StatusCode::SUCCESS;
uint32_t writtenBufferSize{0};
// Pass the allocated buffer and obtain a copy of the context binary written into the buffer
if (QNN_CONTEXT_NO_ERROR !=
  m_qnnFunctionPointers.qnnInterface.contextGetBinary(context,
                                                      reinterpret_cast<void*>(saveBuffer),
                                                      requiredBufferSize,
                                                      &writtenBufferSize)) {
QNN_ERROR("Could not get binary.");
status = StatusCode::FAILURE;
}

// Check if the supplied buffer size is at least as big as the amount of data witten by the backend
if (requiredBufferSize < writtenBufferSize) {
  QNN_ERROR(
    "Illegal written buffer size [%d] bytes. Cannot exceed allocated memory of [%d] bytes",
    writtenBufferSize,
    requiredBufferSize);
  status = StatusCode::FAILURE;
}

// Use caching utility to save metadata along with the binary buffer from the backend
if (status == StatusCode::SUCCESS &&
  tools::datautil::StatusCode::SUCCESS != tools::datautil::writeBinaryToFile(outputPath,
                                                                            saveBinaryName + ".bin",
                                                                            (uint8_t*)saveBuffer,
                                                                            writtenBufferSize)) {
  QNN_ERROR("Could not serialize to file.");
  status = StatusCode::FAILURE;
}

从缓存的二进制文件加载上下文

与上一步类似，已保存为二进制文件的上下文可以被加载，从而避免每次都创建新的上下文。以下代码片段演示了这一步骤：

auto returnStatus   = StatusCode::SUCCESS;
std::shared_ptr<uint8_t> buffer{nullptr};
uint32_t graphsCount {0};
buffer = std::shared_ptr<uint8_t>(new uint8_t[bufferSize], std::default_delete<uint8_t[]>());
if (!buffer) {
    QNN_ERROR("Failed to allocate memory.");
    return StatusCode::FAILURE;
}

if (tools::datautil::StatusCode::SUCCESS !=
    tools::datautil::readBinaryFromFile(
    cachedBinaryPath, reinterpret_cast<uint8_t*>(buffer.get()), bufferSize)) {
    QNN_ERROR("Failed to read binary file.");
    returnStatus = StatusCode::FAILURE;
}

/* Create a QnnSystemContext handle to access system context APIs. */
QnnSystemContext_Handle_t sysCtxHandle{nullptr};
if (QNN_SUCCESS != m_qnnFunctionPointers.qnnSystemInterface.systemContextCreate(&sysCtxHandle)) {
  QNN_ERROR("Could not create system handle.");
  returnStatus = StatusCode::FAILURE;
}

/* Retrieve metadata from the context binary through QNN System Context API. */
QnnSystemContext_BinaryInfo_t* binaryInfo{nullptr};
uint32_t binaryInfoSize{0};
if (StatusCode::SUCCESS == returnStatus &&
    QNN_SUCCESS != m_qnnFunctionPointers.qnnSystemInterface.systemContextGetBinaryInfo(
                    sysCtxHandle,
                    static_cast<void*>(buffer.get()),
                    bufferSize,
                    &binaryInfo,
                    &binaryInfoSize)) {
    QNN_ERROR("Failed to get context binary info");
    returnStatus = StatusCode::FAILURE;
}

qnn_wrapper_api::GraphInfo_t** graphsInfo;
/* Make a copy of the metadata. */
if (StatusCode::SUCCESS == returnStatus &&
    !copyMetadataToGraphsInfo(binaryInfo, graphsInfo, graphsCount)) {
  QNN_ERROR("Failed to copy metadata.");
  returnStatus = StatusCode::FAILURE;
}

/* Release resources associated with previously created QnnSystemContext handle. */
m_qnnFunctionPointers.qnnSystemInterface.systemContextFree(sysCtxHandle);
sysCtxHandle = nullptr;

/* readBuffer contains the binary data that was previously obtained from a backend. Pass this
  cached binary data to the backend to recreate the same context. */
if (StatusCode::SUCCESS == returnStatus &&
    m_qnnFunctionPointers.qnnInterface.contextCreateFromBinary(backendHandle,
                                                              deviceHandle,
                                                              (const QnnContext_Config_t**)&contextConfig,
                                                              reinterpret_cast<void*>(readBuffer),
                                                              bufferSize,
                                                              &context,
                                                              profileBackendHandle)) {
  QNN_ERROR("Could not create context from binary.");
  returnStatus = StatusCode::FAILURE;
}

// Optionally, extract profiling numbers if desired
if (ProfilingLevel::OFF != m_profilingLevel) {
  extractBackendProfilingInfo(profileBackendHandle);
}

/* Obtain and save graph handles for each graph present in the context based on the saved graph
  names in the metadata */
if (StatusCode::SUCCESS == returnStatus) {
  for (size_t graphIdx = 0; graphIdx < m_graphsCount; graphIdx++) {
    if (QNN_SUCCESS !=
        m_qnnFunctionPointers.qnnInterface.graphRetrieve(
            context, (*graphsInfo)[graphIdx].graphName, &((*graphsInfo)[graphIdx].graph))) {
      QNN_ERROR("Unable to retrieve graph handle for graph Idx: %d", graphIdx);
      returnStatus = StatusCode::FAILURE;
    }
  }
}

运行图

当上下文创建完成、图已添加并最终化，或从二进制文件中检索到上下文后，即可执行上下文中的一个或多个图。运行图包括：

设置输入和输出张量。
将输入数据填充到输入张量中。
调用后端中的执行方法。
获取输出并保存。

以下代码片段演示了这一过程：

// Select a graph from graphsInfo if there are more than one graph in this context
uint32_t graphIdx;
QNN_DEBUG("Starting execution for graphIdx: %d", graphIdx);
  Qnn_Tensor_t* inputs  = nullptr;
  Qnn_Tensor_t* outputs = nullptr;
  // IOTensor utility is used to set up input and output tensor structures
  if (iotensor::StatusCode::SUCCESS !=
        ioTensor.setupInputAndOutputTensors(&inputs, &outputs, (*graphsInfo)[graphIdx])) {
    QNN_ERROR("Error in setting up Input and output Tensors for graphIdx: %d", graphIdx);
    returnStatus = StatusCode::FAILURE;
    break;
  }
  
  // Grab input raw file paths to read input data
  auto inputFileList = inputFileLists[graphIdx];
  auto graphInfo     = (*graphsInfo)[graphIdx];
  if (!inputFileList.empty()) {
    /* *qnn-sample-app* reads data based on the batch size until the whole buffer is filled.
        If there isn't sufficient data, it pads the rest with zeroes. */
    size_t totalCount = inputFileList[0].size();
    while (!inputFileList[0].empty()) {
      size_t startIdx = (totalCount - inputFileList[0].size());
  
      // IOTensor utility is used to populate input tensors with input data
      if (iotensor::StatusCode::SUCCESS !=
            m_ioTensor.populateInputTensors(
              graphIdx, inputFileList, inputs, graphInfo, inputDataType)) {
        returnStatus = StatusCode::FAILURE;
      }
  
      if (StatusCode::SUCCESS == returnStatus) {
        // Execute the graph in the backend with optional profile handle
        QNN_DEBUG("Successfully populated input tensors for graphIdx: %d", graphIdx);
        Qnn_ErrorHandle_t executeStatus = QNN_GRAPH_NO_ERROR;
        executeStatus = m_qnnFunctionPointers.qnnInterface.graphExecute(graphInfo.graph,
                                                                        inputs,
                                                                        graphInfo.numInputTensors,
                                                                        outputs,
                                                                        graphInfo.numOutputTensors,
                                                                        profileBackendHandle,
                                                                        nullptr);
        if (QNN_GRAPH_NO_ERROR != executeStatus) {
          returnStatus = StatusCode::FAILURE;
        }
        if (StatusCode::SUCCESS == returnStatus) {
          QNN_DEBUG("Successfully executed graphIdx: %d ", graphIdx);
          // IOTensor utility is used to write output tensors to raw files
          if (iotensor::StatusCode::SUCCESS !=
                ioTensor.writeOutputTensors(graphIdx,
                                            startIdx,
                                            graphInfo.graphName,
                                            outputs,
                                            graphInfo.outputTensors,
                                            graphInfo.numOutputTensors,
                                            outputDataType,
                                            graphsCount,
                                            outputPath)) {
              returnStatus = StatusCode::FAILURE;
            }
          }
        }
        if (StatusCode::SUCCESS != returnStatus) {
          QNN_ERROR("Execution of Graph: %d failed!", graphIdx);
          break;
        }
      }
    }
  
    // Clean up all the tensors after execution is completed
    ioTensor.tearDownInputAndOutputTensors(
        inputs, outputs, graphInfo.numInputTensors, graphInfo.numOutputTensors);
    inputs  = nullptr;
    outputs = nullptr;
    if (StatusCode::SUCCESS != returnStatus) {
      break;
    }
}

IOTensor 是随源代码提供的实用工具，位于 ${QNN_SDK_ROOT}/examples/QNN/SampleApp/SampleApp/src/Utils/IOTensor.cpp。它公开了几个有助于执行图的方法，这些方法在前面的代码片段中已使用：

setupInputAndOutputTensors 用于设置与输入和输出张量相关的结构。
populateInputTensors 用于将输入数据复制到输入张量结构中。
tearDownInputAndOutputTensors 用于清理与输入和输出张量关联的资源。

有关这些 API 的更多详细信息，请参见 IOTensor 源代码。

释放上下文

所有执行完成后，可以按如下方式释放上下文：

if (QNN_CONTEXT_NO_ERROR !=
      m_qnnFunctionPointers.qnnInterface.contextFree(context, profileBackendHandle)) {
  QNN_ERROR("Could not free context");
  return StatusCode::FAILURE;
}

终止后端

可以按如下方式终止后端：

if (QNN_BACKEND_NO_ERROR != m_qnnFunctionPointers.qnnInterface.backendFree(backendHandle)) {
  QNN_ERROR("Could not free backend");
  return StatusCode::FAILURE;
}

SNPE 示例应用

有关使用 SNPE 的 C++ API 和示例应用执行，请参见 Qualcomm AI Runtime SDK 文档。

简介

架构

关键文档

技术

系统

发行说明

构建并运行 QNN 示例应用

设置 QAIRT SDK

构建 QNN 示例应用

在 Linux（基于 Yocto）上运行 QNN 示例应用

命令行参数

工作流程与 API 使用

加载必备的共享库

加载后端

解析共享库中的符号

QNN API 的用法

使用 QNN Interface 获取函数指针

设置日志记录

初始化后端

初始化性能分析

创建设备

注册算子包

创建上下文

准备图

最终化图

将上下文保存为二进制文件

从缓存的二进制文件加载上下文

运行图

释放上下文

终止后端

SNPE 示例应用

​构建并运行 QNN 示例应用

​设置 QAIRT SDK

​构建 QNN 示例应用

​在 Linux（基于 Yocto）上运行 QNN 示例应用

​命令行参数

​工作流程与 API 使用

​加载必备的共享库

​加载后端

​解析共享库中的符号

​QNN API 的用法

​使用 QNN Interface 获取函数指针

​设置日志记录

​初始化后端

​初始化性能分析

​创建设备

​注册算子包

​创建上下文

​准备图

​最终化图

​将上下文保存为二进制文件

​从缓存的二进制文件加载上下文

​运行图

​释放上下文

​终止后端

​SNPE 示例应用

构建并运行 QNN 示例应用

设置 QAIRT SDK

构建 QNN 示例应用

在 Linux（基于 Yocto）上运行 QNN 示例应用

命令行参数

工作流程与 API 使用

加载必备的共享库

加载后端

解析共享库中的符号

QNN API 的用法

使用 QNN Interface 获取函数指针

设置日志记录

初始化后端

初始化性能分析

创建设备

注册算子包

创建上下文

准备图

最终化图

将上下文保存为二进制文件

从缓存的二进制文件加载上下文

运行图

释放上下文

终止后端

SNPE 示例应用