动态AIPP（多个动态AIPP输入）

使用约束

动态AIPP和动态Batch同时使用时：
- 调用aclmdlCreateAIPP接口设置batchSize时，batchSize要设置为最大batch size。
- 模型中需要进行动态AIPP处理的data节点，其对应的输入内存大小需按照最大Batch来申请。
动态AIPP和动态分辨率同时使用时：
- 若在设置动态AIPP参数时，开启了抠图或缩放或补边功能，则不能与动态分辨率同时使用。
- 若在设置动态AIPP参数时，未开启抠图或缩放或补边功能，在与动态分辨率同时使用时，需确保通过aclmdlSetAIPPSrcImageSize接口设置的宽、高与通过aclmdlSetDynamicHWSize接口设置的宽、高相等，都必须设置成模型转换时动态分辨率最大档位的宽、高。
- 模型中需要进行动态AIPP处理的data节点，其对应的输入内存大小需按照最大分辨率（宽、高）来申请。
动态AIPP和动态Shape输入（设置Shape范围）同时使用时，动态AIPP的输出图片宽、高要在所设置的Shape范围内。
对同一个模型，AIPP（包括静态AIPP和动态AIPP）与动态维度（ND格式）不能同时使用。
AscendCL还提供了基于DVPP（Digital Vision Pre-Processing）硬件进行媒体数据处理的功能，包括缩放、抠图、格式转换、图片编解码、视频编解码等，功能比AIPP丰富，但对于输入/输出图片、内存有一定的约束。

基于DVPP的媒体数据处理接口介绍，请参见媒体数据处理（含图像/视频等）。

父主题： 模型动态AIPP推理

动态AIPP（单个动态AIPP输入）

视频课程

通过在线视频课程学习该功能，请参见AscendCL模型推理动态特性。

接口调用流程

动态AIPP场景下模型推理与基础推理应用的流程类似，都涉及AscendCL初始化与去初始化、运行管理资源申请与释放、模型构建、模型加载、模型执行、模型卸载等。

本节中重点描述动态AIPP场景下模型推理与基础推理应用的不同之处：

模型构建时，需配置动态AIPP相关参数：

构建模型时，需通过ATC工具的insert_op_conf参数配置动态AIPP模式。ATC工具的参数说明请参见《ATC工具使用指南》。

构建模型成功后，在生成的om模型中，会新增相应的输入（下文简称动态AIPP输入），在模型推理时通过该新增的输入提供具体的AIPP配置值。

例如，a输入的AIPP配置是动态的，在om模型中，会有与a对应的b输入来描述a的AIPP配置信息。在模型执行时，准备a输入的数据结构请参见准备模型执行的输入/输出数据结构，准备b输入的数据结构、设置b输入的数据请参见以下内容。
在执行模型推理前：
- 准备动态AIPP输入的数据结构：
  1. 申请动态AIPP输入对应的内存前，需要先调用aclmdlGetInputIndexByName接口根据输入名称（固定为ACL_DYNAMIC_AIPP_NAME）获取模型中标识该输入的index。
    
    :::note 说明 ACL_DYNAMIC_AIPP_NAME是一个宏，宏的定义如下：
    #define ACL_DYNAMIC_AIPP_NAME "ascend_dynamic_aipp_data"
    :::
  2. 调用aclmdlGetInputSizeByIndex根据index获取输入内存大小。
  3. 调用aclrtMalloc接口根据2中的大小申请内存。
    
    申请动态AIPP输入对应的内存后，无需用户设置该内存中的数据（否则可能会导致业务异常），用户调用2中的接口后，系统会自动向该内存中填入数据。
  4. 调用aclCreateDataBuffer接口创建aclDataBuffer类型的数据，用于存放动态AIPP输入数据的内存地址、内存大小。
  5. 调用aclmdlCreateDataset接口创建aclmdlDataset类型的数据，并调用aclmdlAddDatasetBuffer接口向aclmdlDataset类型的数据中增加aclDataBuffer类型的数据。
