!29480 THOR中文API修改

Merge pull request !29480 from melody/master

docs/api/api_python/nn/mindspore.nn.thor.txt

@@ -0,0 +1,75 @@
+mindspore.nn.thor(net, learning_rate, damping, momentum, weight_decay=0.0, loss_scale=1.0, batch_size=32, use_nesterov=False, decay_filter=<function <lambda> at 0x0000029724CFA048>, split_indices=None, enable_clip_grad=False, frequency=100)
+
+    通过二阶算法THOR更新参数。
+
+    基于跟踪的、硬件驱动层定向的自然梯度下降计算（THOR）算法论文地址为：
+
+    `THOR: Trace-based Hardware-driven layer-ORiented Natural Gradient Descent Computation <https://www.aaai.org/AAAI21Papers/AAAI-6611.ChenM.pdf>`_
+
+    更新公式如下：
+
+    .. math::
+        \begin{array}{ll} \\
+            A_i = a_i{a_i}^T \\
+            G_i = D_{s_i}{ D_{s_i}}^T \\
+            m_i = \beta * m_i + ({G_i^{(k)}}+\lambda I)^{-1}) g_i ({\overline A_{i-1}^{(k)}}+\lambda I)^{-1} \\
+            w_i = w_i - \alpha * m_i \\
+        \end{array}
+
+    :math:`D_{s_i}`表示第i层输出的loss函数的导数。
+    :math:`a_{i-1}`表示第i层的输入，它是上一层的激活。
+    :math:`\beta`表示动量，:math:`I`代表单位矩阵。
+    :math:`\overline A`表示矩阵A的转置。
+    :math:`\lambda`表示'damping'，:math:`g_i`表示第i层的梯度。
+    :math:`\otimes`表示克罗内克尔积，:math:`\alpha`表示学习率。
+
+    注：
+        在分离参数组时，如果权重衰减为正，则每个组的权重衰减将应用于参数。当不分离参数组时，如果`weight_decay`为正数，则API中的`weight_decay`将应用于名称中没有'beta'或 'gamma'的参数。
+
+        在分离参数组时，如果要集中梯度，请将grad_centralization设置为True，但梯度集中只能应用于卷积层的参数。
+        如果非卷积层的参数设置为True，则会报错。
+
+        为了提高参数组的性能，可以支持参数的自定义顺序。
+
+    参数：
+        net (Cell)：训练网络。
+
+        learning_rate (Tensor)：学习率的值。
+
+        damping (Tensor)：阻尼值。
+
+        momentum (float)：float类型的超参数，表示移动平均的动量。至少为0.0。
+
+        weight_decay (int, float)：权重衰减（L2 penalty）。必须等于或大于0.0。默认值：0.0。
+
+        loss_scale (float)：loss缩放的值。必须大于0.0。一般情况下，使用默认值。默认值：1.0。
+
+        batch_size (int)：batch的大小。默认值：32。
+
+        use_nesterov (bool)：启用Nesterov动量。默认值：False。
+
+        decay_filter (function)：用于确定权重衰减应用于哪些层的函数，只有在weight_decay>0时才有效。默认值：lambda x: x.name not in []。
+
+        split_indices (list)：按A/G层（A/G含义见上述公式）索引设置allreduce融合策略。仅在分布式计算中有效。ResNet50作为一个样本，A/G的层数分别为54层，当split_indices设置为[26,53]时，表示A/G被分成两组allreduce，一组为0~26层，另一组是27~53层。默认值：None。
+
+        enable_clip_grad (bool)：是否剪切梯度。默认值：False。
+
+        frequency(int)：A/G和$A^{-1}/G^{-1}$的更新间隔。当频率等于N（N大于1）时，A/G和$A^{-1}/G^{-1}$将每N步更新一次，和其他步骤将使用过时的A/G和$A^{-1}/G^{-1}$更新权重。默认值：100。
+
+    输入：
+        - **gradients** （tuple[Tensor]） - 训练参数的梯度，矩阵维度与训练参数相同。
+
+    输出：
+        tuple[bool]，所有元素都为True。
+
+    异常：
+        TypeError：`learning_rate`不是张量。
+        TypeError：`loss_scale`、`momentum`或`frequency`不是浮点数。
+        TypeError：`weight_decay`既不是浮点数也不是整数。
+        TypeError：`use_nesterov`不是布尔值。
+        TypeError：`frequency`不是整数。
+        ValueError：`loss_scale`小于或等于0。
+        ValueError：`weight_decay`或`momentum`小于0。
+        ValueError：`frequency`小于2。
+
+    

docs/api/api_python/train/mindspore.train.train_thor.ConvertModelUtils.txt

