企业官网建设流程全解析

• 算子库
• 人工智能
• CANN

导读

Muls 是 CANN ops-math 数学算子库中完成 Tensor 与 Scalar 逐元素乘法的基础算子，本文以仓库文档 math/muls/docs/aclnnMuls&aclnnInplaceMuls.md 为主体，系统讲解其 aclnn 接口的两种调用形态（普通模式aclnnMuls与就地模式aclnnInplaceMuls）。读完本文，你将掌握：Muls 算子在各类 Ascend/Atlas 产品上的支持情况、两段式接口的完整调用流程与参数约束、参数校验失败时的错误码含义，以及可直接复制运行的 C++ 调用示例，并结合仓库源码理解其底层实现路径。

产品支持情况

根据文档与 math/muls/README.md，Muls 算子的 aclnn 接口支持情况如下：

需要特别注意的是，在Atlas 推理系列产品与Atlas 训练系列产品上，aclnnMuls/aclnnInplaceMuls不支持 BFLOAT16 数据类型，选用 BFLOAT16 前需确认目标设备的支持范围。

功能说明与计算公式

• 接口功能：完成 tensor 与 scalar 间的乘法计算，即对输入张量self的每个元素乘上标量other。
• 计算公式：

$$ out_i = self_i \times other $$

从算子定义看（见 math/muls/op_graph/muls_proto.h），该算子的输入为x、标量属性为value、输出为y，且输出与输入保持相同的 dtype 与 shape，兼容 PyTorch 的muls算子语义。

接口总览：普通模式与就地模式

aclnnMuls与aclnnInplaceMuls实现相同的计算功能，二者的区别仅在于结果存储方式，请根据实际场景选择：

• aclnnMuls：需新建一个输出张量对象out存储计算结果，原输入张量保持不变。
• aclnnInplaceMuls：无需新建输出张量对象，直接在输入张量selfRef的内存中就地覆写计算结果，适合需要节省内存、且原始输入不再使用的场景。

从源码 math/muls/op_api/muls.cpp 可以看到两者底层的实现差异：

• Muls：通过executor->AllocTensor(self->GetViewShape(), self->GetDataType())基于输入张量的视图 shape 与数据类型新建一个输出张量mulsOut，再以OP_INPUT(self)+OP_OUTPUT(mulsOut)+OP_ATTR(alpha)挂载 AICore 算子启动列表；
• MulsInplace：直接将self作为输出（auto mulsOut = self;），输入输出指向同一块内存，其余启动逻辑与普通模式完全一致。

两种模式最终都复用同一个 AICore 计算任务（ADD_TO_LAUNCHER_LIST_AICORE(Muls, ...)），区别只体现在输出张量对象的分配策略上。

两段式接口机制

每个算子均采用两段式接口调用（机制详见 docs/zh/context/two_phase_api.md）：

1. 必须先调用第一段接口aclnnMulsGetWorkspaceSize或aclnnInplaceMulsGetWorkspaceSize，完成入参校验、输出 shape 推导、kernel tiling 等工作，并返回：
   • workspaceSize：算子在 NPU 上完成计算所需申请的临时内存（workspace）大小；
   • executor：包含了算子计算流程的 op 执行器。
2. 根据workspaceSize在 Device 侧申请内存后，再调用第二段接口aclnnMuls或aclnnInplaceMuls真正执行计算。

注意：第二段接口不能重复调用。正确的调用次序必须是GetWorkspaceSize → 执行接口，且每个第一段接口得到的executor只能被消费一次。

四个接口的函数原型如下：

aclnnStatus aclnnMulsGetWorkspaceSize( const aclTensor *self, const aclScalar *other, aclTensor *out, uint64_t *workspaceSize, aclOpExecutor **executor)

aclnnStatus aclnnMuls( void *workspace, uint64_t workspaceSize, aclOpExecutor *executor, aclrtStream stream)

aclnnStatus aclnnInplaceMulsGetWorkspaceSize( aclTensor *selfRef, const aclScalar *other, uint64_t *workspaceSize, aclOpExecutor **executor)

aclnnStatus aclnnInplaceMuls( void *workspace, uint64_t workspaceSize, aclOpExecutor *executor, aclrtStream stream)

可以看到，普通模式需要传入输入self、标量other与输出out三个参数，而就地模式只需传入selfRef与other两个参数，输出即输入本身。

aclnnMulsGetWorkspaceSize 接口详解

参数说明

补充说明：