- 设置动态AIPP参数值：
  
  图1 接口调用流程
  1. 调用aclmdlGetInputIndexByName接口根据输入名称（固定为ACL_DYNAMIC_AIPP_NAME）获取模型中标识该输入的index。
  2. 设置动态AIPP参数值。
    1. 调用aclmdlCreateAIPP接口创建aclmdlAIPP类型。
    2. 根据实际需求，调用aclmdlAIPP数据类型下的操作接口设置动态AIPP参数值。
    3. 动态AIPP场景下，aclmdlSetAIPPSrcImageSize接口（设置原始图片的宽和高）必须调用。
    4. 调用aclmdlSetInputAIPP接口设置模型推理时的动态AIPP数据。
    5. 及时调用aclmdlDestroyAIPP接口销毁aclmdlAIPP类型。

示例代码

调用接口后，需增加异常处理的分支，并记录报错日志、提示日志，此处不一一列举。以下是关键步骤的代码示例，不可以直接拷贝编译运行，仅供参考。

 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42  // 1.模型加载，加载成功后，再设置动态AIPP参数值 // ...... // 2.准备模型描述信息modelDesc_，准备模型的输入数据input_和模型的输出数据output_ // 3.自定义函数，设置动态AIPP参数值 int ModelSetDynamicAIPP() { // 3.1 获取标识动态AIPP输入的index size_t index; // modelDesc_为aclmdlCreateDesc表示模型描述信息，根据1中加载成功的模型的ID，获取该模型的描述信息 aclError ret = aclmdlGetInputIndexByName(modelDesc_, ACL_DYNAMIC_AIPP_NAME, &index); // 3.2 设置动态AIPP参数值 uint64_t batchNumber = 1; aclmdlAIPP *aippDynamicSet = aclmdlCreateAIPP(batchNumber); ret = aclmdlSetAIPPSrcImageSize(aippDynamicSet, 256, 224); ret = aclmdlSetAIPPInputFormat(aippDynamicSet, ACL_YUV420SP_U8); ret = aclmdlSetAIPPCscParams(aippDynamicSet, 1, 256, 443, 0, 256, -86, -178, 256, 0, 350, 0, 0, 0, 0, 128, 128); ret = aclmdlSetAIPPRbuvSwapSwitch(aippDynamicSet, 0); ret = aclmdlSetAIPPDtcPixelMean(aippDynamicSet, 0, 0, 0, 0, 0); ret = aclmdlSetAIPPDtcPixelMin(aippDynamicSet, 0, 0, 0, 0, 0); ret = aclmdlSetAIPPPixelVarReci(aippDynamicSet, 1.0, 1.0, 1.0, 1.0, 0); ret = aclmdlSetAIPPCropParams(aippDynamicSet, 1, 2, 2, 224, 224, 0); ret = aclmdlSetInputAIPP(modelId_, input_, index, aippDynamicSet); ret = aclmdlDestroyAIPP(aippDynamicSet); // ...... } // 4.自定义函数，执行模型 int ModelExecute(int index) { aclError ret; // 4.1 调用自定义函数，设置动态AIPP参数值 ret = ModelSetDynamicAIPP(); // 4.2 执行模型，modelId_表示加载成功的模型的ID，input_和output_分别表示模型的输入和输出 ret = aclmdlExecute(modelId_, input_, output_); // ...... } // 5.处理模型推理结果 // TODO

父主题： 模型动态AIPP推理

动态AIPP（多个动态AIPP输入）

接口调用流程

模型有多个动态AIPP输入时的推理基本流程与单个动态AIPP输入类似，请参见动态AIPP（单个动态AIPP输入）。

多个动态AIPP输入与单个动态AIPP输入的不同点如下：

需调用aclmdlGetAippType接口查询指定模型的指定输入是否有关联的动态AIPP输入，若有，则输出标识动态AIPP输入的index，该参数值可作为aclmdlSetAIPPByInputIndex接口的入参之一，来设置对应输入上的动态AIPP参数值。
为避免在错误的输入上设置动态AIPP参数，用户可调用aclmdlGetInputNameByIndex接口先获取指定输入index的输入名称，根据输入名称所对应的index设置动态AIPP参数。

