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

动态Batch/动态分辨率/动态维度（设置多档维度值）

接口调用流程

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

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

构建模型时，需配置动态Batch、动态分辨率、动态维度（ND格式）相关的信息：

若模型推理时包含动态Batch特性，在模型推理时，需调用pyACL提供的接口设置模型推理时需使用的“batch size”，模型支持的“batch size”已提前在构建模型时配置（使用ATC工具的“dynamic_batch_size”参数）。

若模型推理时包含动态分辨率特性，在模型推理时，需调用pyACL提供的接口设置模型推理时需使用的分辨率，模型支持的分辨率已提前在构建模型时配置（使用ATC工具的“dynamic_image_size”参数）。

若模型推理时包含动态维度（ND格式）特性，在模型推理时，需调用pyACL提供的接口设置模型推理时需使用的维度值，模型支持哪些维度值已提前在构建模型时配置（使用ATC工具的“dynamic_dims”参数）。

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

例如，a输入的“batch size”是动态的，在om模型中，会新增与a对应的b输入来描述a的batch信息。在模型执行时，准备a输入的数据结构请参见准备模型执行的输入/输出数据结构，准备b输入的数据结构、设置b输入的数据请参见2。

ATC工具的参数说明请参见《ATC工具使用指南》。
在执行模型推理前：
- 需准备动态Batch/动态分辨率/动态维度输入的数据结构：
  1. 申请动态Batch/动态分辨率/动态维度输入对应的内存前，需要先调用acl.mdl.get_input_index_by_name接口根据输入名称（固定为“ascend_mbatch_shape_data”）获取模型中标识该输入的index。
  2. 调用acl.mdl.get_input_size_by_index根据index获取输入内存大小。
  3. 调用acl.rt.malloc接口根据2.b中的大小申请内存。
    
    申请动态Batch/动态分辨率/动态AIPP/动态维度输入对应的内存后，无需用户设置该内存中的数据（否则可能会导致业务异常），用户调用2.b中的接口后，系统会自动向该内存中填入数据。
  4. 调用acl.create_data_buffer接口创建aclDataBuffer类型的数据，用于存放动态Batch/动态分辨率/动态维度输入数据的内存地址、内存大小。
  5. 调用acl.mdl.create_dataset接口创建aclmdlDataset类型的数据，并调用acl.mdl.add_dataset_buffer接口向aclmdlDataset类型的数据中增加aclDataBuffer类型的数据。
- 需设置动态Batch/动态分辨率/动态维度参数值：
  
  图1 接口调用流程
  1. 调用acl.mdl.get_input_index_by_name接口根据输入名称（固定为“ascend_mbatch_shape_data”）获取模型中标识该输入的index。
  2. 设置动态Batch/动态分辨率/动态维度参数值。
    - 调用acl.mdl.set_dynamic_batch_size接口设置动态Batch。
      
      此处设置的“batch size”只能是构建模型时设置的Batch档位中的某一个。
      
      也可以调用acl.mdl.get_dynamic_batch接口获取指定模型支持的Batch档位数以及每一档中的“batch size”。
    - 调用acl.mdl.set_dynamic_hw_size接口设置动态分辨率。
      
      此处设置的分辨率只能是构建模型时设置的分辨率档位中的某一个。
      
      也可以调用acl.mdl.get_dynamic_hw接口获取指定模型支持的分辨率档位数以及每一档中的宽、高。
    - 调用acl.mdl.set_input_dynamic_dims接口设置动态维度的维度值。
      
      此处设置的动态维度的值只能是构建模型时设置的档位中的某一档。
      
      也可以调用acl.mdl.get_input_dynamic_dims接口获取指定模型支持的动态维度档位数以及每一档中的值。

备注

须知