• 表格中"非连续 Tensor √"表示接口支持 stride 非连续的输入输出张量，相关背景可参考 docs/zh/context/non_contiguous_tensor.md；数据格式统一为 ND，可参见 docs/zh/context/data_format.md。
• Atlas 推理系列产品、Atlas 训练系列产品不支持 BFLOAT16 数据类型。
• 从算子底层定义看（math/muls/op_host/muls_def.cpp），kernel 实际支持的 dtype 集合为 BF16、FLOAT16、FLOAT、INT16、INT32、INT64、COMPLEX32、COMPLEX64，aclnn 接口层更宽的 dtype 列表（如 DOUBLE、INT8、UINT8、BOOL、COMPLEX128 等）会在接口内部通过数据类型推导与转换完成衔接。

返回值与错误码

返回aclnnStatus状态码，具体参见 aclnn返回码。第一段接口完成入参校验，出现以下场景时报错：

aclnnMuls 接口详解

参数说明

返回值

返回aclnnStatus状态码，具体参见 aclnn返回码。

aclnnInplaceMulsGetWorkspaceSize 接口详解

参数说明

与普通模式最大的差异在于selfRef一个参数同时承担输入与输出两个角色，因此接口不再需要out参数，其数据类型推导要求也直接体现在selfRef与other之间。

返回值与错误码

返回aclnnStatus状态码，具体参见 aclnn返回码。第一段接口完成入参校验，出现以下场景时报错：

aclnnInplaceMuls 接口详解

参数说明

返回值

返回aclnnStatus状态码，具体参见 aclnn返回码。

约束说明

• 确定性计算：aclnnMuls 与 aclnnInplaceMuls 默认采用确定性实现（确定性计算的含义可参考 docs/zh/context/determinism_compute.md）。
• 精度风险：INT32/INT64 类型计算存在精度损失，需谨慎使用。从算子定义注释（math/muls/op_graph/muls_proto.h）可以印证：FLOAT32 类型参数无精度损失；当 INT32/INT64 参数值超过 2^24 时会发生精度损失，此时建议改用 Mul 算子。

调用示例

仓库提供了可直接编译运行的完整示例，分别位于 math/muls/examples/test_aclnn_muls.cpp 与 math/muls/examples/test_aclnn_inplace_muls.cpp，与文档中的示例代码一致，两者核心流程完全相同，仅输入输出构造方式不同。

aclnnMuls 示例代码