示例代码

// 1.模型加载，加载成功后，再设置动态AIPP参数值
// ......

// 2.准备模型描述信息modelDesc_，准备模型的输入数据input_和模型的输出数据output_
// ......

// 3.自定义函数，设置动态AIPP参数值
int  ModelSetDynamicAIPP()
&#123;
    // 3.1 获取标识动态AIPP输入的index
    std::vector<size_t> dataNeedDynamicAipp;
    for (size_t index = 0; index < aclmdlGetNumInputs(modelDesc_); ++index) &#123;
        aclmdlInputAippType aippType;
        size_t dynamicAttachedDataIndex;
        aclError ret = aclmdlGetAippType(modelId_, index, &aippType, &dynamicAttachedDataIndex);
        if (aippType == ACL_DATA_WITH_DYNAMIC_AIPP) &#123;
            dataNeedDynamicAipp.push_back(index);
        &#125;
    &#125;

    // 3.2 当前示例中以2个动态AIPP输入为例，用户可根据实际情况修改
    if (dataNeedDynamicAipp.size() != 2) &#123;
        return -1;
    &#125;
    // 创建第一个动态aipp配置参数
    uint64_t batchNumber1 = 1;
    aclmdlAIPP *aippDynamicSet1 = aclmdlCreateAIPP(batchNumber1);
    ret = aclmdlSetAIPPSrcImageSize(aippDynamicSet1, 256, 224);
    ret = aclmdlSetAIPPInputFormat(aippDynamicSet1, ACL_YUV420SP_U8);
    ret = aclmdlSetAIPPCscParams(aippDynamicSet1, 1, 256, 443, 0, 256, -86, -178, 256, 0, 350, 0, 0, 0, 0, 128, 128);
    ret = aclmdlSetAIPPRbuvSwapSwitch(aippDynamicSet1, 0);
    ret = aclmdlSetAIPPDtcPixelMean(aippDynamicSet1, 0, 0, 0, 0, 0);
    ret = aclmdlSetAIPPDtcPixelMin(aippDynamicSet1, 0, 0, 0, 0, 0);
    ret = aclmdlSetAIPPPixelVarReci(aippDynamicSet1, 1.0, 1.0, 1.0, 1.0, 0);
    ret = aclmdlSetAIPPCropParams(aippDynamicSet1, 1, 2, 2, 224, 224, 0);
    // 设置模型推理时的动态aipp参数值
    ret = aclmdlSetAIPPByInputIndex(modelId_, input_, dataNeedDynamicAipp[0], aippDynamicSet1);
    ret = aclmdlDestroyAIPP(aippDynamicSet1);

    // 创建第二个动态aipp配置参数
    uint64_t batchNumber2 = 2;
    aclmdlAIPP *aippDynamicSet2 = aclmdlCreateAIPP(batchNumber2);
    ret = aclmdlSetAIPPSrcImageSize(aippDynamicSet2, 224, 224);
    // 此处可以继续调用其它AIPP参数设置接口
    // 设置模型推理时的动态aipp参数值
    ret = aclmdlSetAIPPByInputIndex(modelId_, input_, dataNeedDynamicAipp[1], aippDynamicSet2);
    ret = aclmdlDestroyAIPP(aippDynamicSet2);
&#125;

// 4.自定义函数，执行模型
int ModelExecute(int index)
&#123;
        aclError ret;
        // 4.1 调用自定义函数，设置动态AIPP参数值
	ret = ModelSetDynamicAIPP();
        // 4.2 执行模型，modelId_表示加载成功的模型的ID，input_和output_分别表示模型的输入和输出
        ret = aclmdlExecute(modelId_, input_, output_);
        // ......
&#125;

// 5.处理模型推理结果
// TODO

父主题： 模型动态AIPP推理

Stream管理

