已关闭

[Documentation|文档反馈]: [AI 识别] ops-nn op_api_list.md 文档问题汇总（28个问题项） #2588

StoneChan_创建于 5月8日关闭于 5月25日

StoneChan_成员

5月8日创建

[Documentation|文档反馈]: [AI 识别] ops-nn op_api_list.md 文档问题汇总（28个问题项）

标签: documentation
生成时间: 2026-05-08 17:23:19
涉及接口数:28（1个链接断链 + 27个遗漏接口）
目标仓库: cann/ops-nn

Thanks for sending an issue! Please fill in the following template.

Document Link（文档链接）

docs/zh/op_api_list.md

扫描摘要

检查项	扫描数	通过数	失败数
接口名一致性	377	377	0
aclnn文档存在性	377	377	0
链接跳转有效性	377	376	1
确定性说明一致性(A2/A3)	377	333	44
总计	377	332	45

通过率: 88.1%

Issues Section（问题文档片段）

二、链接断链（1个接口）

接口名	链接路径	状态
aclnnEmbeddingRenorm	`../../index/gather_v2/docs/aclnnEmbeddingRenorm.md`	link_broken

三、接口遗漏（27个接口）

op_api_list.md 缺失 27 个实际存在的接口

以下是实际存在但未列入 op_api_list.md 的接口完整列表：

loss 目录（7个）

序号	接口名	算子目录
1	aclnnBinaryCrossEntropyWithLogitsBackward	`loss/sigmoid_cross_entropy_with_logits_grad_v2/`
2	aclnnFusedCrossEntropyLossWithMaxSum	`loss/fused_cross_entropy_loss_with_max_sum/`
3	aclnnCrossEntropyLossGrad	`loss/cross_entropy_loss_grad/`
4	aclnnLpLoss	`experimental/loss/lp_loss/`
5	aclnnL1LossGrad	`experimental/loss/l1_loss_grad/`
6	aclnnsmoothl1lossv2	`experimental/loss/smooth_l1_loss_v2/`
7	aclnnBinaryCrossEntropyWithLogitsBackward	`experimental/loss/sigmoid_cross_entropy_with_logits_grad_v2/`

index 目录（3个）

序号	接口名	算子目录
1	aclnnMaxUnpool2d	`index/scatter_elements/`
2	aclnnMaxUnpool3d	`index/scatter_elements/`
3	aclnnExpandIntoJaggedPermute	`index/expand_into_jagged_permute/`

matmul 目录（9个）

序号	接口名	算子目录
1	aclnnAddmm&aclnnInplaceAddmm	`matmul/mat_mul_v3/`
2	aclnnRotateQuant	`matmul/rotate_quant/`
3	aclnnQuantMatmulV4	`matmul/quant_batch_matmul_v3/`
4	aclnnQuantMatmulV3	`matmul/quant_batch_matmul_v3/`
5	aclnnBatchMatmulQuant	`matmul/batch_matmul_quant/`
6	aclnnTransposeBatchMatMulWeightNZ	`matmul/transpose_batch_mat_mul/`
7	aclnnWeightQuantBatchMatmul	`matmul/weight_quant_batch_matmul/`
8	aclnnQuantMatmul	`matmul/quant_matmul/`
9	aclnnQuantMatmulV2	`matmul/quant_matmul/`

optim 目录（1个）

序号	接口名	算子目录
1	aclnnApplyAdam	`optim/apply_adam/`

experimental/activation 目录（7个）

序号	接口名	算子目录
1	aclnnHardShrink	`experimental/activation/hard_shrink/`
2	aclnnFusedBiasLeakyRelu	`experimental/activation/fused_bias_leaky_relu/`
3	aclnnFastGeluV2	`experimental/activation/fast_gelu_v2/`
4	aclnnSoftsign	`experimental/activation/softsign/`
5	aclnnLogSoftmaxV2	`experimental/activation/log_softmax_v2/`
6	aclnnSiluMul	`experimental/activation/silu_mul/`
7	aclnnSoftsignBackward	`experimental/activation/softsign_grad/`

按目录分类统计：

loss: 7 个
matmul: 9 个
index: 3 个
optim: 1 个
experimental/activation: 7 个

Root Cause Analysis（根本原因分析）

确定性配置机制

ops-nn 仓库使用系统级配置方式：

用户调用: aclrtCtxSetSysParamOpt(ACL_OPT_DETERMINISTIC, 1)  // 开启确定性
算子读取: aclrtGetSysParamOpt(ACL_OPT_DETERMINISTIC, &value) // 检查配置

判断规则：

文档声明"支持通过aclrtCtxSetSysParamOpt开启确定性" → 代码应调用 aclrtGetSysParamOpt
文档声明"默认确定性实现" → 代码不应有配置选项

主要问题

类型A（31个）: 文档声称支持，代码不支持

影响：用户无法开启确定性，文档误导用户
修复方案：要么补充代码实现，要么修改文档声明

类型B（4个）: 文档不一致

影响：用户无法确定真实行为
修复方案：同步两处文档

类型C（3个）: 文档声明确定性但代码有配置

影响：文档与代码矛盾
修复方案：如果代码支持配置，文档应声明"支持开启"

类型D（6个）: aclnn文档缺失

影响：接口缺少必要的确定性说明
修复方案：补充aclnn文档

Suggested Fix（修复建议）

修复优先级

高优先级（类型A）: 31个接口文档声称支持但代码不支持
- 需确认是否需要补充代码实现
- 或修改文档为"不支持配置开启"
中优先级（类型B+C）: 7个接口文档与代码矛盾
- 同步 op_api_list 与 aclnn文档
低优先级（类型D）: 6个接口缺少aclnn文档说明
- 补充缺失的确定性说明

具体修复方式

问题类型	修复方式
类型A	1. 补充代码实现 `aclrtGetSysParamOpt(ACL_OPT_DETERMINISTIC)` 2. 或修改文档为"不支持配置开启"
类型B	同步两处文档，确保一致
类型C	如果代码支持配置，文档应改为"支持开启"
类型D	补充aclnn文档的"确定性计算"章节

扫描报告: reports/op-api-list-validation/ops-nn_op_api_list_validation_report_v4_20260508_172319.md
JSON数据: reports/op-api-list-validation/ops-nn_op_api_list_scan_data.json
提交地址: https://gitcode.com/cann/ops-nn/issues/new

StoneChan_成员

5月8日评论：

e8edce413f0b4813a73acc6d2c9bd69c.xlsx

StoneChan_成员

5月9日评论：

dd3742552fcb49a398b091b434a7a67b.xlsx

StoneChan_成员

5月9日修改了issue 的描述

StoneChan_成员

5月9日评论：

确定性问题暂时删除

StoneChan_成员

5月9日修改了issue 的描述

StoneChan_成员

5月9日修改标题为 “[Documentation|文档反馈]: [AI 识别] ops-nn op_api_list.md 文档问题汇总（28个问题项）”，原标题为“[Documentation|文档反馈]: [AI 识别] ops-nn op_api_list.md 文档问题汇总（72个问题项）”