Pull Request has been successfully merged by CANN-robot.
(Thank you for zhanw_coding's contribution.)变更摘要
本 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 条,新增元素个数不一致、存在重复元素、outshape 与重排结果不一致三类。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:


代码审查
审查总结
发现的问题(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:


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
/approveor/lgtm- Commenting
/approveimplies 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. 👍


🟡 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。


🟡 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。


compile


| 🚀 CI 流水线已启动 |
|---|
| 📋 执行详情: 点击查看流水线 |


/lgtm
/approve
by agent


描述
本PR修正transpose算子(aclnnPermute/aclnnChannelShuffle)的文档问题,并补充Transpose的图模式(GE IR)调用样例与调用说明。主要改动如下:
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)。Contiguous/ViewCopy实现细节及“支持非连续Tensor/空Tensor”等已由参数说明承载的能力描述。aclnnChannelShuffle(中英文同步)
(N, C, *)张量、通道维固定为第1维(下标从0开始、长度为C),避免被误解为第-3维为channel。self的数据类型补充BFLOAT16,与out及代码DTYPE_SUPPORT_LIST一致。Atlas训练系列产品不支持BFLOAT16。groups的参数描述与拦截表统一为“通道维长度C”。conversion/transpose/README(中英文同步)
x直接给出支持的数据类型,表下按产品系列说明不支持的类型(含4bit类型与Kirin系列)。perm、y的描述(引用x、perm),补充取值范围、元素个数与唯一性约束;约束说明同步完善。test_geir_permute(Permute IR)、test_geir_transpose(Transpose IR)。新增
conversion/transpose/examples/test_geir_transpose.cppmath/truncate_mod/examples/test_geir_truncate_mod.cpp,通过op_graph/transpose_proto.h构图调用Transpose算子。perm为数据依赖输入,形状推导需要其取值,因此使用Const节点提供。docs/zh/op_api_list.mdaclnnChannelShuffle的接口说明。关联的Issue
测试
.clang-format校验(clang-format --dry-run --Werror无告警),无超过120列的行。文档更新
conversion/transpose/docs/aclnnPermute.md、aclnnPermute_en.mdconversion/transpose/docs/aclnnChannelShuffle.md、aclnnChannelShuffle_en.mdconversion/transpose/README.md、README_en.mdconversion/transpose/examples/test_geir_transpose.cpp(新增)docs/zh/op_api_list.md类型标签