CANN ops-nn aclnnIndexFillTensor/aclnnInplaceIndexFillTensor 算子指南:两段式接口、参数约束与 NPU 实现原理
CANN ops-nn aclnnIndexFillTensor/aclnnInplaceIndexFillTensor 算子指南:两段式接口、参数约束与 NPU 实现原理
导读
本文围绕 CANN ops-nn 神经网络算子库中的 aclnnIndexFillTensor 与 aclnnInplaceIndexFillTensor 两个张量填充算子展开,讲解它们"沿指定维度 dim,用 value 替换 index 指定位置元素"的核心功能、两段式调用流程、全部参数约束与错误码场景,并结合仓库源码剖析其参数校验、Tiling 分核策略与 AICore 内核实现。读完本文,你将掌握在 Atlas A2/A3 系列产品上正确调用这两类接口完成原地与非原地填充的完整实战能力,并能理解算子从 Host 侧入参校验到 Device 侧并行计算的全链路原理。
产品支持情况
aclnnIndexFillTensor 与 aclnnInplaceIndexFillTensor 在以下产品上受支持:
| 产品 | 是否支持 |
|---|---|
| Atlas A3 训练系列产品 / Atlas A3 推理系列产品 | √ |
| Atlas A2 训练系列产品 / Atlas A2 推理系列产品 | √ |
从源码看,这一支持范围与算子定义中注册的 AICore 配置一致:index_fill_def.cpp 中通过 AddConfig("ascend910b", ...) 与 AddConfig("ascend910_93", ...) 完成了 A2(ascend910b)与 A3(ascend910_93)两个平台的算子注册。
功能说明
接口功能为:沿输入 self 的给定轴 dim,将 index 指定位置的值使用 value 进行替换。
以输入 self 为 3×3 矩阵为例:
[[1, 2, 3],
[4, 5, 6],
[7, 8, 9]]
- 若
dim = 0,index = [0, 2],value = 0时,计算结果为:
[[0, 0, 0],
[4, 5, 6],
[0, 0, 0]]
即把第 0 行与第 2 行的整行元素全部替换为 0。
- 若
dim = 1,index = [0, 2],value = 0时,计算结果为:
[[0, 2, 0],
[0, 5, 0],
[0, 8, 0]]
即把每一行的第 0 列与第 2 列元素替换为 0,其余位置保持不变。
函数原型与两段式调用
aclnnIndexFillTensor 和 aclnnInplaceIndexFillTensor 实现相同的功能,使用区别如下,请根据自身实际场景选择合适的算子:
aclnnIndexFillTensor:需新建一个输出张量对象存储计算结果(非原地填充,对应 index_fill_def.cpp 中独立的输出y);aclnnInplaceIndexFillTensor:无需新建输出张量对象,直接在输入张量的内存中存储计算结果(原地填充)。
两个算子均采用两段式接口:必须先调用 aclnnIndexFillTensorGetWorkspaceSize 或 aclnnInplaceIndexFillTensorGetWorkspaceSize 获取计算所需 workspace 大小以及包含算子计算流程的执行器(executor),再调用 aclnnIndexFillTensor 或 aclnnInplaceIndexFillTensor 执行计算。该模式在 aclnn_index_fill_tensor.h 中有完整的四个接口声明,第一段接口标注为 aclnn_ops_infer domain,第二段接口负责实际执行。
四个接口的原型如下:
aclnnStatus aclnnIndexFillTensorGetWorkspaceSize(
const aclTensor* self,
int64_t dim,
const aclIntArray* index,
const aclScalar* value,
aclTensor* out,
uint64_t* workspaceSize,
aclOpExecutor** executor)
aclnnStatus aclnnIndexFillTensor(
void* workspace,
uint64_t workspaceSize,
aclOpExecutor* executor,
aclrtStream stream)
aclnnStatus aclnnInplaceIndexFillTensorGetWorkspaceSize(
aclTensor* selfRef,
int64_t dim,
const aclIntArray* index,
const aclScalar* value,
uint64_t* workspaceSize,
aclOpExecutor** executor)
aclnnStatus aclnnInplaceIndexFillTensor(
void* workspace,
uint64_t workspaceSize,
aclOpExecutor* executor,
aclrtStream stream)
aclnnIndexFillTensorGetWorkspaceSize 参数说明
| 参数名 | 输入/输出 | 描述 | 使用说明 | 数据类型 | 数据格式 | 维度(shape) | 非连续Tensor |
|---|---|---|---|---|---|---|---|
| self | 输入 | 功能示例中的 self,即待被在指定位置的值用 value 替换的张量。 | - | FLOAT16、FLOAT、DOUBLE、INT8、UINT8、INT16、INT32、INT64、BOOL、BFLOAT16 | ND | 0-8 | √ |
| dim | 输入 | 指定了 self 将要填充的维度。 | 当 self 为 1-8 维时,dim 的取值范围在 [-self.dim(), self.dim());当 self 为 0 维时,dim 的取值范围在 [-1, 1)。 | int64 | - | - | - |
| index | 输入 | 指定 self 在 dim 维度将要填充的下标。 | 其中的元素值小于 self 对应 dim 的维度大小。 | - | - | - | - |
| value | 输入 | 指定填充的数据值。 | 需要可转化为 self 的数据类型。 | 与 self 一致 | - | - | - |
| out | 输出 | 指定的输出张量。 | - | 与 self 一致 | ND | 与 self 一致 | √ |
| workspaceSize | 输出 | 返回需要在 Device 侧申请的 workspace 大小。 | - | - | - | - | - |
| executor | 输出 | 返回 op 执行器,包含了算子计算流程。 | - | - | - | - | - |
源码视角:参数校验与 dtype 支持差异
参数表格中的约束并非仅在文档层面,aclnn_index_fill_tensor.cpp 中的 CheckParams 会在第一段接口中按顺序完成四类校验:空指针检查(CheckNotNull)、数据类型合法性检查(CheckDtypeValid)、shape 与 dim 范围检查(CheckShape)、value 类型检查(CheckPromoteType,明确拒绝复数类型)。
值得注意的一个细节是 dtype 支持列表在不同平台存在差异(aclnn_index_fill_tensor.cpp):
- 通用支持列表:
DT_INT32、DT_FLOAT16、DT_FLOAT、DT_INT64、DT_BOOL; - 910B(A2)与 910_93(A3)专属支持列表:在上述基础上额外支持
DT_BF16、DT_INT8、DT_UINT8、DT_INT16、DT_DOUBLE,即文档表格中列出的完整十种类型。
CheckShape 同时完成了三类范围校验(aclnn_index_fill_tensor.cpp):self 与 out 的 shape 相等性、self 最大 8 维限制、dim 的正负取值区间以及 index 元素必须落在 [-dimSize, dimSize) 区间内。
第一段接口的返回值与错误码
aclnnStatus 返回状态码。第一段接口完成入参校验,出现以下场景时报错:
| 返回值 | 错误码 | 描述 |
|---|---|---|
| ACLNN_ERR_PARAM_NULLPTR | 161001 | 传入的 self、index、value 或 out 是空指针。 |
| ACLNN_ERR_PARAM_INVALID | 161002 | self、index、value 的数据类型不在支持的范围之内。 |
| ACLNN_ERR_PARAM_INVALID | 161002 | dim 的绝对值超出 self 的 dim 最大值或超出 8 维。 |
| ACLNN_ERR_PARAM_INVALID | 161002 | index 中的值超过 self 指定 dim 的最大值。 |
| ACLNN_ERR_PARAM_INVALID | 161002 | self 与 out 的 shape 不相等。 |
| ACLNN_ERR_PARAM_INVALID | 161002 | self 与 out 的数据类型不相等。 |
这些错误码场景在 UT 测试用例 中均有对应断言,例如 test_index_fill_input_nullptr_out 与 test_index_fill_output_nullptr_out 断言返回 ACLNN_ERR_PARAM_NULLPTR,test_index_fill_index_illegal_out、test_index_fill_max_dim_overflow_out、test_index_fill_output_shape_out 等断言返回 ACLNN_ERR_PARAM_INVALID,与文档表格完全对应。
第一段接口的底层计算流程
通过 GetWorkspaceSize 完成校验后,实现代码 会按以下步骤构建计算图并计算 workspace 大小:
- 空 Tensor 与空 index 场景:当
self为空 Tensor 或index->Size() == 0时,显式将workspaceSize置 0,并统一执行ViewCopy保证 out 被正确刷新,避免随机 workspace 值引发 OOM; - 负数 dim 转换:将负 dim 统一转换为正索引(
dim += selfDim); - 连续化处理:通过
l0op::Contiguous将 self 与 index 转换为连续张量; - 类型转换:将
aclIntArray类型的 index 转为aclTensor,将aclScalar类型的 value 转为与 self 同类型的 Tensor; - 核心计算:调用统一的
l0op::IndexFill(全量走 AICore 实现,对应 op_kernel/index_fill.cpp 中注册的index_fill内核); - 结果回写:通过
ViewCopy将计算结果拷贝到输出 out 上(out 可能是非连续 Tensor); - 通过
uniqueExecutor->GetWorkspaceSize()获取最终 workspace 大小并转移 executor。
aclnnIndexFillTensor 参数说明
| 参数名 | 输入/输出 | 描述 |
|---|---|---|
| workspace | 输入 | 在 Device 侧申请的 workspace 内存地址。 |
| workspaceSize | 输入 | 在 Device 侧申请的 workspace 大小,由第一段接口 aclnnIndexFillTensorGetWorkspaceSize 获取。 |
| executor | 输入 | op 执行器,包含了算子计算流程。 |
| stream | 输入 | 指定执行任务的 Stream。 |
返回值:aclnnStatus 返回状态码。第二段接口的实现非常精简,aclnn_index_fill_tensor.cpp 中直接调用 CommonOpExecutorRun(workspace, workspaceSize, executor, stream),将控制权交给算子执行框架完成设备侧计算。
aclnnInplaceIndexFillTensorGetWorkspaceSize 参数说明
| 参数名 | 输入/输出 | 描述 | 使用说明 | 数据类型 | 数据格式 | 维度(shape) | 非连续Tensor |
|---|---|---|---|---|---|---|---|
| selfRef | 输入 | 待被在指定位置的值用 value 替换的张量。 | - | FLOAT16、FLOAT、DOUBLE、INT8、UINT8、INT16、INT32、INT64、BOOL、BFLOAT16 | ND | 0-8 | √ |
| dim | 输入 | 指定了 selfRef 将要填充的维度。 | 当 self 为 1-8 维时,dim 的取值范围在 [-self.dim(), self.dim());当 self 为 0 维时,dim 的取值范围在 [-1, 1)。 | int64 | - | - | - |
| index | 输入 | 指定 self 在 dim 维度将要填充的下标。 | 其中的元素值小于 selfRef 对应的 dim 的维度大小。 | - | - | - | - |
| value | 输入 | 指定填充的数据值。 | - | 与 selfRef 一致 | - | - | - |
| workspaceSize | 输出 | 返回需要在 Device 侧申请的 workspace 大小。 | - | - | - | - | - |
| executor | 输出 | 返回 op 执行器,包含了算子计算流程。 | - | - | - | - | - |
源码视角:inplace 版本的实现本质
从源码看,inplace 版本并非独立的计算实现,而是对非原地版本的复用:aclnn_index_fill_tensor.cpp 中 aclnnInplaceIndexFillTensorGetWorkspaceSize 直接以 selfRef 同时作为 self 和 out 调用 aclnnIndexFillTensorGetWorkspaceSize,将输出张量绑定为输入张量自身。因此第一段接口中非原地版本对"self 与 out 的 shape/数据类型必须相等"的校验,在 inplace 场景下天然满足。
第一段接口的返回值与错误码
aclnnStatus:返回状态码。第一段接口完成入参校验,出现以下场景时报错:
| 返回值 | 错误码 | 描述 |
|---|---|---|
| ACLNN_ERR_PARAM_NULLPTR | 161001 | 传入的 selfRef、index、value 是空指针。 |
| ACLNN_ERR_PARAM_INVALID | 161002 | selfRef、index、value 的数据类型不在支持的范围之内。 |
| ACLNN_ERR_PARAM_INVALID | 161002 | dim 的绝对值超出 selfRef 的 dim 最大值或超出 8 维。 |
| ACLNN_ERR_PARAM_INVALID | 161002 | index 中的值超过 selfRef 指定 dim 的最大值。 |
对比可见,inplace 版本因无独立 out 参数,错误场景比非原地版本少两类(shape 不相等、dtype 不相等)。
aclnnInplaceIndexFillTensor 参数说明
| 参数名 | 输入/输出 | 描述 |
|---|---|---|
| workspace | 输入 | 在 Device 侧申请的 workspace 内存地址。 |
| workspaceSize | 输入 | 在 Device 侧申请的 workspace 大小,由第一段接口 aclnnInplaceIndexFillTensorGetWorkspaceSize 获取。 |
| executor | 输入 | op 执行器,包含了算子计算流程。 |
| stream | 输入 | 指定执行任务的 Stream。 |
返回值:aclnnStatus 返回状态码,执行逻辑同样通过 CommonOpExecutorRun 完成(aclnn_index_fill_tensor.cpp)。
约束说明
- 确定性计算:
aclnnIndexFillTensor与aclnnInplaceIndexFillTensor默认确定性实现。
源码视角:Tiling 分核策略与 workspace 规划
Host 侧 Tiling 由 index_fill_tiling.cpp 完成,它决定了算子在不同输入形状下的并行执行策略,是理解算子性能的关键:
Tiling Key 的五个分支(ComputeTilingKey)将输入 reshape 为统一的 [P, N, Q] 视图(P 为 dim 之前维度乘积,N 为 dim 维度大小,Q 为 dim 之后维度乘积),并根据 N/Q 规模选择分支:
tilingKey = 0(front_q):非尾轴且Q >= 1024,按 Q 切分,对应内核 index_fill_front_q.h;tilingKey = 1(front_n):非尾轴且 N 或 Q 较大,对应index_fill_front_n.h;tilingKey = 2(front_p):非尾轴小规模场景,对应index_fill_front_p.h;tilingKey = 3(tail_n):尾轴且N >= coreNum * 256,对应index_fill_tail_n.h;tilingKey = 4(tail_p):尾轴小规模场景,对应index_fill_tail_p.h。
五个分支在 index_fill.cpp 中通过 TILING_KEY_IS 宏分发到对应模板实例,并依据 sizeof(T)(half/float/uint8/uint64 四档)进一步实例化。
索引处理双模式(IndicesTaskTiling):当 N < coreNum * 32 时按 indicesNum 分核(indicesProcessMode = 0),否则按 N 分核(indicesProcessMode = 1)。前者在 index_fill_base.h 中把整个 ws 加载进 UB 后逐索引置 1 并原子累加回 GM;后者(IndicesTaskByN)则先将自己负责的 N 区间置零,再遍历全部索引命中区间内者单点写出,并利用 SYS_FLAG(值 133)与核间自旋等待实现多核同步。
workspace 大小计算(Init):基础部分为"标记 Tensor + 同步 Tensor + 复制 Tensor"(约 N * 2 + coreNum 字节并 32 字节对齐),并固定追加 SYS_WORK_SPACE_SIZE(16 MB);随后按 Tiling Key 与数据类型(INT64/DOUBLE 视为 8B 类型,乘以 qMultiplier = 2)追加各分支所需的 gather/比较 workspace。这解释了第一段接口中 workspaceSize 的来源——Host 侧按最坏情况预留,Device 侧按需申请。
调用示例
以下示例代码仅供参考,具体编译和执行过程请参考仓库中 examples 目录下的完整样例(test_aclnn_index_fill_tensor.cpp、test_aclnn_inplace_index_fill_tensor.cpp),它们与文档示例一一对应。
aclnnIndexFillTensor 调用示例
#include <iostream>
#include <vector>
#include "acl/acl.h"
#include "aclnnop/aclnn_index_fill_tensor.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); return ret);
ret = aclrtCreateStream(stream);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtCreateStream failed. ERROR: %d\n", ret); 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对外接口列表
// 根据自己的实际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 = {3, 3};
std::vector<int64_t> outShape = selfShape;
void* selfDeviceAddr = nullptr;
void* outDeviceAddr = nullptr;
aclTensor* self = nullptr;
aclScalar* value = nullptr;
aclIntArray* index = nullptr;
aclTensor* out = nullptr;
std::vector<float> selfHostData = {0, 1, 2, 3, 4, 5, 6, 7, 8};
std::vector<float> outHostData = {0, 0, 0, 0, 0, 0, 0, 0, 0};
int64_t dim = 1;
float fillVal = 10;
int64_t indexVal = 0;
// 创建self aclTensor
ret = CreateAclTensor(selfHostData, selfShape, &selfDeviceAddr, aclDataType::ACL_FLOAT, &self);
CHECK_RET(ret == ACL_SUCCESS, return ret);
// 创建out aclTensor
ret = CreateAclTensor(outHostData, outShape, &outDeviceAddr, aclDataType::ACL_FLOAT, &out);
CHECK_RET(ret == ACL_SUCCESS, return ret);
// 创建value aclScalar
value = aclCreateScalar(&fillVal, aclDataType::ACL_FLOAT);
CHECK_RET(value != nullptr, return ret);
// 创建index aclIntArray
index = aclCreateIntArray(&indexVal, 1);
CHECK_RET(index != nullptr, return ret);
// 3. 调用CANN算子库API,需要修改为具体的API名称
uint64_t workspaceSize = 0;
aclOpExecutor* executor;
// 调用aclnnIndexFillTensor第一段接口
ret = aclnnIndexFillTensorGetWorkspaceSize(self, dim, index, value, out, &workspaceSize, &executor);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnIndexFillTensorGetWorkspaceSize 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);
}
// 调用aclnnIndexFillTensor第二段接口
ret = aclnnIndexFillTensor(workspaceAddr, workspaceSize, executor, stream);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnIndexFillTensor 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. 释放申请的变量,需要根据具体API的接口定义修改
aclDestroyTensor(self);
aclDestroyTensor(out);
aclDestroyScalar(value);
aclDestroyIntArray(index);
// 7. 释放device资源,需要根据具体API的接口定义修改
aclrtFree(selfDeviceAddr);
aclrtFree(outDeviceAddr);
if (workspaceSize > 0) {
aclrtFree(workspaceAddr);
}
aclrtDestroyStream(stream);
aclrtResetDevice(deviceId);
aclFinalize();
return 0;
}
aclnnInplaceIndexFillTensor 调用示例
与上一示例相比,inplace 版本的核心差异在于:不需要创建独立的 out 张量,第一段接口只传 self、dim、index、value 四个入参;结果回读时直接读取 selfDeviceAddr 指向的内存即可。
#include <iostream>
#include <vector>
#include "acl/acl.h"
#include "aclnnop/aclnn_index_fill_tensor.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); return ret);
ret = aclrtCreateStream(stream);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclrtCreateStream failed. ERROR: %d\n", ret); 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 = {3, 3};
void* selfDeviceAddr = nullptr;
aclTensor* self = nullptr;
aclScalar* value = nullptr;
aclIntArray* index = nullptr;
std::vector<float> selfHostData = {0, 1, 2, 3, 4, 5, 6, 7, 8};
int64_t dim = 1;
float fillVal = 10;
int64_t indexVal = 0;
// 创建self aclTensor
ret = CreateAclTensor(selfHostData, selfShape, &selfDeviceAddr, aclDataType::ACL_FLOAT, &self);
CHECK_RET(ret == ACL_SUCCESS, return ret);
// 创建value aclScalar
value = aclCreateScalar(&fillVal, aclDataType::ACL_FLOAT);
CHECK_RET(value != nullptr, return ret);
// 创建index aclIntArray
index = aclCreateIntArray(&indexVal, 1);
CHECK_RET(index != nullptr, return ret);
// 3. 调用CANN算子库API,需要修改为具体的API名称
uint64_t workspaceSize = 0;
aclOpExecutor* executor;
// 调用aclnnInplaceIndexFillTensor第一段接口
ret = aclnnInplaceIndexFillTensorGetWorkspaceSize(self, dim, index, value, &workspaceSize, &executor);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnInplaceIndexFillTensorGetWorkspaceSize 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);
}
// 调用aclnnInplaceIndexFillTensor第二段接口
ret = aclnnInplaceIndexFillTensor(workspaceAddr, workspaceSize, executor, stream);
CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnInplaceIndexFillTensor 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(selfShape);
std::vector<float> resultData(size, 0);
ret = aclrtMemcpy(resultData.data(), resultData.size() * sizeof(resultData[0]), selfDeviceAddr,
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. 释放申请的变量,需要根据具体API的接口定义修改
aclDestroyTensor(self);
aclDestroyScalar(value);
aclDestroyIntArray(index);
// 7. 释放device资源,需要根据具体API的接口定义修改
aclrtFree(selfDeviceAddr);
if (workspaceSize > 0) {
aclrtFree(workspaceAddr);
}
aclrtDestroyStream(stream);
aclrtResetDevice(deviceId);
aclFinalize();
return 0;
}
使用建议与注意事项
综合文档约束与源码实现,实际使用时有几点值得留意:
- 按场景选择接口:如果输入张量后续不再需要原始值,优先使用
aclnnInplaceIndexFillTensor,省去 out 张量的创建与拷贝;否则使用aclnnIndexFillTensor保留原张量; - dtype 的平台差异:
BFLOAT16、INT8、UINT8、INT16、DOUBLE等类型仅在 A2/A3(ascend910b / ascend910_93)平台支持列表内(aclnn_index_fill_tensor.cpp),跨平台迁移时需要重新核对; - index 越界会报错:第一段接口会严格校验
index元素必须落在<a href="https://link.gitcode.com/i/39c1f77c72aae414cb19f8546001439f" target="_blank">-dimSize, dimSize)区间内([CheckShape),返回ACLNN_ERR_PARAM_INVALID(161002),请在调用前自行完成索引合法性检查; - 负数 dim 与负数 index 均受支持:dim 支持
<a href="https://link.gitcode.com/i/73ff7185c5e6a400a18fbfc6c356dcca" target="_blank">-self.dim(), self.dim())的负索引,index 元素同样支持负数(kernel 内通过indicesValue < 0 ? indicesValue + N : indicesValue完成转换,见 [index_fill_base.h); - workspace 申请:仅当第一段接口返回的
workspaceSize > 0时才需要调用aclrtMalloc申请 Device 侧内存,且示例中在任务结束后需同步释放; - 非连续 Tensor:self 与 out 均支持非连续 Tensor,第一段接口内部会通过
Contiguous与ViewCopy自动处理,调用方无需手动做连续化。
相关资源
- 算子完整说明与调用入口:experimental/index/index_fill/README.md
- 接口声明:op_api/aclnn_index_fill_tensor.h
- 接口实现(校验与计算图构建):op_api/aclnn_index_fill_tensor.cpp
- 算子定义(输入输出与属性注册):op_host/index_fill_def.cpp
- Tiling 实现(分核策略与 workspace 规划):op_host/arch22/index_fill_tiling.cpp
- 内核入口与五个分支:op_kernel/index_fill.cpp、op_kernel/index_fill_base.h、
index_fill_front_{q,p,n}.h与index_fill_tail_{n,p}.h - 可运行样例:examples/test_aclnn_index_fill_tensor.cpp、examples/test_aclnn_inplace_index_fill_tensor.cpp
- 单元测试(覆盖正常、异常、边界场景):tests/ut/op_api/test_aclnn_index_fill_tensor.cpp、tests/ut/op_api/test_aclnn_inplace_index_fill_tensor.cpp