Merged
docs(quant): 规范量化矩阵乘与参数转换算子的中文文档 #13862
panzhijaAdd on 15 days ago
docs(quant): 规范量化矩阵乘与参数转换算子的中文文档 #13862
Merged
panzhijaAdd on 15 days ago
panzhija
panzhijaCollaborators
15 days ago

描述

修正量化矩阵乘与量化参数转换算子的中文文档,使 README 结构、接口说明及示例与仓库 wiki 模板和当前源码一致。

  • 按模板整理产品支持、功能、参数、约束和调用说明,完善文档及样例链接。
  • 统一 ACLNN 参数表、函数原型、返回码表、公式、代码块及嵌套列表格式,并整理相关 IR、融合说明和 PyTorch 接口文档。
  • 修正量化参数转换说明:明确 TransQuantParam 保留完整 32 位 scale、offset 中点向远离 0 的方向舍入、输入不广播,以及输出对齐、补零和 Host 内存释放规则;澄清 TransQuantParamV2/V3 的舍入模式与形状约束。
  • 完善文档内调用示例的头文件、指针初始化和失败检查。

关联的Issue

关联 Issue #8344:https://gitcode.com/cann/ops-nn/issues/8344

测试

  • Markdown 格式、列表与表格结构、相对链接与锚点、UTF-8 编码、公式渲染及公开 API 声明一致性检查通过。
  • 23 个 C++ 示例通过基于类型桩和仓库公开声明的语法检查,3 个 Python 示例通过语法检查。
  • TransQuantParam 的 12 项 Host 行为检查通过,覆盖编码位域、舍入、广播行为、对齐补零和参数错误码;日志依赖使用桩。
  • 提交时的 pre-commit 检查通过,包括 codespell 和 OAT;未进行真实 CANN 链接或 NPU 执行。

文档更新

更新以下 6 个算子的 23 份中文 Markdown 文档,包含 README、ACLNN、IR、融合及 PyTorch 接口说明:

  • quant_batch_matmul_inplace_add
  • quant_batch_matmul_v3
  • quant_batch_matmul_v4
  • quant_matmul_activation_quant
  • trans_quant_param
  • trans_quant_param_v2

类型标签

AI/Agent生成声明