对同一个模型，不能同时调用acl.mdl.set_dynamic_batch_size接口设置动态Batch、调用acl.mdl.set_dynamic_hw_size接口设置动态分辨率、调用acl.mdl.set_input_dynamic_dims接口设置动态维度的维度值，只能调用其中一种。
申请模型推理的输出内存时，可以按照各档位的实际大小申请内存，也可以调用acl.mdl.get_output_size_by_index接口获取内存大小后再申请内存（建议使用该方式，确保内存足够）。
动态AIPP和动态Batch同时使用时：
- 调用acl.mdl.create_aipp接口设置“batchSize”时，“batchSize”要设置为最大Batch数。
- 模型中需要进行动态AIPP处理的data节点，其对应的输入内存大小需按照最大Batch来申请。
动态AIPP和动态分辨率同时使用时：
- 若在设置动态AIPP参数时，开启了抠图或缩放或补边功能，则不能与动态分辨率同时使用。
- 若在设置动态AIPP参数时，未开启抠图或缩放或补边功能，在与动态分辨率同时使用时，需确保通过acl.mdl.set_aipp_src_image_size接口设置的宽和高，与通过acl.mdl.set_dynamic_hw_size接口设置的宽和高相等，都必须设置成模型转换时动态分辨率最大档位的宽和高。
- 模型中需要进行动态AIPP处理的data节点，其对应的输入内存大小需按照最大分辨率（宽、高）来申请。
静态AIPP和动态分辨率同时使用时，由于动态分辨率场景下输入图片的宽和高不确定，因此在使用ATC工具的“insert_op_conf”参数传入AIPP配置文件时，AIPP配置文件中不能开启Crop和Padding功能，并且需要将配置文件中的“src_image_size_w”和“src_image_size_h”取值设置为0。
对同一个模型，AIPP（包括静态AIPP和动态AIPP）与动态维度（ND格式）不能同时使用。

动态Batch示例代码

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

 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  python # 1.模型加载，加载成功后，再设置动态Batch。 # ...... # 2.创建aclmdlDataset类型的数据，用于描述模型的输入数据input、输出数据output。 # ...... # 3.自定义函数，设置动态Batch。 def model_set_dynamicinfo(): # 3.1 获取动态Batch输入的index，标识动态Batch输入的输入名称固定为“ascend_mbatch_shape_data”。 index, ret = acl.mdl.get_input_index_by_name(model_desc, "ascend_mbatch_shape_data") # 3.2 设置Batch，model_id表示加载成功的模型的ID，input表示aclmdlDataset类型的数据，index表示标识动态Batch输入的输入index。 batchSize = 8 ret = acl.mdl.set_dynamic_batch_size(model_id_, input, index, batch_size) # ...... # 4.自定义函数，执行模型。 def model_execute(index): # 4.1 调用自定义函数，设置动态Batch。 ret = model_set_dynamicinfo() # 4.2 执行模型，model_id表示加载成功的模型的ID，input和output分别表示模型的输入和输出。 ret = acl.mdl.execute(model_id, input, output) # ...... } # 5.处理模型推理结果。 # ......

动态分辨率示例代码

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

 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  python # 1.模型加载，加载成功后，再设置动态分辨率。 # ...... # 2.创建aclmdlDataset类型的数据，用于描述模型的输入数据input、输出数据output。 # ...... # 3.自定义函数，设置动态分辨率。 def model_set_dynamicInfo(): # 3.1 获取动态分辨率输入的index，标识动态分辨率输入的输入名称固定为“ascend_mbatch_shape_data”。 index, ret = acl.mdl.get_input_index_by_name(modelDesc, "ascend_mbatch_shape_data") # 3.2 设置输入图片分辨率，model_id表示加载成功的模型的ID，input表示aclmdlDataset类型的数据，index表示标识动态分辨率输入的输入index。 height = 224 width = 224 ret = acl.mdl.set_dynamic_hw_size(model_id, input, index, height, width) # ...... # 4.自定义函数，执行模型。 def model_execute(index): # 4.1 调用自定义函数，设置动态分辨率。 ret = model_set_dynamicInfo() # 4.2 执行模型，model_id表示加载成功的模型的ID，input和output分别表示模型的输入和输出。 ret = acl.mdl.execute(model_id, input, output) # ...... # 5.处理模型推理结果。 # ......

ND格式，动态维度示例代码

