已关闭
[Documentation|文档反馈]: op_api 对外头文件 @param 注释与签名不一致 8 处（幽灵参/缺参/名称零匹配/参数序错含静默算错） #5833
dihidao创建于 22 天前关闭于 17 天前
游震
22 天前 评论：
22 天前 评论：
您好，感谢反馈！
问题分析
一、出参顺序/名称与签名错位（第 1、4、6 项，绑定误导风险）
mc2/moe_distribute_dispatch_teardown/op_api/aclnn_moe_distribute_dispatch_teardown.h：注释末两个出参为 expertTokenNumsOut、epRecvCountsOut，签名（:60-61）实为 assistInfoForCombineOut、expertTokenNumsOut——assistInfoForCombineOut 完全无注释，epRecvCountsOut 在签名中不存在；comm_type 与签名 commType 拼写不一致属实。按注释顺序绑定会使第 3、4 个出参错位：tiling 侧要求 assistInfoForCombineOut 的 dim0 必须等于 a1*128（moe_distribute_dispatch_teardown_tiling_base.cpp:604-610），多数错绑会以参数校验错误暴露，但报错指向的参数与开发者预期完全对不上，定位成本高；形状恰好匹配时则直接产出语义错误的结果。moe/moe_token_permute_with_routing_map/op_host/op_api/aclnn_moe_token_permute_with_routing_map.h：注释出参序 permutedTokensOut→sortedIndicesOut→permuteProbsOutOptional，签名（:41）实为 permuteTokensOut→permuteProbsOutOptional→sortedIndicesOut，后两个出参互换，且首出参名称 permutedTokensOut/permuteTokensOut 也不一致。op_api 层对 sortedIndicesOut（int32）与 permuteProbsOutOptional（须与 probsOptional 同 dtype）有校验（aclnn_moe_token_permute_with_routing_map.cpp:75-89），错绑通常以参数错误暴露而非静默算错，但按注释排查会被报错信息误导。同族 moe_token_unpermute 的第一段接口注释完全没有 @param 条目，restoreShapeOptional 等全部形参无说明。- rope 系列 4 个文件（interleave_rope/op_host/op_api 下的 aclnn_interleave_rope.h 与 aclnn_rotary_position_embedding.h，rotary_position_embedding/op_host/op_api 下的 aclnn_rotary_position_embedding.h 及 v2）：注释均为 sin 在前、cos 在后，签名均为 (x, cos, sin, …)。sin 与 cos 的 dtype、shape 约束完全相同，交换传参不会触发任何编译期或运行时校验，会直接得到错误的旋转位置编码结果——这 4 处属于真正的静默算错场景，与您的风险排序一致。
二、形参缺失说明（第 2、5、7、8 项）
posembedding/norm_rope_concat/op_host/op_api/aclnn_norm_rope_concat.h：签名 35 个形参中注释仅覆盖 25 个，11 个出参张量（queryOutput/keyOutput/valueOutput/normQueryMean…normAddedKeyRstd）仅有一条泛化的 out 描述，且该描述引用的 x 并不在本接口签名中。experimental/attention/flash_attn_exp/op_api/aclnn_flash_attn.h：签名中的 maxSeqlenQ/maxSeqlenKV（:84）无注释；@param q [IN] …把方向标记后置，不符合 doxygen@param[in] name的标准语法，生成文档时方向属性无法被识别。gmm/grouped_matmul_finalize_routing/op_api/主文件、v2、weight_nz 共 3 个文件：签名中的 int64_t dtype 形参无注释。dtype 是输出类型选择参数（参与 op_api/grouped_matmul_finalize_routing.cpp:41 的 GetOutputDataType 决定输出 dtype），同目录 v3 与 weight_nz_v2 已有正确注释，可作对齐参考。mc2/quant_grouped_mat_mul_allto_allv/op_api/主文件与 v2：签名中的 int64_t groupSize 形参无注释。
三、doxygen 语法缺失（第 3 项）
attention/nsa_compress_attention_infer/op_host/op_api/aclnn_nsa_compress_attention_infer.h（experimental 同名文件同型）：第一段接口 23 个形参中 19 条说明写作param [in] xxx缺 @ 前缀，仅 4 条带 @，按 doxygen 标准语法只能渲染后 4 条；注释中 topkMaskOptional/compressStride/topkIndicesOut 与签名 topKMaskOptional/compressBlockStride/topKOutput 的名称也不一致。
处理方向
可行的修复方向与您的建议一致：以函数签名为基准逐条重写注释——补齐 assistInfoForCombineOut、maxSeqlenQ/maxSeqlenKV、dtype、groupSize 及 norm_rope_concat 各出参等缺失说明，修正出参顺序与名称拼写，统一为 doxygen 标准的 @param[in]/@param[out] 写法（gmm v3、weight_nz_v2 中 dtype 的注释写法可直接参考），并一并清理上述拷贝残留；修改仅涉及注释，不改变接口签名与行为。另外，您提到 494 个头文件扫描共 153 个候选，如方便欢迎把完整清单补充到本 Issue，便于一次性排查未报告的同类问题。我们会对上述文件逐项确认并评估批量修正方案，有进展将在本 Issue 同步。
游震
22 天前 评论：
22 天前 评论：
问题1： @tangjn
问题2： @yue-ma
问题3： @L_Euler
问题4： @kdy18482276080
问题5： @yipyip
问题6： @jiangjiawei
问题7： @yangziqi_007
问题8： @luobaiqing
此处折叠了13条事件消息 查看更多
huangshuai59
17 天前 评论：
17 天前 评论：
问题8已修复合入
17 天前 将 IceBearPolar 设为负责人
17 天前 移除了负责人 IceBearPolar
Han-Xiaobin
17 天前 评论：
17 天前 评论：
问题3已修复合入
kdy18482276080
17 天前 评论：
17 天前 评论：
问题4已修复合入
17 天前 移除了负责人 kdy18482276080
17 天前 将 kdy18482276080 设为负责人，移除负责人 L_Euler
17 天前 移除了负责人 jiangjiawei
17 天前 关闭了 issue
16 天前 添加了label：resolved
场景：开发者按 op_api 对外头文件注释调用 aclnn 接口（494 个 .h 机器扫描 153 候选人工核验后产出）。
问题与位置（master 2026-10-06 核实）：
影响：1/4/6 为静默算错（最高风险），其余编译失败或不知道必填参数。
问题复现方式：master 对照上述行号与签名。
修复建议：逐条按签名重写注释。已检索本仓历史 issues（#5705 为 Python 接口问题），未见本批 @param 问题报告。