Merged
docs(softshrink,sparse_apply_ftrl): 对齐代码实现修正产品支持与约束说明 #13829
docs(softshrink,sparse_apply_ftrl): 对齐代码实现修正产品支持与约束说明 #13829
Merged
小王!Add on 15 days ago
小王!
小王!Collaborators
15 days ago

描述

本 PR 仅修改资料,不修改算子代码,针对 SparseApplyFtrl 与 SoftShrink 的静态检视资料问题,以当前代码实现(含 canndev A2/A3 TBE 实现)为基准统一文档口径。

SoftShrink

  • 产品支持表:Atlas 200I/500 A2 改为不支持,与 aclnn 文档及无 310b binary_config 的事实一致;补充 A2/A3、Atlas推理/训练由 canndev TBE 承接的说明。
  • 明确 Atlas推理/训练仅支持 FLOAT/FLOAT16,不支持 BFLOAT16;A2/A3 与 950 支持 BFLOAT16。
  • 参数表修正为 input_x/output_y/lambd,lambd 标注为属性、格式改为 -,与 OpDef Attr(lambd).Float(0.5f) 一致。
  • 约束补充:lambd 仅 FLOAT,0/正数/+Inf 合法,负数/NaN 拒绝;输入 x=NaN 时本仓 Ascend C 实现输出 0;空 Tensor、动态 shape、确定性实现。
  • aclnn 文档修正 lambd 标量的数据格式/维度/非连续字段为 -;错误表补充 lambd dtype 非 FLOAT、lambd 为 NaN。
  • 修正 out dtype 说明:实现按 out dtype 进行 Cast,允许与 self 不同,建议保持一致。
  • 调用说明改为模板要求的“调用方式/样例代码/说明”,补充 GE图模式入口。

SparseApplyFtrl

  • 产品支持表:补充 A3/A2、Atlas推理/训练由 canndev TBE 承接;Atlas 200I/500 A2 不支持。
  • 参数表:use_locking 明确为可选属性、默认 false、当前实现不使用。
  • 约束补充:grad 与 var 维数一致;标量支持 0-D 或 shape [1];本仓 Ascend C 要求 var/accum/linear ≥2 维且未显式限制 rank 上限;lr>0/l1,l2≥0/lr_power≤0 为调用方保证、Host 不做值域校验;输出为独立缓冲非原地;仅 ND。
  • 调用说明改为模板要求并链接 GEIR 示例;说明 TF 通路仅注册 SparseApplyFtrl,ResourceSparseApplyFtrl 由 canndev 承接。

关联的Issue

#8371
https://gitcode.com/cann/ops-nn/issues/8371

测试

不涉及

文档更新

  • 更新 SoftShrink 中英文 README 与 aclnn 文档。
  • 更新 SparseApplyFtrl 中英文 README。
  • 明确 A2/A3/推理/训练实现归属、dtype/format/rank 约束与特殊值语义。

类型标签

AI/Agent生成声明

