Closed
修复 ops-nn QUICKSTART.md 文档扫描问题(11处) #14310
liujing987913Add on 9 days agoClosed at 9 days ago
修复 ops-nn QUICKSTART.md 文档扫描问题(11处) #14310
Closed
liujing987913Add on 9 days agoClosed at 9 days ago
liujing987913
liujing987913Collaborators
9 days ago

描述

  • 背景:AIDD/文档质量扫描发现 ops-nn 仓 docs/QUICKSTART.md 文档问题 11 处
  • 修改分类:代码块语言标签 1、参数名/括号 1、行内代码标记 1、引导句标点 3、漏字 1、术语大小写 3(Kernel/Tensor/Host+Vector)
  • 涉及文件:docs/QUICKSTART.md(1 个文件,11 处)
  • 验证:git diff 确认为纯文本修改,无代码内容误改;已人工核对

关联的Issue

https://gitcode.com/cann/ops-nn/issues/8705

测试

文档更新

本次 PR 更新 ops-nn docs/QUICKSTART.md,修正标点/术语/行内代码格式问题 11 处,详见 diff。

类型标签

  • 文档更新
likedislike
The current Pull Request has been closed by liujing987913.
liujing987913liujing987913Collaborators
9 days ago Created pull request, commit 7ab511c9
liujing987913liujing987913Collaborators
9 days ago Associated issue: [Documentation|文档反馈]: 修复 ops-nn QUICKSTART.md 文档扫描问题(11处)
atomgit-bot
atomgit-bot
9 days ago Comments:

变更摘要

本 PR 主要针对文档质量扫描发现的问题,对 ops-nn 仓库的多份算子接口文档进行修正,涉及 docs/QUICKSTART.md、matmul/flat_quant 与 matmul/matmul_compress 的 aclnn 接口文档,以及 quant/trans_quant_param 下的 aclnnTransQuantParam.md。改动内容包括标点与引导句、术语大小写(Kernel/Tensor/Host/Vector)、行内代码标记、代码块语言标签等格式类修正;同时 aclnnFlatQuantV3 的参数命名由 groupListOptional 统一为 groupList 并删去 nullptr 场景的冗余说明,aclnnTransQuantParam 的功能说明、参数表、返回码表、约束说明与调用示例被整体重写。

主要改动

  • aclnnTransQuantParam 接口文档整体重写: 功能说明由按 scaleSize/offsetSize 取最大值并按 16 元素对齐申请数组的描述,改为按 scale 高位截取、置 bit46、再按 offset 饱和到 [-256,255] 写入 bit37~45 的位运算公式;参数表中 scaleArray、offsetArray 等描述同步简化,错误码表按 rowspan 拆分逐条列出触发条件,约束说明仅保留确定性计算条目。
  • aclnnTransQuantParam 调用示例改写: 示例代码改用 acl/acl.h、CHECK_RET/LOG_PRINT 宏与 ACL_SUCCESS 判断,并移除原有的 std::cout、std::cerr 输出与注释说明,free(result) 保留。
  • aclnnFlatQuantV3 量化分组参数更名: 文档中将 groupListOptional 统一改称 groupList,并删除「groupListOptional 为 nullptr 时 groupListType 可传任意值」的说明,影响差异说明、参数表、错误码表和约束说明。
  • aclnnMatmulCompress 输出参数说明补充: out 参数的数据类型列由 - 改为「通过示例中的 msModelSlim 工具获取」。
  • docs/QUICKSTART.md 与 flat_quant 文档格式修正: docs/QUICKSTART.md 修正引导句冒号、输出代码块语言标签由 bash 改为 output、AddExample 路径的三反引号改为单反引号、--vendor_name(可选) 括号与参数名说明,以及 Kernel/Tensor/Host/Vector 等术语大小写;flat_quant 文档在相关列表项前补充零宽空格等细节调整。

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

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

代码审查

审查结论

各文件审查情况