@@ -0,0 +1,58 @@
+Class mindspore.train.train_thor.ConvertModelUtils
+
+    该接口用于增加计算图，提升二阶算法THOR运行时的性能。
+    
+
+convert_to_thor_model(model, network, loss_fn=None, optimizer=None, metrics=None, amp_level='O0', loss_scale_manager=None, keep_batchnorm_fp32=False)
+
+        该接口用于增加计算图，提升二阶算法THOR运行时的性能。
+
+        参数：
+            model (Object)：用于训练的高级API。
+                            `Model`将图层分组到具有训练特征的对象中。
+            network (Cell)：训练网络。
+            loss_fn (Cell)：目标函数。默认值：None。
+            optimizer (Cell)：用于更新权重的优化器。默认值：None。
+            metrics (Union[dict, set])：在训练期间由模型评估的词典或一组度量。例如：{'accuracy', 'recall'}。默认值：None。
+            amp_level (str)：混合精度训练的级别。支持["O0", "O2", "O3", "auto"]。默认值："O0"。
+
+                - O0：不改变。
+                - O2：将网络转换为float16，使用动态loss scale保持BN在float32中运行。
+                - O3：将网络强制转换为float16，并使用附加属性`keep_batchnorm_fp32=False`。
+                - auto：在不同设备中，将级别设置为建议级别。GPU上建议使用O2，Ascend上建议使用O3。建议级别基于专家经验，不能总是一概而论。用户应指定特殊网络的级别。
+
+            loss_scale_manager (Union[None, LossScaleManager])：如果为None，则不会按比例缩放loss。
+                否则，通过LossScaleManager和优化器缩放loss不能为None。这是一个关键参数。
+                例如，使用`loss_scale_manager=None`设置值。
+            keep_batchnorm_fp32 (bool)：保持BN在`float32`中运行。如果为True，则将覆盖之前的级别设置。默认值：False。
+
+        返回：
+             model (Object)：用于训练的高级API。
+                            `Model`将图层分组到具有训练特征的对象中。
+
+        支持平台：
+            ``Ascend`` ``GPU``
+
+        示例：
+            >>> from mindspore import nn
+            >>> from mindspore import Tensor
+            >>> from mindspore.nn import thor
+            >>> from mindspore import Model
+            >>> from mindspore import FixedLossScaleManager
+            >>> from mindspore.train.callback import LossMonitor
+            >>> from mindspore.train.train_thor import ConvertModelUtils
+            >>>
+            >>> net = Net()
+            >>> dataset = create_dataset()
+            >>> temp = Tensor([4e-4, 1e-4, 1e-5, 1e-5], mstype.float32)
+            >>> opt = thor(net, learning_rate=temp, damping=temp, momentum=0.9, loss_scale=128, frequency=4)
+            >>> loss = nn.SoftmaxCrossEntropyWithLogits(sparse=True, reduction='mean')
+            >>> loss_scale = FixedLossScaleManager(128, drop_overflow_update=False)
+            >>> model = Model(net, loss_fn=loss, optimizer=opt, loss_scale_manager=loss_scale, metrics={'acc'},
+            ...               amp_level="O2", keep_batchnorm_fp32=False)
+            >>> model = ConvertModelUtils.convert_to_thor_model(model=model, network=net, loss_fn=loss, optimizer=opt,
+            ...                                                 loss_scale_manager=loss_scale, metrics={'acc'},
+            ...                                                 amp_level="O2", keep_batchnorm_fp32=False)
+            >>> loss_cb = LossMonitor()
+            >>> model.train(1, dataset, callbacks=loss_cb, sink_size=4, dataset_sink_mode=True)
+        

docs/api/api_python/train/mindspore.train.train_thor.ConvertNetUtils.txt

@@ -0,0 +1,22 @@
+Class mindspore.train.train_thor.ConvertNetUtils
+
+    将网络转换为thor层网络，用于计算并存储二阶信息矩阵。
+    
+
+convert_to_thor_net(net)
+
+        该接口用于将网络转换为thor层网络，用于计算并存储二阶信息矩阵。
+
+        注：
+            此接口由二阶优化器thor自动调用。
+
+        参数：
+            net (Cell): 由二阶优化器thor训练的网络。
+
+        支持平台：
+            ``Ascend`` ``GPU``
+
+        示例：
+            >>> ConvertNetUtils().convert_to_thor_net(net)
+
+        

docs/api/api_python/train/mindspore.train.train_thor.txt

@@ -0,0 +1,12 @@
+mindspore.train.train_thor
+转换为二阶相关的类和函数。
+
+Class mindspore.train.train_thor.ConvertModelUtils
+
+    将模型转换为thor模型，增加计算图，提升二阶算法THOR运行时的性能。
+    
+
+Class mindspore.train.train_thor.ConvertNetUtils
+
+    该接口用于将网络转换为thor层网络，用于计算并存储二阶信息矩阵。
+