Merged
docs_fix #14323
佐助大王Add on 9 days ago
docs_fix #14323
Merged
佐助大王Add on 9 days ago
佐助大王
佐助大王Collaborators
9 days ago

描述

本 PR 修复若干资料问题,涵盖接口约束描述纠偏、参数语义澄清、公式勘误与 Markdown 排版修复,中英文资料同步修改。

1. aclnnL1Loss int64 输入约束补全(loss/lp_loss,中英文)

原约束仅笼统表述“out为int64数据类型时仅reduction=2可用”,未说明 self/target 的 dtype 组合规则。现按接口实现(CheckDtypeValid)补充完整组合约束(不满足时返回161002):

  • reduction=0(none):双int64可用;self为int64且target为浮点时报错;self为浮点且target为int64时可用(提升为浮点计算);
  • reduction=1(mean):双int64时报错;一侧浮点一侧int64时可用(提升为浮点计算);
  • reduction=2(sum):含int64的任意组合均可用,双int64走整数路径,单侧提升为浮点计算。

2. aclnnNLLLossBackward / aclnnNLLLoss2dBackward totalWeight 参数语义澄清(loss/nll_loss_grad,中英文)

原文描述“totalWeight通过target取相应位置的weight……求和”,易被误解为算子内部计算该参数。实际 totalWeight 为输入参数:reduction为mean时由调用方传入按 target、weight 和 ignoreIndex 计算得到的权重和;其他 reduction 下不参与计算。中英文参数表同步更正。

3. fused_adamw 公式勘误(optim/fused_adamw,中英文)

参数更新公式中解耦权重衰减项误写为 θ_{t-1},更正为 θ_t,与 AdamW 解耦权重衰减(decoupled weight decay)标准公式一致。

4. aclnnMseLossGrad Markdown 排版修复(experimental/loss/mse_loss_grad)

aclnnMseLossGradGetWorkspaceSize 函数签名的代码块缺少闭合 ```,导致后续代码块渲染异常,补齐闭合符。

关联的Issue

#7165
#7707
#8204
#8473

测试

  • 仅资料(.md)修改,不涉及算子代码与执行逻辑,本地无需编译/UT验证;
  • 已核对上述约束表述与 op_api 接口实现(aclnnL1Loss 的 CheckDtypeValid、NLLLoss 系列参数校验)及 AdamW 标准公式一致;
  • 中英文资料逐条对照,语义一致。

文档更新

  • loss/lp_loss/docs/aclnnL1Loss.md、aclnnL1Loss_en.md
  • loss/nll_loss_grad/docs/aclnnNLLLossBackward.md、aclnnNLLLossBackward_en.md、aclnnNLLLoss2dBackward.md、aclnnNLLLoss2dBackward_en.md
  • optim/fused_adamw/README.md、README_en.md
  • experimental/loss/mse_loss_grad/docs/aclnnMseLossGrad.md

类型标签

AI/Agent生成声明

likedislike
Pull Request has been successfully merged by CANN-robot.
(Thank you for 佐助大王's contribution.)
佐助大王佐助大王Collaborators
9 days ago Created pull request, commit 48508d81
atomgit-bot
atomgit-bot
9 days ago Comments:

变更摘要

本 PR 修正若干资料问题,只涉及 .md 文档,涵盖接口约束描述、参数语义、公式和 Markdown 排版,中英文文档同步更新。包括:aclnnL1Loss 补充 int64 输入的 dtype 组合约束;aclnnNLLLossBackward / aclnnNLLLoss2dBackward 澄清 totalWeight 是调用方输入的参数;fused_adamw 更正解耦权重衰减公式中的参数下标;aclnnMseLossGrad 补齐代码块闭合符。

主要改动

  • aclnnL1Loss 补全 int64 dtype 组合约束:将原先只说明“out为int64时仅 reduction=2 可用”的笼统表述,替换为按 reduction=0/1/2 分列 self/target 的 int64 与浮点组合规则,并注明不满足时返回 161002;中英文文档同步。
  • totalWeight 参数语义澄清:在 aclnnNLLLossBackward 与 aclnnNLLLoss2dBackward 的中英文参数表中,将“由算子通过 target 取 weight 并求和”的表述改为“totalWeight 是输入,reduction 为 mean 时由调用方传入按 target、weight 和 ignoreIndex 计算得到的权重和,其他 reduction 下不参与计算”。
  • fused_adamw 更新公式勘误:中文与英文 README 的参数更新公式中,解耦权重衰减项由 \theta_{t-1} 更正为 \theta_{t},与 AdamW 解耦权重衰减标准形式一致。
  • aclnnMseLossGrad 排版修复:在 aclnnMseLossGradGetWorkspaceSize 函数签名的代码块后补加闭合的 ```,修复后续代码块渲染异常。

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

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

