Merged
docs(softshrink,sparse_apply_ftrl): 对齐代码实现修正产品支持与约束说明 #13829
小王!Add on 15 days ago
docs(softshrink,sparse_apply_ftrl): 对齐代码实现修正产品支持与约束说明 #13829
Merged
Total: 6 files changed+132-104
| @@ -7,10 +7,14 @@ | |||
| 7 | | <term>Ascend 950PR&950DT系列产品</term> | √ | | 7 | | <term>Ascend 950PR&950DT系列产品</term> | √ | |
| 8 | | <term>Atlas A3系列产品</term> | √ | | 8 | | <term>Atlas A3系列产品</term> | √ | |
| 9 | | <term>Atlas A2系列产品</term> | √ | | 9 | | <term>Atlas A2系列产品</term> | √ | |
| 10 | -| <term>Atlas 200I/500 A2推理产品</term> | √ | | 10 | +| <term>Atlas 200I/500 A2推理产品</term> | × | |
| 11 | | <term>Atlas推理系列产品</term> | √ | | 11 | | <term>Atlas推理系列产品</term> | √ | |
| 12 | | <term>Atlas训练系列产品</term> | √ | | 12 | | <term>Atlas训练系列产品</term> | √ | |
| 13 | 13 | ||
| 14 | +> 说明: | ||
| 15 | +> - Ascend 950PR/950DT 由本仓 Ascend C 实现提供;Atlas A3/A2、Atlas推理/训练由 canndev TBE 实现承接;Atlas 200I/500 A2 无对应二进制配置,不支持。 | ||
| 16 | +> - Ascend 950PR/950DT、Atlas A3/A2 支持 FLOAT、FLOAT16、BFLOAT16;Atlas推理/训练仅支持 FLOAT、FLOAT16,不支持 BFLOAT16。 | ||
| 17 | + | ||
| 14 | ## 功能说明 | 18 | ## 功能说明 |
| 15 | 19 | ||
| 16 | - 算子功能:对输入张量应用Softshrink激活函数。 | 20 | - 算子功能:对输入张量应用Softshrink激活函数。 |
| @@ -44,42 +48,44 @@ $$ | |||
| 44 | </tr></thead> | 48 | </tr></thead> |
| 45 | <tbody> | 49 | <tbody> |
| 46 | <tr> | 50 | <tr> |
| 47 | - <td>x</td> | 51 | + <td>input_x</td> |
| 48 | <td>输入</td> | 52 | <td>输入</td> |
| 49 | <td>待进行Softshrink计算的输入张量,公式中的x。</td> | 53 | <td>待进行Softshrink计算的输入张量,公式中的x。</td> |
| 50 | <td>fp16、fp32、bf16</td> | 54 | <td>fp16、fp32、bf16</td> |
| 51 | <td>ND</td> | 55 | <td>ND</td> |
| 52 | </tr> | 56 | </tr> |
| 53 | <tr> | 57 | <tr> |
| 54 | - <td>lambd</td> | 58 | + <td>output_y</td> |
| 55 | - <td>输入</td> | ||
| 56 | - <td>Softshrink的阈值参数,默认值为0.5。接口内部将标量转换为fp32参与计算,非fp32类型存在精度转换,阈值精度敏感场景建议直接传入fp32标量。 | ||
| 57 | - </td> | ||
| 58 | - <td>除COMPLEX64、COMPLEX128外的数值标量类型</td> | ||
| 59 | - <td>1</td> | ||
| 60 | - </tr> | ||
| 61 | - <tr> | ||
| 62 | - <td>y</td> | ||
| 63 | <td>输出</td> | 59 | <td>输出</td> |
| 64 | - <td>Softshrink计算的输出张量。</td> | 60 | + <td>Softshrink计算的输出张量,shape与input_x一致。</td> |
| 65 | <td>fp16、fp32、bf16</td> | 61 | <td>fp16、fp32、bf16</td> |
| 66 | <td>ND</td> | 62 | <td>ND</td> |
| 67 | </tr> | 63 | </tr> |
| 64 | + <tr> | ||
| 65 | + <td>lambd</td> | ||
| 66 | + <td>属性</td> | ||
| 67 | + <td>Softshrink的阈值参数,公式中的λ,默认值为0.5。取值为NaN或负数时接口返回非法参数错误;+Inf合法。</td> | ||
| 68 | + <td>FLOAT</td> | ||
| 69 | + <td>-</td> | ||
| 70 | + </tr> | ||
| 68 | </tbody></table> | 71 | </tbody></table> |
| 69 | 72 | ||
| 70 | ## 约束说明 | 73 | ## 约束说明 |
| 71 | 74 | ||
| 72 | - 数据格式仅支持ND。 | 75 | - 数据格式仅支持ND。 |
| 73 | -- 输入x的dtype为fp16/fp32/bf16,输出y与输入x的dtype一致。 | 76 | +- 输入input_x的dtype为fp16/fp32/bf16,输出output_y与input_x的dtype一致;Atlas推理/训练不支持BF16(仅FLOAT、FLOAT16)。 |
| 74 | - 输入支持任意rank(0~8维);0维标量输入会被视作shape为(1,)的1维tensor处理。 | 77 | - 输入支持任意rank(0~8维);0维标量输入会被视作shape为(1,)的1维tensor处理。 |
| 75 | -- lambd取值范围为[0, +∞),不允许为负数或nan。 | 78 | +- lambd仅支持FLOAT标量,取值范围为[0, +∞):允许0、正数和+Inf,负数或NaN会返回参数非法错误。 |
| 76 | -- lambd支持除复数外的数值标量类型,接口内部统一转换为fp32后参与计算;非fp32标量存在精度转换,阈值精度敏感场景建议直接使用fp32标量。 | 79 | +- 本仓Ascend C实现中,输入input_x为NaN时输出为0,不进行NaN透传;依赖NaN传播的调用方需注意该差异。 |
| 77 | - 支持空Tensor(元素个数为0),直接返回同shape的空输出。 | 80 | - 支持空Tensor(元素个数为0),直接返回同shape的空输出。 |
| 78 | - 支持动态shape(含-1维度):tiling在运行期按实际shape计算切分,无需重新编译。 | 81 | - 支持动态shape(含-1维度):tiling在运行期按实际shape计算切分,无需重新编译。 |
| 79 | - 默认确定性实现,相同输入始终产生相同输出。 | 82 | - 默认确定性实现,相同输入始终产生相同输出。 |
| 80 | 83 | ||
| 81 | ## 调用说明 | 84 | ## 调用说明 |
| 82 | 85 | ||
| 83 | -| 调用方式 | 调用样例 | 说明 | | 86 | +| 调用方式 | 样例代码 | 说明 | |
| 84 | |--------------|------------------------------------------------------------------------|--------------------------------------------------------------| | 87 | |--------------|------------------------------------------------------------------------|--------------------------------------------------------------| |
| 85 | -| aclnn调用 | [test_aclnn_softshrink.cpp](./examples/test_aclnn_softshrink.cpp) | 通过[aclnnSoftshrink](./docs/aclnnSoftshrink.md)接口方式调用Softshrink算子。 | | 88 | +| aclnn API | [test_aclnn_softshrink.cpp](./examples/test_aclnn_softshrink.cpp) | 通过[aclnnSoftshrink](./docs/aclnnSoftshrink.md)接口方式调用Softshrink算子。 | |
| 89 | +| GE图模式 | [softshrink_proto.h](./op_graph/softshrink_proto.h) | 通过算子IR构图方式调用Softshrink算子。 | | ||
| 90 | + | ||
| 91 | +> 样例的编译与运行请参考[aclnnSoftshrink调用示例](./docs/aclnnSoftshrink.md#调用示例)及CANN样例编译运行说明。 | ||
| @@ -9,10 +9,14 @@ English | [简体中文](./README.md) | |||
| 9 | | <term>Ascend 950PR&950DT products</term> | √ | | 9 | | <term>Ascend 950PR&950DT products</term> | √ | |
| 10 | | <term>Atlas A3 products</term> | √ | | 10 | | <term>Atlas A3 products</term> | √ | |
| 11 | | <term>Atlas A2 products</term> | √ | | 11 | | <term>Atlas A2 products</term> | √ | |
| 12 | -| <term>Atlas 200I/500 A2 inference products</term> | √ | | 12 | +| <term>Atlas 200I/500 A2 inference products</term> | × | |
| 13 | | <term>Atlas inference products</term> | √ | | 13 | | <term>Atlas inference products</term> | √ | |
| 14 | | <term>Atlas training products</term> | √ | | 14 | | <term>Atlas training products</term> | √ | |
| 15 | 15 | ||
| 16 | +> Notes: | ||
| 17 | +> - Ascend 950PR/950DT is provided by the Ascend C implementation in this repository; Atlas A3/A2 and Atlas inference/training products are provided by the canndev TBE implementation. Atlas 200I/500 A2 has no corresponding binary configuration and is not supported. | ||
| 18 | +> - Ascend 950PR/950DT, Atlas A3, and Atlas A2 support FLOAT, FLOAT16, and BFLOAT16. Atlas inference/training products support only FLOAT and FLOAT16, not BFLOAT16. | ||
| 19 | + | ||
| 16 | ## Function | 20 | ## Function |
| 17 | 21 | ||
| 18 | - Operator function: Apply the Softshrink activation function to the input tensor. | 22 | - Operator function: Apply the Softshrink activation function to the input tensor. |
| @@ -46,41 +50,44 @@ $$ | |||
| 46 | </tr></thead> | 50 | </tr></thead> |
| 47 | <tbody> | 51 | <tbody> |
| 48 | <tr> | 52 | <tr> |
| 49 | - <td>x</td> | 53 | + <td>input_x</td> |
| 50 | <td>Input</td> | 54 | <td>Input</td> |
| 51 | <td>Input tensor for the Softshrink computation, x in the formula.</td> | 55 | <td>Input tensor for the Softshrink computation, x in the formula.</td> |
| 52 | <td>fp16, fp32, bf16</td> | 56 | <td>fp16, fp32, bf16</td> |
| 53 | <td>ND</td> | 57 | <td>ND</td> |
| 54 | </tr> | 58 | </tr> |
| 55 | <tr> | 59 | <tr> |
| 56 | - <td>lambd</td> | 60 | + <td>output_y</td> |
| 57 | - <td>Input</td> | ||
| 58 | - <td>Threshold parameter of Softshrink. Default value: 0.5. | ||
| 59 | - </td> | ||
| 60 | - <td>fp32</td> | ||
| 61 | - <td>1</td> | ||
| 62 | - </tr> | ||
| 63 | - <tr> | ||
| 64 | - <td>y</td> | ||
| 65 | <td>Output</td> | 61 | <td>Output</td> |
| 66 | - <td>Output tensor of the Softshrink computation.</td> | 62 | + <td>Output tensor of the Softshrink computation. Its shape is the same as that of input_x.</td> |
| 67 | <td>fp16, fp32, bf16</td> | 63 | <td>fp16, fp32, bf16</td> |
| 68 | <td>ND</td> | 64 | <td>ND</td> |
| 69 | </tr> | 65 | </tr> |
| 66 | + <tr> | ||
| 67 | + <td>lambd</td> | ||
| 68 | + <td>Attribute</td> | ||
| 69 | + <td>Threshold parameter of Softshrink, λ in the formula. Default value: 0.5. NaN and negative values are rejected as invalid parameters; +Inf is allowed.</td> | ||
| 70 | + <td>FLOAT</td> | ||
| 71 | + <td>-</td> | ||
| 72 | + </tr> | ||
| 70 | </tbody></table> | 73 | </tbody></table> |
| 71 | 74 | ||
| 72 | ## Constraints | 75 | ## Constraints |
| 73 | 76 | ||
| 74 | - Only the ND data format is supported. | 77 | - Only the ND data format is supported. |
| 75 | -- The dtype of input x is fp16/fp32/bf16, and output y has the same dtype as input x. | 78 | +- The dtype of input_x is fp16/fp32/bf16, and output_y has the same dtype as input_x. Atlas inference/training products do not support BF16 and support only FLOAT and FLOAT16. |
| 76 | - Inputs of any rank are supported (0D to 8D). A 0D scalar input is processed as a 1D tensor with shape (1,). | 79 | - Inputs of any rank are supported (0D to 8D). A 0D scalar input is processed as a 1D tensor with shape (1,). |
| 77 | -- The value range of lambd is [0, +∞). Negative values and nan are not allowed. | 80 | +- lambd must be a FLOAT scalar in the range [0, +∞): 0, positive values, and +Inf are allowed; negative values and NaN return an invalid-parameter error. |
| 81 | +- In the Ascend C implementation in this repository, when input_x is NaN, the output is 0. NaN is not propagated; callers that rely on NaN propagation should note this difference. | ||
| 78 | - Empty tensors (with 0 elements) are supported, and an empty output of the same shape is directly returned. | 82 | - Empty tensors (with 0 elements) are supported, and an empty output of the same shape is directly returned. |
| 79 | - Dynamic shapes (including -1 dimensions) are supported: tiling computes the split based on the actual shape at runtime, without recompilation. | 83 | - Dynamic shapes (including -1 dimensions) are supported: tiling computes the split based on the actual shape at runtime, without recompilation. |
| 80 | - Deterministic implementation by default: the same input always produces the same output. | 84 | - Deterministic implementation by default: the same input always produces the same output. |
| 81 | 85 | ||
| 82 | ## Invocation Description | 86 | ## Invocation Description |
| 83 | 87 | ||
| 84 | -| Invocation method | Invocation sample | Description | | 88 | +| Invocation method | Sample code | Description | |
| 85 | |--------------|------------------------------------------------------------------------|--------------------------------------------------------------| | 89 | |--------------|------------------------------------------------------------------------|--------------------------------------------------------------| |
| 86 | -| aclnn invocation | [test_aclnn_softshrink.cpp](./examples/test_aclnn_softshrink.cpp) | Invoke the Softshrink operator through the [aclnnSoftshrink](./docs/aclnnSoftshrink_en.md) API. | | 90 | +| aclnn API | [test_aclnn_softshrink.cpp](./examples/test_aclnn_softshrink.cpp) | Invoke the Softshrink operator through the [aclnnSoftshrink](./docs/aclnnSoftshrink_en.md) API. | |
| 91 | +| GE graph mode | [softshrink_proto.h](./op_graph/softshrink_proto.h) | Invoke the Softshrink operator by constructing a graph with the operator IR. | | ||
| 92 | + | ||
| 93 | +> For sample compilation and execution, see the [aclnnSoftshrink sample](./docs/aclnnSoftshrink_en.md#example) and the CANN sample compilation and execution guide. | ||
| @@ -21,6 +21,8 @@ | |||
| 21 | - <term>Atlas训练系列产品</term>:支持 | 21 | - <term>Atlas训练系列产品</term>:支持 |
| 22 | <!-- end id6 --> | 22 | <!-- end id6 --> |
| 23 | 23 | ||
| 24 | +> 说明:Ascend 950PR/950DT 由本仓 Ascend C 实现提供;Atlas A3/A2、Atlas推理/训练由 canndev TBE 实现承接;Atlas 200I/500 A2 无对应二进制配置,不支持。Atlas推理/训练仅支持 FLOAT、FLOAT16,不支持 BFLOAT16。 | ||
| 25 | + | ||
| 24 | ## 功能说明 | 26 | ## 功能说明 |
| 25 | 27 | ||
| 26 | - 接口功能:以元素为单位,强制收缩λ范围内的元素。 | 28 | - 接口功能:以元素为单位,强制收缩λ范围内的元素。 |
| @@ -96,17 +98,17 @@ aclnnStatus aclnnSoftshrink( | |||
| 96 | <td>lambd(aclScalar*)</td> | 98 | <td>lambd(aclScalar*)</td> |
| 97 | <td>输入</td> | 99 | <td>输入</td> |
| 98 | <td>输入的标量,公式中的输入λ。</td> | 100 | <td>输入的标量,公式中的输入λ。</td> |
| 99 | - <td>数值要求大于等于0。接口内部将标量转换为FLOAT参与计算,非FLOAT类型存在精度转换(如DOUBLE按IEEE754舍入到FLOAT、超出FLOAT表示范围的整数会丢失精度),阈值精度敏感场景建议直接传入FLOAT标量。</td> | 101 | + <td>必须为FLOAT标量且数值大于等于0;负数和NaN返回参数非法错误,+Inf合法。</td> |
| 100 | - <td>除COMPLEX64、COMPLEX128外的数值标量类型</td> | 102 | + <td>FLOAT</td> |
| 101 | - <td>ND</td> | 103 | + <td>-</td> |
| 102 | - <td>0-8</td> | 104 | + <td>-</td> |
| 103 | - <td>√</td> | 105 | + <td>-</td> |
| 104 | </tr> | 106 | </tr> |
| 105 | <tr> | 107 | <tr> |
| 106 | <td>out(aclTensor*)</td> | 108 | <td>out(aclTensor*)</td> |
| 107 | <td>输出</td> | 109 | <td>输出</td> |
| 108 | <td>Softshrink计算的出参。</td> | 110 | <td>Softshrink计算的出参。</td> |
| 109 | - <td><ul><li>支持空Tensor。</li><li>shape需要与self一致。</li></ul></td> | 111 | + <td><ul><li>支持空Tensor。</li><li>shape需要与self一致。</li><li>dtype可以与self不同,接口按out的dtype进行Cast;建议与self一致以避免精度损失。</li></ul></td> |
| 110 | <td>FLOAT、FLOAT16、BFLOAT16</td> | 112 | <td>FLOAT、FLOAT16、BFLOAT16</td> |
| 111 | <td>ND</td> | 113 | <td>ND</td> |
| 112 | <td>0-8</td> | 114 | <td>0-8</td> |
| @@ -164,10 +166,13 @@ aclnnStatus aclnnSoftshrink( | |||
| 164 | <td>传入的self、lambd或out是空指针。</td> | 166 | <td>传入的self、lambd或out是空指针。</td> |
| 165 | </tr> | 167 | </tr> |
| 166 | <tr> | 168 | <tr> |
| 167 | - <td rowspan="4">ACLNN_ERR_PARAM_INVALID</td> | 169 | + <td rowspan="5">ACLNN_ERR_PARAM_INVALID</td> |
| 168 | - <td rowspan="4">161002</td> | 170 | + <td rowspan="5">161002</td> |
| 169 | <td>self或out的数据类型不在支持的范围之内。</td> | 171 | <td>self或out的数据类型不在支持的范围之内。</td> |
| 170 | </tr> | 172 | </tr> |
| 173 | + <tr> | ||
| 174 | + <td>lambd的数据类型不是FLOAT。</td> | ||
| 175 | + </tr> | ||
| 171 | <tr> | 176 | <tr> |
| 172 | <td>self和out的shape不一致。</td> | 177 | <td>self和out的shape不一致。</td> |
| 173 | </tr> | 178 | </tr> |
| @@ -175,7 +180,7 @@ aclnnStatus aclnnSoftshrink( | |||
| 175 | <td>self或out的维数大于8。</td> | 180 | <td>self或out的维数大于8。</td> |
| 176 | </tr> | 181 | </tr> |
| 177 | <tr> | 182 | <tr> |
| 178 | - <td>lambd < 0。</td> | 183 | + <td>lambd < 0 或 lambd 为 NaN。</td> |
| 179 | </tr> | 184 | </tr> |
| 180 | </tbody></table> | 185 | </tbody></table> |
| 181 | 186 | ||
| @@ -227,10 +232,11 @@ aclnnStatus aclnnSoftshrink( | |||
| 227 | - 确定性计算: | 232 | - 确定性计算: |
| 228 | - aclnnSoftshrink默认确定性实现。 | 233 | - aclnnSoftshrink默认确定性实现。 |
| 229 | 234 | ||
| 230 | -- 数据格式仅支持ND;out的dtype与self一致。 | 235 | +- 数据格式仅支持ND。 |
| 231 | - self支持0~8维输入;0维标量输入会被视作shape为(1,)的1维tensor处理。 | 236 | - self支持0~8维输入;0维标量输入会被视作shape为(1,)的1维tensor处理。 |
| 232 | -- lambd取值范围为[0, +∞),不允许为负数或nan。 | 237 | +- out的dtype可以与self不同,接口按out的dtype进行Cast;建议与self一致以避免精度损失。 |
| 233 | -- lambd支持除复数外的数值标量类型,接口内部统一转换为FLOAT后参与计算;非FLOAT标量存在精度转换,阈值精度敏感场景建议直接使用FLOAT标量。 | 238 | +- lambd仅支持FLOAT标量,取值范围为[0, +∞):允许0、正数和+Inf,负数或NaN返回ACLNN_ERR_PARAM_INVALID(161002)。 |
| 239 | +- 输入self为NaN时,输出为0,不进行NaN透传;依赖NaN传播的调用方需注意该差异。 | ||
| 234 | - 支持空Tensor(元素个数为0),直接返回同shape的空输出。 | 240 | - 支持空Tensor(元素个数为0),直接返回同shape的空输出。 |
| 235 | - 支持动态shape(含-1维度):tiling在运行期按实际shape计算切分,无需重新编译。 | 241 | - 支持动态shape(含-1维度):tiling在运行期按实际shape计算切分,无需重新编译。 |
| 236 | 242 | ||
| @@ -23,6 +23,8 @@ | |||
| 23 | - <term>Atlas training products</term>: Supported | 23 | - <term>Atlas training products</term>: Supported |
| 24 | <!-- end id6 --> | 24 | <!-- end id6 --> |
| 25 | 25 | ||
| 26 | +> Note: Ascend 950PR/950DT is provided by the Ascend C implementation in this repository; Atlas A3/A2 and Atlas inference/training products are provided by the canndev TBE implementation. Atlas 200I/500 A2 has no corresponding binary configuration and is not supported. Atlas inference/training products support only FLOAT and FLOAT16, not BFLOAT16. | ||
| 27 | + | ||
| 26 | ## Function | 28 | ## Function |
| 27 | 29 | ||
| 28 | - Description: Performs element-wise Hardshrink, forcing elements within the range of λ to zero. | 30 | - Description: Performs element-wise Hardshrink, forcing elements within the range of λ to zero. |
| @@ -98,17 +100,17 @@ aclnnStatus aclnnSoftshrink( | |||
| 98 | <td>lambd(aclScalar*)</td> | 100 | <td>lambd(aclScalar*)</td> |
| 99 | <td>Input</td> | 101 | <td>Input</td> |
| 100 | <td>Input scalar, which is λ in the formula.</td> | 102 | <td>Input scalar, which is λ in the formula.</td> |
| 101 | - <td>The value must be greater than or equal to 0.</td> | 103 | + <td>Must be a FLOAT scalar greater than or equal to 0. Negative values and NaN return an invalid-parameter error; +Inf is allowed.</td> |
| 102 | <td>FLOAT</td> | 104 | <td>FLOAT</td> |
| 103 | - <td>ND</td> | 105 | + <td>-</td> |
| 104 | - <td>0-8</td> | 106 | + <td>-</td> |
| 105 | - <td>√</td> | 107 | + <td>-</td> |
| 106 | </tr> | 108 | </tr> |
| 107 | <tr> | 109 | <tr> |
| 108 | <td>out (aclTensor*)</td> | 110 | <td>out (aclTensor*)</td> |
| 109 | <td>Output</td> | 111 | <td>Output</td> |
| 110 | <td>Output parameter of the Softshrink computation.</td> | 112 | <td>Output parameter of the Softshrink computation.</td> |
| 111 | - <td><ul><li>Supports empty tensors.</li><li>The shape must be the same as that of self.</li></ul></td> | 113 | + <td><ul><li>Supports empty tensors.</li><li>The shape must be the same as that of self.</li><li>The dtype can differ from that of self; the API casts the result to the out dtype. Using the same dtype as self is recommended to avoid precision loss.</li></ul></td> |
| 112 | <td>FLOAT, FLOAT16, BFLOAT16</td> | 114 | <td>FLOAT, FLOAT16, BFLOAT16</td> |
| 113 | <td>ND</td> | 115 | <td>ND</td> |
| 114 | <td>0-8</td> | 116 | <td>0-8</td> |
| @@ -166,9 +168,12 @@ aclnnStatus: return status code. For details, see [aclnn Return Codes](../../../ | |||
| 166 | <td>self, lambd, or out is a null pointer.</td> | 168 | <td>self, lambd, or out is a null pointer.</td> |
| 167 | </tr> | 169 | </tr> |
| 168 | <tr> | 170 | <tr> |
| 169 | - <td rowspan="4">ACLNN_ERR_PARAM_INVALID</td> | 171 | + <td rowspan="5">ACLNN_ERR_PARAM_INVALID</td> |
| 170 | - <td rowspan="4">161002</td> | 172 | + <td rowspan="5">161002</td> |
| 171 | - <td>The data type of self, lambd, or out is not within the supported range.</td> | 173 | + <td>The data type of self or out is not within the supported range.</td> |
| 174 | + </tr> | ||
| 175 | + <tr> | ||
| 176 | + <td>The data type of lambd is not FLOAT.</td> | ||
| 172 | </tr> | 177 | </tr> |
| 173 | <tr> | 178 | <tr> |
| 174 | <td>The shapes of self and out are inconsistent.</td> | 179 | <td>The shapes of self and out are inconsistent.</td> |
| @@ -177,7 +182,7 @@ aclnnStatus: return status code. For details, see [aclnn Return Codes](../../../ | |||
| 177 | <td>The dimension of self or out is greater than 8.</td> | 182 | <td>The dimension of self or out is greater than 8.</td> |
| 178 | </tr> | 183 | </tr> |
| 179 | <tr> | 184 | <tr> |
| 180 | - <td>lambd is less than 0.</td> | 185 | + <td>lambd is less than 0 or is NaN.</td> |
| 181 | </tr> | 186 | </tr> |
| 182 | </tbody></table> | 187 | </tbody></table> |
| 183 | 188 | ||
| @@ -229,6 +234,14 @@ aclnnStatus: return status code. For details, see [aclnn Return Codes](../../../ | |||
| 229 | - Deterministic computation: | 234 | - Deterministic computation: |
| 230 | - aclnnSoftshrink defaults to a deterministic implementation. | 235 | - aclnnSoftshrink defaults to a deterministic implementation. |
| 231 | 236 | ||
| 237 | +- Only the ND data format is supported. | ||
| 238 | +- self supports 0D to 8D input. A 0D scalar input is processed as a 1D tensor with shape (1,). | ||
| 239 | +- The dtype of out can differ from that of self; the API casts the result to the out dtype. Using the same dtype as self is recommended to avoid precision loss. | ||
| 240 | +- lambd must be a FLOAT scalar in the range [0, +∞): 0, positive values, and +Inf are allowed; negative values and NaN return ACLNN_ERR_PARAM_INVALID(161002). | ||
| 241 | +- When self is NaN, the output is 0. NaN is not propagated; callers that rely on NaN propagation should note this difference. | ||
| 242 | +- Empty tensors (with 0 elements) are supported, and an empty output of the same shape is directly returned. | ||
| 243 | +- Dynamic shapes (including -1 dimensions) are supported: tiling computes the split based on the actual shape at runtime, without recompilation. | ||
| 244 | + | ||
| 232 | ## Example | 245 | ## Example |
| 233 | 246 | ||
| 234 | The following sample code is for reference only. For the compilation and execution procedure, see [Compile and Run Samples](../../../docs/en/context/compile_and_run_sample.md). | 247 | The following sample code is for reference only. For the compilation and execution procedure, see [Compile and Run Samples](../../../docs/en/context/compile_and_run_sample.md). |
| @@ -8,8 +8,12 @@ | |||
| 8 | | <term>Atlas A3系列产品</term> | √ | | 8 | | <term>Atlas A3系列产品</term> | √ | |
| 9 | | <term>Atlas A2系列产品</term> | √ | | 9 | | <term>Atlas A2系列产品</term> | √ | |
| 10 | | <term>Atlas 200I/500 A2推理产品</term> | × | | 10 | | <term>Atlas 200I/500 A2推理产品</term> | × | |
| 11 | -| <term>Atlas推理系列产品</term> | × | | 11 | +| <term>Atlas推理系列产品</term> | √ | |
| 12 | -| <term>Atlas训练系列产品</term> | × | | 12 | +| <term>Atlas训练系列产品</term> | √ | |
| 13 | + | ||
| 14 | +> 说明: | ||
| 15 | +> - Ascend 950PR/950DT 由本仓 Ascend C 实现提供(OpDef 注册 ascend950/ascend350,构建 ascend950/ascend350);Atlas A3/A2、Atlas推理/训练由 canndev TBE 实现承接;Atlas 200I/500 A2 无对应二进制配置,不支持。 | ||
| 16 | +> - 当前各实现的数据类型均为 FLOAT(var/accum/linear/grad/lr/l1/l2/lr_power)与 INT32/INT64(indices),数据格式为 ND。 | ||
| 13 | 17 | ||
| 14 | ## 功能说明 | 18 | ## 功能说明 |
| 15 | 19 | ||
| @@ -146,7 +150,7 @@ $$ | |||
| 146 | <tr> | 150 | <tr> |
| 147 | <td>use_locking</td> | 151 | <td>use_locking</td> |
| 148 | <td>属性</td> | 152 | <td>属性</td> |
| 149 | - <td>是否使用锁保护更新操作(当前实现未使用)</td> | 153 | + <td>可选属性,默认false。是否使用锁保护更新操作;当前实现未使用该属性,不改变更新行为。</td> |
| 150 | <td>BOOL</td> | 154 | <td>BOOL</td> |
| 151 | <td>-</td> | 155 | <td>-</td> |
| 152 | </tr> | 156 | </tr> |
| @@ -154,28 +158,22 @@ $$ | |||
| 154 | 158 | ||
| 155 | ## 约束说明 | 159 | ## 约束说明 |
| 156 | 160 | ||
| 157 | -1. var/accum/linear必须具有相同的shape和dtype(float32)。 | 161 | +1. var/accum/linear必须具有相同的shape和dtype(FLOAT)。 |
| 158 | -2. grad.shape[1:] 必须等于var.shape[1:],grad.shape[0] 必须等于indices.shape[0]。 | 162 | +2. grad必须与var维数相同;grad.shape[0]必须等于indices.shape[0],grad.shape[1:]必须等于var.shape[1:]。 |
| 159 | -3. indices必须为1-D tensor。 | 163 | +3. indices必须为1-D tensor,dtype为INT32或INT64。 |
| 160 | -4. lr/l1/l2/lr\_power为标量tensor(0-D)。 | 164 | +4. lr/l1/l2/lr\_power为标量tensor,形态为0-D或shape为[1]的1-D tensor;动态shape(-1/-2)在InferShape中按动态处理,`(1,1)`等更高维形态会被拒绝。 |
| 161 | -5. **lr为学习率,作为输入时不能为0**。 | 165 | +5. **本仓Ascend C实现要求var/accum/linear至少为2维,当前未显式校验rank上限(受框架/接口限制)**;Atlas A3/A2等由canndev TBE承接的实现对rank下限较宽(允许1-D var),跨产品使用时请按对应实现版本约束准备输入。 |
| 162 | -6. **indices必须唯一**(不可有重复值)。TensorFlow和Ascend官方均声明:indices重复时行为未定义。 | 166 | +6. **lr为学习率,调用方必须保证lr > 0**;l1、l2应大于等于0,lr\_power应小于等于0。Host/Tiling不读取设备侧标量值,因此不做运行时值域校验,非法值会导致结果未定义。 |
| 163 | -7. **indices取值范围必须满足0 <= indices[i] < var.shape[0]**。kernel不做运行时越界检查,越界将导致内存越界读写。 | 167 | +7. **indices必须唯一**(不可有重复值)。TensorFlow和Ascend官方均声明:indices重复时行为未定义;当前实现未做运行时重复检查。 |
| 164 | -8. **输入tensor必须为连续内存布局**。kernel使用扁平寻址假设连续内存;`AutoContiguous()`仅在aclnn通路生效,geir/tf通路需调用方保证输入连续。 | 168 | +8. **indices取值范围必须满足0 <= indices[i] < var.shape[0]**。kernel不做运行时越界检查,越界将导致内存越界读写。 |
| 169 | +9. **输入tensor必须为连续内存布局**。kernel使用扁平寻址假设连续内存;`AutoContiguous()`只在aclnn通路生效,geir/tf通路需调用方保证输入连续。 | ||
| 170 | +10. **输出var/accum/linear为独立输出缓冲,不与输入原地共享存储**。调用方应使用输出tensor获取更新结果。 | ||
| 171 | +11. **数据格式仅支持ND**。本版本binary_config仅提供FLOAT+INT32/INT64、ND的组合;历史版本中的NCHW/NHWC等位置化组合不在本版本支持范围内。 | ||
| 165 | 172 | ||
| 166 | ## 调用说明 | 173 | ## 调用说明 |
| 167 | 174 | ||
| 168 | -<table><thead> | 175 | +| 调用方式 | 样例代码 | 说明 | |
| 169 | - <tr> | 176 | +|:---|:---|:---| |
| 170 | - <th>调用方式</th> | 177 | +| GE图模式 | [test_geir_sparse_apply_ftrl.cpp](./examples/test_geir_sparse_apply_ftrl.cpp) | 通过[SparseApplyFtrl算子IR](./op_graph/sparse_apply_ftrl_proto.h)构图方式调用SparseApplyFtrl算子。 | |
| 171 | - <th>调用样例</th> | 178 | + |
| 172 | - <th>说明</th> | 179 | +> TensorFlow通路当前仅注册`SparseApplyFtrl`;`ResourceSparseApplyFtrl`未在本仓插件中注册,由canndev实现承接。示例的编译与运行请参考CANN样例编译运行说明。 |
| 173 | - </tr></thead> | ||
| 174 | -<tbody> | ||
| 175 | - <tr> | ||
| 176 | - <td>图模式调用</td> | ||
| 177 | - <td><a>-</a></td> | ||
| 178 | - <td>通过[算子IR]<a href="op_graph/sparse_apply_ftrl_proto.h">(..op_graph/sparse_apply_ftrl_proto.h)</a>构图方式调用SparseApplyFtrl算子。</td> | ||
| 179 | - </tr> | ||
| 180 | -</tbody> | ||
| 181 | -</table> | ||
| @@ -10,8 +10,12 @@ English | [简体中文](./README.md) | |||
| 10 | | <term>Atlas A3 products</term> | √ | | 10 | | <term>Atlas A3 products</term> | √ | |
| 11 | | <term>Atlas A2 products</term> | √ | | 11 | | <term>Atlas A2 products</term> | √ | |
| 12 | | <term>Atlas 200I/500 A2 inference products</term> | × | | 12 | | <term>Atlas 200I/500 A2 inference products</term> | × | |
| 13 | -| <term>Atlas inference products</term> | × | | 13 | +| <term>Atlas inference products</term> | √ | |
| 14 | -| <term>Atlas training products</term> | × | | 14 | +| <term>Atlas training products</term> | √ | |
| 15 | + | ||
| 16 | +> Notes: | ||
| 17 | +> - Ascend 950PR/950DT is provided by the Ascend C implementation in this repository (OpDef registers ascend950/ascend350; the build covers ascend950/ascend350). Atlas A3/A2 and Atlas inference/training products are provided by the canndev TBE implementation. Atlas 200I/500 A2 has no corresponding binary configuration and is not supported. | ||
| 18 | +> - The current implementations use FLOAT for var/accum/linear/grad/lr/l1/l2/lr_power, INT32/INT64 for indices, and the ND data format. | ||
| 15 | 19 | ||
| 16 | ## Function | 20 | ## Function |
| 17 | 21 | ||
| @@ -148,7 +152,7 @@ $$ | |||
| 148 | <tr> | 152 | <tr> |
| 149 | <td>use_locking</td> | 153 | <td>use_locking</td> |
| 150 | <td>Attribute</td> | 154 | <td>Attribute</td> |
| 151 | - <td>Specifies whether to use a lock to protect the update operation (not used in the current implementation)</td> | 155 | + <td>Optional attribute. Default value: false. Specifies whether to use a lock to protect the update operation. The current implementation does not use this attribute and its value does not change the update behavior.</td> |
| 152 | <td>BOOL</td> | 156 | <td>BOOL</td> |
| 153 | <td>-</td> | 157 | <td>-</td> |
| 154 | </tr> | 158 | </tr> |
| @@ -156,28 +160,22 @@ $$ | |||
| 156 | 160 | ||
| 157 | ## Constraints | 161 | ## Constraints |
| 158 | 162 | ||
| 159 | -1. var/accum/linear must have the same shape and dtype (float32). | 163 | +1. var/accum/linear must have the same shape and dtype (FLOAT). |
| 160 | -2. grad.shape[1:] must equal var.shape[1:], and grad.shape[0] must equal indices.shape[0]. | 164 | +2. grad must have the same rank as var; grad.shape[0] must equal indices.shape[0], and grad.shape[1:] must equal var.shape[1:]. |
| 161 | -3. indices must be a 1-D tensor. | 165 | +3. indices must be a 1-D tensor with dtype INT32 or INT64. |
| 162 | -4. lr/l1/l2/lr\_power are scalar tensors (0-D). | 166 | +4. lr/l1/l2/lr\_power are scalar tensors in the form of a 0-D tensor or a 1-D tensor with shape [1]. Dynamic shapes (-1/-2) are handled as dynamic in InferShape; higher-rank forms such as `(1,1)` are rejected. |
| 163 | -5. **lr is the learning rate and cannot be 0 when passed in as an input**. | 167 | +5. **The Ascend C implementation in this repository requires var/accum/linear to have at least 2 dimensions; the rank upper bound is not explicitly validated by this operator and is subject to framework/interface limits**. Implementations backed by canndev TBE (for example, Atlas A3/A2) accept a lower rank bound (1-D var is allowed). When using multiple products, prepare inputs according to the constraints of the corresponding implementation version. |
| 164 | -6. **indices must be unique** (duplicate values are not allowed). Both TensorFlow and Ascend officially state that the behavior is undefined when indices contain duplicates. | 168 | +6. **lr is the learning rate; the caller must ensure lr > 0**. l1 and l2 should be greater than or equal to 0, and lr\_power should be less than or equal to 0. Host/Tiling does not read device-side scalar values, so no runtime value-range validation is performed; invalid values lead to undefined results. |
| 165 | -7. **The value range of indices must satisfy 0 <= indices[i] < var.shape[0]**. The kernel does not perform a runtime out-of-bounds check; going out of bounds will cause out-of-bounds memory reads and writes. | 169 | +7. **indices must be unique** (duplicate values are not allowed). Both TensorFlow and Ascend officially state that the behavior is undefined when indices contain duplicates; the current implementation does not perform a runtime duplicate check. |
| 166 | -8. **The input tensors must have a contiguous memory layout**. The kernel uses flat addressing, which assumes contiguous memory; `AutoContiguous()` takes effect only on the aclnn path, and on the geir/tf path the caller must guarantee that the inputs are contiguous. | 170 | +8. **The value range of indices must satisfy 0 <= indices[i] < var.shape[0]**. The kernel does not perform a runtime out-of-bounds check; going out of bounds will cause out-of-bounds memory reads and writes. |
| 171 | +9. **The input tensors must have a contiguous memory layout**. The kernel uses flat addressing, which assumes contiguous memory; `AutoContiguous()` takes effect only on the aclnn path, and on the geir/tf path the caller must guarantee that the inputs are contiguous. | ||
| 172 | +10. **The outputs var/accum/linear are independent output buffers and do not share storage in-place with the inputs**. The caller should use the output tensors to obtain the updated results. | ||
| 173 | +11. **Only the ND data format is supported**. The current binary_config provides only FLOAT + INT32/INT64 with ND. Positional formats such as NCHW/NHWC from historical versions are not supported in this version. | ||
| 167 | 174 | ||
| 168 | ## Invocation Description | 175 | ## Invocation Description |
| 169 | 176 | ||
| 170 | -<table><thead> | 177 | +| Invocation method | Sample code | Description | |
| 171 | - <tr> | 178 | +|:---|:---|:---| |
| 172 | - <th>Invocation method</th> | 179 | +| GE graph mode | [test_geir_sparse_apply_ftrl.cpp](./examples/test_geir_sparse_apply_ftrl.cpp) | Invokes the SparseApplyFtrl operator by constructing a graph with the [SparseApplyFtrl operator IR](./op_graph/sparse_apply_ftrl_proto.h). | |
| 173 | - <th>Invocation sample</th> | 180 | + |
| 174 | - <th>Description</th> | 181 | +> The TensorFlow path currently registers only `SparseApplyFtrl`. `ResourceSparseApplyFtrl` is not registered in the plugin in this repository and is provided by the canndev implementation. For sample compilation and execution, see the CANN sample compilation and execution guide. |
| 175 | - </tr></thead> | ||
| 176 | -<tbody> | ||
| 177 | - <tr> | ||
| 178 | - <td>Graph-mode invocation</td> | ||
| 179 | - <td><a>-</a></td> | ||
| 180 | - <td>Invokes the SparseApplyFtrl operator by constructing the graph through the [operator IR] <a href="op_graph/sparse_apply_ftrl_proto.h">(..op_graph/sparse_apply_ftrl_proto.h)</a>.</td> | ||
| 181 | - </tr> | ||
| 182 | -</tbody> | ||
| 183 | -</table> | ||
🟡 Medium Priority
变更行:activation/softshrink/docs/aclnnSoftshrink.md:101(“必须为FLOAT标量…负数和NaN返回参数非法错误”)以及配套新增的错误码行 :174(“lambd的数据类型不是FLOAT。”)、约束行 :238,README.md:78 做了同样声明。
证据链:本仓 op_api 的参数校验入口 op_api/aclnn_softshrink.cpp 的 CheckParams(self, lambd, out) 只有 5 步——CheckNotNull、CheckDtypeValid(self, out)、CheckShape(self, out)、CheckLambdValue(lambd)、CheckFormat(self, out);其中 CheckDtypeValid(aclnn_softshrink.cpp:44-63)只对 self/out 做 OP_CHECK_DTYPE_NOT_SUPPORT,CheckLambdValue(:89-98)仅做
!(lambd->ToFloat() >= 0.0f)值域判断,后续调用是l0op::SoftShrink(selfContiguous, lambd->ToFloat(), ...)(:151)。即:当前实现接受任意数值类型的 aclScalar(如 DOUBLE/INT32),统一 ToFloat 后继续计算,不会返回 ACLNN_ERR_PARAM_INVALID(161002)。失败模式:调用方按新文档预期“传 DOUBLE 标量 → 得到 161002”来处理(例如据此做参数兼容判断或断言失败路径),实际拿到的是 ACLNN_SUCCESS + 静默的 DOUBLE→FLOAT 精度截断,问题被延后到精度偏差而非报错;对阈值精度敏感的场景尤其误导。PR 描述也承认该约束依赖尚未合入的代码 PR !13609。
建议:与代码 PR !13609 同步合入该约束;若无法同步,请在本行及 :174、:238 处标注适用版本,或改回“非 FLOAT 会被转换为 FLOAT 参与计算”的当前行为描述。