#include <iostream> #include <vector> #include "acl/acl.h" #include "aclnnop/aclnn_mul.h" #define CHECK_RET(cond, return_expr) \ do { \ if (!(cond)) { \ return_expr; \ } \ } while (0) #define LOG_PRINT(message, ...) \ do { \ printf(message, ##__VA_ARGS__); \ } while (0) int64_t GetShapeSize(const std::vector<int64_t>& shape) { int64_t shapeSize = 1; for (auto i : shape) { shapeSize *= i; } return shapeSize; } int Init(int32_t deviceId, aclrtStream* stream) { // 固定写法，资源初始化 auto ret = aclInit(nullptr); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclInit failed. ERROR: %d\n", ret); return ret); ret = aclrtSetDevice(deviceId); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtSetDevice failed. ERROR: %d\n", ret); aclFinalize(); return ret); ret = aclrtCreateStream(stream); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtCreateStream failed. ERROR: %d\n", ret); aclrtResetDevice(deviceId); aclFinalize(); return ret); return 0; } template <typename T> int CreateAclTensor(const std::vector<T>& hostData, const std::vector<int64_t>& shape, void** deviceAddr, aclDataType dataType, aclTensor** tensor) { auto size = GetShapeSize(shape) * sizeof(T); // 调用aclrtMalloc申请device侧内存 auto ret = aclrtMalloc(deviceAddr, size, ACL_MEM_MALLOC_HUGE_FIRST); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtMalloc failed. ERROR: %d\n", ret); return ret); // 调用aclrtMemcpy将host侧数据拷贝到device侧内存上 ret = aclrtMemcpy(*deviceAddr, size, hostData.data(), size, ACL_MEMCPY_HOST_TO_DEVICE); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtMemcpy failed. ERROR: %d\n", ret); return ret); // 计算连续tensor的strides std::vector<int64_t> strides(shape.size(), 1); for (int64_t i = shape.size() - 2; i >= 0; i--) { strides[i] = shape[i + 1] * strides[i + 1]; } // 调用aclCreateTensor接口创建aclTensor *tensor = aclCreateTensor(shape.data(), shape.size(), dataType, strides.data(), 0, aclFormat::ACL_FORMAT_ND, shape.data(), shape.size(), *deviceAddr); return 0; } int main() { // 1.（固定写法）device/stream初始化，参考acl API手册 // 根据自己的实际device填写deviceId int32_t deviceId = 0; aclrtStream stream; auto ret = Init(deviceId, &stream); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("Init acl failed. ERROR: %d\n", ret); return ret); // 2.构造输入与输出，需要根据API的接口自定义构造 std::vector<int64_t> selfShape = {4, 2}; std::vector<int64_t> outShape = {4, 2}; void* selfDeviceAddr = nullptr; void* outDeviceAddr = nullptr; aclTensor* self = nullptr; aclScalar* other = nullptr; aclTensor* out = nullptr; std::vector<float> selfHostData = {0, 1, 2, 3, 4, 5, 6, 7}; float otherValue = 1.2f; std::vector<float> outHostData(8, 0); // 创建self aclTensor ret = CreateAclTensor(selfHostData, selfShape, &selfDeviceAddr, aclDataType::ACL_FLOAT, &self); CHECK_RET(ret == ACL_SUCCESS, return ret); // 创建other aclScalar other = aclCreateScalar(&otherValue, aclDataType::ACL_FLOAT); CHECK_RET(other != nullptr, return ret); // 创建out aclTensor ret = CreateAclTensor(outHostData, outShape, &outDeviceAddr, aclDataType::ACL_FLOAT, &out); CHECK_RET(ret == ACL_SUCCESS, return ret); // 3.调用CANN算子库API，需要修改为具体的API名称 uint64_t workspaceSize = 0; aclOpExecutor* executor; // 调用aclnnMuls第一段接口 ret = aclnnMulsGetWorkspaceSize(self, other, out, &workspaceSize, &executor); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnMulsGetWorkspaceSize failed. ERROR: %d\n", ret); return ret); // 根据第一段接口计算出的workspaceSize申请device内存 void* workspaceAddr = nullptr; if (workspaceSize > 0) { ret = aclrtMalloc(&workspaceAddr, workspaceSize, ACL_MEM_MALLOC_HUGE_FIRST); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("allocate workspace failed. ERROR: %d\n", ret); return ret); } // 调用aclnnMuls第二段接口 ret = aclnnMuls(workspaceAddr, workspaceSize, executor, stream); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnMuls failed. ERROR: %d\n", ret); return ret); // 4.（固定写法）同步等待任务执行结束 ret = aclrtSynchronizeStream(stream); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtSynchronizeStream failed. ERROR: %d\n", ret); return ret); // 5.获取输出的值，将device侧内存上的结果拷贝至host侧，需要根据具体API的接口定义修改 auto size = GetShapeSize(outShape); std::vector<float> resultData(size, 0); ret = aclrtMemcpy(resultData.data(), resultData.size() * sizeof(resultData[0]), outDeviceAddr, size * sizeof(resultData[0]), ACL_MEMCPY_DEVICE_TO_HOST); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("copy result from device to host failed. ERROR: %d\n", ret); return ret); for (int64_t i = 0; i < size; i++) { LOG_PRINT("result[%ld] is: %f\n", i, resultData[i]); } // 6.释放aclTensor和aclScalar，需要根据具体API的接口定义修改 aclDestroyTensor(self); aclDestroyScalar(other); aclDestroyTensor(out); // 7.释放device资源 aclrtFree(selfDeviceAddr); aclrtFree(outDeviceAddr); if (workspaceSize > 0) { aclrtFree(workspaceAddr); } aclrtDestroyStream(stream); aclrtResetDevice(deviceId); aclFinalize(); return 0; }

上述示例以{0, 1, 2, 3, 4, 5, 6, 7}的 FLOAT 张量与标量1.2f相乘，预期输出为{0, 1.2, 2.4, 3.6, 4.8, 6.0, 7.2, 8.4}（由于浮点表示，打印结果可能存在微小尾差）。整个流程可以归纳为七个固定步骤：

1. 初始化：aclInit→aclrtSetDevice→aclrtCreateStream；
2. 构造输入输出：通过aclrtMalloc+aclrtMemcpy准备 Device 侧数据，再用aclCreateTensor/aclCreateScalar创建 aclTensor 与 aclScalar；
3. 两段式调用：先aclnnMulsGetWorkspaceSize获取 workspaceSize 与 executor，按需aclrtMalloc申请 workspace，再aclnnMuls执行；
4. 同步等待：aclrtSynchronizeStream等待任务完成；
5. 回拷结果：aclrtMemcpy将 Device 侧输出拷贝至 Host 侧并打印；
6. 释放张量：aclDestroyTensor/aclDestroyScalar；
7. 释放资源：aclrtFree、aclrtDestroyStream、aclrtResetDevice、aclFinalize。

