Merged
docs: transpose 算子更新文档说明 #7492
zhanw_codingAdd on 2 days ago
docs: transpose 算子更新文档说明 #7492
Merged
zhanw_codingAdd on 2 days ago
zhanw_coding
zhanw_codingCollaborators
2 days ago

描述

本PR修正transpose算子(aclnnPermute/aclnnChannelShuffle)的文档问题,并补充Transpose的图模式(GE IR)调用样例与调用说明。主要改动如下:

  1. aclnnPermute(中英文同步)

    • 调用示例与conversion/transpose/examples/test_aclnn_permute.cpp逐字对齐(括号风格、aclIntArray*写法、static_cast<uint64_t>(0)、注释文字等)。
    • 参数表字段规范为维度(shape)、非连续Tensor;二阶段参数名workspace_size修正为workspaceSize;workspaceSize/executor/workspace/stream描述改为规范固定话术。
    • 对齐self/out的数据类型:与aclnn_permute.cpp的DTYPE_SUPPORT_LIST一致,去除多余的句号并统一排列顺序。
    • 补充dims的“元素个数等于self维度数”“元素不可重复”“负数表示从尾部计数”,以及self的空Tensor支持说明。
    • 错误码表补充三类ACLNN_ERR_PARAM_INVALID场景:dims元素个数与self维度数不一致、dims存在重复元素、out的shape与按dims重排self后的shape不一致(rowspan由4调整为7)。
    • 约束说明仅保留“维度不超过8维”“确定性计算”,移除Contiguous/ViewCopy实现细节及“支持非连续Tensor/空Tensor”等已由参数说明承载的能力描述。
  2. aclnnChannelShuffle(中英文同步)

    • 功能说明改为(N, C, *)张量、通道维固定为第1维(下标从0开始、长度为C),避免被误解为第-3维为channel。
    • self的数据类型补充BFLOAT16,与out及代码DTYPE_SUPPORT_LIST一致。
    • 新增产品差异说明:Atlas训练系列产品不支持BFLOAT16。
    • groups的参数描述与拦截表统一为“通道维长度C”。
  3. conversion/transpose/README(中英文同步)

    • 参数表中x直接给出支持的数据类型,表下按产品系列说明不支持的类型(含4bit类型与Kirin系列)。
    • 修正perm、y的描述(引用x、perm),补充取值范围、元素个数与唯一性约束;约束说明同步完善。
    • 调用说明统一为“调用Transpose算子”,并补充图模式调用:test_geir_permute(Permute IR)、test_geir_transpose(Transpose IR)。
  4. 新增conversion/transpose/examples/test_geir_transpose.cpp

    • 写法参考math/truncate_mod/examples/test_geir_truncate_mod.cpp,通过op_graph/transpose_proto.h构图调用Transpose算子。
    • perm为数据依赖输入,形状推导需要其取值,因此使用Const节点提供。
  5. docs/zh/op_api_list.md

    • 同步aclnnChannelShuffle的接口说明。

关联的Issue

测试

  • 文档改动:已校验npu标签配对、代码围栏配对、相对链接有效性、HTML表格列数与行尾空白。
  • 新增样例:已通过仓库.clang-format校验(clang-format --dry-run --Werror无告警),无超过120列的行。
  • 样例已在ascend950上板验证ok。

文档更新

  • conversion/transpose/docs/aclnnPermute.md、aclnnPermute_en.md
  • conversion/transpose/docs/aclnnChannelShuffle.md、aclnnChannelShuffle_en.md
  • conversion/transpose/README.md、README_en.md
  • conversion/transpose/examples/test_geir_transpose.cpp(新增)
  • docs/zh/op_api_list.md

类型标签