在AscendCL中，Stream是一个任务队列，应用程序通过Stream来管理任务的并行，一个Stream内部的任务保序执行，即Stream根据发送过来的任务依次执行；不同Stream中的任务并行执行。一个默认Context下会挂一个默认Stream，如果不显式创建Stream，可使用默认Stream。默认Stream作为接口入参时，直接传NULL。

AscendCL提供以下几种Stream管理机制，其中，多Stream场景下的同步等待流程请参见多Stream时的同步等待流程：

单线程单Stream
单线程多Stream
多线程多Stream

单线程单Stream

 1 2 3 4 5 6 7 8 9 10 11 12 13 14  cpp #include "acl/acl.h" // ...... // 显式创建一个Stream aclrtStream stream; aclrtCreateStream(&stream); // 调用触发任务的接口，传入stream参数 aclrtMemcpyAsync(dstPtr, dstSize, srcPtr, srcSize, ACL_MEMCPY_HOST_TO_DEVICE, stream); // 调用aclrtSynchronizeStream接口，阻塞应用程序运行，直到指定Stream中的所有任务都完成。 aclrtSynchronizeStream(stream); // Stream使用结束后，显式销毁Stream aclrtDestroyStream(stream); // ......

单线程多Stream

 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34  cpp #include "acl/acl.h" // ...... int32_t deviceId = 0 ; uint32_t modelId1 = 0; uint32_t modelId2 = 1; aclrtContext context; aclrtStream stream1； aclrtStream stream2； // 如果只创建了一个Context，线程默认将这个Context作为线程当前的Context； // 如果是多个Context，则需要调用aclrtSetCurrentContext接口设置当前线程的Context aclrtCreateContext(&context, deviceId); aclrtCreateStream(&stream1); // 调用触发任务的接口，例如异步模型推理，任务下发在stream1 aclmdlDataset *input1; aclmdlDataset *output1; aclmdlExecuteAsync(modelId1, input1, output1, stream1)； aclrtCreateStream(&stream2); // 调用触发任务的接口，例如异步模型推理，任务下发在stream2 aclmdlDataset *input2; aclmdlDataset *output2; aclmdlExecuteAsync(modelId2, input1, output2, stream2)； // 流同步 aclrtSynchronizeStream(stream1)； aclrtSynchronizeStream(stream2)； // 释放资源 aclrtDestroyStream(stream1); aclrtDestroyStream(stream2); aclrtDestroyContext(context); // ....

多线程多Stream

 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28  cpp #include "acl/acl.h" // ...... void runThread(aclrtStream stream) { int32_t deviceId =0 ; aclrtContext context; // 如果只创建了一个Context，线程默认将这个Context作为线程当前的Context； // 如果是多个Context，则需要调用aclrtSetCurrentContext接口设置当前线程的Context aclrtCreateContext(&context, deviceId); aclrtCreateStream(&stream); // 调用触发任务的接口 // .... // 释放资源 aclrtDestroyStream(stream); aclrtDestroyContext(context); } aclrtStream stream1； aclrtStream stream2； // 创建2个线程，每个线程对应一个Stream std::thread t1(runThread, stream1); std::thread t2(runThread, stream2); // 显式调用join函数确保结束线程 t1.join(); t2.join();

多Stream时的同步等待流程

开发应用时，如果涉及多Stream之间的任务等待，则应用程序中必须包含相关的代码逻辑，关于该场景的接口调用流程，请依次参见AscendCL接口调用流程以及本节中的说明。

图1 同步等待流程_多Stream场景

多Stream之间任务的同步等待可以利用Event实现，调用aclrtStreamWaitEvent接口阻塞指定Stream的运行，直到指定的Event完成。需在调用aclrtStreamWaitEvent接口前，先调用aclrtRecordEvent接口。调用示例请参见Stream间任务的同步等待示例代码。

模型加载与执行的流程请参见基础推理应用。

算子加载与执行的流程请参见单算子调用。

父主题： 扩展更多特性

同步等待

视频课程