文件 结论
docs/QUICKSTART.md 已逐条审查(引号/冒号/行内代码/术语大小写/```output 标签、vendor_name 参数名);未引入不安全命令或误导性操作(--force 处既有风险提示保留),无问题
matmul/flat_quant/docs/aclnnFlatQuantV2.md 有问题 1 处(P3,不可见零宽空格)
matmul/flat_quant/docs/aclnnFlatQuantV3.md 有问题 2 处(P2 参数名一致性、P3 零宽空格)
matmul/matmul_compress/docs/aclnnMatmulCompress.md 有问题 1 处(P2 输出参数说明填错)
quant/trans_quant_param/docs/aclnnTransQuantParam.md 有问题 6 处(P2×3、P3×3,集中在文档被整体重写后丢失的接口契约)

问题统计

  • P0:0
  • P1:0
  • P2:5(输出 Tensor 使用说明错位、groupList 改名造成同文档参数名分裂、quantParamSize 说明写反、quantParam 内存所有权契约丢失、offsetArray 可选调用约定丢失)
  • P3:5(const float*/float* 不一致、编码公式缺位重解释且掩码结论反转、示例缺 <cstdlib>/<cstdint>、两份 flat_quant 文档各插入零宽空格)

整体风险判断

QUICKSTART.md 的 11 处文本修正确实属于低风险且改动正确。但本 PR 的实际改动范围明显大于标题所述:aclnnTransQuantParam.md 被近乎整篇重写(+172/−175),在"润色"过程中删掉了输出长度 P(16 元素对齐补齐)计算、quantParam 的 calloc/free 所有权、offsetArray 的 nullptr 调用约定与非广播语义等接口契约条款,同时新写的输出参数说明存在反向表述;aclnnFlatQuantV3.md 把 groupListOptional 单边改名成签名中并不存在的 groupList;aclnnMatmulCompress.md 把工具说明张冠李戴到输出 Tensor 上。这些均会直接误导调用方(错误的输出长度推算、非法 free/内存泄漏、161002 误触发),建议按上述 5 个 P2 修正后再合入;P3 项可一并清理(尤其零宽空格与文档扫描目标直接冲突)。

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

💬 仅评论


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

likedislike
Incorrect?
CANN-robotCANN-robotCollaborators
9 days ago Added label: stat/needs-squash
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

⚠️ This PR does not yet meet the following requirements:lgtm (requires ≥ 2 person(s) per module)、approve (requires ≥ 1 person(s) per module)

Module Approval Details

module lgtm status approve status
*/*/docs/acl*.md ❌ (0/2)(You can also ask: 冯英, 蔡雯雯, 陈律丞, 刘晓芳, 陈展熹) ❌ (0/1)(You can also ask: 杨露, 刘晓芳, 陈娇, 杜慧萍, 冯英)
docs ❌ (0/2)(You can also ask: 范其瑞, 刘波, 刘晓芳, 陈娇, 汤平川) ❌ (0/1)(You can also ask: 刘晓芳, 陈娇, 杜慧萍, 冯英, 蔡雯雯)

💡 Tip:

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

CLA Signature Pass

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

likedislike
CANN-robotCANN-robotCollaborators
9 days ago Set zengjuan,u010470851,smdbha,oscillated,sxb154714,chenfeng61,chaotang233,crystalhu,yangyang016,fanqirui,gitee-duhuiping,su-yueming,zhajianqing123,yourealize,chenqi317,LinPX,wang-xing001,liubo75,tangweiwei2,wangzitao_leo,void_ptr,xubinglin,zhaoyingchao2,gitcode-chenjiao,liujie12345678,rueenov11,lwx1255555,pingchuantang,Chen_HaoWen,qianzehong,fengying555682,liuyang_806,caiwenwen,yanglu-1 as approver
CANN-robotCANN-robotCollaborators
9 days ago Set gitee-duhuiping,gitcode-chenjiao,lwx1255555,fengying555682,caiwenwen,yanglu-1 as approver
liujing987913
liujing987913Collaborators
9 days ago Comments:

compile

likedislike
liujing987913liujing987913Collaborators
9 days ago Pre merge succeeded (commit_id: 3b37745093c7124fae0dd4c57c3e5f7d012f3568)
CANN-robot
CANN-robotCollaborators
9 days ago Comments:
🚀 CI 流水线已启动
📋 执行详情: 点击查看流水线
likedislike
CANN-robotCANN-robotCollaborators
9 days ago Added label: ci-pipeline-running
atomgit-bot
atomgit-bot9 days agoStart code review1
quant/trans_quant_param/docs/aclnnTransQuantParam.md
@@ -164,0 +129,4 @@
129+ <td>quantParam(uint64_t**)</td>
130+ <td>输出</td>
131+ <td>表示指向存储转换得到的quantParam数据的内存地址,对应公式中的`out`。</td>
132+ <td>-</td>
atomgit-bot
atomgit-bot9 days agoComments:

🟡 Medium Priority

改动行(132):quantParam(uint64_t**) 的"使用说明"由两条明确契约改为 -:

  • "传入一个uint64_t*变量的地址,无需预先申请输出数组";

证据链:改动后的调用示例(231-238 行)仍是 uint64_t* result = nullptr; 传 &result,并在末尾 free(result);但文档里已没有任何一句说明这块内存由接口分配、由调用者释放。

失效模式:

  1. 调用者可能自行 malloc 一段 Host 内存并把地址传给 quantParam,接口内部再覆盖写入 calloc 得到的新指针,导致调用者自己的内存泄漏;
  2. 调用者不知道需要 free,每次调用泄漏一块 Host 内存;
  3. 与示例 free(result) 形成"文档未说、示例在做"的矛盾,若某条出错路径下指针并非由接口分配,free 即非法。

建议:不要清空 quantParam 的使用说明:恢复"无需预先申请输出数组,接口申请 Host 内存并写入 *quantParam,调用者使用后须 free"的所有权说明,并补充申请失败时 *quantParam 的取值,使其与调用示例中的 free(result) 一致。

likedislike
Incorrect?
atomgit-bot
atomgit-bot9 days agoStart code review1
quant/trans_quant_param/docs/aclnnTransQuantParam.md
@@ -164,0 +139,4 @@
139+ <td>quantParamSize(uint64_t*)</td>
140+ <td>输出</td>
141+ <td>表示存储quantParam数据的数量。</td>
142+ <td>需要自行保证`quantParamSize`与`quantParam`包含的元素个数相同。</td>
atomgit-bot
atomgit-bot9 days agoComments:

🟡 Medium Priority

改动行(142):quantParamSize(uint64_t*) 的使用说明由"由接口写回,包含补齐元素;计数单位为元素,不是字节"改为"需要自行保证quantParamSize与quantParam包含的元素个数相同"。

证据链:139-141 行明确 quantParamSize 是输出参数(<td>输出</td>,描述为"存储quantParam数据的数量"),131 行 quantParam 也是输出参数(uint64_t**)。输出参数由接口写回,调用者不可能、也不需要"自行保证"两者元素个数相同;而且 quantParamSize 是单个 uint64_t 计数变量,本身并不"包含元素",无从比较元素个数。

同时,本次改动(28-48 行)完全删除了原"功能说明"中输出元素数 PP 的计算公式(P=1P=1 或 16⌈L/16⌉16\lceil L/16\rceil)与"包含补齐元素、计数单位为元素"的说明,并把原"约束说明"中关于补齐、长度对齐的条目一并删除,导致 quantParamSize 到底等于多少(是否含 16 元素对齐补齐)在整篇文档中已无处可查;而调用示例(233-237 行)仍按 resultSize 遍历访问 result。

失效模式:调用者按新文档理解会预先给 resultSize 赋值或按 scaleSize/offsetSize 自行推算长度,实际接口写回的是含补齐的长度(多为 16 的整数倍),按推算值遍历会漏读或误判输出规模。

建议:输出参数的使用说明不应写成"由用户自行保证":改为"由接口写回,表示 quantParam 数组的元素个数(含补齐元素,计数单位为元素)",并补回输出元素数 P 的计算公式,避免调用者自行推算长度。

likedislike
Incorrect?
atomgit-bot
atomgit-bot9 days agoStart code review1
matmul/matmul_compress/docs/aclnnMatmulCompress.md
@@ -129,3 +129,3 @@
129- <td>-</td>
129+ <td>通过示例中的msModelSlim工具获取</td>
130130 <td>FLOAT16</td>
131131 <td>ND</td>
atomgit-bot
atomgit-bot9 days agoComments:

🟡 Medium Priority

改动行(129):把 out(126 行 <td>out</td>、127 行 <td>输出</td>、128 行 <td>输出Tensor。</td>)的"使用说明"列由 - 改为"通过示例中的msModelSlim工具获取"。

证据链:本文档 26/34 行明确说明 msModelSlim 的作用是压缩右矩阵 r,产出压缩后的 x2、compressIndex 等输入(299-301 行示例第 2 步也只对输入侧做预处理);out 是本接口的输出Tensor,由算子内部解压+矩阵乘+反量化生成,调用者在进入接口前必须已经创建该输出 Tensor(由 GetWorkspaceSize 创建 aclTensor),不可能"从工具获取"。

失效模式:调用者按文档理解会以为 out 需要先从 msModelSlim 取得数据再传入,从而构造/填充错误的输出 Tensor,或误以为输出内存由工具提供;与 119 行同一条文案(compressIndex 属于输入,填此说明合理)被机械复制到输出行,属于错位修改。

建议:把 out 行的"使用说明"恢复为空占位 -,或改写为输出 Tensor 的创建/shape 约束说明;不要把 msModelSlim 工具说明套在输出参数上。

Suggestions
131
- <td>ND</td>
131
+ <td>-</td>
Apply suggestion
likedislike
Incorrect?
atomgit-bot
atomgit-bot9 days agoStart code review1
matmul/flat_quant/docs/aclnnFlatQuantV3.md
@@ -259,2 +259,2 @@
259- <td>代表groupListOptional输入的分组方式。</td>
260- <td><ul><li>当groupListOptional不为nullptr时支持取值0,1,2。当groupListOptional为nullptr时groupListType可以传任意值不影响计算结果。</li></ul></td>
259+ <td>代表groupList输入的分组方式。</td>
260+ <td><ul><li>当groupListOptional不为nullptr时支持取值0,1,2。</li></ul></td>
atomgit-bot
atomgit-bot9 days agoComments:

🟡 Medium Priority

改动行(27、259、369):把 groupListOptional 改成了 groupList。

证据链:本文件的函数原型(153 行 const aclTensor *groupListOptional)、参数表参数名(227 行 <td>groupListOptional(aclTensor*)</td>)、约束说明(418-431 行全部为 groupListOptional)都仍使用 groupListOptional。改动只在 27 行差异说明、259 行描述、369 行错误码描述三处做了单边改名。

更直接的矛盾在同一张表的同一行:257-260 行 groupListType 行的"描述"列改成"代表groupList输入的分组方式",而紧邻的"使用说明"列(260 行)仍写"当groupListOptional不为nullptr时支持取值0,1,2"——同一个表格行内出现两个不同的参数名。

失效模式:接口签名中不存在名为 groupList 的参数,读者按 259/369 行的名字对照原型与头文件找不到对应入参,排查 161002 报错(369 行)时无法定位到实际形参;同时文档最关键的"参数名—约束—错误"对应关系被破坏。

建议:将 27、259、369 行恢复为 groupListOptional,与函数原型(153 行)、参数表(227 行)、约束说明(418-431 行)保持一致;若要改名则需同步全部出现位置与头文件。

likedislike
Incorrect?
atomgit-bot
atomgit-bot9 days agoStart code review1
quant/trans_quant_param/docs/aclnnTransQuantParam.md
@@ -164,0 +109,4 @@
109+ <td>offsetArray(float*)</td>
110+ <td>输入</td>
111+ <td>表示指向存储offset数据的内存,对应公式中的`offset`。</td>
112+ <td>需要保证offset数据中不存在NaN和inf。</td>
atomgit-bot
atomgit-bot9 days agoComments:

🟡 Medium Priority

改动行(109-112):offsetArray 的"输入/输出"列由"可选输入"改为"输入","使用说明"由"不使用时传入nullptr,并将offsetSize设为0,输出中的offset位域保持为0 / 提供时须连续存放 offsetSize 个 float"改为"需要保证offset数据中不存在NaN和inf"。

证据链:功能说明 35-36 行仍写"若offset不存在,不再进行后续计算",错误码表 187-190 行仍把"offsetArray不为空指针但offsetSize < 1"和"offsetArray为空指针但offsetSize不等于0"作为 161002,说明该参数确实可选、且存在严格的 nullptr + offsetSize=0 调用约定;但参数表已不再说明如何表达"不提供 offset"。

失效模式:调用者只想要纯 scale 编码时,文档没有告诉他传 nullptr 且 offsetSize=0,很容易保留旧的 offsetSize(或传 nullptr 但 offsetSize 非 0),直接触发 161002;也可能误以为必须准备一段 offset 数据。此外原约束"两个数组长度可以不同、不进行广播(如 scaleSize=3、offsetSize=1 时只有第 0 个输出包含 offset)"也被一并删除,调用者可能按广播理解而传错长度。

建议:把 offsetArray 标回"可选输入",并在使用说明中恢复"不使用 offset 时传 nullptr 且 offsetSize 为 0",同时恢复"scaleSize 与 offsetSize 可不同、不广播"的语义说明。

likedislike
Incorrect?
CANN-robotCANN-robotCollaborators
9 days ago Removed label: ci-pipeline-running
CANN-robotCANN-robotCollaborators
9 days ago Added label: ci-pipeline-passed
liujing987913liujing987913Collaborators
9 days ago Close pull request
yuning_chen
yuning_chenCollaborators
9 days ago Comments:

您好,pr合入已准备就绪,请尽快联系committer进行检视,谢谢!
@fengying555682 @caiwenwen @oscillated @lwx1255555 @yourealize @yanglu-1 @gitcode-chenjiao @gitee-duhuiping @fanqirui @liubo75 @pingchuantang

likedislike