Closed
[Documentation|文档反馈]: transpose算子(aclnnPermute/aclnnChannelShuffle)文档调用方式、数据类型与格式规范问题 #4805
zhanw_codingAdd on  2 days agoClosed at  2 days ago
zhanw_coding
zhanw_codingCollaborators
2 days ago Create

一、文档链接 (必填)

二、问题文档片段 (必填)

1. aclnnPermute.md

  • 调用示例与 conversion/transpose/examples/test_aclnn_permute.cpp 不一致:函数括号风格、aclIntArray* 写法、workspace 判空写法(> 0 与 static_cast<uint64_t>(0))、注释文字均不同。
  • 参数表字段名使用了全角括号与空格:维度(shape)、非连续 Tensor。
  • 二阶段参数名写成 workspace_size,与函数原型中的 workspaceSize 不一致。
  • workspaceSize、executor、workspace、stream 的描述未使用规范固定话术(含多余中英文空格)。
  • 参数表 out 的数据类型末尾多一个句号,且与 self 的排列顺序不一致,易被误读为两者存在差异。
  • 一段接口拦截表缺少代码中实际存在的三类 ACLNN_ERR_PARAM_INVALID 场景:dims 元素个数与 self 维度数不一致、dims 存在重复元素、out 的 shape 与按 dims 重排 self 后的 shape 不一致。
  • self 使用说明缺少空 Tensor 支持说明;dims 使用说明缺少“元素个数等于 self 维度数”“元素不可重复”“负数表示从尾部计数”。
  • 约束说明包含 Contiguous/ViewCopy 等实现细节,且“支持非连续Tensor”“支持空Tensor”属于能力描述,已在参数说明中体现,不应作为约束重复。

2. aclnnChannelShuffle.md

  • 功能说明写作“将(*, C, H, W)张量的channels分成g个组”,* 位于通道维前,易被误解为第-3维为channel;实际通道维固定为第1维(下标从0开始)。
  • self 的数据类型列表缺少 BFLOAT16,与 out 列表及代码 DTYPE_SUPPORT_LIST 不一致。
  • 缺少产品差异说明:Atlas训练系列产品 不支持 BFLOAT16。

3. conversion/transpose/README.md

  • 调用说明只有 aclnn 接口,缺少图模式调用;已提供 examples/test_geir_permute.cpp,且缺少 Transpose 算子自身的 GE IR 样例。
  • 数据类型沿用了上游“GPU/CPU支持的数据类型”表述(DT_COMPLEX32、DT_QINT8 等),与实际可调用的 NPU 接口不一致。
  • 参数说明中 perm、y 的描述引用了 self、dims,与实际参数名 x、perm 不符;perm 取值范围缺少负索引、元素个数与唯一性约束。
  • 调用说明中算子名不统一(ChannelShuffle/Permute/Transpose混用)。

4. docs/zh/op_api_list.md

  • aclnnChannelShuffle 的接口说明仍为旧表述“将(*, C, H, W)张量的channels分成g个组……随机重排”,与修正后的文档不一致。

三、存在的问题与期望

  • 调用方式不完整:缺少 Transpose 的图模式样例与调用说明,aclnn示例与代码不一致。
  • 数据类型不一致:self/out 列表以及 README、op_api_list 中的描述与代码/IR定义不一致。
  • 规范性问题:表头字段、参数名、固定话术、错误码完整性、约束与实现细节混写等。
  • 期望:按 aclnn 文档规范统一修正中英文文档、补齐调用方式与错误码、对齐数据类型,并新增 Transpose 的 GE IR 样例与 README 调用说明。

关联PR:https://gitcode.com/cann/ops-math/pull/7492

likedislike
zhanw_codingzhanw_codingCollaborators
2 days ago Added label: documentation
zhanw_coding
zhanw_codingCollaborators
2 days ago Comments:

/assign

likedislike
CANN-robotCANN-robotCollaborators
2 days ago Assign zhanw_coding as responsible person
CANN-robotCANN-robotCollaborators
2 days ago Close issue
CANN-robotCANN-robotCollaborators
2 days ago changed custom state from 待办的 to 已完成
CANN-robotCANN-robotCollaborators
2 days ago Added label: resolved