调用接口后，需增加异常处理的分支，示例代码中不一一列举。以下是关键步骤的代码示例，不可以直接拷贝运行，仅供参考。

 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  python import acl # ...... # 1.模型加载，加载成功后，再设置动态维度。 # ...... # 2.准备模型描述信息model_desc，准备模型的输入数据input_dataset和模型的输出数据output_dataset。 # ...... # 3.自定义函数，设置动态维度。 def model_set_dynamic_info(): # 3.1 获取动态维度输入的index，标识动态维度输入的输入名称固定为“ascend_mbatch_shape_data”。 index, ret = acl.mdl.get_input_index_by_name(model_desc, "ascend_mbatch_shape_data") # 3.2 设置具体档位信息，包括维度数dimCount和各个维度的数值，model_id表示加载成功的模型的ID，input_dataset表示aclmdlDataset类型的数据，index表示标识动态维度输入的输入index。 current_dims = {'name': '', 'dimCount': 4, 'dims': [8, 3, 224, 224]} ret = acl.mdl.set_input_dynamic_dims(mode_id, input_dataset, index, current_dims) # ...... # 4.自定义函数，执行模型。 def ModelExecute(int index): # 4.1 调用自定义函数，设置动态维度。 ret = model_set_dynamic_info() # 4.2 执行模型，model_id表示加载成功的模型的ID，input_dataset和output_dataset分别表示模型的输入和输出。 ret = acl.mdl.execute(model_id, input_dataset, output_dataset) # ...... # 5.处理模型推理结果。 # ......

父主题： 模型动态推理

接口调用流程

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

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

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

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

例如，a输入的AIPP配置是动态的，在om模型中，会有与a对应的b输入来描述a的AIPP配置信息。在模型执行时，准备a输入的数据结构请参见准备模型执行的输入/输出数据结构，准备b输入的数据结构、设置b输入的数据请参见以下内容。
在执行模型推理前：
- 准备动态AIPP输入的数据结构：
  1. 申请动态AIPP输入对应的内存前，需要先调用acl.mdl.get_input_index_by_name接口根据输入名称（固定为“ascend_dynamic_aipp_data”）获取模型中标识该输入的index。
  2. 调用acl.mdl.get_input_size_by_index根据index获取输入内存大小。
  3. 调用acl.rt.malloc接口根据2中的大小申请内存。
    
    申请动态AIPP输入对应的内存后，无需用户设置该内存中的数据（否则可能会导致业务异常），用户调用2中的接口后，系统会自动向该内存中填入数据。
  4. 调用acl.create_data_buffer接口创建aclDataBuffer类型的数据，用于存放动态AIPP输入数据的内存地址、内存大小。
  5. 调用acl.mdl.create_dataset接口创建aclmdlDataset类型的数据，并调用acl.mdl.add_dataset_buffer接口向aclmdlDataset类型的数据中增加aclDataBuffer类型的数据。
- 设置动态AIPP参数值：
  
  图1 接口调用流程
  1. 调用acl.mdl.get_input_index_by_name接口根据输入名称（固定为“ACL_DYNAMIC_AIPP_NAME”）获取模型中标识该输入的index。
  2. 设置动态AIPP参数值。
    1. 调用acl.mdl.create_aipp接口创建aclmdlAIPP类型。
    2. 根据实际需求，调用aclmdlAIPP数据类型下的操作接口设置动态AIPP参数值。
    3. 动态AIPP场景下，acl.mdl.set_aipp_src_image_size接口（设置原始图片的宽和高）必须调用。
    4. 调用acl.mdl.set_input_aipp接口设置模型推理时的动态AIPP数据。
    5. 及时调用acl.mdl.destroy_aipp接口销毁aclmdlAIPP类型。

:::note 说明 pyACL还提供了基于DVPP（Digital Vision Pre-Processing）硬件进行媒体数据处理的功能，包括缩放、抠图、格式转换、图片编解码、视频编解码等，功能比AIPP丰富，但对于输入/输出图片、内存有一定的约束。

基于DVPP的媒体数据处理接口介绍，请参见媒体数据处理。 :::

父主题： 模型动态AIPP推理

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

基本原理

若模型推理时包含动态AIPP特性，在模型推理时，需调用pyACL提供的接口设置模型推理时需使用的AIPP配置，模型支持的AIPP模式已提前在构建模型时配置（使用ATC工具的“insert_op_conf”参数）。

ATC工具的参数说明请参见《ATC工具使用指南》。

