产品支持情况

产品	是否支持
Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件	√
Atlas 200I/500 A2 推理产品	√
Atlas 推理系列产品	√
Atlas 训练系列产品	√
Atlas 200/300/500 推理产品	√

功能说明

执行模型推理。

本接口是异步接口，调用接口成功仅表示任务下发成功，不表示任务执行成功。调用该接口后，需调用同步等待接口（例如，aclrtSynchronizeStream）确保任务已执行完成，否则可能会导致训练或推理等业务异常、Device断链掉卡等未知情况。

函数原型

aclError aclmdlExecuteAsync(uint32_t modelId, const aclmdlDataset *input, aclmdlDataset *output, aclrtStream stream)

参数说明

参数名	输入/输出	说明
modelId	输入	指定需要执行推理的模型的ID。调用模型加载接口（例如aclmdlLoadFromFile接口、aclmdlLoadFromMem等）成功后，会返回模型ID，该ID作为本接口的输入。
input	输入	模型推理的输入数据的指针。对于捕获Stream上下发任务的场景，此处传nullptr。
output	输出	模型推理的输出数据的指针。对于捕获Stream上下发任务的场景，此处传nullptr。
stream	输入	指定Stream。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

约束说明

对同一个modelId的模型，不能调用aclmdlExecuteAsync接口执行多Stream并发场景下的模型推理。错误示例如下，该示例中，两次aclmdlExecuteAsync接口多Stream并发执行，导致报错：
```
//......
aclmdlExecuteAsync(modelId1, input, output, stream1);
aclmdlExecuteAsync(modelId1, input, output, stream2);
aclrtSynchronizeStream(stream1);
aclrtSynchronizeStream(stream2);
//......
```

若由于业务需求，必须在多线程中使用同一个modelId，则用户线程间需加锁，保证刷新输入输出内存、保证执行是连续操作，例如：

// 线程A的接口调用顺序：
lock(handle1) -> aclrtMemcpyAsync(stream1)刷新输入输出内存 -> aclmdlExecuteAsync(modelId1,stream1)执行推理 -> unlock(handle1)

// 线程B的接口调用顺序：
lock(handle1) -> aclrtMemcpyAsync(stream1)刷新输入输出内存 -> aclmdlExecuteAsync(modelId1,stream1)执行推理 -> unlock(handle1)

若需要使用外置Allocator，则注册Allocator时的stream需与模型执行时的stream保持一致。
存放模型输入/输出数据的Device内存，可以使用以下接口申请：aclrtMalloc、或aclrtMallocHost、或aclrtMallocCached接口、或acldvppMalloc接口、或hi_mpi_dvpp_malloc接口。
其中：
- 各内存申请接口的使用场景、使用约束请参见各内存申请接口的说明。
- aclrtMallocHost接口仅在如下形态才能申请Device内存：
  Ascend RC形态
- acldvppMalloc接口和hi_mpi_dvpp_malloc接口是媒体数据处理功能专用的内存申请接口，一般从性能角度，为了减少拷贝，媒体数据处理的输出作为模型推理的输入，实现内存复用。
- 由于硬件对内存有对齐和补齐要求，若用户使用这些接口申请大块内存并自行划分、管理内存时，需满足对应接口的对齐和补齐约束，请参见内存二次分配管理。

参考资源

接口调用流程及示例代码，参见异步模型推理。