通过在线视频课程学习该功能，请参见AscendCL同步&异步特性。

同步机制

AscendCL提供以下几种同步机制：

Event的同步等待示例代码：调用aclrtSynchronizeEvent接口，阻塞应用程序运行，等待Event完成。
Stream内任务的同步等待示例代码：调用aclrtSynchronizeStream接口，阻塞应用程序运行，直到指定Stream中的所有任务都完成。
Stream间任务的同步等待示例代码：调用aclrtStreamWaitEvent接口，阻塞指定Stream的运行，直到指定的Event完成。支持多个Stream等待同一个Event的场景。接口调用流程请参见多Stream时的同步等待流程。
Device的同步等待示例代码：调用aclrtSynchronizeDevice接口，阻塞应用程序运行，直到正在运算中的Device完成运算。

Event的同步等待示例代码

 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21  cpp #include "acl/acl.h" // ...... // 创建一个Event aclrtEvent event; aclrtCreateEvent(&event); // 创建一个Stream aclrtStream stream; aclrtCreateStream(&stream); // stream末尾添加了一个event aclrtRecordEvent(event, stream); // 阻塞应用程序运行，等待event发生，也就是stream执行完成 // stream完成后产生event，唤醒执行应用程序的控制流，开始执行程序 aclrtSynchronizeEvent(event); // 显式销毁资源 aclrtDestroyStream(stream); aclrtDestroyEvent(event); // ......

Stream内任务的同步等待示例代码

Stream间任务的同步等待示例代码

 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24  cpp #include "acl/acl.h" // ...... // 创建一个Event aclrtEvent event; aclrtCreateEvent(&event); // 创建两个Stream aclrtStream s1; aclrtStream s2; aclrtCreateStream(&s1); aclrtCreateStream(&s2); // 在s1末尾添加了一个event aclrtRecordEvent(event, s1); // 阻塞s2运行，直到指定event发生，也就是s1执行完成 // s1完成后，唤醒s2，继续执行s2的任务 aclrtStreamWaitEvent(s2, event); // 显式销毁资源 aclrtDestroyStream(s2); aclrtDestroyStream(s1); aclrtDestroyEvent(event); // ......

Device的同步等待示例代码

 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20  cpp #include "acl/acl.h" // ...... // 指定device aclrtSetDevice(0); // 创建context aclrtContext ctx; aclrtCreateContext(&ctx, 0); // 创建stream aclrtStream stream; aclrtCreateStream(&stream); // 阻塞应用程序运行，直到正在运算中的Device完成运算 aclrtSynchronizeDevice(); // 资源销毁 aclrtDestroyStream(stream); aclrtDestroyContext(ctx); aclrtResetDevice(0); 

父主题： 扩展更多特性

AI Core异常信息获取

基本原理

使用场景****举例：执行整网模型推理时，如果产生AI Core报错，可以调用本接口获取报错算子的描述信息，再做进一步错误排查。

推荐的接口调用顺序如下：

定义并实现异常回调函数fn(aclrtExceptionInfoCallback类型)，回调函数原型请参见aclrtSetExceptionInfoCallback 。

实现回调函数的关键步骤如下：
1. 在异常回调函数fn内调用aclrtGetDeviceIdFromExceptionInfo、aclrtGetStreamIdFromExceptionInfo、aclrtGetTaskIdFromExceptionInfo接口分别获取Device ID、Stream ID、Task ID。
2. 在异常回调函数fn内调用aclmdlCreateAndGetOpDesc接口获取算子的描述信息。
3. 在异常回调函数fn内调用aclGetTensorDescByIndex接口获取指定算子输入/输出的tensor描述。
4. 在异常回调函数fn内如下接口获取tensor描述中的数据，进行进一步分析。
  
  例如，调用aclGetTensorDescAddress接口获取tensor数据的内存地址（用户可从该内存地址中获取tensor数据）、调用aclGetTensorDescType接口获取tensor描述中的数据类型、调用aclGetTensorDescFormat接口获取tensor描述中的Format、调用aclGetTensorDescNumDims接口获取tensor描述中的Shape维度个数、调用aclGetTensorDescDimV2接口获取Shape中指定维度的大小。
