Pull Request has been successfully merged by CANN-robot.
(Thank you for panzhija's contribution.)变更摘要
本 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:


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


compile


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


流水线分析报告 — 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 对缺失):
matmul/quant_batch_matmul_inplace_add/README.md→ 缺matmul/quant_batch_matmul_inplace_add/README_en.mdmatmul/quant_batch_matmul_v3/README.md→ 缺matmul/quant_batch_matmul_v3/README_en.mdmatmul/quant_batch_matmul_v4/README.md→ 缺matmul/quant_batch_matmul_v4/README_en.mdmatmul/quant_batch_matmul_v4/docs/ascendir_QuantBatchMatmulV4.md→ 缺matmul/quant_batch_matmul_v4/docs/ascendir_QuantBatchMatmulV4_en.mdmatmul/quant_matmul_activation_quant/README.md→ 缺matmul/quant_matmul_activation_quant/README_en.mdquant/trans_quant_param/README.md→ 缺quant/trans_quant_param/README_en.mdquant/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


🟡 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 场景保持一致。


🟡 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 组合表保持一致。


/approve


compile


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


/lgtm
by agent


/lgtm
/approve


Pull Request 已合并或已关闭。
If you want to solve this problem, you can click here to do it in the FAQs.


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.


描述
修正量化矩阵乘与量化参数转换算子的中文文档,使 README 结构、接口说明及示例与仓库 wiki 模板和当前源码一致。
关联的Issue
关联 Issue #8344:https://gitcode.com/cann/ops-nn/issues/8344
测试
文档更新
更新以下 6 个算子的 23 份中文 Markdown 文档,包含 README、ACLNN、IR、融合及 PyTorch 接口说明:
类型标签
AI/Agent生成声明