代码审查

审查结论

发现的问题(按优先级)

优先级 数量 位置
P0 / P1 0 —
P2 1 optim/fused_adamw/README.md:47(同一问题同样存在于 README_en.md:49)
P3 0 —

P2 — fused_adamw 公式单边修复导致跨文件不一致
本次改动把 README(中/英)参数更新公式中的解耦衰减项由 θ_{t-1} 改为 θ_t,与 kernel 实现一致(op_kernel/fused_adamw_kernel.h:221-226 / 347-352 先对当前参数执行 param *= 1 - lr*weightDecay,再 param -= step_size*m̂/(√v̂+eps)),修正方向正确。但同一算子的接口文档 docs/aclnnFusedAdamw.md:51、docs/aclnnFusedAdamw_en.md:53 仍是旧的 θ_{t-1},修复后同一算子出现两份互相矛盾的公式,按接口文档实现的用户会得到与 kernel 语义不同的更新式。

逐文件核对结果

文件 结论
experimental/loss/mse_loss_grad/docs/aclnnMseLossGrad.md no issues — 补齐的闭合 ``` 正确对应第 31 行开启的代码块,后续代码块渲染恢复正常;该目录仅有中文文档,无英文版本需同步
loss/lp_loss/docs/aclnnL1Loss.md no issues — 新增三条 int64 dtype 组合约束与 op_api/aclnn_l1_loss.cpp:64-105 的 CheckDtypeValid 分支逐条对应(none: !IsFloating(self)&&IsFloating(target) 报错;mean: 双非浮点报错),161002 与该文档错码表一致;被删除的“out 为 int64 仅 reduction=2 可用”在实现中并无对应校验(none + 双 int64 实际可用),属勘误而非信息丢失
loss/lp_loss/docs/aclnnL1Loss_en.md no issues — 与中文版三条约束语义一致,未引入与参数表/错码表的冲突
loss/nll_loss_grad/docs/aclnnNLLLoss2dBackward.md no issues — totalWeight 确实为输入张量,实现直接 Cast 后传入 NLLLossGrad(op_api/aclnn_nll_loss2d_backward.cpp:229-261),仅 mean 参与除法,描述与实现吻合;null/dtype/shape 校验仍在该文档错码表中列出
loss/nll_loss_grad/docs/aclnnNLLLoss2dBackward_en.md no issues — 与中文版同义,未与错码表冲突
loss/nll_loss_grad/docs/aclnnNLLLossBackward.md no issues — 同上,op_api/aclnn_nll_loss_backward.cpp:133-136, 253-261 印证 totalWeight 为外部传入输入
loss/nll_loss_grad/docs/aclnnNLLLossBackward_en.md no issues — 与中文版一致
optim/fused_adamw/README.md 1 处 P2(见上,需同步 docs/aclnnFusedAdamw.md)
optim/fused_adamw/README_en.md 同一根因,合并计入上述 P2(docs/aclnnFusedAdamw_en.md:53 需同步)

总体风险判断

本次仅为资料修改,不触及算子代码、接口签名与执行逻辑,无安全/性能/构建面风险。唯一实质问题是 fused_adamw 公式勘误只改了 README 而遗漏接口文档(中英各一处),会留下同仓库两份矛盾公式,建议合入前补齐两处 θ_{t-1} → θ_t。其余 6 处文档改动表述准确、与实现及既有错码表自洽。

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

💬 仅评论


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

likedislike
Incorrect?
CANN-robotCANN-robotCollaborators
9 days ago Added label: cann-cla/yes
CANN-robot
CANN-robotCollaborators
9 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 ✅ 杨东, 杨露, 於欣洁 (3/2) ✅ 杨露 (1/1)
*/*/docs/acl*.md ✅ 杨露, 杨东, 於欣洁 (3/2) ✅ 杨露 (1/1)
experimental ✅ 杨东, 於欣洁, 王子韬 (3/2) ✅ 杨东, 於欣洁 (2/1)
optim ✅ 於欣洁, 杨东 (2/2) ✅ 於欣洁, 杨东 (2/1)

💡 Tip:

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

CLA Signature Pass

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

likedislike
CANN-robotCANN-robotCollaborators
9 days ago Set zengjuan,u010470851,chenfeng61,chaotang233,crystalhu,yu-xinjie62,yangyang016,fanqirui,gitee-duhuiping,su-yueming,yourealize,chenqi317,wang-xing001,liubo75,tangweiwei2,gitcode-chenjiao,east_yang,lwx1255555,pingchuantang,qianzehong,fengying555682,caiwenwen,yanglu-1 as approver
10 event messages are collapsed here。 See more
佐助大王佐助大王Collaborators
9 days ago Modify description of pull request
佐助大王
佐助大王Collaborators
9 days ago Comments:

compile

likedislike
佐助大王佐助大王Collaborators
9 days ago Pre merge succeeded (commit_id: f3539ab786deddb232eeab741f7df37732cc9b0a)
CANN-robot
CANN-robotCollaborators
9 days ago Comments:
🚀 CI 流水线已启动
📋 执行详情: 点击查看流水线
likedislike
atomgit-bot
atomgit-bot9 days agoStart code review2
optim/fused_adamw/README.md
@@ -45,3 +45,3 @@
4545 
4646 $$
47- \theta_{t+1}=\theta_{t}-\frac{\eta}{\sqrt{\hat{v}_{t}}+\epsilon} \hat{m}_{t}-\eta \cdot \lambda \cdot \theta_{t-1}
47+ \theta_{t+1}=\theta_{t}-\frac{\eta}{\sqrt{\hat{v}_{t}}+\epsilon} \hat{m}_{t}-\eta \cdot \lambda \cdot \theta_{t}
atomgit-bot
atomgit-bot9 days agoComments:

🟡 Medium Priority

证据链:

  1. 本次改动行 optim/fused_adamw/README.md:47(及 README_en.md:49)把参数更新公式的解耦权重衰减项由 \theta_{t-1} 改为 \theta_{t},与实现一致——op_kernel/fused_adamw_kernel.h:221-226 与 347-352 先执行 decayFactor = 1.0f - lr * weightDecay; Muls(param, param, decayFactor)(即对当前参数 θ_t 做衰减),再在 Step 8 中 Sub(param, param, step_size*m̂/(√v̂+eps)),所以 θ_{t+1} = θ_t - ηλθ_t - ... 的写法是正确的。
  2. 但同一操作符的接口文档 optim/fused_adamw/docs/aclnnFusedAdamw.md:51 与 optim/fused_adamw/docs/aclnnFusedAdamw_en.md:53 仍是旧写法 ... - \eta \cdot \lambda \cdot \theta_{t-1},本次未同步修改。
  3. 失效模式:修复后仓库内对同一算子给出两份互相矛盾的更新公式;用户按接口文档(aclnnFusedAdamw.md)自行实现或对照实现时,会把权重衰减作用于 θ_{t-1},得到与 kernel 不一致的迭代结果,且后续无法判断哪份文档为准。属于本次单边修改新引入的跨文件不一致(README 已改、接口文档未改)。

建议:在同一个 PR 中同步把 optim/fused_adamw/docs/aclnnFusedAdamw.md:51 与 optim/fused_adamw/docs/aclnnFusedAdamw_en.md:53 的 \eta \cdot \lambda \cdot \theta_{t-1} 改为 \eta \cdot \lambda \cdot \theta_{t},保持 README 与接口文档公式一致;若确认 kernel 行为如此,最好再补一句说明衰减作用于更新前的当前参数 θ_t(decayFactor = 1 - lr*weightDecay)。

likedislike
Incorrect?
佐助大王
佐助大王Collaborators
9 days ago Comments:

是将本次梯度更新到下次梯度

likedislike
CANN-robotCANN-robotCollaborators
9 days ago Added label: ci-pipeline-running
CANN-robotCANN-robotCollaborators
9 days ago Removed label: ci-pipeline-running
CANN-robotCANN-robotCollaborators
9 days ago Added label: ci-pipeline-passed
佐助大王佐助大王Collaborators
9 days ago Resolved final issue
yanglu-1
yanglu-1Collaborators
9 days ago Comments:

/approve
/lgtm

likedislike
yuning_chen
yuning_chenCollaborators
9 days ago Comments:
wangzitao
wangzitaoCollaborators
9 days ago Comments:

/lgtm
by agent

likedislike
於欣洁
於欣洁Collaborators
9 days ago Comments:

/lgtm
/approve

likedislike
CANN-robotCANN-robotCollaborators
9 days ago Added label: approved
east_yang
east_yangCollaborators
9 days ago Comments:

/lgtm
/approve

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

Pull Request 已合并或已关闭。

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

likedislike