调用aclrtSetExceptionInfoCallback接口设置异常回调函数。
执行模型推理。

如果存在AI Core报错，则触发回调函数fn，获取算子的信息，进行进一步分析。

示例代码

本节中的示例重点介绍AI Core异常信息获取的代码逻辑，AscendCL初始化和去初始化请参见AscendCL初始化与去初始化，运行管理资源申请与释放请参见运行管理资源申请与释放，模型加载、准备模型推理的输入/输出数据的接口调用流程、模型执行、模型卸载等请参见模型推理。

 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52  // 1.AscendCL初始化 // 2.申请运行管理资源，包括设置用于计算的Device、创建Context、创建Stream // 3.模型加载，加载成功后，返回标识模型的modelId // 4.创建aclmdlDataset类型的数据，用于描述模型的输入数据input、输出数据output // 5.实现异常回调函数 void callback(aclrtExceptionInfo *exceptionInfo) { deviceId = aclrtGetDeviceIdFromExceptionInfo(exceptionInfo); streamId = aclrtGetStreamIdFromExceptionInfo(exceptionInfo); taskId = aclrtGetTaskIdFromExceptionInfo(exceptionInfo); char opName[256]; aclTensorDesc *inputDesc = nullptr; aclTensorDesc *outputDesc = nullptr; size_t inputCnt = 0; size_t outputCnt = 0; // 用户可以将获取的算子信息写入到文件，或者另起线程，当发生异常回调时触发线程处理函数，在线程处理函数中将算子信息在屏幕上显示 aclmdlCreateAndGetOpDesc(deviceId, streamId, taskId, opName, 256, &inputDesc, &inputCnt, &outputDesc, &outputCnt); // 可以调用AscendCL tensor的相关接口，获取算子的相关信息，用户可以根据自己需要调用 for (size_t i = 0; i < inputCnt; ++i) { const aclTensorDesc *desc = aclGetTensorDescByIndex(inputDesc, i); aclGetTensorDescAddress(desc); aclGetTensorDescFormat(desc); } for (size_t i = 0; i < outputCnt; ++i) { const aclTensorDesc *desc = aclGetTensorDescByIndex(outputDesc, i); aclGetTensorDescAddress(desc); aclGetTensorDescFormat(desc); } aclDestroyTensorDesc(inputDesc); aclDestroyTensorDesc(outputDesc); } // 6.设置异常回调 aclrtSetExceptionInfoCallback(callback); // 7.执行模型 ret = aclmdlExecute(modelId, input, output); // 8.处理模型推理结果 // 9.释放描述模型输入/输出信息、内存等资源，卸载模型 // 10.释放运行管理资源 // 11. AscendCL去初始化 // ......

父主题： 扩展更多特性

在线提单

使用约束​

动态AIPP（单个动态AIPP输入）​

视频课程​

接口调用流程​

示例代码​

动态AIPP（多个动态AIPP输入）​

接口调用流程​

示例代码​

Stream管理​

单线程单Stream​

单线程多Stream​

多线程多Stream​

多Stream时的同步等待流程​

同步等待​

视频课程​

同步机制​

Event的同步等待示例代码​

Stream内任务的同步等待示例代码​

Stream间任务的同步等待示例代码​

Device的同步等待示例代码​

AI Core异常信息获取​

基本原理​

示例代码​

使用约束

动态AIPP（单个动态AIPP输入）

视频课程

接口调用流程

示例代码

动态AIPP（多个动态AIPP输入）

接口调用流程

示例代码

Stream管理

单线程单Stream

单线程多Stream

多线程多Stream

多Stream时的同步等待流程

同步等待

视频课程

同步机制

Event的同步等待示例代码

Stream内任务的同步等待示例代码

Stream间任务的同步等待示例代码

Device的同步等待示例代码

AI Core异常信息获取

基本原理

示例代码