备注

须知

动态AIPP和动态Batch同时使用时：
- 调用acl.mdl.create_aipp接口设置“batchSize”时，“batchSize”要设置为最大Batch数。
- 模型中需要进行动态AIPP处理的data节点，其对应的输入内存大小需按照最大Batch来申请。
动态AIPP和动态分辨率同时使用时：
- 若在设置动态AIPP参数时，开启了抠图或缩放或补边功能，则不能与动态分辨率同时使用。
- 若在设置动态AIPP参数时，未开启抠图或缩放或补边功能，在与动态分辨率同时使用时，需确保通过acl.mdl.set_aipp_src_image_size接口设置的宽和高，与通过acl.mdl.set_dynamic_hw_size接口设置的宽和高相等，都必须设置成模型转换时动态分辨率最大档位的宽和高。
- 模型中需要进行动态AIPP处理的data节点，其对应的输入内存大小需按照最大分辨率（宽、高）来申请。
对同一个模型，AIPP（包括静态AIPP和动态AIPP）与动态维度（ND格式）不能同时使用。

示例代码

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

import acl
## ......

ACL_YUV420SP_U8 = 1

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

## 2.创建aclmdlDataset类型的数据，用于描述模型的输入数据input_dataset和模型的输出数据output_dataset。
## ......

## 3.自定义函数，设置动态AIPP参数值。
def model_set_dynamic_aipp():
    # 3.1 获取标识动态AIPP输入的index。
    index, ret = acl.mdl.get_input_index_by_name(model_desc, "ascend_dynamic_aipp_data")

    # 3.2 设置动态AIPP参数值。
    batch_number = 1
    aipp_dynamic_set = acl.mdl.create_aipp(batch_number)
    ret = acl.mdl.set_aipp_src_image_size(aipp_dynamic_set, 256, 224)
    ret = acl.mdl.set_aipp_input_format(aipp_dynamic_set, ACL_YUV420SP_U8)
    ret = acl.mdl.set_aipp_csc_params(aipp_dynamic_set, 1, 256, 443, 0, 256, -86, -178, 256, 0, 350, 0, 0, 0, 0, 128, 128)
    ret = acl.mdl.set_aipp_rbuv_swap_switch(aipp_dynamic_set, 0)
    ret = acl.mdl.set_aipp_dtc_pixel_mean(aipp_dynamic_set, 0, 0, 0, 0, 0)
    ret = acl.mdl.set_aipp_dtc_pixel_min(aipp_dynamic_set, 0, 0, 0, 0, 0)
    ret = acl.mdl.set_aipp_pixel_var_reci(aipp_dynamic_set, 1, 1, 1, 1, 0)
    ret = acl.mdl.set_aipp_crop_params(aipp_dynamic_set, 1, 0, 0, 224, 224, 0)
    ret = acl.mdl.set_input_aipp(model_id, input_dataset, index, aipp_dynamic_set)
    ret = acl.mdl.destroy_aipp(aipp_dynamic_set)	
    # ......

## 4.自定义函数，执行模型。
def model_execute(index)
    # 4.1 调用自定义函数，设置动态AIPP参数值。
    ret = model_set_dynamic_aipp()
    # 4.2 执行模型，modelId_表示加载成功的模型的ID，input_和output_分别表示模型的输入和输出。
    ret = acl.mdl.execute(model_id, input_dataset, output_dataset)
    # ......

## 5.处理模型推理结果。
## ......

父主题： 模型动态AIPP推理

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

基本原理

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

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

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

示例代码

