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
Total: 5 files changed+192-197
@@ -36,7 +36,7 @@
36 git clone -b ${tag_version} https://gitcode.com/cann/ops-nn.git && cd ops-nn36 git clone -b ${tag_version} https://gitcode.com/cann/ops-nn.git && cd ops-nn
37 ```37 ```
38 38 
39-> 说明:如需切换源码分支版本,请参见如下指导。39+> 说明:如需切换源码分支版本,请参见如下指导:
40>40>
41> 1. 在源码目录执行`git status --short --branch`,查询当前检出状态。检出版本标签时会处于分离头指针(detached HEAD)状态,这是正常现象;可执行`git describe --tags --exact-match`确认当前标签。41> 1. 在源码目录执行`git status --short --branch`,查询当前检出状态。检出版本标签时会处于分离头指针(detached HEAD)状态,这是正常现象;可执行`git describe --tags --exact-match`确认当前标签。
42> 2. 先执行`git fetch origin --tags`更新远端分支和标签信息,再执行`git checkout ${tag_version}`检出目标版本,注意满足源码与CANN版本配套关系。检出版本标签后不要执行`git pull`;如需更新开发分支,应先切换到相应分支,再执行`git pull --ff-only`。42> 2. 先执行`git fetch origin --tags`更新远端分支和标签信息,再执行`git checkout ${tag_version}`检出目标版本,注意满足源码与CANN版本配套关系。检出版本标签后不要执行`git pull`;如需更新开发分支,应先切换到相应分支,再执行`git pull --ff-only`。
@@ -57,15 +57,15 @@
57bash build.sh --pkg --soc=${soc_version} --ops=add_example -j1657bash build.sh --pkg --soc=${soc_version} --ops=add_example -j16
58```58```
59 59 
60-产品名对应的\$\{soc\_version\}取值如下,请按实际场景传参。60+产品名对应的\$\{soc\_version\}取值如下,请按实际场景传参:
61 61 
62- Atlas A2系列产品:取值为ascend910b62- Atlas A2系列产品:取值为ascend910b
63- Atlas A3系列产品:取值为ascend910_9363- Atlas A3系列产品:取值为ascend910_93
64- 950系列产品:取值为ascend95064- 950系列产品:取值为ascend950
65 65 
66-若提示如下信息,说明编译成功。66+若提示如下信息,说明编译成功:
67 67 
68-```bash68+```output
69Self-extractable archive "cann-ops-nn-custom_linux-${arch}.run" successfully created.69Self-extractable archive "cann-ops-nn-custom_linux-${arch}.run" successfully created.
70```70```
71 71 
@@ -85,11 +85,11 @@ Self-extractable archive "cann-ops-nn-custom_linux-${arch}.run" successfully cre
85>85>
86> 错误使用`--force`可能导致算子在运行时加载失败,因此不建议默认使用。86> 错误使用`--force`可能导致算子在运行时加载失败,因此不建议默认使用。
87 87 
88-`AddExample`安装在```${ASCEND_HOME_PATH}/opp/vendors```路径中,```${ASCEND_HOME_PATH}```表示CANN软件安装目录。88+`AddExample`安装在`${ASCEND_HOME_PATH}/opp/vendors`路径中,`${ASCEND_HOME_PATH}`表示CANN软件安装目录。
89 89 
90### 4. 配置环境变量90### 4. 配置环境变量
91 91 
92-将自定义算子包的路径加入环境变量,确保运行时能够找到。92+将自定义算子包的路径加入环境变量,确保运行时能够找到对应库文件。
93 93 
94```bash94```bash
95export LD_LIBRARY_PATH=${ASCEND_HOME_PATH}/opp/vendors/custom_nn/op_api/lib:${LD_LIBRARY_PATH}95export LD_LIBRARY_PATH=${ASCEND_HOME_PATH}/opp/vendors/custom_nn/op_api/lib:${LD_LIBRARY_PATH}
@@ -108,7 +108,7 @@ bash build.sh --run_example add_example eager cust --vendor_name=custom --soc=${
108- <算子名>:add_example108- <算子名>:add_example
109- <运行模式>:eager109- <运行模式>:eager
110- <包模式>:cust110- <包模式>:cust
111-- --vendor_name(可选):vendorname表示构建的自定义算子包名,默认名为custom111+- --vendor_name(可选):vendor_name表示构建的自定义算子包名,默认名为custom
112 112 
113> **注意**:运行样例时需确保`--soc`参数与编译算子包时使用的`--soc`取值一致,否则可能报`error 161001`(如`aclnnXxxGetWorkspaceSize failed`)。如遇此错误,请回到[第2节](#2-编译addexample算子)核对`--soc`取值后重新编译安装。113> **注意**:运行样例时需确保`--soc`参数与编译算子包时使用的`--soc`取值一致,否则可能报`error 161001`(如`aclnnXxxGetWorkspaceSize failed`)。如遇此错误,请回到[第2节](#2-编译addexample算子)核对`--soc`取值后重新编译安装。
114 114 
@@ -132,7 +132,7 @@ add_example first input[7] is: 1.000000, second input[7] is: 1.000000, result[7]
132 132 
133### 1. 修改Kernel实现133### 1. 修改Kernel实现
134 134 
135-找到AddExample算子的核心kernel实现文件`examples/add_example/op_kernel/add_example.h`,尝试将算子中的Add操作改为Mul操作:135+找到AddExample算子的核心Kernel实现文件`examples/add_example/op_kernel/add_example.h`,尝试将算子中的Add操作改为Mul操作:
136 136 
137```cpp137```cpp
138__aicore__ inline void AddExample<T>::Compute(int64_t currentNum)138__aicore__ inline void AddExample<T>::Compute(int64_t currentNum)
@@ -161,7 +161,7 @@ __aicore__ inline void AddExample<T>::Compute(int64_t currentNum)
161 bash build.sh --pkg --soc=${soc_version} --ops=add_example -j16161 bash build.sh --pkg --soc=${soc_version} --ops=add_example -j16
162 ```162 ```
163 163 
164- 产品名对应的\$\{soc\_version\}取值如下,请按实际场景传参。164+ 产品名对应的\$\{soc\_version\}取值如下,请按实际场景传参:
165 165 
166 - Atlas A2系列产品:取值为ascend910b166 - Atlas A2系列产品:取值为ascend910b
167 - Atlas A3系列产品:取值为ascend910_93167 - Atlas A3系列产品:取值为ascend910_93
@@ -255,7 +255,7 @@ __aicore__ inline void AddExample<T>::Compute(int64_t currentNum)
255 255 
256找到并编辑`AddExample`的`examples/add_example/examples/test_aclnn_add_example.cpp`,修改输入张量的形状和数值。256找到并编辑`AddExample`的`examples/add_example/examples/test_aclnn_add_example.cpp`,修改输入张量的形状和数值。
257 257 
258-**修改输入/输出数据**:修改输入、输出的shape信息,以及初始化数据,构造相应的输入、输出tensor。258+**修改输入/输出数据**:修改输入、输出的shape信息,以及初始化数据,构造相应的输入、输出Tensor。
259 259 
260```cpp260```cpp
261int aclnnAddExampleTest(int32_t deviceId, aclrtStream& stream) {261int aclnnAddExampleTest(int32_t deviceId, aclrtStream& stream) {
@@ -276,7 +276,7 @@ int aclnnAddExampleTest(int32_t deviceId, aclrtStream& stream) {
276}276}
277```277```
278 278 
279-> **注意**:修改shape时需同步修改对应host侧数据vector的长度(本例`selfX`、`selfY`、`out`三者的vector长度都要从默认的2048改为4096 = 8×8×8×8),并保证三者shape一致,否则会出现数据越界或结果不匹配。279+> **注意**:修改shape时需同步修改对应Host侧数据Vector的长度(本例`selfX`、`selfY`、`out`三者的vector长度都要从默认的2048改为4096 = 8×8×8×8),并保证三者shape一致,否则会出现数据越界或结果不匹配。
280 280 
281### 2. 重新编译并验证281### 2. 重新编译并验证
282 282 
@@ -109,7 +109,7 @@
109 P_i = cast\_to\_dst\_type(V_i/mxscale, round\_mode), \space i\space from\space 1\space to\space blocksize\\109 P_i = cast\_to\_dst\_type(V_i/mxscale, round\_mode), \space i\space from\space 1\space to\space blocksize\\
110 $$110 $$
111 111 
112- - 量化后的$P_{i}$按对应的$V_{i}$的位置组成输出yOut,mxscale按对应的axis维度上的分组组成输出mxscaleOut。112+ - ​量化后的$P_{i}$按对应的$V_{i}$的位置组成输出yOut,mxscale按对应的axis维度上的分组组成输出mxscaleOut。
113 113 
114 - 当dstTypeMax != 0.0/6.0/7.0时:114 - 当dstTypeMax != 0.0/6.0/7.0时:
115 115 
@@ -137,7 +137,7 @@
137 - 计算块缩放因子:$S_{ue8m0}^b=2^{E_{int}^b}$137 - 计算块缩放因子:$S_{ue8m0}^b=2^{E_{int}^b}$
138 - 计算块转换因子:$R_{fp32}^b=\frac{1}{fp32(S_{ue8m0}^b)}$138 - 计算块转换因子:$R_{fp32}^b=\frac{1}{fp32(S_{ue8m0}^b)}$
139 - 应用到量化的最终步骤,对于每个块内元素,$d^i = DType(d_{fp32}^i \cdot R_{fp32}^n)$,最终输出的量化结果是$\left(S^b, [d^i]_{i=1}^k\right)$,其中$S^b$代表块的缩放因子,这里指$S_{ue8m0}^b$,$[d^i]_{i=1}^k$代表块内量化后的数据。139 - 应用到量化的最终步骤,对于每个块内元素,$d^i = DType(d_{fp32}^i \cdot R_{fp32}^n)$,最终输出的量化结果是$\left(S^b, [d^i]_{i=1}^k\right)$,其中$S^b$代表块的缩放因子,这里指$S_{ue8m0}^b$,$[d^i]_{i=1}^k$代表块内量化后的数据。
140- - 量化后的$P_{i}$按对应的$V_{i}$的位置组成输出yOut,mxscale按对应的axis维度上的分组组成输出mxscaleOut。140+ - ​量化后的$P_{i}$按对应的$V_{i}$的位置组成输出yOut,mxscale按对应的axis维度上的分组组成输出mxscaleOut。
141 141 
142## 函数原型142## 函数原型
143 143 
@@ -24,7 +24,7 @@
24## 功能说明24## 功能说明
25 25 
26- **与V2版本的差异**:26- **与V2版本的差异**:
27- - V3版本新增了`groupListOptional`、`groupListType`参数,用于指定量化分组情况。27+ - V3版本新增了`groupList`、`groupListType`参数,用于指定量化分组情况。
28 - V2版本新增了`dstTypeMax`参数,用于在pergroup量化方式(对应float4_e2m1输出类型)中控制目标数据类型的最大值。28 - V2版本新增了`dstTypeMax`参数,用于在pergroup量化方式(对应float4_e2m1输出类型)中控制目标数据类型的最大值。
29 - V1版本不支持自定义目标数据类型最大值,默认使用目标精度能表示的最大值。29 - V1版本不支持自定义目标数据类型最大值,默认使用目标精度能表示的最大值。
30 30 
@@ -111,7 +111,7 @@
111 P_i = cast\_to\_dst\_type(V_i/mxscale, round\_mode), \space i\space from\space 1\space to\space blocksize\\111 P_i = cast\_to\_dst\_type(V_i/mxscale, round\_mode), \space i\space from\space 1\space to\space blocksize\\
112 $$112 $$
113 113 
114- - 量化后的$P_{i}$按对应的$V_{i}$的位置组成输出yOut,mxscale按对应的axis维度上的分组组成输出mxscaleOut。114+ - ​量化后的$P_{i}$按对应的$V_{i}$的位置组成输出yOut,mxscale按对应的axis维度上的分组组成输出mxscaleOut。
115 115 
116 - 当dstTypeMax != 0.0/6.0/7.0时:116 - 当dstTypeMax != 0.0/6.0/7.0时:
117 117 
@@ -139,7 +139,7 @@
139 - 计算块缩放因子:$S_{ue8m0}^b=2^{E_{int}^b}$139 - 计算块缩放因子:$S_{ue8m0}^b=2^{E_{int}^b}$
140 - 计算块转换因子:$R_{fp32}^b=\frac{1}{fp32(S_{ue8m0}^b)}$140 - 计算块转换因子:$R_{fp32}^b=\frac{1}{fp32(S_{ue8m0}^b)}$
141 - 应用到量化的最终步骤,对于每个块内元素,$d^i = DType(d_{fp32}^i \cdot R_{fp32}^n)$,最终输出的量化结果是$\left(S^b, [d^i]_{i=1}^k\right)$,其中$S^b$代表块的缩放因子,这里指$S_{ue8m0}^b$,$[d^i]_{i=1}^k$代表块内量化后的数据。141 - 应用到量化的最终步骤,对于每个块内元素,$d^i = DType(d_{fp32}^i \cdot R_{fp32}^n)$,最终输出的量化结果是$\left(S^b, [d^i]_{i=1}^k\right)$,其中$S^b$代表块的缩放因子,这里指$S_{ue8m0}^b$,$[d^i]_{i=1}^k$代表块内量化后的数据。
142- - 量化后的$P_{i}$按对应的$V_{i}$的位置组成输出yOut,mxscale按对应的axis维度上的分组组成输出mxscaleOut。142+ - ​量化后的$P_{i}$按对应的$V_{i}$的位置组成输出yOut,mxscale按对应的axis维度上的分组组成输出mxscaleOut。
143 143 
144## 函数原型144## 函数原型
145 145 
@@ -256,8 +256,8 @@ aclnnStatus aclnnFlatQuantV3(
256 <tr>256 <tr>
257 <td>groupListType(int64)</td>257 <td>groupListType(int64)</td>
258 <td>输入</td>258 <td>输入</td>
259- <td>代表groupListOptional输入的分组方式。</td>259+ <td>代表groupList输入的分组方式。</td>
260- <td><ul><li>当groupListOptional不为nullptr时支持取值0,1,2。当groupListOptional为nullptr时groupListType可以传任意值不影响计算结果。</li></ul></td>260+ <td><ul><li>当groupListOptional不为nullptr时支持取值0,1,2。</li></ul></td>
atomgit-bot
atomgit-botatomgit-bot9 days ago

🟡 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?
261 <td>-</td>261 <td>-</td>
262 <td>-</td>262 <td>-</td>
263 <td>-</td>263 <td>-</td>
@@ -366,7 +366,7 @@ aclnnStatus aclnnFlatQuantV3(
366 <td>out的数据类型为INT32时,x的shape尾轴不是out的shape尾轴大小的8倍,或者x与out的shape的非尾轴的大小不一致。</td>366 <td>out的数据类型为INT32时,x的shape尾轴不是out的shape尾轴大小的8倍,或者x与out的shape的非尾轴的大小不一致。</td>
367 </tr>367 </tr>
368 <tr>368 <tr>
369- <td>groupListOptional、groupListType的数据类型、维度、shape或参数取值不符合约束。</td>369+ <td>groupList、groupListType的数据类型、维度、shape或参数取值不符合约束。</td>
370 </tr>370 </tr>
371 </tbody></table>371 </tbody></table>
372 372 
@@ -429,8 +429,6 @@ aclnnStatus aclnnFlatQuantV3(
429 - 当groupListType为0时,groupListOptional必须为非负单调非递减数列,表示分组后每组大小的cumsum结果(累计和),最后一个值应小于等于x中tensor的第一维。429 - 当groupListType为0时,groupListOptional必须为非负单调非递减数列,表示分组后每组大小的cumsum结果(累计和),最后一个值应小于等于x中tensor的第一维。
430 - 当groupListType为1时,groupListOptional必须为非负数列,表示分组后每组大小,数值的总和应小于等于x中tensor的第一维。430 - 当groupListType为1时,groupListOptional必须为非负数列,表示分组后每组大小,数值的总和应小于等于x中tensor的第一维。
431 - 当groupListType为2时,groupListOptional必须为非负数列,数据排布为[[groupIdx0, groupSize0], [groupIdx1, groupSize1]...],其中groupSize为分组后每组大小,第二列数值的总和应小于等于x中tensor的第一维。431 - 当groupListType为2时,groupListOptional必须为非负数列,数据排布为[[groupIdx0, groupSize0], [groupIdx1, groupSize1]...],其中groupSize为分组后每组大小,第二列数值的总和应小于等于x中tensor的第一维。
432- - groupListOptional为nullptr时:
433- - groupListType可以传任意值不影响计算结果。
434 <!-- end id8 -->432 <!-- end id8 -->
435- 确定性计算:433- 确定性计算:
436 - aclnnFlatQuantV3默认确定性实现。434 - aclnnFlatQuantV3默认确定性实现。
@@ -126,7 +126,7 @@ aclnnStatus aclnnMatmulCompress(
126 <td>out</td>126 <td>out</td>
127 <td>输出</td>127 <td>输出</td>
128 <td>输出Tensor。</td>128 <td>输出Tensor。</td>
129- <td>-</td>129+ <td>通过示例中的msModelSlim工具获取</td>
130 <td>FLOAT16</td>130 <td>FLOAT16</td>
131 <td>ND</td>131 <td>ND</td>
atomgit-bot
atomgit-botatomgit-bot9 days ago

🟡 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?
132 <td>2</td>132 <td>2</td>
@@ -23,144 +23,129 @@
23 23 
24## 功能说明24## 功能说明
25 25 
26-- 接口功能:在Host侧将FLOAT32格式的scale及可选offset编码为UINT64量化参数。接口申请输出数组,并通过quantParam返回数组地址,通过quantParamSize返回包含补齐元素的数组长度。26+- 接口功能:将输入scale数据从FLOAT32类型转换为硬件需要的UINT64类型,并存储到quantParam中。
27- 计算公式:27- 计算公式:
28+ 1. `out`为64位格式,初始为0。
28 29 
29- 1. 令$L=\max(\mathrm{scaleSize},\mathrm{offsetSize})$,输出数组的元素数$P$按下式计算,并写入`*quantParamSize`。接口申请$P$个UINT64元素并全部初始化为0;下文用$q_i$表示`(*quantParam)[i]`。30+ 2. `scale`按bit位保留高19位(即bit位13~31,低13位清零),写入`out`的低32位,并将46位修改为1。
30 31 
31 $$32 $$
32- P=\begin{cases}33+ out = out\ |\ (scale\ \&\ 0xFFFFE000)\ |\ (1\ll46)
33- 1, & L=1\\
34- 16\lceil L/16\rceil, & L>1
35- \end{cases}
36 $$34 $$
35+ 3. 根据`offset`取值进行后续计算:
36+ - 若`offset`不存在,不再进行后续计算。
37+ - 若`offset`存在:
38+ 1. 将`offset`值处理为int,范围为[-256, 255]。
37 39 
38- 2. 对$0\le i<\mathrm{scaleSize}$,将`scaleArray[i]`按位重解释为UINT32,保留完整32位,再扩展为UINT64并将bit 46置1。位编号从0开始;这一步不清除scale的低13位。40+ $$
41+ offset = Max(Min(INT(Round(offset)),255),-256)
42+ $$
39 43 
40- $$44+ 2. 再将`offset`按bit位保留9位并存储于out的37到45位。
41- q_i=\operatorname{UINT64}\left(\operatorname{BitCast}_{\mathrm{UINT32}}(\mathrm{scaleArray}[i])\right)\mathbin{|}(1\ll46)
42- $$
43 45 
44- 3. 若`offsetArray`为nullptr,不写入offset;否则,对$0\le i<\mathrm{offsetSize}$,先按`std::round`规则舍入到最近整数,中间值向远离0的方向舍入,例如0.5变为1、-0.5变为-1。舍入结果须可用32位有符号整数表示,再饱和到[-256,255]:46+ $$
45- 47+ out = (out\ \&\ 0x4000FFFFFFFF)\ |\ ((offset\ \&\ 0x1FF)\ll37)
46- $$48+ $$
47- o_i=\max\left(-256,\min\left(255,\operatorname{Round}_{\mathrm{away}}(\mathrm{offsetArray}[i])\right)\right)
48- $$
49- 
50- 将$o_i$转换为UINT64,取低9位写入$q_i$的bit 37~45,保留已写入的scale及bit 46:
51- 
52- $$
53- q_i=(q_i\mathbin{\&}0x4000FFFFFFFF)\mathbin{|}
54- \left((\operatorname{UINT64}(o_i)\mathbin{\&}0x1FF)\ll37\right)
55- $$
56- 
57-两个数组按各自长度独立处理,不进行广播。未写入scale或offset的位置保持相应位域为0;$L\le i<P$的补齐元素为0。
58 49 
59## 函数原型50## 函数原型
60 51 
61-该接口同步完成Host计算,直接返回结果,不使用workspace、executor或stream。52+```Cpp
62- 
63-```cpp
64aclnnStatus aclnnTransQuantParam(53aclnnStatus aclnnTransQuantParam(
65- const float* scaleArray,54+ const float *scaleArray,
66- uint64_t scaleSize,55+ uint64_t scaleSize,
67- const float* offsetArray,56+ const float *offsetArray,
68- uint64_t offsetSize,57+ uint64_t offsetSize,
69- uint64_t** quantParam,58+ uint64_t **quantParam,
70- uint64_t* quantParamSize)59+ uint64_t *quantParamSize)
71```60```
72 61 
73## aclnnTransQuantParam62## aclnnTransQuantParam
74 63 
75-- **参数说明**64+- **参数说明:**
76 65 
77- 输入数组和输出数组均位于Host侧,不使用aclTensor。参数表中的数据格式、维度及非连续Tensor列不适用,统一以“-”表示。66+ <table style="undefined;table-layout: fixed; width: 1550px"><colgroup>
78- 67+ <col style="width: 170px">
79- <table style="table-layout: fixed; width: 1500px">68+ <col style="width: 120px">
80- <colgroup>69+ <col style="width: 271px">
81- <col style="width: 210px">70+ <col style="width: 330px">
82- <col style="width: 100px">71+ <col style="width: 223px">
83- <col style="width: 240px">72+ <col style="width: 101px">
84- <col style="width: 390px">73+ <col style="width: 190px">
85- <col style="width: 230px">74+ <col style="width: 145px">
86- <col style="width: 120px">75+ </colgroup>
87- <col style="width: 110px">76+ <thead>
88- <col style="width: 100px">77+ <tr>
89- </colgroup>78+ <th>参数名</th>
90- <thead>79+ <th>输入/输出</th>
91- <tr>80+ <th>描述</th>
92- <th>参数名</th>81+ <th>使用说明</th>
93- <th>输入/输出</th>82+ <th>数据类型</th>
94- <th>描述</th>83+ <th>数据格式</th>
95- <th>使用说明</th>84+ <th>维度(shape)</th>
96- <th>数据类型</th>85+ <th>非连续Tensor</th>
97- <th>数据格式</th>86+ </tr></thead>
98- <th>维度(shape)</th>87+ <tbody>
99- <th>非连续Tensor</th>88+ <tr>
100- </tr>89+ <td>scaleArray(float*)</td>
101- </thead>90+ <td>输入</td>
102- <tbody>91+ <td>表示指向存储scale数据的内存,对应公式中的`scale`。</td>
103- <tr>92+ <td>需要保证scale数据中不存在NaN和inf。</td>
104- <td>scaleArray(const float*)</td>93+ <td>-</td>
105- <td>输入</td>94+ <td>-</td>
106- <td>指向待编码的scale数组,对应公式中的scaleArray。</td>95+ <td>-</td>
107- <td>连续存放scaleSize个float元素;数值不能包含NaN或Inf。</td>96+ <td>-</td>
108- <td>FLOAT32</td>97+ </tr>
109- <td>-</td>98+ <tr>
110- <td>-</td>99+ <td>scaleSize(uint64_t)</td>
111- <td>-</td>100+ <td>输入</td>
112- </tr>101+ <td>表示scale数据的数量。</td>
113- <tr>102+ <td>需要自行保证`scaleSize`与`scaleArray`包含的元素个数相同。</td>
114- <td>scaleSize(uint64_t)</td>103+ <td>-</td>
115- <td>输入</td>104+ <td>-</td>
116- <td>scaleArray的元素数,对应公式中的scaleSize。</td>105+ <td>-</td>
117- <td>须大于0,且与scaleArray的实际长度一致。</td>106+ <td>-</td>
118- <td>-</td>107+ </tr>
119- <td>-</td>108+ <tr>
120- <td>-</td>109+ <td>offsetArray(float*)</td>
121- <td>-</td>110+ <td>输入</td>
122- </tr>111+ <td>表示指向存储offset数据的内存,对应公式中的`offset`。</td>
123- <tr>112+ <td>需要保证offset数据中不存在NaN和inf。</td>
atomgit-bot
atomgit-botatomgit-bot9 days ago

🟡 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?
124- <td>offsetArray(const float*)</td>113+ <td>-</td>
125- <td>可选输入</td>114+ <td>-</td>
126- <td>指向待编码的offset数组,对应公式中的offsetArray。</td>115+ <td>-</td>
127- <td><ul><li>不使用时传入nullptr,并将offsetSize设为0,输出中的offset位域保持为0。</li><li>提供时须连续存放offsetSize个float元素;数值不能包含NaN或Inf,舍入结果须可用32位有符号整数表示。</li></ul></td>116+ <td>-</td>
128- <td>FLOAT32</td>117+ </tr>
129- <td>-</td>118+ <tr>
130- <td>-</td>119+ <td>offsetSize(uint64_t)</td>
131- <td>-</td>120+ <td>输入</td>
132- </tr>121+ <td>表示offset数据的数量。</td>
133- <tr>122+ <td>需要自行保证`offsetSize`与`offsetArray`包含的元素个数相同。</td>
134- <td>offsetSize(uint64_t)</td>123+ <td>-</td>
135- <td>输入</td>124+ <td>-</td>
136- <td>offsetArray的元素数,对应公式中的offsetSize。</td>125+ <td>-</td>
137- <td>offsetArray为nullptr时须为0;否则须大于0,且与offsetArray的实际长度一致。</td>126+ <td>-</td>
138- <td>-</td>127+ </tr>
139- <td>-</td>128+ <tr>
140- <td>-</td>129+ <td>quantParam(uint64_t**)</td>
141- <td>-</td>130+ <td>输出</td>
142- </tr>131+ <td>表示指向存储转换得到的quantParam数据的内存地址,对应公式中的`out`。</td>
143- <tr>132+ <td>-</td>
atomgit-bot
atomgit-botatomgit-bot9 days ago

🟡 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?
144- <td>quantParam(uint64_t**)</td>133+ <td>-</td>
145- <td>输出</td>134+ <td>-</td>
146- <td>接收编码结果数组的地址,数组元素对应公式中的q。</td>135+ <td>-</td>
147- <td><ul><li>传入一个uint64_t*变量的地址,无需预先申请输出数组。</li><li>接口通过calloc申请Host内存并写入*quantParam,调用者使用后须通过std::free释放该内存。</li></ul></td>136+ <td>-</td>
148- <td>UINT64</td>137+ </tr>
149- <td>-</td>138+ <tr>
150- <td>-</td>139+ <td>quantParamSize(uint64_t*)</td>
151- <td>-</td>140+ <td>输出</td>
152- </tr>141+ <td>表示存储quantParam数据的数量。</td>
153- <tr>142+ <td>需要自行保证`quantParamSize`与`quantParam`包含的元素个数相同。</td>
atomgit-bot
atomgit-botatomgit-bot9 days ago

🟡 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?
154- <td>quantParamSize(uint64_t*)</td>143+ <td>-</td>
155- <td>输出</td>144+ <td>-</td>
156- <td>接收输出数组的元素数,对应公式中的P。</td>145+ <td>-</td>
157- <td>由接口写回,包含补齐元素;计数单位为元素,不是字节。计算方法见<a href="#功能说明">功能说明</a>。</td>146+ <td>-</td>
158- <td>-</td>147+ </tr>
159- <td>-</td>148+ </tbody>
160- <td>-</td>
161- <td>-</td>
162- </tr>
163- </tbody>
164 </table>149 </table>
165 150 
166- **返回值**151- **返回值**
@@ -169,76 +154,88 @@ aclnnStatus aclnnTransQuantParam(
169 154 
170 接口完成入参校验,出现以下场景时报错:155 接口完成入参校验,出现以下场景时报错:
171 156 
172- <table style="table-layout: fixed; width: 1000px">157+ <table style="undefined;table-layout: fixed;width: 1170px"><colgroup>
173- <colgroup>158+ <col style="width: 268px">
174- <col style="width: 300px">159+ <col style="width: 140px">
175- <col style="width: 150px">160+ <col style="width: 762px">
176- <col style="width: 550px">161+ </colgroup>
177- </colgroup>162+ <thead>
178- <thead>163+ <tr>
179- <tr>164+ <th>返回码</th>
180- <th>返回码/状态码</th>165+ <th>错误码</th>
181- <th>码值</th>166+ <th>描述</th>
182- <th>描述</th>167+ </tr>
183- </tr>168+ </thead>
184- </thead>169+ <tbody>
185- <tbody>170+ <tr>
186- <tr>171+ <td rowspan="3">ACLNN_ERR_PARAM_NULLPTR</td>
187- <td>ACLNN_ERR_PARAM_NULLPTR</td>172+ <td rowspan="3">161001</td>
188- <td>161001</td>173+ <td>参数quantParam是空指针。</td>
189- <td>quantParam或quantParamSize是空指针。</td>174+ </tr>
190- </tr>175+ <tr>
191- <tr>176+ <td>参数scaleArray是空指针。</td>
192- <td>ACLNN_ERR_PARAM_INVALID</td>177+ </tr>
193- <td>161002</td>178+ <tr>
194- <td><ul><li>scaleArray为空指针,或scaleSize为0。</li><li>offsetArray不为空指针,但offsetSize为0。</li><li>offsetArray为空指针,但offsetSize不为0。</li></ul></td>179+ <td>参数quantParamSize是空指针。</td>
195- </tr>180+ </tr>
196- <tr>181+ <tr>
197- <td>ACLNN_ERR_INNER_NULLPTR</td>182+ <td rowspan="3">ACLNN_ERR_PARAM_INVALID</td>
198- <td>561103</td>183+ <td rowspan="3">161002</td>
199- <td>输出数组的Host内存申请失败,此时*quantParam为nullptr,*quantParamSize为0。</td>184+ <td>当scaleArray不为空指针时,参数scaleSize < 1。</td>
200- </tr>185+ </tr>
201- </tbody>186+ <tr>
202- </table>187+ <td>当offsetArray不为空指针时,参数offsetSize < 1。</td>
188+ </tr>
189+ <tr>
190+ <td>当offsetArray为空指针时,参数offsetSize不等于0。</td>
191+ </tr>
192+ <tr>
193+ <td>ACLNN_ERR_INNER_NULLPTR</td>
194+ <td>561103</td>
195+ <td>输出缓冲区quantParam的内存申请失败(*quantParam为空指针)。</td>
196+ </tr>
197+ </tbody></table>
203 198 
204## 约束说明199## 约束说明
205 200 
206-- scaleArray、offsetArray的实际长度须与声明的元素数一致,接口不校验数组的实际内存容量。201+- 确定性计算:
207-- 两个输入数组的长度可以不同,不进行广播。例如,scaleSize为3、offsetSize为1时,仅第0个输出元素包含offset,第1、2个元素仅包含scale;若要共用同一个offset,须在调用前将offsetArray扩展为3个元素。202+ - aclnnTransQuantParam默认确定性实现。
208-- 输出长度包含按16个元素对齐的补齐部分。例如,scaleSize与offsetSize均为3时,quantParamSize为16,前3个元素为编码结果,后13个元素为0;两者的最大值为1时,quantParamSize为1。
209-- 返回的quantParam数组位于Host内存;后续接口若需要Device侧数据,须按该接口要求拷贝并构造输入。
210-- 确定性计算:aclnnTransQuantParam默认确定性实现。
211 203 
212## 调用示例204## 调用示例
213 205 
214示例代码如下,仅供参考,具体编译和执行过程请参考[编译与运行样例](../../../docs/zh/context/compile_and_run_sample.md)。206示例代码如下,仅供参考,具体编译和执行过程请参考[编译与运行样例](../../../docs/zh/context/compile_and_run_sample.md)。
215 207 
216-```cpp208+```Cpp
217-#include <cstdint>
218-#include <cstdlib>
219#include <iostream>209#include <iostream>
210+#include "acl/acl.h"
220#include "aclnnop/aclnn_trans_quant_param.h"211#include "aclnnop/aclnn_trans_quant_param.h"
221 212 
213+#define CHECK_RET(cond, return_expr) \
214+ do { \
215+ if (!(cond)) { \
216+ return_expr; \
217+ } \
218+ } while (0)
219+ 
220+#define LOG_PRINT(message, ...) \
221+ do { \
222+ printf(message, ##__VA_ARGS__); \
223+ } while (0)
224+ 
222int main()225int main()
223{226{
224- // 输入为Host数组;传入nullptr、0可省略offset。227+ float scaleArray[3] = {1.0, 1.0, 1.0};
225- const float scaleArray[] = {1.0F, 1.0F, 1.0F};228+ uint64_t scaleSize = 3;
226- const float offsetArray[] = {1.0F, 1.0F, 1.0F};229+ float offsetArray[3] = {1.0, 1.0, 1.0};
227- const uint64_t scaleSize = sizeof(scaleArray) / sizeof(scaleArray[0]);230+ uint64_t offsetSize = 3;
228- const uint64_t offsetSize = sizeof(offsetArray) / sizeof(offsetArray[0]);
229 uint64_t* result = nullptr;231 uint64_t* result = nullptr;
230 uint64_t resultSize = 0;232 uint64_t resultSize = 0;
231- const auto ret = aclnnTransQuantParam(scaleArray, scaleSize, offsetArray, offsetSize, &result, &resultSize);233+ auto ret = aclnnTransQuantParam(scaleArray, scaleSize, offsetArray, offsetSize, &result, &resultSize);
232- if (ret != ACLNN_SUCCESS) {234+ CHECK_RET(ret == ACL_SUCCESS, LOG_PRINT("aclnnTransQuantParam failed. ERROR: %d\n", ret); return ret);
233- std::cerr << "aclnnTransQuantParam failed. ERROR: " << ret << '\n';235+ for (auto i = 0; i < resultSize; i++) {
234- return 1;236+ LOG_PRINT("result[%d] is: %ld\n", i, result[i]);
235 }237 }
236- 238+ free(result);
237- // 本例返回16个元素:前3个为编码结果,后13个为补齐的0。
238- for (uint64_t i = 0; i < resultSize; ++i) {
239- std::cout << "result[" << i << "] is: " << result[i] << '\n';
240- }
241- std::free(result);
242 return 0;239 return 0;
243}240}
244```241```