The current Pull Request has been closed by liujing987913.
变更摘要
本 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:


代码审查
审查结论
各文件审查情况
| 文件 | 结论 |
|---|---|
| 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:


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
/approveor/lgtm- Commenting
/approveimplies 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. 👍


compile


| 🚀 CI 流水线已启动 |
|---|
| 📋 执行详情: 点击查看流水线 |


🟡 Medium Priority
改动行(132):quantParam(uint64_t**) 的"使用说明"由两条明确契约改为 -:
- "传入一个uint64_t*变量的地址,无需预先申请输出数组";
证据链:改动后的调用示例(231-238 行)仍是 uint64_t* result = nullptr; 传 &result,并在末尾 free(result);但文档里已没有任何一句说明这块内存由接口分配、由调用者释放。
失效模式:
- 调用者可能自行 malloc 一段 Host 内存并把地址传给
quantParam,接口内部再覆盖写入 calloc 得到的新指针,导致调用者自己的内存泄漏; - 调用者不知道需要 free,每次调用泄漏一块 Host 内存;
- 与示例
free(result)形成"文档未说、示例在做"的矛盾,若某条出错路径下指针并非由接口分配,free 即非法。
建议:不要清空 quantParam 的使用说明:恢复"无需预先申请输出数组,接口申请 Host 内存并写入 *quantParam,调用者使用后须 free"的所有权说明,并补充申请失败时 *quantParam 的取值,使其与调用示例中的 free(result) 一致。


🟡 Medium Priority
改动行(142):quantParamSize(uint64_t*) 的使用说明由"由接口写回,包含补齐元素;计数单位为元素,不是字节"改为"需要自行保证quantParamSize与quantParam包含的元素个数相同"。
证据链:139-141 行明确 quantParamSize 是输出参数(<td>输出</td>,描述为"存储quantParam数据的数量"),131 行 quantParam 也是输出参数(uint64_t**)。输出参数由接口写回,调用者不可能、也不需要"自行保证"两者元素个数相同;而且 quantParamSize 是单个 uint64_t 计数变量,本身并不"包含元素",无从比较元素个数。
同时,本次改动(28-48 行)完全删除了原"功能说明"中输出元素数 的计算公式( 或 )与"包含补齐元素、计数单位为元素"的说明,并把原"约束说明"中关于补齐、长度对齐的条目一并删除,导致 quantParamSize 到底等于多少(是否含 16 元素对齐补齐)在整篇文档中已无处可查;而调用示例(233-237 行)仍按 resultSize 遍历访问 result。
失效模式:调用者按新文档理解会预先给 resultSize 赋值或按 scaleSize/offsetSize 自行推算长度,实际接口写回的是含补齐的长度(多为 16 的整数倍),按推算值遍历会漏读或误判输出规模。
建议:输出参数的使用说明不应写成"由用户自行保证":改为"由接口写回,表示 quantParam 数组的元素个数(含补齐元素,计数单位为元素)",并补回输出元素数 P 的计算公式,避免调用者自行推算长度。


🟡 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 工具说明套在输出参数上。
| 131
| - <td> |
|
131 | + <td>-</td> |


🟡 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 行)保持一致;若要改名则需同步全部出现位置与头文件。


🟡 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 可不同、不广播"的语义说明。


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


描述
关联的Issue
https://gitcode.com/cann/ops-nn/issues/8705
测试
文档更新
本次 PR 更新 ops-nn docs/QUICKSTART.md,修正标点/术语/行内代码格式问题 11 处,详见 diff。
类型标签