likedislike
Pull Request has been successfully merged by CANN-robot.
(Thank you for 小王!'s contribution.)
小王!小王!Collaborators
15 days ago Created pull request, commit 06da60ee
atomgit-bot
atomgit-bot
15 days ago Comments:

变更摘要

本 PR 为纯文档变更(不涉及任何算子代码、测试或构建脚本),以当前代码实现(含 canndev A2/A3 TBE 实现)为基准,修正并统一 SoftShrink 与 SparseApplyFtrl 两个算子资料中的产品支持范围、参数定义、约束条件和调用说明,中文与英文文档同步更新。

主要改动

  • SoftShrink 产品支持与数据类型范围修正:Atlas 200I/500 A2推理产品 由支持改为不支持(无对应二进制配置),并补充说明 Ascend 950PR/950DT 由本仓 Ascend C 实现提供、Atlas A3/A2 及推理/训练产品由 canndev TBE 承接;明确 Atlas 推理/训练仅支持 FLOAT、FLOAT16,不支持 BFLOAT16。
  • SoftShrink 参数表与 lambd 语义对齐实现:参数名改为 input_x/output_y,lambd 由输入标量改为属性、数据类型限定为 FLOAT、数据格式标注为 - 并给出默认值 0.5 与取值规则;aclnnSoftshrink 文档中该标量的格式、维度、非连续字段改为 -。
  • SparseApplyFtrl 产品支持与 use_locking 说明修正:Atlas推理系列产品、Atlas训练系列产品 由不支持改为支持并注明由 canndev TBE 实现承接;use_locking 明确为可选属性、默认 false、当前实现不使用且不影响更新行为。
  • SparseApplyFtrl 约束说明扩充:新增 grad 与 var 维数一致、标量形态为 0-D 或 shape [1]、本仓 Ascend C 要求 var/accum/linear 至少 2 维且未显式限制 rank 上限、lr>0/l1、l2≥0/lr_power≤0 由调用方保证且 Host 不做值域校验、输出为独立缓冲非原地、仅支持 ND 等条款。
  • 调用说明模板化与错误码补充:两个算子的调用说明改为“调用方式/样例代码/说明”并补充 GE图模式 入口(softshrink_proto.h、test_geir_sparse_apply_ftrl.cpp),aclnnSoftshrink 错误表新增 lambd 数据类型非 FLOAT 及 lambd 为 NaN 两类 ACLNN_ERR_PARAM_INVALID(161002) 场景,并说明 out 的 dtype 可与 self 不同、接口按 out dtype 进行 Cast。

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

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

代码审查

检视结论

按优先级统计

  • P0:0 项
  • P1:0 项
  • P2:1 项(softshrink aclnn 文档声明了当期未实现的 lambd dtype 校验与 161002 错误码)
  • P3:2 项(softshrink README 与 aclnn 文档的 out dtype 口径冲突;sparse_apply_ftrl README 提及不存在的 aclnn 通路)

逐文件检视结果

文件 结果
activation/softshrink/README.md 1 项 P3(:76 输出 dtype 口径与 aclnn 文档矛盾);产品支持表、lambd 属性/FLOAT/默认 0.5、NaN→0、空 Tensor/动态 shape、调用说明链接与锚点(#调用示例、op_graph/softshrink_proto.h、examples/test_aclnn_softshrink.cpp 均存在)已核对一致
activation/softshrink/README_en.md no issues(与中文版同步;#example 锚点有效)
activation/softshrink/docs/aclnnSoftshrink.md 1 项 P2(:101,含 :174/:238 同源);lambd 标量维度/格式/非连续改为 -、错误表 rowspan 4→5 结构正确、Cast 说明与代码一致
activation/softshrink/docs/aclnnSoftshrink_en.md no issues(约束段无重复、无自相矛盾;表格列数与 rowspan 正确)
optim/sparse_apply_ftrl/README.md 1 项 P3(:169 aclnn 通路表述);其余新增约束逐条与代码核对通过:grad 与 var 同 rank(infershape:149-150)、标量 0-D 或 [1] 且 (1,1) 拒绝(infershape:180-186 / tiling:176-182)、Ascend C 要求 var≥2 维且无 rank 上限校验(tiling:83-85)、输出为独立缓冲非原地(simt.h:94-96)、仅 ND 与 FLOAT+INT32/INT64 组合(def.cpp:36-105)、use_locking 可选默认 false 且实现未用(def.cpp:108)、OpDef/构建 ascend950+ascend350(def.cpp:118-119、CMakeLists:13)、TF 插件仅注册 SparseApplyFtrl(framework/sparse_apply_ftrl_tf_plugin.cpp:19)
optim/sparse_apply_ftrl/README_en.md no issues(与中文版约束一一对应;示例链接 examples/test_geir_sparse_apply_ftrl.cpp 存在)

安全与误用检查

6 个文件均为资料文件,未引入 chmod 777、关闭 TLS/鉴权、暴露 0.0.0.0、明文密钥、弱默认口令、远程脚本管道执行、覆盖系统目录或未固定版本依赖等不安全示例;调用示例仍为本地编译运行的 aclnn/GE 代码,无令牌或凭据泄漏风险。

总体风险判断

低风险。变更以“文档对齐实现”为目标,绝大多数新增约束(SparseApplyFtrl 全量约束、softshrink 的 NaN 语义/空 Tensor/动态 shape/产品支持表)已与代码逐一验证一致;主要风险集中在 softshrink 侧两处口径问题:一是把依赖另一个未合入代码 PR 的“lambd 仅 FLOAT + 161002”提前写进文档(本文档单独合入即产生文档/实现不一致),二是 README 与 aclnn 文档对 out dtype 给出互斥约束。建议修完 P2 后再合入,或确认 !13609 与本 PR 同批落地。

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

💬 仅评论


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

likedislike
Incorrect?
CANN-robotCANN-robotCollaborators
15 days ago Added label: cann-cla/yes
CANN-robot
CANN-robotCollaborators
15 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 ✅ 杨露, 钱泽洪, 陈琦, 冯英 (4/2) ✅ 冯英, 杨露 (2/1)
*/*/docs/acl*.md ✅ 杨露, 冯英, 钱泽洪, 陈琦 (4/2) ✅ 杨露, 冯英 (2/1)
activation ✅ 钱泽洪, 陈琦 (2/2) ✅ 钱泽洪 (1/1)
optim ✅ 钱泽洪, 陈琦 (2/2) ✅ 钱泽洪 (1/1)

💡 Tip:

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

CLA Signature Pass

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

likedislike
CANN-robotCANN-robotCollaborators
15 days ago Set zengjuan,u010470851,chenfeng61,chaotang233,kevin_huang1234,crystalhu,yu-xinjie62,yangyang016,fanqirui,gitee-duhuiping,wangrui_,renruhai,su-yueming,zhajianqing123,yourealize,chenqi317,wang-xing001,liubo75,tangweiwei2,gitcode-chenjiao,chenxingyu18,liujie12345678,east_yang,pingchuantang,Chen_HaoWen,qianzehong,fengying555682,caiwenwen,yanglu-1 as approver
6 event messages are collapsed here。 See more
CANN-robotCANN-robotCollaborators
15 days ago Added label: cann-cla/yes
atomgit-bot
atomgit-bot15 days agoStart code review1
activation/softshrink/docs/aclnnSoftshrink.md
@@ -101,3 +101,1 @@
101- <td>ND</td>
102- <td>0-8</td>
103- <td>√</td>
101+ <td>必须为FLOAT标量且数值大于等于0;负数和NaN返回参数非法错误,+Inf合法。</td>
atomgit-bot
atomgit-bot15 days agoComments:

🟡 Medium Priority

变更行:activation/softshrink/docs/aclnnSoftshrink.md:101(“必须为FLOAT标量…负数和NaN返回参数非法错误”)以及配套新增的错误码行 :174(“lambd的数据类型不是FLOAT。”)、约束行 :238,README.md:78 做了同样声明。

证据链:本仓 op_api 的参数校验入口 op_api/aclnn_softshrink.cpp 的 CheckParams(self, lambd, out) 只有 5 步——CheckNotNull、CheckDtypeValid(self, out)、CheckShape(self, out)、CheckLambdValue(lambd)、CheckFormat(self, out);其中 CheckDtypeValid(aclnn_softshrink.cpp:44-63)只对 self/out 做 OP_CHECK_DTYPE_NOT_SUPPORT,CheckLambdValue(:89-98)仅做 !(lambd->ToFloat() >= 0.0f) 值域判断,后续调用是 l0op::SoftShrink(selfContiguous, lambd->ToFloat(), ...)(:151)。即:当前实现接受任意数值类型的 aclScalar(如 DOUBLE/INT32),统一 ToFloat 后继续计算,不会返回 ACLNN_ERR_PARAM_INVALID(161002)。

失败模式:调用方按新文档预期“传 DOUBLE 标量 → 得到 161002”来处理(例如据此做参数兼容判断或断言失败路径),实际拿到的是 ACLNN_SUCCESS + 静默的 DOUBLE→FLOAT 精度截断,问题被延后到精度偏差而非报错;对阈值精度敏感的场景尤其误导。PR 描述也承认该约束依赖尚未合入的代码 PR !13609。

建议:与代码 PR !13609 同步合入该约束;若无法同步,请在本行及 :174、:238 处标注适用版本,或改回“非 FLOAT 会被转换为 FLOAT 参与计算”的当前行为描述。

likedislike
Incorrect?
小王!小王!Collaborators
14 days ago Pre merge succeeded (commit_id: fb67e7d5942150bce4ae56573026b1cc7ad69ce3)
小王!小王!Collaborators
14 days ago Force-pushed 1 commits:d6b9f0dd-docs(softshrink,sparse_apply_ftrl): 对齐代码实现修正产品支持与约束说明
小王!小王!Collaborators
14 days ago Pre merge succeeded (commit_id: 78b75904ab7dc8ac2dd90a5acc320a1465e4e5e5)
CANN-robotCANN-robotCollaborators
14 days ago Removed label: cann-cla/yes
CANN-robotCANN-robotCollaborators
14 days ago Removed label: stat/needs-squash
CANN-robot
CANN-robotCollaborators
14 days ago Comments:

Notification

This pull request has been changed(code update) or closed, so removes the following label(s): stat/needs-squash.

likedislike
CANN-robotCANN-robotCollaborators
14 days ago Added label: cann-cla/yes
小王!
小王!Collaborators
14 days ago Comments:

compile

likedislike
小王!小王!Collaborators
14 days ago Pre merge succeeded (commit_id: e0359bc3f77c52090b71eda7f19cf7462dbf420e)
小王!小王!Collaborators
14 days ago Modify description of pull request
CANN-robot
CANN-robotCollaborators
14 days ago Comments:
🚀 CI 流水线已启动
📋 执行详情: 点击查看流水线
likedislike
CANN-robotCANN-robotCollaborators
14 days ago Added label: ci-pipeline-running
CANN-robotCANN-robotCollaborators
14 days ago Removed label: ci-pipeline-running
CANN-robotCANN-robotCollaborators
14 days ago Added label: ci-pipeline-passed
yuning_chen
yuning_chenCollaborators
14 days ago Comments:
chenqi317
chenqi317Collaborators
14 days ago Comments:

/lgtm

likedislike
小王!小王!Collaborators
12 days ago Modify description of pull request
小王!小王!Collaborators
12 days ago Modify description of pull request
小王!小王!Collaborators
12 days ago Resolved final issue
fengying555682
fengying555682Collaborators
12 days ago Comments:

/lgtm
/approve

likedislike
yanglu-1
yanglu-1Collaborators
12 days ago Comments:

/lgtm
/approve

likedislike
qianzehong
qianzehongCollaborators
12 days ago Comments:

/lgtm
/approve

likedislike
CANN-robotCANN-robotCollaborators
12 days ago Added label: lgtmapproved
CANN-robotCANN-robotCollaborators
12 days ago Closed associated issue
CANN-robotCANN-robotCollaborators
12 days ago Merged pull request
CANN-robot
CANN-robotCollaborators
12 days ago Comments:

Pull Request 已合并或已关闭。

If you want to solve this problem, you can click here to do it in the FAQs.

likedislike