| @@ -36,7 +36,7 @@ | |||
| 36 | git clone -b ${tag_version} https://gitcode.com/cann/ops-nn.git && cd ops-nn | 36 | 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 @@ | |||
| 57 | bash build.sh --pkg --soc=${soc_version} --ops=add_example -j16 | 57 | bash 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系列产品:取值为ascend910b | 62 | - Atlas A2系列产品:取值为ascend910b |
| 63 | - Atlas A3系列产品:取值为ascend910_93 | 63 | - Atlas A3系列产品:取值为ascend910_93 |
| 64 | - 950系列产品:取值为ascend950 | 64 | - 950系列产品:取值为ascend950 |
| 65 | 65 | ||
| 66 | -若提示如下信息,说明编译成功。 | 66 | +若提示如下信息,说明编译成功: |
| 67 | 67 | ||
| 68 | -```bash | 68 | +```output |
| 69 | Self-extractable archive "cann-ops-nn-custom_linux-${arch}.run" successfully created. | 69 | Self-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 | ```bash | 94 | ```bash |
| 95 | export LD_LIBRARY_PATH=${ASCEND_HOME_PATH}/opp/vendors/custom_nn/op_api/lib:${LD_LIBRARY_PATH} | 95 | export 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_example | 108 | - <算子名>:add_example |
| 109 | - <运行模式>:eager | 109 | - <运行模式>:eager |
| 110 | - <包模式>:cust | 110 | - <包模式>:cust |
| 111 | -- --vendor_name(可选):vendorname表示构建的自定义算子包名,默认名为custom | 111 | +- --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 | ```cpp | 137 | ```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 -j16 | 161 | 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系列产品:取值为ascend910b | 166 | - Atlas A2系列产品:取值为ascend910b |
| 167 | - Atlas A3系列产品:取值为ascend910_93 | 167 | - 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 | ```cpp | 260 | ```cpp |
| 261 | int aclnnAddExampleTest(int32_t deviceId, aclrtStream& stream) { | 261 | int 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> |
| 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> | ||||
🟡 Medium Priority 改动行(129):把 证据链:本文档 26/34 行明确说明 msModelSlim 的作用是压缩右矩阵 r,产出压缩后的 x2、compressIndex 等输入(299-301 行示例第 2 步也只对输入侧做预处理); 失效模式:调用者按文档理解会以为 建议:把 Suggestions
![]() ![]() 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 | ||
| 64 | aclnnStatus aclnnTransQuantParam( | 53 | aclnnStatus 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 | ## aclnnTransQuantParam | 62 | ## 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> |
🟡 Medium Priority 改动行(109-112): 证据链:功能说明 35-36 行仍写"若 失效模式:调用者只想要纯 scale 编码时,文档没有告诉他传 建议:把 offsetArray 标回"可选输入",并在使用说明中恢复"不使用 offset 时传 nullptr 且 offsetSize 为 0",同时恢复"scaleSize 与 offsetSize 可不同、不广播"的语义说明。 ![]() ![]() 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> |
🟡 Medium Priority 改动行(132):
证据链:改动后的调用示例(231-238 行)仍是 失效模式:
建议:不要清空 quantParam 的使用说明:恢复"无需预先申请输出数组,接口申请 Host 内存并写入 *quantParam,调用者使用后须 free"的所有权说明,并补充申请失败时 *quantParam 的取值,使其与调用示例中的 free(result) 一致。 ![]() ![]() 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> |
🟡 Medium Priority 改动行(142): 证据链:139-141 行明确 同时,本次改动(28-48 行)完全删除了原"功能说明"中输出元素数 的计算公式( 或 )与"包含补齐元素、计数单位为元素"的说明,并把原"约束说明"中关于补齐、长度对齐的条目一并删除,导致 失效模式:调用者按新文档理解会预先给 建议:输出参数的使用说明不应写成"由用户自行保证":改为"由接口写回,表示 quantParam 数组的元素个数(含补齐元素,计数单位为元素)",并补回输出元素数 P 的计算公式,避免调用者自行推算长度。 ![]() ![]() 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 | -```cpp | 208 | +```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 | + | ||
| 222 | int main() | 225 | int 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 | ``` |


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