Closed
[Documentation|文档反馈]: softshrink,sparse_apply_ftrl 资料与代码实现不一致,产品支持/约束/调用说明需统一 #8371
小王!Add on  14 days agoClosed at  12 days ago
小王!
小王!Collaborators
14 days ago Create

问题现象

SparseApplyFtrl 与 SoftShrink 的 README / aclnn 资料与当前代码实现不一致,主要包括产品支持范围、参数角色与格式、dtype/rank 约束、特殊值语义和调用说明。

SoftShrink

  • README 将 Atlas 200I/500 A2 标为支持,但 aclnn 文档标不支持,且 softshrink_def.cpp 仅注册 ascend950/ascend350、canndev 无 310b binary_config。
  • README 多产品支持声明未区分本仓 Ascend C 实现与 canndev TBE 实现;Atlas推理/训练不支持 BF16 的限制未在 README 说明。
  • README 参数表使用 x/y,lambd 标成“输入”、格式写成 1;OpDef 实际为 Input(input_x)、Output(output_y)、Attr(lambd).Float(0.5f)。
  • aclnn 文档给标量 lambd(aclScalar*) 填了 ND / 0-8 / 非连续√,但标量没有布局、维度和 stride 语义。
  • 资料未说明 lambd 为 NaN 时会被拒绝、+Inf 合法,以及输入 x=NaN 时本仓 Ascend C 实现输出 0(不做 NaN 透传)。
  • aclnn 错误表只写 lambd < 0,未覆盖 NaN。
  • README 调用说明列名/术语不符合模板,且未列出已交付的 GEIR 图模式入口。

SparseApplyFtrl

  • README 产品支持表未说明 A3/A2、Atlas推理/训练由 canndev TBE 承接;Atlas 200I/500 A2 无 binary_config。
  • use_locking 未说明为可选属性、默认 false、当前实现不使用。
  • 标量输入资料写 0-D,实际 InferShape 接受 0-D 或 shape [1],并允许动态 -1/-2、拒绝 (1,1)。
  • 未明确 grad 与 var 维数一致、var/accum/linear 至少 2 维、本仓未显式校验 rank 上限、A2/A3 canndev 路径允许 1-D var 的兼容性差异。
  • 未明确 lr>0、l1/l2>=0、lr_power<=0 为调用方保证,Host/Tiling 不读取设备侧标量值、不做运行时值域校验。
  • 未明确输出 var/accum/linear 为独立输出缓冲、非原地;当前 binary_config 仅支持 FLOAT+INT32/INT64、ND。
  • README 调用说明样例为空的 <a>-</a>,未链接已存在的 GEIR 示例;未说明 TF 通路仅注册 SparseApplyFtrl,ResourceSparseApplyFtrl 由 canndev 承接。

A2/A3 兼容性

  • SoftShrink:ascend910_93(A3)、ascend910b(A2)的 canndev binary_config 支持 FP16/FP32/BF16、ND;ascend310p/ascend910 仅 FP16/FP32。
  • SparseApplyFtrl:ascend910_93、ascend910b、ascend310p、ascend910 的 canndev binary_config 支持 FLOAT + INT32/INT64、ND。
  • 当前 ops-nn Ascend C 实现只注册/构建 ascend950/ascend350,资料需注明实现归属,避免把 A2/A3 误认为本仓 Ascend C 直接构建。

影响

用户按资料选型或构造输入时可能得到与实现相反的产品支持结论、错误的参数角色/格式、错误的 dtype/rank 约束,或对 NaN/+Inf/非原地输出产生错误预期。

修复

仅修改资料,不修改代码,PR:

修改范围:

  • activation/softshrink/README.md
  • activation/softshrink/README_en.md
  • activation/softshrink/docs/aclnnSoftshrink.md
  • activation/softshrink/docs/aclnnSoftshrink_en.md
  • optim/sparse_apply_ftrl/README.md
  • optim/sparse_apply_ftrl/README_en.md

验证

  • git diff --check 通过。
  • pre-commit run --files <6 个资料文件> 全部通过(trailing-whitespace、end-of-file-fixer、codespell、OAT 等)。
  • 无源码、测试、构建脚本改动;未上板验证。
likedislike
yuning_chenyuning_chenCollaborators
14 days ago Assign qq_52056150 as responsible person
CANN-robotCANN-robotCollaborators
12 days ago Close issue
CANN-robotCANN-robotCollaborators
12 days ago changed custom state from 待办的 to 已完成
CANN-robotCANN-robotCollaborators
12 days ago Added label: resolved
chenjiayi_chenjiayi_Collaborators
2 days ago changed custom category from 任务 to 文档
chenjiayi_chenjiayi_Collaborators
2 days ago Change title to "[Documentation|文档反馈]: softshrink,sparse_apply_ftrl 资料与代码实现不一致,产品支持/约束/调用说明需统一", originally titled "docs(softshrink,sparse_apply_ftrl): 资料与代码实现不一致,产品支持/约束/调用说明需统一".
chenjiayi_chenjiayi_Collaborators
2 days ago Added label: documentation