调用接口后，需增加异常处理的分支，示例代码中不一一列举。以下是关键步骤的代码示例，不可以直接拷贝运行，仅供参考。

 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 53 54 55 56 57 58 59 60 61 62  python import acl # ...... ACL_DATA_WITH_DYNAMIC_AIPP = 2 ACL_YUV420SP_U8 = 1 # 1.模型加载，加载成功后，再设置动态AIPP参数值。 # ...... # 2.准备模型描述信息model_desc，准备模型的输入数据input_dataset和模型的输出数据output_dataset。 # ...... # 3.自定义函数，设置动态AIPP参数值。 def model_set_dynamic_aipp(): # 3.1 获取标识动态AIPP输入的index。 need_dynamic_aipp = [] input_num = acl.mdl.get_num_inputs(model_desc) for index in range(input_num): aipp_type, dynamic_attached_index, ret = acl.mdl.get_aipp_type(model_id, index) if aipp_type == ACL_DATA_WITH_DYNAMIC_AIPP: need_dynamic_aipp.append(index) # 3.2 当前示例中以2个动态AIPP输入为例，用户可根据实际情况修改。 if len(need_dynamic_aipp) != 2: return 1 # 创建第一个动态aipp配置参数。 batch_number_first = 1 aipp_dynamic_set_first = acl.mdl.create_aipp(batch_number_first) ret = acl.mdl.set_aipp_src_image_size(aipp_dynamic_set_first, 256, 224) ret = acl.mdl.set_aipp_input_format(aipp_dynamic_set_first, ACL_YUV420SP_U8) ret = acl.mdl.set_aipp_csc_params(aipp_dynamic_set_first, 1, 256, 443, 0, 256, -86, -178, 256, 0, 350, 0, 0, 0, 0, 128, 128) ret = acl.mdl.set_aipp_rbuv_swap_switch(aipp_dynamic_set_first, 0) ret = acl.mdl.set_aipp_dtc_pixel_mean(aipp_dynamic_set_first, 0, 0, 0, 0, 0) ret = acl.mdl.set_aipp_dtc_pixel_min(aipp_dynamic_set_first, 0, 0, 0, 0, 0) ret = acl.mdl.set_aipp_pixel_var_reci(aipp_dynamic_set_first, 1.0, 1.0, 1.0, 1.0, 0) ret = acl.mdl.set_aipp_crop_params(aipp_dynamic_set_first, 1, 2, 2, 224, 224, 0) # 设置模型推理时的动态aipp参数值。 ret = acl.mdl.set_aipp_by_input_index(model_id, input_dataset, need_dynamic_aipp[0], aipp_dynamic_set_first) ret = acl.mdl.destroy_aipp(aipp_dynamic_set_first) # 创建第二个动态aipp配置参数。 batch_number_second = 2 aipp_dynamic_set_second = acl.mdl.create_aipp(batch_number_second) ret = acl.mdl.set_aipp_src_image_size(aipp_dynamic_set_second, 224, 224) # 此处可以继续调用其它AIPP参数设置接口。 # 设置模型推理时的动态aipp参数值。 ret = acl.mdl.set_aipp_by_input_index(model_id, input_dataset, need_dynamic_aipp[1], aipp_dynamic_set_second) ret = acl.mdl.destroy_aipp(aipp_dynamic_set_second) return ret # 4.自定义函数，执行模型。 def ModelExecute(int index): # 4.1 调用自定义函数，设置动态AIPP参数值。 ret = model_set_dynamic_aipp() # 4.2 执行模型，modelId_表示加载成功的模型的ID，input_dataset和output_dataset分别表示模型的输入和输出。 ret = acl.mdl.execute(model_id, input_dataset, output_dataset) # ...... # 5.处理模型推理结果。 # ......

父主题： 模型动态AIPP推理

原理介绍

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

父主题： Stream管理

多Stream接口调用流程

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

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

多Stream之间任务的同步等待可以利用Event实现，调用acl.rt.stream_wait_event接口阻塞指定Stream的运行，直到指定的Event完成。需在调用acl.rt.stream_wait_event接口前，先调用acl.rt.record_event接口。调用示例请参见关于Stream间任务的同步等待。

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

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

父主题： Stream管理

在线提单

动态Batch/动态分辨率/动态维度（设置多档维度值）​

接口调用流程​

动态Batch示例代码​

动态分辨率示例代码​

ND格式，动态维度示例代码​

接口调用流程​

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

基本原理​

示例代码​

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

基本原理​

示例代码​

原理介绍​

多Stream接口调用流程​

动态Batch/动态分辨率/动态维度（设置多档维度值）

接口调用流程

动态Batch示例代码

动态分辨率示例代码

ND格式，动态维度示例代码

接口调用流程

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

基本原理

示例代码

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

基本原理

示例代码

原理介绍

多Stream接口调用流程