Merged
docs(softshrink,sparse_apply_ftrl): 对齐代码实现修正产品支持与约束说明 #13829
docs(softshrink,sparse_apply_ftrl): 对齐代码实现修正产品支持与约束说明 #13829
Merged
小王!Add on 15 days ago
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## Function20## 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## Constraints75## 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 Description86## 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>
atomgit-bot
atomgit-botatomgit-bot15 days ago

🟡 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 参与计算”的当前行为描述。

likedislike
Incorrect?
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>: Supported23- <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## Function28## 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## Example245## Example
233 246 
234The 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).247The 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## Function20## 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## Constraints161## 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 Description175## 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>