aclnnInplaceMuls 示例代码

就地模式与普通模式代码几乎一致，差异集中在第 2、3、5、6 步：

#include <iostream> #include <vector> #include "acl/acl.h" #include "aclnnop/aclnn_mul.h" #define CHECK_RET(cond, return_expr) \ do { \ if (!(cond)) { \ return_expr; \ } \ } while (0) #define LOG_PRINT(message, ...) \ do { \ printf(message, ##__VA_ARGS__); \ } while (0) int64_t GetShapeSize(const std::vector<int64_t>& shape) { int64_t shapeSize = 1; for (auto i : shape) { shapeSize *= i; } return shapeSize; } int Init(int32_t deviceId, aclrtStream* stream) { // 固定写法，资源初始化 auto ret = aclInit(nullptr); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclInit failed. ERROR: %d\n", ret); return ret); ret = aclrtSetDevice(deviceId); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtSetDevice failed. ERROR: %d\n", ret); aclFinalize(); return ret); ret = aclrtCreateStream(stream); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtCreateStream failed. ERROR: %d\n", ret); aclrtResetDevice(deviceId); aclFinalize(); return ret); return 0; } template <typename T> int CreateAclTensor(const std::vector<T>& hostData, const std::vector<int64_t>& shape, void** deviceAddr, aclDataType dataType, aclTensor** tensor) { auto size = GetShapeSize(shape) * sizeof(T); // 调用aclrtMalloc申请device侧内存 auto ret = aclrtMalloc(deviceAddr, size, ACL_MEM_MALLOC_HUGE_FIRST); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtMalloc failed. ERROR: %d\n", ret); return ret); // 调用aclrtMemcpy将host侧数据拷贝到device侧内存上 ret = aclrtMemcpy(*deviceAddr, size, hostData.data(), size, ACL_MEMCPY_HOST_TO_DEVICE); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtMemcpy failed. ERROR: %d\n", ret); return ret); // 计算连续tensor的strides std::vector<int64_t> strides(shape.size(), 1); for (int64_t i = shape.size() - 2; i >= 0; i--) { strides[i] = shape[i + 1] * strides[i + 1]; } // 调用aclCreateTensor接口创建aclTensor *tensor = aclCreateTensor(shape.data(), shape.size(), dataType, strides.data(), 0, aclFormat::ACL_FORMAT_ND, shape.data(), shape.size(), *deviceAddr); return 0; } int main() { // 1.（固定写法）device/stream初始化，参考acl API手册 // 根据自己的实际device填写deviceId int32_t deviceId = 0; aclrtStream stream; auto ret = Init(deviceId, &stream); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("Init acl failed. ERROR: %d\n", ret); return ret); // 2.构造输入，需要根据API的接口自定义构造 std::vector<int64_t> selfRefShape = {4, 2}; std::vector<int64_t> outShape = {4, 2}; void* selfRefDeviceAddr = nullptr; aclTensor* selfRef = nullptr; aclScalar* other = nullptr; std::vector<float> selfRefHostData = {0, 1, 2, 3, 4, 5, 6, 7}; float otherValue = 1.2f; // 创建selfRef aclTensor ret = CreateAclTensor(selfRefHostData, selfRefShape, &selfRefDeviceAddr, aclDataType::ACL_FLOAT, &selfRef); CHECK_RET(ret == ACL_SUCCESS, return ret); // 创建other aclScalar other = aclCreateScalar(&otherValue, aclDataType::ACL_FLOAT); CHECK_RET(other != nullptr, return ret); // 3.调用CANN算子库API，需要修改为具体的API名称 uint64_t workspaceSize = 0; aclOpExecutor* executor; // 调用aclnnInplaceMuls第一段接口 ret = aclnnInplaceMulsGetWorkspaceSize(selfRef, other, &workspaceSize, &executor); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnInplaceMulsGetWorkspaceSize failed. ERROR: %d\n", ret); return ret); // 根据第一段接口计算出的workspaceSize申请device内存 void* workspaceAddr = nullptr; if (workspaceSize > 0) { ret = aclrtMalloc(&workspaceAddr, workspaceSize, ACL_MEM_MALLOC_HUGE_FIRST); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("allocate workspace failed. ERROR: %d\n", ret); return ret); } // 调用aclnnInplaceMuls第二段接口 ret = aclnnInplaceMuls(workspaceAddr, workspaceSize, executor, stream); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnInplaceMuls failed. ERROR: %d\n", ret); return ret); // 4.（固定写法）同步等待任务执行结束 ret = aclrtSynchronizeStream(stream); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtSynchronizeStream failed. ERROR: %d\n", ret); return ret); // 5.获取输出的值，将device侧内存上的结果拷贝至host侧，需要根据具体API的接口定义修改 auto size = GetShapeSize(selfRefShape); std::vector<float> resultData(size, 0); ret = aclrtMemcpy(resultData.data(), resultData.size() * sizeof(resultData[0]), selfRefDeviceAddr, size * sizeof(resultData[0]), ACL_MEMCPY_DEVICE_TO_HOST); CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("copy result from device to host failed. ERROR: %d\n", ret); return ret); for (int64_t i = 0; i < size; i++) { LOG_PRINT("result[%ld] is: %f\n", i, resultData[i]); } // 6.释放aclTensor和aclScalar，需要根据具体API的接口定义修改 aclDestroyTensor(selfRef); aclDestroyScalar(other); // 7.释放device资源，需要根据具体API的接口定义修改 aclrtFree(selfRefDeviceAddr); if (workspaceSize > 0) { aclrtFree(workspaceAddr); } aclrtDestroyStream(stream); aclrtResetDevice(deviceId); aclFinalize(); return 0; }

