函数：query_size_from_mem
函数：execute_async
| C函数原型 | aclError aclmdlExecuteAsync(uint32_t modelId, const aclmdlDataset *input, aclmdlDataset *output, aclrtStream stream) |
|---|---|
| Python函数 | ret = acl.mdl.execute_async(model_id, input, output_, stream) |
| 函数功能 | 执行模型推理，异步接口。 |
| 输入说明 | model_id：int，指定需要执行推理的模型的ID。 input：int，模型推理的输入数据的指针地址。 output：int，模型推理的输出数据的指针地址。 stream：int，指定已创建的Stream指针地址，如需指定新的Stream，可通过acl.rt.create_stream等接口创建并获取Stream指针地址。 |
| 返回值说明 | ret：int，错误码。 - 返回0表示成功。 - 返回其它值表示失败。 |
| 约束说明 | - 对同一个“model_id”的模型，不能调用acl.mdl.execute_async接口执行多Stream并发场景下的模型推理。 - 若由于业务需求，必须在多线程中使用同一个“model_id”，则用户线程间需加锁，保证刷新输入输出内存、保证执行是连续操作，例如： text<br> // 线程A的接口调用顺序：<br> lock(handle1) -> acl.rt.memcpy_async(stream1)刷新输入输出内存 -> acl.mdl.execute_async(modelId1,stream1)执行推理 -> unlock(handle1)<br> // 线程B的接口调用顺序：<br> lock(handle1) -> acl.rt.memcpy_async(stream1)刷新输入输出内存 -> acl.mdl.execute_async(modelId1,stream1)执行推理 -> unlock(handle1)<br> - 模型加载、模型执行、模型卸载的操作必须在同一个Context下（关于Context的创建请参见acl.rt.create_context）。 - 存放模型输入/输出数据的内存，可以使用以下接口申请：acl.rt.malloc、或acl.rt.malloc_host、或acl.rt.malloc_cached接口、或acl.media.dvpp_malloc接口、或acl.himpi.dvpp_malloc接口。 其中，acl.media.dvpp_malloc接口和acl.himpi.dvpp_malloc接口是媒体数据处理功能专用的内存申请接口，一般从性能角度，为了减少拷贝，媒体数据处理的输出作为模型推理的输入，实现内存复用。 由于硬件对内存有对齐和补齐要求，若用户使用这些接口申请大块内存并自行划分、管理内存时，需满足对应接口的对齐和补齐约束，请参见内存二次分配管理。 |
| 参考资源 | - 接口调用流程，参见接口调用流程。 - 接口调用示例，参见示例代码。 - Stream创建与管理，请参见Stream管理。 |
父主题： 模型加载与执行
函数：unload
| C函数原型 | aclError aclmdlUnload(uint32_t modelId) |
|---|---|
| Python函数 | ret = acl.mdl.unload(model_id) |
| 函数功能 | 系统完成模型推理后，可调用该接口卸载模型，释放资源，同步接口。 |
| 输入说明 | model_id：int，指定需卸载的模型的ID。 |
| 返回值说明 | ret：int，错误码。 - 返回0表示成功。 - 返回其它值表示失败。 |
| 约束说明 | - 在调用acl.mdl.unload接口卸载指定模型时，需确保其它接口没有正在使用该模型。 - 模型加载、模型执行、模型卸载的操作必须在同一个Context下（关于Context的创建请参见acl.rt.create_context）。 |
| 参考资源 | 接口调用流程，参见pyACL接口调用流程。 |
父主题： 模型加载与执行
函数：query_size
| C函数原型 | aclError aclmdlQuerySize(const char *fileName, size_t *workSize, size_t *weightSize) |
|---|---|
| Python函数 | work_size, weight_size, ret = acl.mdl.query_size(file_name) |
| 函数功能 | 根据模型文件获取模型执行时所需的权值内存大小、工作内存大小，同步接口。 |
| 输入说明 | file_name：str，需要获取内存信息的模型路径，路径中包含文件名。运行程序（APP）的用户需要对该路径有访问权限。 |
| 返回值说明 | work_size：int，模型执行时所需的工作内存的大小，单位Byte。 weight_size：int，模型执行时所需权值内存的大小，单位Byte。 ret：int，错误码。 - 返回0表示成功。 - 返回其它值表示失败。 |
| 约束说明 | 当由用户管理内存时，为确保内存不浪费，在申请工作内存、权值内存前，需要调用acl.mdl.query_size接口查询模型运行时所需工作内存、权值内存的大小。 如果模型输入数据的Shape不确定，则不能调用acl.mdl.query_size接口查询内存大小，在加载模型时，就无法由用户管理内存，因此需选择由系统管理内存的模型加载接口（例如，acl.mdl.load_from_file、acl.mdl.load_from_mem）。 |
| 参考资源 | 接口调用流程，参见模型加载。 |
父主题： 模型加载与执行
函数：query_size_from_mem
| C函数原型 | aclError aclmdlQuerySizeFromMem(const void *model, size_t modelSize, size_t *workSize, size_t *weightSize) |
|---|---|
| Python函数 | work_size, weight_size, ret = acl.mdl.query_size_from_mem(model, model_size) |
| 函数功能 | 根据内存中的模型数据获取模型执行时所需的权值内存大小、内存大小，同步接口。 |
| 输入说明 | model：int，需要获取内存信息的模型数据对应的指针地址。 model_size：int，模型数据长度，单位Byte。 |
| 返回值说明 | work_size：int，模型执行时所需的工作内存的大小，单位Byte。 weight_size：int，模型执行时所需权值内存的大小，单位Byte。 ret：int，错误码。 - 返回0表示成功。 - 返回其它值表示失败。 |
| 约束说明 | 执行和权重内存为Device内存，而且需要用户申请和释放。 |
父主题： 模型加载与执行
函数：set_dynamic_batch_size
| C函数原型 | aclError aclmdlSetDynamicBatchSize(uint32_t modelId, aclmdlDataset *dataset, size_t index, uint64_t batchSize) |
|---|---|
| Python函数 | ret = acl.mdl.set_dynamic_batch_size(model_id, dataset, index, batch_size) |
| 函数功能 | 在动态Batch场景下，在模型执行前调用本接口设置模型推理时的批量大小Batch（每次处理图片的数量）。 |
| 输入说明 | model_id：int，模型ID。 调用acl.mdl.load_from_file接口/acl.mdl.load_from_mem接口/acl.mdl.load_from_file_with_mem接口/acl.mdl.load_from_mem_with_mem接口加载模型成功后，会返回模型ID。 dataset：int，表示模型的输入数据对应的指针地址。 使用aclmdlDataset类型的数据描述模型推理时的输入数据，输入的内存地址、内存大小用aclDataBuffer类型的数据来描述。 index：int，标识动态Batch输入的输入index，需调用acl.mdl.get_input_index_by_name接口获取，动态Batch和动态分辨率输入的名称固定为“ascend_mbatch_shape_data”，动态AIPP输入的名称固定为“ascend_dynamic_aipp_data”。 batch_size：int，指定模型推理时的批量大小Batch。 可以调用acl.mdl.get_dynamic_batch接口获取指定模型支持的Batch档位数以及每一档中的Batch数。 |
| 返回值说明 | ret：int，错误码。 - 返回0表示成功。 - 返回其它值表示失败。 |
| 约束说明 | 无 |
| 参考资源 | 接口调用流程与示例，参见动态Batch/动态分辨率/动态维度（设置多档维度值）。 |
父主题： 模型加载与执行
函数：set_dynamic_hw_size
| C函数原型 | aclError aclmdlSetDynamicHWSize(uint32_t modelId, aclmdlDataset *dataset, size_t index, uint64_t height, uint64_t width) |
|---|---|
| Python函数 | ret = acl.mdl.set_dynamic_hw_size(model_id, dataset, index, height, width) |
| 函数功能 | 设置模型推理时输入图片的高和宽。 |
| 输入说明 | model_id：int，模型ID。 调用acl.mdl.load_from_file接口/acl.mdl.load_from_mem接口/acl.mdl.load_from_file_with_mem接口/acl.mdl.load_from_mem_with_mem接口加载模型成功后，会返回模型ID。 dataset：表示模型的输入数据。 使用aclmdlDataset类型的数据描述模型推理时的输入数据，输入的内存地址、内存大小用aclDataBuffer类型的数据来描述。 index：int，标识动态Batch输入的输入index，需调用acl.mdl.get_input_index_by_name接口获取，动态Batch和动态分辨率输入的名称固定为“ascend_mbatch_shape_data”，动态AIPP输入的名称固定为“ascend_dynamic_aipp_data”。 height：int，需设置的H值。 width：int，需设置的W值。 可以调用acl.mdl.get_dynamic_hw接口获取指定模型支持的分辨率档位数以及每一档中的宽、高。 |
| 返回值说明 | ret：int，错误码。 - 返回0表示成功。 - 返回其它值表示失败。 |
| 约束说明 | 无 |
| 参考资源 | 接口调用流程与示例，参见动态Batch/动态分辨率/动态维度（设置多档维度值）。 |
父主题： 模型加载与执行
函数：create_and_get_op_desc
| C函数原型 | aclError aclmdlCreateAndGetOpDesc(uint32_t deviceId, uint32_t streamId, uint32_t taskId, char *opName, size_t opNameLen, aclTensorDesc **inputDesc, size_t *numInputs, aclTensorDesc **outputDesc, size_t *numOutputs) |
|---|---|
| Python函数 | op_name, input_desc, num_inputs, output_desc, num_outputs, ret = acl.mdl.create_and_get_op_desc(device_id, stream_id, task_id, op_name_len) |
| 函数功能 | 获取指定算子的描述信息，包括算子名、输入Tensor描述、输出Tensor描述，如果查询不到指定算子，则返回报错。同步接口。 |
| 输入说明 | device_id：int，指定Device ID。 调用acl.rt.get_device_id_from_exception_info接口获取异常信息中的Device ID，作为本接口的输入。 stream_id：int，指定Stream ID。 调用acl.rt.get_stream_id_from_exception_info接口获取异常信息中的Stream ID，作为本接口的输入。 task_id：int，指定Task ID。 调用acl.rt.****get_task_id_from_exception_info接口获取异常信息中的Task ID，作为本接口的输入。 op_name_len：int，算子名称字符串长度。 若用户指定的长度比实际算子名称的长度短，则返回报错。 |
| 返回值说明 | op_name：string，算子名称字符串。 input_desc：int，算子所有输入的Tensor描述，指向一块连续内存的首地址。 num_inputs：int，输入个数。 output_desc：int，算子所有输出的Tensor描述，指向一块连续内存的首地址。 num_outputs：int，输出个数。 ret：int，错误码。 - 返回0表示成功。 - 返回其它值表示失败。 |
| 约束说明 | 使用场景****举例：执行整网模型推理时（不支持动态Shape场景），如果产生AI Core报错，可以调用本接口获取报错算子的描述信息，再做进一步错误排查。 推荐的接口调用顺序如下： 1. 定义并实现异常回调函数fn(aclrtExceptionInfoCallback类型)，回调函数原型请参见acl.rt.set_exception_info_callback。 实现回调函数的关键步骤如下： 1. 在异常回调函数fn内调用acl.rt.get_device_id_from_exception_info、acl.rt.get_stream_id_from_exception_info、acl.rt.get_task_id_from_exception_info接口分别获取Device ID、Stream ID、Task ID。 2. 在异常回调函数fn内调用acl.mdl.create_and_get_op_desc接口获取算子的描述信息。 3. 在异常回调函数fn内调用acl.get_tensor_desc_by_index接口获取指定算子输入/输出的Tensor描述。 4. 在异常回调函数fn内如下接口获取Tensor描述中的数据，进行进一步分析。 例如，调用acl.get_tensor_desc_address接口获取Tensor数据的内存地址（用户可从该内存地址中获取Tensor数据）、调用acl.get_tensor_desc_type接口获取Tensor描述中的数据类型、调用acl.get_tensor_desc_format接口获取Tensor描述中的Format、调用acl.get_tensor_desc_num_dims接口获取Tensor描述中的Shape维度个数、调用acl.get_tensor_desc_dim_v2接口获取Shape中指定维度的大小。 2. 调用acl.rt.set_exception_info_callback接口设置异常回调函数。 3. 执行模型推理。 如果存在AI Core报错，则触发回调函数fn，获取算子的信息，进行进一步分析。 |
| 参考资源 | 接口调用示例，参见AI Core异常信息获取。 |
父主题： 模型加载与执行
在线提单