likedislike
Pull Request has been successfully merged by CANN-robot.
(Thank you for zhanw_coding's contribution.)
zhanw_codingzhanw_codingCollaborators
2 days ago Created pull request, commit 61aa0de5
atomgit-bot
atomgit-bot
2 days ago Comments:

变更摘要

本 PR 为 conversion/transpose 算子的文档更新,不涉及实现代码。改动集中在 README.md、README_en.md、aclnnChannelShuffle.md、aclnnPermute.md 等中英文文档:统一算子参数命名(输入 x/self、排列参数 perm/dims、输出 y/out),补全并细分数据类型支持列表与不同产品系列的差异说明,明确 perm/dims 的取值、个数与去重约束及输出 shape 推导公式,新增空 Tensor、非连续 Tensor 等约束说明,并在调用说明中补充图模式调用入口。

主要改动

  • 参数与数据类型表重写(README.md、README_en.md):将 x、perm、y 三者描述由“见下方”改为显式数据类型枚举(含 INT8…BFLOAT16、HIFLOAT8、FLOAT8_E5M2、FLOAT8_E4M3FN、FLOAT4_E2M1、HIFLOAT4、HIFLOAT4_SCALE 等),并用各产品系列(Ascend 950PR&950DT、Atlas A3/A2、Atlas 推理/训练产品、Kirin X90/9030 等)不支持类型说明替换原 GPU/CPU 支持类型描述。
  • 约束说明具体化(README.md、README_en.md):由“无”改为明确 x 维度不超过 8 维、perm 元素个数等于 x 的维度数量、取值范围为 [-x维度数量, x维度数量-1] 且不可重复、y.shape[i] = x.shape[perm[i]] 且 dtype 与 x 一致。
  • aclnnPermute 文档能力与报错补充(docs/aclnnPermute.md、docs/aclnnPermute_en.md):新增支持空 Tensor(self 的 shape 含 0 时输出空 Tensor)与非连续 Tensor(先转连续 Tensor,结果通过 ViewCopy 写回 out);dims 增加“元素个数等于维度数量、不可重复、负数从尾部计数”的要求;ACLNN_ERR_PARAM_INVALID(161002)错误场景由 4 条扩展为 7 条,新增元素个数不一致、存在重复元素、out shape 与重排结果不一致三类。
  • aclnnChannelShuffle 功能与数据类型调整(docs/aclnnChannelShuffle.md、docs/aclnnChannelShuffle_en.md):功能说明从 (*, C, H, W) 张量改为 (N, C, *) 张量、通道维固定为第 1 维且长度为 C,groups 需整除通道维长度 C;输入/输出数据类型列表补充 BFLOAT16(输入侧),并新增 <term>Atlas训练系列产品</term> 不支持 BFLOAT16 的产品说明。
  • 调用说明与示例代码整理(README*.md、docs/aclnnPermute*.md):调用方式表中算子命名修正为 ChannelShuffle、Transpose、Permute,并新增图模式调用 test_geir_permute(基于 op_graph/permute_proto.h 构图);aclnnPermute 示例代码调整缩进与函数括号风格,workspaceSize 判断改为 static_cast<uint64_t>(0)。

🧩 本次 Review 已使用自定义 Skill:

likedislike
Incorrect?
atomgit-bot
atomgit-bot
2 days ago Comments:

代码审查

审查总结

发现的问题(3 项)

优先级 数量
P0 0
P1 0
P2 2
P3 1

逐文件审查结论

  • conversion/transpose/README.md:发现问题(1 项 P2:第 28-29 行分产品 dtype 排除项与 docs/aclnnPermute.md:128/131、docs/aclnnChannelShuffle.md:128 互相矛盾;1 项 P2:第 24 行 FLOAT4/HIFLOAT4 系列“列出支持但所有产品均标注不支持”自相矛盾;1 项 P3:第 24 行 dtype 列表漏掉 aclnn 文档仍声明支持的 DOUBLE/COMPLEX64/COMPLEX128)。
  • conversion/transpose/README_en.md:no issues(内容与中文版一一对应,另两处问题在中文版已上报,此处仅需同步修复;新增的图模式调用链接 examples/test_geir_permute.cpp、op_graph/permute_proto.h 均已核实存在)。
  • conversion/transpose/docs/aclnnChannelShuffle.md:no issues(功能说明改为按第 1 维通道分组、self 补上 BFLOAT16 以对齐 out 行、新增 <!-- npu="910" id7 --> 块 id 唯一、groups 校验描述与错误码表一致;错误码表 rowspan 与行数匹配)。
  • conversion/transpose/docs/aclnnChannelShuffle_en.md:no issues(与中文版同步;错误码表 rowspan="5" 与首行重复文本为改动前既有问题,不在本次范围)。
  • conversion/transpose/docs/aclnnPermute.md:no issues(rowspan 由 4 改 7 与新增 3 条错误项行数一致;空 Tensor/非连续 Tensor/dims 约束与参数表描述一致;示例代码仅排版与 static_cast<uint64_t>(0) 调整,语义等价,资源释放路径完整)。
  • conversion/transpose/docs/aclnnPermute_en.md:no issues(rowspan=7 与 7 条错误项匹配,新增约束与中文版一致)。

总体风险判断:改动为纯文档,不涉及可执行代码;主要风险集中在 README 与两份 aclnn 接口文档之间新引入的数据类型/产品支持口径不一致,可能导致用户按 README 选择实际不支持的 dtype(或反之规避已支持的 dtype),属文档准确性问题,建议合入前与算子实际注册(op_host/transpose_def.cpp 及各架构模板)对齐一次口径。</||DSML|| parameter>
</||DSML|| invoke>
</||DSML|| calls>

类型 数量
🔴 阻塞 0
🟡 建议 2

💬 仅评论


🧩 本次 Review 已使用自定义 Skill:

likedislike
Incorrect?
CANN-robotCANN-robotCollaborators
2 days ago Added label: cann-cla/yes
CANN-robot
CANN-robotCollaborators
2 days ago Comments:

Thanks for your pull-request.
The full list of commands accepted by me can be found at here.
You can get sig-info at here.
You can self-configure the PR merge rules for this repository. For more details, please refer to Here.
For more, you also can visit HICANN.


PR Approval Progress

✅ Congratulations! All modules have met the lgtm and approve requirements.

Module Approval Details

module lgtm status approve status
*/*/README.md ✅ 陈娇, onanfield, 顾宝成 (3/2) ✅ 陈娇 (1/1)
*/*/docs/acl*.md ✅ 陈娇, onanfield, 顾宝成 (3/2) ✅ 陈娇 (1/1)
conversion/transpose ✅ 顾宝成, onanfield (2/2) ✅ onanfield, 顾宝成 (2/1)
repo-cann/ops-math ✅ onanfield, 顾宝成 (2/2) ✅ onanfield, 顾宝成 (2/1)

💡 Tip:

  • Committer can comment /approve or /lgtm
  • Commenting /approve implies both code review (lgtm) and intent to merge (approve)

CLA Signature Pass

zhanw_coding, thanks for your pull request. All authors of the commits have signed the CLA. 👍

likedislike
CANN-robotCANN-robotCollaborators
2 days ago Set FelixTang7,yue-ma,zhou-qilong,gitee-duhuiping,wangrui_,rxtfeng,loov1,zhangzijie,jia0liang,zl_hw,songkai111,gitcode-chenjiao,chenxingyu18,lwx1255555,pingchuantang,llimwang,gubaocheng,andong_hw,fengying555682,xuejinghui,onanfield,jiangjiawei,clinglai0517,caiwenwen,yanglu-1 as approver
CANN-robotCANN-robotCollaborators
2 days ago Set FelixTang7,yue-ma,zhou-qilong,gitee-duhuiping,wangrui_,rxtfeng,loov1,zhangzijie,zl_hw,songkai111,gitcode-chenjiao,chenxingyu18,lwx1255555,pingchuantang,llimwang,gubaocheng,andong_hw,fengying555682,xuejinghui,onanfield,jiangjiawei,clinglai0517,caiwenwen,yanglu-1 as approver
atomgit-bot
atomgit-bot2 days agoStart code review1
conversion/transpose/README.md
@@ -24,3 +24,1 @@
24-| x | 输入张量 | 需要进行维度置换的输入张量。 | 见下方 | ND |
25-| perm | 输入张量 | 表示x的维度的排列。取值需在[0,self的维度数量-1]范围内。 | INT64、INT32 | - |
26-| y | 输出 | 维度最大不超过8维,shape由dims和原self的shape共同决定,dtype需要与self一致。 | 同x | ND |
24+| x | 输入张量 | 需要进行维度置换的输入张量。 | INT8、UINT8、INT16、UINT16、INT32、UINT32、INT64、UINT64、FLOAT、FLOAT16、BFLOAT16、BOOL、HIFLOAT8、FLOAT8_E5M2、FLOAT8_E4M3FN、FLOAT4_E2M1、FLOAT4_E1M2、HIFLOAT4、HIFLOAT4_SCALE | ND |
atomgit-bot
atomgit-bot2 days agoComments:

🟡 Medium Priority

变更行:README.md 第 24 行把 FLOAT4_E2M1、FLOAT4_E1M2、HIFLOAT4、HIFLOAT4_SCALE 四种低位宽类型列入 x 的「支持数据类型」;同一改动的新增行第 28 行又声明 Atlas 950PR&950DT、Atlas A3、Atlas A2、Atlas 200I/500 A2、Atlas 推理、Atlas 训练 均「不支持」这四种类型,第 29 行再声明 Kirin X90/9030 也「不支持」这四种类型。

受影响契约:README 的「参数说明」dtype 列表 ∪「产品支持情况」表(第 5-14 行共 8 个产品)共同决定该算子实际可用的 dtype。

失败模式:README 第 5-14 行的 8 个产品已被第 28-29 行全部覆盖,且每一行都把这 4 种类型划为不支持,因此按文档自身逻辑,FLOAT4_E2M1/FLOAT4_E1M2/HIFLOAT4/HIFLOAT4_SCALE 在所有受支持产品上都不可用,第 24 行把它们列为「支持」即自相矛盾。用户若据第 24 行在 950 系列上构造 FLOAT4/HIFLOAT4 输入调用算子,会直接命中 dtype 校验失败(aclnnPermute 返回 ACLNN_ERR_PARAM_INVALID 161002)或 tiling 侧不支持分支。另外 HIFLOAT4 系列通常正是 950 系列的低精度格式,把 950PR&950DT 整体列入不支持清单也值得复核。

建议:确认 FLOAT4_E2M1/FLOAT4_E1M2/HIFLOAT4/HIFLOAT4_SCALE 的真实产品支持范围:若有产品支持(如 Ascend 950 系列),从第 28 行的排除清单中移除并保持第 24 行不变;若均不支持,从第 24 行 dtype 列表中删除这 4 种类型。同步修改 README_en.md。

likedislike
Incorrect?
atomgit-bot
atomgit-bot2 days agoStart code review1
conversion/transpose/README.md
@@ -28,2 +28,2 @@
28-- <term>GPU支持的数据类型</term>:数据类型支持DT_BF16, DT_FLOAT16, DT_FLOAT, DT_DOUBLE, DT_INT64, DT_INT32, DT_UINT8, DT_UINT16, DT_UINT32, DT_UINT64, DT_INT8, DT_INT16, DT_COMPLEX32, DT_COMPLEX64, DT_COMPLEX128, DT_QINT8, DT_QUINT8, DT_QINT16, DT_QUINT16, DT_QINT32, DT_BOOL, DT_HIFLOAT8, DT_FLOAT8_E5M2, DT_FLOAT8_E4M3FN。
29-- <term>CPU支持的数据类型</term>:数据类型支持同GPU。
28+- <term>Ascend 950PR&950DT系列产品</term>、<term>Atlas A3系列产品</term>、<term>Atlas A2系列产品</term>、<term>Atlas 200I/500 A2推理产品</term>、<term>Atlas推理系列产品</term>、<term>Atlas训练系列产品</term>:数据类型不支持FLOAT4_E2M1、FLOAT4_E1M2、HIFLOAT4、HIFLOAT4_SCALE。
29+- <term>Kirin X90处理器系列产品</term>、<term>Kirin 9030处理器系列产品</term>:数据类型不支持INT16、UINT16、UINT32、INT64、UINT64、BFLOAT16、BOOL、HIFLOAT8、FLOAT8_E5M2、FLOAT8_E4M3FN、FLOAT4_E2M1、FLOAT4_E1M2、HIFLOAT4、HIFLOAT4_SCALE。
atomgit-bot
atomgit-bot2 days agoComments:

🟡 Medium Priority

变更行:README.md 第 28-29 行新增了「按产品列出不支持的数据类型」两块说明(README_en.md 第 30-31 行同义)。

受影响契约:README 声称 ①Atlas 950PR&950DT / Atlas A3 / Atlas A2 / Atlas 200I/500 A2 / Atlas 推理 / Atlas 训练 仅「不支持 FLOAT4_E2M1、FLOAT4_E1M2、HIFLOAT4、HIFLOAT4_SCALE」,言下之意 HIFLOAT8、FLOAT8_E5M2、FLOAT8_E4M3FN、BFLOAT16 在这些产品上均受支持;②Kirin X90/9030 的不支持清单。

失败模式:同一 PR 修改的 docs/aclnnPermute.md 第 128 行明确写「Atlas训练系列产品:数据类型不支持 COMPLEX128、BFLOAT16、HIFLOAT8、FLOAT8_E5M2、FLOAT8_E4M3FN」,第 131 行写「Atlas A2系列产品、Atlas A3系列产品:数据类型不支持 HIFLOAT8、FLOAT8_E5M2、FLOAT8_E4M3FN」;docs/aclnnChannelShuffle.md 第 128 行还新增了「Atlas训练系列产品:数据类型不支持 BFLOAT16」。两份文档描述的是同一 README 第 42 行指向的 aclnnPermute 接口,却给出互斥结论。用户按 README 在 A2/A3 上用 HIFLOAT8/FLOAT8_*、或在 Atlas 训练上用 BFLOAT16 调用 aclnnPermute,第一段接口会返回 ACLNN_ERR_PARAM_INVALID(161002),属于可预判的使用失败。此外 README 第 5-14 行「产品支持情况」将 Atlas 200I/500 A2、Atlas 推理列为「√」,而两份 aclnn 文档(id4/id5)写「不支持」,新增的第 28 行又以「仅部分 dtype 不支持」的口吻描述这两个产品,进一步强化了这种不一致。

建议:按算子实际注册的 dtype 统一 README 与 docs/aclnnPermute.md、docs/aclnnChannelShuffle.md 的产品差异说明:在 README 第 28-29 行补上 910 不支持 BFLOAT16、A2/A3 不支持 HIFLOAT8/FLOAT8_E5M2/FLOAT8_E4M3FN 等条目(或反向修正 aclnn 文档),并同步 README_en.md。

likedislike
Incorrect?
zhanw_codingzhanw_codingCollaborators
2 days ago Pre merge succeeded (commit_id: 1994f97129f378121e32e1e05c00d60b5bb10e03)
5 event messages are collapsed here。 See more
zhanw_codingzhanw_codingCollaborators
2 days ago Resolved final issue
zhanw_coding
zhanw_codingCollaborators
2 days ago Comments:

compile

likedislike
zhanw_codingzhanw_codingCollaborators
2 days ago Pre merge succeeded (commit_id: d64f83044108a9c0b212d52e40c22dd3a29c18ef)
CANN-robot
CANN-robotCollaborators
2 days ago Comments:
🚀 CI 流水线已启动
📋 执行详情: 点击查看流水线
likedislike
CANN-robotCANN-robotCollaborators
2 days ago Added label: ci-pipeline-running
zhanw_codingzhanw_codingCollaborators
2 days ago Modify description of pull request
CANN-robotCANN-robotCollaborators
2 days ago Removed label: ci-pipeline-running
CANN-robotCANN-robotCollaborators
2 days ago Added label: ci-pipeline-passed
chenjiaoCollaborators
2 days ago Comments:

/approve

likedislike
zhanw_codingzhanw_codingCollaborators
2 days ago Modify description of pull request
onanfieldCollaborators
2 days ago Comments:

/lgtm
/approve

likedislike
CANN-robotCANN-robotCollaborators
2 days ago Added label: approved
gubaochengCollaborators
2 days ago Comments:

/lgtm
/approve
by agent

likedislike
CANN-robotCANN-robotCollaborators
2 days ago Added label: lgtm
CANN-robotCANN-robotCollaborators
2 days ago Closed associated issue
CANN-robotCANN-robotCollaborators
2 days ago Merged pull request