likedislike
Pull Request has been successfully merged by CANN-robot.
(Thank you for panzhija's contribution.)
panzhijapanzhijaCollaborators
15 days ago Created pull request, commit a8002fa8
atomgit-bot
atomgit-bot
15 days ago Comments:

变更摘要

本 PR 是纯文档更新,聚焦量化矩阵乘与量化参数转换算子的中文文档规范化。主要涉及 quant_batch_matmul_inplace_add、quant_batch_matmul_v3、quant_batch_matmul_v4、quant_matmul_activation_quant、trans_quant_param、trans_quant_param_v2 六个算子,统一了 README 结构(产品支持、功能、参数、约束、调用说明)、ACLNN 参数表与返回码表、函数原型与代码块格式,并修正了 TransQuantParam/TransQuantParamV2/V3 的编码与舍入语义描述。

主要改动

  • TransQuantParam 编码语义修正:明确 scale 保留完整 32 位浮点位模式(不再清除低 13 位)并置 bit 46,offset 采用中点向远离 0 方向舍入后饱和到 [-256,255] 写入 bit 37~45;补充输出按 16 元素对齐补齐、scale/offset 不广播、输出由 calloc 申请需 std::free 释放等 Host 侧规则。
  • TransQuantParamV2/V3 舍入模式与形状约束澄清:说明 round_mode=0 截断低 13 位、1 按 RNE 保留 19 位(1 符号 + 8 指数 + 10 尾数),offset 始终按 RNE 处理;补充 <term>Ascend 950PR&950DT系列产品</term> 分组场景 (g,n) scale 形状及一维/二维 scale 与 offset 组合下的 out 形状推导规则。
  • 量化矩阵乘 README 与公式重写:quant_batch_matmul_inplace_add、quant_batch_matmul_v3、quant_batch_matmul_v4 的 README 改为统一表格模板,公式改为按量化模式分类的规范化表达(MX、HIFLOAT8 T-T、G-B/B-B 等),并新增版本关系说明(aclnnQuantMatmulV3/V4 标注待废弃、指向 aclnnQuantMatmulV5)以及 dtype、compute_type、group_size 等属性条目。
  • ACLNN 接口文档表格与返回码统一:多个 docs/aclnn*.md 将参数表重构为固定列宽的统一 HTML 表格(参数名含类型标注、补充“非连续Tensor”列),返回码表合并为 返回码/状态码 与 码值,并新增 ACLNN_ERR_INNER_CREATE_EXECUTOR(561101)、ACLNN_ERR_INNER_NULLPTR(561103)、ACLNN_ERR_RUNTIME_ERROR(361001)等条目及 ACLNN_ERR_INNER(561000)说明。
  • 调用示例健壮性与交叉链接完善:示例代码补充 <cstdint>/<cstdio> 头文件、aclrtStream stream = nullptr 初始化与 aclCreateTensor 失败检查,aclnnQuantMatmulActivationQuant 等文档将“实际存储形状见参数和约束说明”改为锚点链接(如 #形状、#布局与存储),并补全 TransQuantParamV2/V3、aclnnQuantMatmulV5 的相对链接。

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

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

代码审查

审查结论

  • [建议] matmul/quant_batch_matmul_v4/README.md:143 fix: README 遗漏 y 的 INT32 输出与 dtype 枚举取值
  • [建议] matmul/quant_batch_matmul_v4/README.md:133 fix: README 的 x1/x2 数据类型表遗漏 INT32(4bit 打包权重)支撑
类型 数量
🔴 阻塞 0
🟡 建议 2

💬 仅评论


🧩 本次 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 ✅ 陈娇, 商晓波, 王子韬 (3/2) ✅ 陈娇 (1/1)
*/*/docs/acl*.md ✅ 陈娇, 王子韬, 商晓波 (3/2) ✅ 陈娇 (1/1)
matmul ✅ 商晓波, 王子韬 (2/2) ✅ 商晓波 (1/1)
quant ✅ 商晓波, 王子韬 (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

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

likedislike
CANN-robotCANN-robotCollaborators
15 days ago Set zengjuan,u010470851,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,pingchuantang,Chen_HaoWen,qianzehong,fengying555682,liuyang_806,caiwenwen,yanglu-1 as approver
CANN-robotCANN-robotCollaborators
15 days ago Set oscillated,sxb154714,chaotang233,yangyang016,fanqirui,gitee-duhuiping,chenqi317,LinPX,tangweiwei2,wangzitao_leo,void_ptr,xubinglin,zhaoyingchao2,gitcode-chenjiao,rueenov11,fengying555682,liuyang_806,caiwenwen,yanglu-1 as approver
panzhijapanzhijaCollaborators
15 days ago Modify description of pull request
panzhija
panzhijaCollaborators
15 days ago Comments:

compile

likedislike
panzhijapanzhijaCollaborators
15 days ago Pre merge succeeded (commit_id: ddbbf044ac93934aef904a82125b7d1378580439)
CANN-robot
CANN-robotCollaborators
15 days ago Comments:
🚀 CI 流水线已启动
📋 执行详情: 点击查看流水线
likedislike
CANN-robotCANN-robotCollaborators
15 days ago Added label: ci-pipeline-running
CANN-robotCANN-robotCollaborators
15 days ago Removed label: ci-pipeline-running
CANN-robotCANN-robotCollaborators
15 days ago Added label: ci-pipeline-failed
CANN-robot
CANN-robotCollaborators
15 days ago Comments:

流水线分析报告 — ops-nn run#17895

流水线: https://gitcode.com/CANN/ops-nn/actions/runs/13e0fa8a61de466ca3be754d452bacbd | PR#13862 | 2026-11-06 18:22:53 ~ 2026-11-06 18:25:20 | 失败 Job 1 个

定界结论: 代码问题 / 代码检查错误 — 双语配对修改检查失败, 7 个文件缺失对应版本
  • 失败类型: 代码问题
  • 根因: 双语配对修改检查失败(中英文文档需成对修改), 共 7 个文件缺失对应版本
  • 处置建议: 通知 PR 提交者补齐每个已修改中文文档对应的英文版本(README_en.md / *_en.md)后重新推送
  • 排除项: Checkout/OBS 下载/上传步骤均正常; 无平台错误、无网络/环境异常

失败根因分析

根因 #1: 代码问题 / 代码检查错误 — 双语配对修改检查失败, 7 个文件缺失对应版本
  • 判据: 双语配对修改检查失败(中英文文档需成对修改)
  • 定位步骤: 3_check-pr.log
  • 影响 Job: CodeCheck_check-pr
  • 影响文件(7 对缺失):
    1. matmul/quant_batch_matmul_inplace_add/README.md → 缺 matmul/quant_batch_matmul_inplace_add/README_en.md
    2. matmul/quant_batch_matmul_v3/README.md → 缺 matmul/quant_batch_matmul_v3/README_en.md
    3. matmul/quant_batch_matmul_v4/README.md → 缺 matmul/quant_batch_matmul_v4/README_en.md
    4. matmul/quant_batch_matmul_v4/docs/ascendir_QuantBatchMatmulV4.md → 缺 matmul/quant_batch_matmul_v4/docs/ascendir_QuantBatchMatmulV4_en.md
    5. matmul/quant_matmul_activation_quant/README.md → 缺 matmul/quant_matmul_activation_quant/README_en.md
    6. quant/trans_quant_param/README.md → 缺 quant/trans_quant_param/README_en.md
    7. quant/trans_quant_param_v2/README.md → 缺 quant/trans_quant_param_v2/README_en.md
  • 根因证据(日志原文):
[shell stderr] ERROR | matmul/quant_batch_matmul_inplace_add/README.md 被修改了,但 matmul/quant_batch_matmul_inplace_add/README_en.md 未在本次 PR 中同步修改
[shell stderr] ERROR | matmul/quant_batch_matmul_v3/README.md 被修改了,但 matmul/quant_batch_matmul_v3/README_en.md 未在本次 PR 中同步修改
[shell stderr] ERROR | matmul/quant_batch_matmul_v4/README.md 被修改了,但 matmul/quant_batch_matmul_v4/README_en.md 未在本次 PR 中同步修改
[shell stderr] ERROR | matmul/quant_batch_matmul_v4/docs/ascendir_QuantBatchMatmulV4.md 被修改了,但 matmul/quant_batch_matmul_v4/docs/ascendir_QuantBatchMatmulV4_en.md 未在本次 PR 中同步修改
[shell stderr] ERROR | matmul/quant_matmul_activation_quant/README.md 被修改了,但 matmul/quant_matmul_activation_quant/README_en.md 未在本次 PR 中同步修改
[shell stderr] ERROR | quant/trans_quant_param/README.md 被修改了,但 quant/trans_quant_param/README_en.md 未在本次 PR 中同步修改
[shell stderr] ERROR | quant/trans_quant_param_v2/README.md 被修改了,但 quant/trans_quant_param_v2/README_en.md 未在本次 PR 中同步修改
[shell stderr] ERROR | 双语配对修改检查失败,共 7 个文件缺失对应版本
[ERROR] 20261106-182423 Check ops-nn md files  is failed.
::error::check_pr.sh 异常退出: exit code=1
结构化定界摘要
[{"repo": "ops-nn", "run_number": 17895, "Failed_Type": "代码问题", "Failed_Sub_Type": "代码检查错误", "Failed_Reason": "双语配对修改检查失败,共 7 个已修改的中文文档缺失对应英文版本(README_en.md/*_en.md)", "evidence": "ERROR | 双语配对修改检查失败,共 7 个文件缺失对应版本", "suggestion": "PR 提交者补齐 7 个文档对应的英文版本后重新推送", "jobs": "CodeCheck_check-pr"}]

由门禁失败定界分析自动生成 | repo: ops-nn | run: 13e0fa8a61de466ca3be754d452bacbd | PR#13862

likedislike
atomgit-bot
atomgit-bot15 days agoStart code review1
matmul/quant_batch_matmul_v4/README.md
@@ -216,0 +141,4 @@
141+| y_offset | 可选输入 | 矩阵乘后的偏移修正参数,在对应量化场景提供;不使用时省略。 | BFLOAT16、FLOAT16、FLOAT32 | ND |
142+| x2_table | 可选输入 | 权重量化查找表预留参数,当前不支持传入。 | INT8 | ND |
143+| y | 输出 | 矩阵乘及量化处理后的结果,数据类型由dtype指定。 | BFLOAT16、FLOAT16、INT8、FLOAT32 | ND |
144+| dtype | 属性 | 输出y的数据类型枚举,支持0(FLOAT32)、1(FLOAT16)、2(INT8)、27(BFLOAT16),须满足对应产品及输入组合的要求。 | INT64 | - |
atomgit-bot
atomgit-bot15 days agoComments:

🟡 Medium Priority

改动行:matmul/quant_batch_matmul_v4/README.md 143–144 行的参数表把 y 的数据类型写成「BFLOAT16、FLOAT16、INT8、FLOAT32」,并声明 dtype 枚举只支持「0(FLOAT32)、1(FLOAT16)、2(INT8)、27(BFLOAT16)」,均未包含 INT32。

影响/契约:同一算子的姐妹文档 docs/aclnnQuantMatmulV5.md 中 out 的数据类型明确为「FLOAT16、INT8、BFLOAT16、INT32、FLOAT32…」(432 行),并在 A2/A3 公共约束中专门描述「x1,x2 为 INT8,out 为 INT32,bias 为 INT32 或 nullptr 时,各 scale 实际不参与计算」(629 行)以及 950 产品 T-C/T-T 表格中的 INT32 输出行(802 行);改写前的 README 组合表也含 y = INT32 的行。

失败模式:按 IR 构网(README 219 行指向 op_graph proto)的使用者会认为输出只能是 FLOAT16/BFLOAT16/INT8/FLOAT32,从而拒绝本应合法的 INT8×INT8→INT32 累加输出场景,或传入 dtype 枚举时缺少对应取值;README 与 API 文档对同一算子的输出契约互相矛盾。

建议:在 y 的数据类型与 dtype 枚举说明中补回 INT32(对应枚举值),与 aclnnQuantMatmulV5.md 的 out 支持列表及 INT8×INT8→INT32 场景保持一致。

likedislike
Incorrect?
atomgit-bot
atomgit-bot15 days agoStart code review1
matmul/quant_batch_matmul_v4/README.md
@@ -216,0 +131,4 @@
131+| 参数名 | 输入/输出/属性 | 描述 | 数据类型 | 数据格式 |
132+| --- | --- | --- | --- | --- |
133+| x1 | 输入 | 矩阵乘的左矩阵。 | INT8、INT4、HIFLOAT8、FLOAT8_E5M2、FLOAT8_E4M3FN、FLOAT4_E2M1 | ND |
134+| x2 | 输入 | 矩阵乘的右矩阵。FLOAT32用于承载特定预处理后的FLOAT4_E2M1权重,不表示普通FLOAT32矩阵乘。 | INT8、INT4、HIFLOAT8、FLOAT8_E5M2、FLOAT8_E4M3FN、FLOAT4_E2M1、FLOAT32 | ND、FRACTAL_NZ、FRACTAL_NZ_C0_32、FRACTAL_NZ_C0_4、FRACTAL_Z |
atomgit-bot
atomgit-bot15 days agoComments:

🟡 Medium Priority

改动行:matmul/quant_batch_matmul_v4/README.md 133–134 行新增的参数表把 x1 的数据类型写成「INT8、INT4、HIFLOAT8、FLOAT8_E5M2、FLOAT8_E4M3FN、FLOAT4_E2M1」,x2 写成「…、FLOAT4_E2M1、FLOAT32」,两份列表都不再包含 INT32;同一 PR 中改写过的公式行(27 行)也把原先的「x2 为 INT32」改成「x2 为 INT4」,A2/A3 组合表(162 行)同样只写 INT4。

影响/契约:同一算子的姐妹文档 docs/aclnnQuantMatmulV5.md 仍明确把 INT32 列为 x1/x2 的合法数据类型(312 行「INT4、INT8、INT32…」、322 行同、465 行「INT32 输入用于存放打包的 INT4 数据,每个 INT32 包含 8 个 INT4 元素」),A2/A3 的 T-C/T-T、K-G 组合表(676、681、684–685、722 行)仍以 INT4/INT32、INT32 形式列出 x2,并配有「每个 INT32 存放 8 个 INT4」的形状约束;README 里这条 A8W4 行(162 行)在改写前也是 INT8 | INT32 | FLOAT32 | UINT64 | … | FLOAT32 | FLOAT16/BFLOAT16。

失败模式:只读 README 的调用者/图模式构网者会认为 INT32(打包 4bit)输入不被支持,从而按 INT4 构造 Tensor 或放弃该路径,或反过来在 IR 侧拒绝了本来合法的 INT32 权重;同一算子两份文档对同一场景给出互相矛盾的 x2 类型,属于本次单方面改写造成的一致性回归。

建议:在参数表 x1、x2 的数据类型列补回 INT32(注明为 8×INT4 打包载体),与 aclnnQuantMatmulV5.md 中 x1/x2 的 INT32 说明及 A2/A3 组合表保持一致。

likedislike
Incorrect?
panzhijapanzhijaCollaborators
15 days ago Pre merge succeeded (commit_id: 848560cb3319d9f059ff0b45ee358e7461e1b349)
panzhijapanzhijaCollaborators
15 days ago Force-pushed 1 commits:b575d81c-docs(quant): 规范量化矩阵乘与参数转换算子的中英文文档
panzhijapanzhijaCollaborators
15 days ago Pre merge succeeded (commit_id: 3bc039f2682ea2edb593740c7fc5d6ebfb13882f)
CANN-robotCANN-robotCollaborators
15 days ago Removed label: cann-cla/yes
CANN-robotCANN-robotCollaborators
15 days ago Added label: cann-cla/yes
CANN-robotCANN-robotCollaborators
15 days ago Set u010470851,chenfeng61,su-yueming,zhajianqing123,yourealize,wang-xing001,liujie12345678,pingchuantang,Chen_HaoWen,qianzehong as approver
chenjiao
chenjiaoCollaborators
14 days ago Comments:

/approve

likedislike
panzhija
panzhijaCollaborators
14 days ago Comments:

compile

likedislike
panzhijapanzhijaCollaborators
14 days ago Pre merge succeeded (commit_id: ff58ae9c442c0bead4943cc9b3ac4920d7c74fd0)
CANN-robot
CANN-robotCollaborators
14 days ago Comments:
🚀 CI 流水线已启动
📋 执行详情: 点击查看流水线
likedislike
CANN-robotCANN-robotCollaborators
14 days ago Removed label: ci-pipeline-failed
CANN-robotCANN-robotCollaborators
14 days ago Added label: ci-pipeline-running
panzhijapanzhijaCollaborators
14 days ago Resolved final issue
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:
wangzitao
wangzitaoCollaborators
14 days ago Comments:

/lgtm
by agent

likedislike
sxb154714
sxb154714Collaborators
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
yangyang016yangyang016Collaborators
9 days ago Deleted associated issue: [Documentation|文档反馈]: 规范六个量化算子的中文文档并修正接口行为说明
yangyang016yangyang016Collaborators
9 days ago Associated issue: [Documentation|文档反馈]: aclnnQuantBatchMatmulInplaceAdd.md 文档存在 1 处问题需修正
CANN-robotCANN-robotCollaborators
9 days ago Removed label: ci-pipeline-passed
CANN-robot
CANN-robotCollaborators
9 days ago Comments:

The following label is not ready.

ci-pipeline-passed: The ci-pipeline-passed label is expired as added over 72 hours. Please use /compile to recompile.

likedislike