已关闭
[Documentation|文档反馈]: op_api 对外头文件 @param 注释与签名不一致 7 处(缺参/幽灵参/名称零匹配/参数序错) #6399
dihidao创建于  16 天前关闭于  5 天前
dihidao
dihidao
16 天前 创建

场景:开发者按 op_api 对外头文件(随包发布)注释调用 aclnn 接口。

问题与位置(master 2026-10-06 核实,911 个含 @param 头文件机器扫描 153 候选人工核验后产出):

  1. matmul/quant_matmul_activation_quant/op_api/aclnn_quant_matmul_activation_quant_weight_nz.h:20 注释仅 4 条 @param,签名 :31 有 17 参——x1Scale/x2Scale/bias/transposeX1/transposeX2/groupSize/activationType/quantMode/roundMode/scaleAlg/dstTypeMax/yOut/yScaleOut 等 13 参零文档;
  2. activation/fast_gelu_grad/op_api/aclnn_fast_gelu_backward.h:20 注释仅 self/out 两条业务参数——签名 :33 为 (gradOutput, self, gradInput, workspaceSize, executor),缺 gradOutput、幽灵参 out、真实出参 gradInput 无文档;
  3. activation/hardtanh_grad/op_api/aclnn_hardtanh_backward.h:59 第二段 runner 挂了第一段的 7 参注释,签名 :93 为 4 参 (workspace, workspaceSize, executor, stream)——按注释准备 gradOutput 等入参 → 编译错;
  4. activation/ge_glu_grad_v2/op_host/op_api/aclnn_geglu_backward.h:44 幽灵参 activateLeft(签名 :66 无此参),workspace_size 与 workspaceSize 拼名也不一致;
  5. index/scatter_elements_v2/op_api/aclnn_scatter.h:155 原地接口注释化独立 out 出参——签名 :180 无 out,按注释额外准备 out 并按 8 参调用 → 编译错;
  6. norm/group_norm_silu_quant/op_host/op_api/aclnn_group_norm_silu_quant.h:21 "esp"应为"eps"且 activateSilu 完全零文档——签名 :64 有 (group, eps, activateSilu, out, meanOut, rstdOut...);
  7. quant/quantize/op_api/aclnn_quantize.h:21 注释 axis 在 dtype 前,签名 :36 为 (x, scales, zeroPoints, aclDataType dtype, int32_t axis, ...)——二者类型不同(int32_t vs aclDataType),按注释顺序位置传参 → 编译错;出参 out 零文档。

影响:op_api 头文件随包发布,按注释调用 → 编译失败或静默错误。

问题复现方式:master 对照上述行号与签名。
修复建议:逐条按签名重写注释。已检索本仓历史 issues(#6336-6339/#6357-6359 为 dtype 表问题),未见本批 @param 问题报告。

likedislike
yuning_chen
yuning_chen成员
16 天前 评论:

初步分析

感谢反馈,我们已开始核对这个问题。

现象理解:若干 op_api 头文件的参数注释和函数签名不一致,包括缺参、多写了签名里没有的参数、参数顺序或名称对不上。
当前判断:初步判断,待复现确认。按注释调用可能编译失败;所列 7 处是否仍和当前签名不一致,需逐条对照头文件核实。
涉及范围:量化 Matmul、激活反向、scatter、group norm silu quant、quantize 等对外头文件注释。
下一步:我们会按给出的位置核对注释和签名,评估按签名重写注释。

likedislike
yuning_chenyuning_chen成员
16 天前 将 yuechenyao_huawei 设为负责人
yuning_chenyuning_chen成员
16 天前 将 east_yang 设为负责人
yuning_chenyuning_chen成员
16 天前 将 bartonfang 设为负责人
yuning_chenyuning_chen成员
16 天前 将 liujie12345678 设为负责人
Lliujie12345678成员
16 天前 将 gitee-duhuiping 设为负责人
BartonFangBartonFang成员
15 天前 关联了pull request:docs(op_api): 修正 aclnn_scatter.h 幽灵参 out 与 group_norm_silu_quant 的 eps/activateSilu 注释(#6399)
Zhengyi ZhangZhengyi Zhang成员
15 天前 关联了pull request:docs(scatter_elements): README 数据类型列表与算子定义对齐&&参数冗余定义删除
Lluoyufan7
15 天前 关联了pull request:fix(activation): 修正 op_api 头文件注释与函数签名不一致
Ggitee-duhuiping成员
14 天前 将 cuijie25 设为负责人
Ccuijie成员
14 天前 关联了pull request:fix(quantize): 修正 aclnnQuantize 头文件注释与函数签名不一致
CANN-robotCANN-robot成员
5 天前 关闭了 issue
CANN-robotCANN-robot成员
5 天前 添加了label:resolved