就地模式的关键差异点：

• 第 2 步只创建selfRef张量与other标量，不创建独立的输出张量；
• 第 5 步直接从selfRefDeviceAddr回拷结果（结果已覆写进原输入内存）；
• 第 6、7 步也无需释放独立的输出张量与输出内存。

源码视角：从 aclnn 接口到 AICore 计算

除了接口文档，Muls 算子在仓库中的实现链路完整可查，可以帮助理解接口背后发生了什么：

1. 算子 IR 定义（math/muls/op_graph/muls_proto.h）：通过REG_OP(Muls)声明输入x、输出y与必选浮点属性value，支持 1D~8D 输入，dtype 覆盖 BF16/F16/F32/INT16/INT32/INT64/COMPLEX32/COMPLEX64，输出与输入同 dtype 同 shape；
2. 算子宿主定义（math/muls/op_host/muls_def.cpp）：注册Muls的 OpDef，配置了动态编译、动态 shape、动态 rank 支持，以及PrecisionReduceFlag(true)精度优化标志，并为 ascend950、ascend350 平台注册 AICore 配置（opFile.value指向muls_apt）；
3. shape 推导（math/muls/op_host/muls_infershape.cpp）：复用Ops::Base::InferShape4Elewise逐元素算子的通用推导逻辑，保证输出 shape 与输入一致；
4. aclnn 层实现（math/muls/op_api/muls.cpp）：Muls与MulsInplace分别通过AllocTensor新建输出或复用输入内存，再经ADD_TO_LAUNCHER_LIST_AICORE将输入、输出与属性alpha组装进 AICore 启动列表，最终由统一的执行器调度到 NPU 上完成逐元素乘标量计算；
5. kernel 与 tiling（math/muls/op_kernel、math/muls/op_host/arch35/muls_tiling_arch35.cpp）：负责在 AICore 侧的实际计算与多核切分策略，arch35对应 Ascend 950/A3 等新一代平台架构。

测试与验证

仓库为 Muls 算子提供了配套的单元测试与示例，可作为接口行为与实现的验证依据：

• aclnn 接口示例：math/muls/examples/test_aclnn_muls.cpp、math/muls/examples/test_aclnn_inplace_muls.cpp；
• op_api 单元测试：math/muls/tests/ut/op_api/test_aclnn_muls.cpp；
• infershape 单元测试：math/muls/tests/ut/op_host/test_muls_infershape.cpp；
• tiling 单元测试：math/muls/tests/ut/op_host/arch35/test_muls_tiling_arch35.cpp；
• ST 用例数据：math/muls/tests/st/arch35/ttk_kernel_muls_st.csv，以及测试基准脚本 math/muls/tests/assets/golden.py。

总结

aclnnMuls与aclnnInplaceMuls是 CANN ops-math 中 Tensor×Scalar 乘法的标准 aclnn 入口：普通模式输出独立张量、原输入保持不变，适合结果需要复用、输入仍需保留的场景；就地模式直接在输入内存覆写结果、省去输出张量的分配与搬运，适合内存敏感或输入生命周期即将结束的场景。二者共享同一套两段式调用范式、数据类型推导规则与错误码体系，且默认确定性实现。开发时只需对照本文的四个接口原型、参数表与两个可直接运行的示例，即可快速在支持的 Ascend/Atlas 产品上完成接入。

• 算子库
• 人工智能
• CANN