optim loss_scale datasethelper chinese api

docs/api/api_python/mindspore.DatasetHelper.txt

@@ -0,0 +1,57 @@
+Class mindspore.DatasetHelper(dataset, dataset_sink_mode=True, sink_size=-1, epoch_num=1)
+
+    DatasetHelper是一个处理MindData数据集的类，提供数据集信息。
+
+    根据不同的上下文，改变数据集的迭代，在不同的上下文中使用相同的迭代。
+
+    注：
+        DatasetHelper的迭代将提供一个epoch的数据。
+
+    参数：
+        dataset (Dataset)：训练数据集迭代器。数据集可以由数据集生成器API在:class:`mindspore.dataset`中生成，例如:class:`mindspore.dataset.ImageFolderDataset`。
+        dataset_sink_mode (bool)：如果值为True，使用:class:`mindspore.ops.GetNext`在设备（Device）上通过数据通道中获取数据，否则在主机直接遍历数据集获取数据。默认值：True。
+        sink_size (int)：控制每个下沉中的数据量。
+                          如果`sink_size`为-1，则下沉每个epoch的完整数据集。
+                          如果`sink_size`大于0，则下沉每个epoch的`sink_size`数据。
+                          默认值：-1。
+        epoch_num (int)：控制待发送的epoch数据量。默认值：1。
+
+    样例：
+        >>> from mindspore import DatasetHelper
+        >>>
+        >>> train_dataset = create_custom_dataset()
+        >>> set_helper = DatasetHelper(train_dataset, dataset_sink_mode=False)
+        >>> # DatasetHelper对象是可迭代的
+        >>> for next_element in set_helper:
+        ...     next_element
+    
+
+continue_send()
+在epoch开始时继续向设备发送数据。
+
+dynamic_min_max_shapes()
+返回动态数据的形状(shape)范围（最小形状(shape)，最大形状(shape)）。
+
+get_data_info()
+下沉模式下，获取当前批次数据的类型和形状(shape)。
+通常在数据形状(shape)动态变化的场景使用。
+
+样例：
+    >>> from mindspore import DatasetHelper
+    >>>
+    >>> train_dataset = create_custom_dataset()
+    >>> dataset_helper = DatasetHelper(train_dataset, dataset_sink_mode=True)
+    >>>
+    >>> types, shapes = dataset_helper.get_data_info()
+
+release()
+释放数据下沉资源。
+
+sink_size()
+获取每次迭代的`sink_size`。
+
+stop_send()
+停止发送数据下沉数据。
+
+types_shapes()
+从当前配置中的数据集获取类型和形状(shape)。

docs/api/api_python/mindspore.DynamicLossScaleManager.txt

@@ -0,0 +1,49 @@
+Class mindspore.DynamicLossScaleManager(init_loss_scale=16777216, scale_factor=2, scale_window=2000)
+
+    动态调整梯度放大系数的管理器，继承自:class:`mindspore.LossScaleManager`。
+
+    参数：
+        init_loss_scale (float)：初始梯度放大系数。默认值：2**24。
+        scale_factor (int)：放大/缩小倍数。默认值：2。
+        scale_window (int)：无溢出时的连续正常step的最大数量。默认值：2000。
+
+    样例：
+        >>> from mindspore import Model, nn, DynamicLossScaleManager
+        >>>
+        >>> net = Net()
+        >>> loss_scale_manager = DynamicLossScaleManager()
+        >>> optim = nn.Momentum(params=net.trainable_params(), learning_rate=0.1, momentum=0.9)
+        >>> model = Model(net, loss_scale_manager=loss_scale_manager, optimizer=optim)
+    
+
+get_drop_overflow_update()
+
+        该值表示是否在发生溢出时放弃本轮参数更新。
+
+        返回：
+            bool，始终为True。
+        
+
+get_loss_scale()
+
+        返回当前梯度放大系数。
+
+        返回：
+            float，梯度放大系数。
+        
+
+get_update_cell()
+
+        返回用于在:class:`mindspore.TrainOneStepWithLossScaleCell`中更新梯度放大系数的`Cell`实例。
+
+        返回：
+            :class:`mindspore.DynamicLossScaleUpdateCell`实例，用于更新梯度放大系数。
+        
+
+update_loss_scale(overflow)
+
+        根据溢出状态更新梯度放大系数。如果发生溢出，减小梯度放大系数，否则增大梯度放大系数。
+
+        参数：
+            overflow (bool)：表示是否溢出。
+        

docs/api/api_python/mindspore.FixedLossScaleManager.txt

@@ -0,0 +1,55 @@
+Class mindspore.FixedLossScaleManager(loss_scale=128.0, drop_overflow_update=True)
+
+    梯度放大系数不变的管理器，继承自:class:`mindspore.LossScaleManager`。
+
+    参数：
+        loss_scale (float)：梯度放大系数。注：如果将`drop_overflow_update`设为False，则定义优化器时需要将优化器的`loss_scale`设为相同的值。默认值：128.0。
+        drop_overflow_update (bool)：出现溢出时，是否执行优化器。如果值为True，则出现溢出时不会执行优化器。默认值：True。
+
+    样例：
+        >>> from mindspore import Model, nn, FixedLossScaleManager
+        >>>
+        >>> net = Net()
+        >>> # 1) 如果存在溢出，则不执行参数更新
+        >>> loss_scale_manager = FixedLossScaleManager()
+        >>> optim = nn.Momentum(params=net.trainable_params(), learning_rate=0.1, momentum=0.9)
+        >>> model = Model(net, loss_scale_manager=loss_scale_manager, optimizer=optim)
+        >>>
+        >>> # 2) 即使发生溢出，也执行参数更新
+        >>> loss_scale = 1024.0
+        >>> loss_scale_manager = FixedLossScaleManager(loss_scale, False)
+        >>> optim = nn.Momentum(params=net.trainable_params(), learning_rate=0.1, momentum=0.9, loss_scale=loss_scale)
+        >>> model = Model(net, loss_scale_manager=loss_scale_manager, optimizer=optim)
+    
+
+get_drop_overflow_update()
+
+        返回`drop_overflow_update`，该值表示是否在发生溢出时放弃本轮参数更新。
+
+        返回：
+            bool, `drop_overflow_update`的值。
+        
+
+get_loss_scale()
+
+        获取loss scale值。
+
+        返回：
+            bool，`loss_scale`的值。
+        
+
+get_update_cell()
+
+        返回用于更新`loss_scale`值的`Cell`实例，该实例将在:class:`mindspore.TrainOneStepWithLossScaleCell`中执行。
+
+        返回：
+            None或`Cell`。当`drop_overflow_update`为True时，返回:class:`mindspore.FixedLossScaleUpdateCell`实例，当`drop_overflow_update`为False时，返回None。
+        
+
+update_loss_scale(overflow)
+
+        更新loss scale值。类:class:`mindspore.FixedLossScaleManager`中，该方法不执行任何操作。
+
+        参数：
+            overflow (bool)：表示是否溢出。
+        

docs/api/api_python/mindspore.LossScaleManager.txt

@@ -0,0 +1,22 @@
+Class mindspore.LossScaleManager
+
+   混合精度梯度放大系数（loss scale）管理器的抽象类。
+
+   派生类需要该类的所有方法。`get_loss_scale`用于获取当前的梯度放大系数。`update_loss_scale`用于更新梯度放大系数，该方法将在训练过程中被调用。`get_update_cell`用于获取更新梯度放大系数的`Cell`实例，该实例在将训练过程中被调用。下沉模式下仅`get_update_cell`方式生效，非下沉模式下两种更新梯度放大系数的方式均生效。
+   例如：:class:`mindspore.FixedLossScaleManager`和:class:`mindspore.DynamicLossScaleManager`。
+    
+
+get_loss_scale()
+获取梯度放大系数（loss scale）的值。
+
+
+get_update_cell()
+获取用于更新梯度放大系数的:class:`mindspore.nn.Cell`实例。
+
+update_loss_scale(overflow)
+
+根据`overflow`状态更新梯度放大系数（loss scale)。
+
+参数：
+    overflow (bool)：表示训练过程是否溢出。
+        

docs/api/api_python/mindspore.connect_network_with_dataset.txt

@@ -0,0 +1,32 @@
+mindspore.connect_network_with_dataset(network, dataset_helper)
+
+    将`network`与`dataset_helper`中的数据集连接。
+
+    此函数使用:class:`mindspore.ops.GetNext`包装输入网络，以便在正向计算期间可以自动从与队列名称对应的数据通道中提取数据，并将数据传递到输入网络。
+
+    注：
+        如果以图模式在Ascend/GPU上运行网络，此函数将使用:class:`mindspore.ops.GetNext`包装输入网络。在其他情况下，输入网络将在没有改动的情况下返回。
+        仅在下沉模式下获取数据需要使用:class:`mindspore.ops.GetNext`，因此此函数不适用于非下沉模式。
+
+    参数：
+        network (Cell)：数据集的训练网络。
+        dataset_helper (DatasetHelper)：一个处理MindData数据集的类，提供了数据集的类型、形状（shape）和队列名称，以包装:class:`mindspore.ops.GetNext`。
+
+    返回：
+        Cell，在Ascend上以图模式运行任务的情况下，一个由:class:`mindspore.ops.GetNext`包装的新网络。在其他情况下是输入网络。
+
+    异常：
+        RuntimeError:  如果该接口在非数据下沉模式调用。
+
+    支持平台：
+        ``Ascend`` ``GPU``
+
+    示例：
+        >>> from mindspore import DatasetHelper
+        >>>
+        >>> # 调用create_dataset函数创建一个通用的数据集，参考mindpore.dataset
+        >>> train_dataset = create_custom_dataset()
+        >>> dataset_helper = DatasetHelper(train_dataset, dataset_sink_mode=True)
+        >>> net = Net()                                                                                                                                                                       
+        >>> net_with_get_next = connect_network_with_dataset(net, dataset_helper)
+    

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

@@ -0,0 +1,94 @@
+Class mindspore.nn.Adagrad(*args, **kwargs)
+
+    使用ApplyAdagrad算子实现Adagrad算法。
+
+    Adagrad用于在线学习和随机优化。
+    请参阅论文`Efficient Learning using Forward-Backward Splitting <https://proceedings.neurips.cc/paper/2009/file/621bf66ddb7c962aa0d22ac97d69b793-Paper.pdf>`_。
+    公式如下：
+
+    .. math::
+        \begin{array}{ll} \\
+            h_{t+1} = h_{t} + g\\
+            w_{t+1} = w_{t} - lr*\frac{1}{\sqrt{h_{t+1}}}*g
+        \end{array}
+
+    :math:`h`表示梯度平方的累积和，:math:`g`表示`grads`。
+    :math:`lr`代表`learning_rate`，:math:`w`代表`params`。
+
+    注：
+        在参数未分组时，优化器配置的`weight_decay`应用于名称含有"beta"或"gamma"的网络参数，通过网络参数分组可调整权重衰减策略。分组时，每组网络参数均可配置`weight_decay`，若未配置，则该组网络参数使用优化器中配置的`weight_decay`。
+
+    参数：
+        params (Union[list[Parameter], list[dict]]): 必须是`Parameter`组成的列表或字典组成的列表。当列表元素是字典时，字典的键可以是"params"、"lr"、"weight_decay"、"grad_centralization"和"order_params"：
+
+            - params: 必填。当前组别的权重，该值必须是`Parameter`列表。
+
+            - lr: 可选。如果键中存在"lr"，则使用对应的值作为学习率。
+              如果没有，则使用优化器中配置的`learning_rate`作为学习率。
+
+            - weight_decay: 可选。如果键中存在"weight_decay"，则使用对应的值作为权重衰减值。如果没有，则使用优化器中配置的`weight_decay`作为权重衰减值。
+
+            - grad_centralization: 可选。如果键中存在"grad_centralization"，则使用对应的值，该值必须为布尔类型。如果没有，则认为`grad_centralization`为False。
+              该参数仅适用于卷积层。
+
+            - order_params: 可选。对应值是预期的参数更新顺序。当使用参数分组功能时，通常使用该配置项保持`parameters`的顺序以提升性能。
+              如果键中存在"order_params"，则会忽略该组配置中的其他键。"order_params"中的参数必须在某一组`params`参数中。
+
+        accum (float): 累加器:math:`h`的初始值，必须大于等于零。默认值：0.1。
+        learning_rate (Union[float, Tensor, Iterable, LearningRateSchedule]): 默认值：0.001。
+
+            - float: 固定的学习率。必须大于等于零。
+
+            - int: 固定的学习率。必须大于等于零。整数类型会被转换为浮点数。
+
+            - Tensor: 可以是标量或一维向量。标量是固定的学习率。一维向量是动态的学习率，第i步将取向量中第i个值作为学习率。
+
+            - Iterable: 动态的学习率。第i步将取迭代器第i个值作为学习率。
+
+            - LearningRateSchedule: 动态的学习率。在训练过程中，优化器将使用步数（step）作为输入，调用`LearningRateSchedule`实例来计算当前学习率。
+
+        update_slots (bool): 如果为True，则更新累加器:math:`h`。默认值：True。
+
+        loss_scale (float): 梯度缩放系数，必须大于0。如果`loss_scale`是整数，它将被转换为浮点数。通常使用默认值，仅当训练时使用了`FixedLossScaleManager`，且`FixedLossScaleManager`的`drop_overflow_update`属性配置为False时，此值需要与`FixedLossScaleManager`中的`loss_scale`相同。有关更多详细信息，请参阅class：`mindspore.FixedLossScaleManager`。
+            默认值：1.0。
+
+        weight_decay (Union[float, int]): 要乘以权重的权重衰减值，必须大于等于0.0。
+            默认值：0.0。
+
+    输入：
+        - **grads** (tuple[Tensor]) - 优化器中`params`的梯度，形状（shape）与`params`相同。
+
+    输出：
+        Tensor[bool]，值为True。
+
+    异常：
+        TypeError: `learning_rate`不是int、float、Tensor、Iterable或`LearningRateSchedule`。
+        TypeError: `parameters`的元素是`Parameter`或字典。
+        TypeError: `accum`或`loss_scale`不是float。
+        TypeError: `update_slots`不是bool。
+        TypeError: `weight_decay`不是float或int。
+        ValueError: `loss_scale`小于或等于0。
+        ValueError: `accum`或`weight_decay`小于0。
+
+    支持平台：
+        ``Ascend`` ``CPU`` ``GPU``
+
+    示例：
+        >>> net = Net()
+        >>> #1) 所有参数使用相同的学习率和权重衰减
+        >>> optim = nn.Adagrad(params=net.trainable_params())
+        >>>
+        >>> #2) 使用参数组并设置不同的值
+        >>> conv_params = list(filter(lambda x: 'conv' in x.name, net.trainable_params()))
+        >>> no_conv_params = list(filter(lambda x: 'conv' not in x.name, net.trainable_params()))
+        >>> group_params = [{'params': conv_params, 'weight_decay': 0.01, 'grad_centralization':True},
+        ...                 {'params': no_conv_params, 'lr': 0.01},
+        ...                 {'order_params': net.trainable_params()}]
+        >>> optim = nn.Adagrad(group_params, learning_rate=0.1, weight_decay=0.0)
+        >>> # conv_params参数组将使用优化器中的学习率0.1、该组的权重衰减0.01、该组的梯度中心化配置True。
+        >>> # no_conv_params参数组将使用该组的学习率0.01、优化器中的权重衰减0.0、梯度中心化使用默认值False。
+        >>> # 优化器按照"order_params"配置的参数顺序更新参数。
+        >>>
+        >>> loss = nn.SoftmaxCrossEntropyWithLogits()
+        >>> model = Model(net, loss_fn=loss, optimizer=optim)
+    

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

@@ -0,0 +1,116 @@
+Class mindspore.nn.Adam(*args, **kwargs)
+
+    通过Adaptive Moment Estimation (Adam)算法更新梯度。
+
+    请参阅论文`Adam: A Method for Stochastic Optimization <https://arxiv.org/abs/1412.6980>`_。
+
+    公式如下：
+
+    .. math::
+        \begin{array}{ll} \\
+            m_{t+1} = \beta_1 * m_{t} + (1 - \beta_1) * g \\
+            v_{t+1} = \beta_2 * v_{t} + (1 - \beta_2) * g * g \\
+            l = \alpha * \frac{\sqrt{1-\beta_2^t}}{1-\beta_1^t} \\
+            w_{t+1} = w_{t} - l * \frac{m_{t+1}}{\sqrt{v_{t+1}} + \epsilon}
+        \end{array}
+
+    :math:`m`代表第一个动量矩阵`moment1`，:math:`v`代表第二个动量矩阵`moment2`，:math:`g`代表`gradients`，:math:`l`代表缩放因子，:math:`\beta_1,\beta_2`代表`beta1`和`beta2`，:math:`t`代表更新步骤，:math:`beta_1^t`和:math:`beta_2^t`代表`beta1_power`和`beta2_power`，:math:`\alpha`代表`learning_rate`，:math:`w`代表`params`，:math:`\epsilon`代表`eps`。
+
+    注：
+        如果前向网络使用了SparseGatherV2等算子，优化器会执行稀疏运算，通过设置`target`为CPU，可在主机（host）上进行稀疏运算。
+        稀疏特性在持续开发中。
+
+        在参数未分组时，优化器配置的`weight_decay`应用于名称含有"beta"或"gamma"的网络参数，通过网络参数分组可调整权重衰减策略。分组时，每组网络参数均可配置`weight_decay`，若未配置，则该组网络参数使用优化器中配置的`weight_decay`。
+
+
+    参数：
+        params (Union[list[Parameter], list[dict]]): 必须是`Parameter`组成的列表或字典组成的列表。当列表元素是字典时，字典的键可以是"params"、"lr"、"weight_decay"、"grad_centralization"和"order_params"：
+
+            - params: 必填。当前组别的权重，该值必须是`Parameter`列表。
+
+            - lr: 可选。如果键中存在"lr"，则使用对应的值作为学习率。
+              如果没有，则使用优化器中配置的`learning_rate`作为学习率。
+
+            - weight_decay: 可选。如果键中存在"weight_decay”，则使用对应的值作为权重衰减值。如果没有，则使用优化器中配置的`weight_decay`作为权重衰减值。
+
+            - grad_centralization: 可选。如果键中存在"grad_centralization"，则使用对应的值，该值必须为布尔类型。如果没有，则认为`grad_centralization`为False。
+              该参数仅适用于卷积层。
+
+            - order_params: 可选。对应值是预期的参数更新顺序。当使用参数分组功能时，通常使用该配置项保持`parameters`的顺序以提升性能。
+              如果键中存在"order_params"，则会忽略该组配置中的其他键。"order_params"中的参数必须在某一组`params`参数中。
+
+        learning_rate (Union[float, Tensor, Iterable, LearningRateSchedule]): 默认值：1e-3。
+
+            - float: 固定的学习率。必须大于等于零。
+
+            - int: 固定的学习率。必须大于等于零。整数类型会被转换为浮点数。
+
+            - Tensor: 可以是标量或一维向量。标量是固定的学习率。一维向量是动态的学习率，第i步将取向量中第i个值作为学习率。
+
+            - Iterable: 动态的学习率。第i步将取迭代器第i个值作为学习率。
+
+            - LearningRateSchedule: 动态的学习率。在训练过程中，优化器将使用步数（step）作为输入，调用`LearningRateSchedule`实例来计算当前学习率。
+
+        beta1 (float): `moment1`的指数衰减率。参数范围（0.0,1.0）。
+                       默认值：0.9。
+
+        beta2 (float): `moment2`的指数衰减率。参数范围（0.0,1.0）。
+                       默认值：0.999。
+
+        eps (float): 将添加到分母中，以提高数值稳定性。必须大于0。默认值：1e-8。
+
+        use_locking (bool): 是否对参数更新加锁保护。
+            如果为True，则`w`、`m`和`v`的tensor更新将受到锁的保护。
+            如果为False，则结果不可预测。默认值：False。
+
+        use_nesterov (bool): 是否使用Nesterov Accelerated Gradient (NAG)算法更新梯度。
+            如果为True，使用NAG更新梯度。
+            如果为False，则在不使用NAG的情况下更新梯度。默认值：False。
+
+        weight_decay (float): 权重衰减（L2 penalty）。必须大于等于0。默认值：0.0。
+
+        loss_scale (float):    梯度缩放系数，必须大于0。如果`loss_scale`是整数，它将被转换为浮点数。通常使用默认值，仅当训练时使用了`FixedLossScaleManager`，且`FixedLossScaleManager`的`drop_overflow_update`属性配置为False时，此值需要与`FixedLossScaleManager`中的`loss_scale`相同。有关更多详细信息，请参阅class：`mindspore.FixedLossScaleManager`。
+            默认值：1.0。
+
+    输入：
+        - **gradients** (tuple[Tensor]) - `params`的梯度，形状（shape）与`params`相同。
+
+    输出：
+        Tensor[bool]，值为True。
+
+    异常：
+        TypeError: `learning_rate`不是int、float、Tensor、Iterable或LearningRateSchedule。
+        TypeError: `parameters`的元素不是Parameter或字典。
+        TypeError: `beta1`、`beta2`、`eps`或`loss_scale`不是float。
+        TypeError: `weight_decay`不是float或int。
+        TypeError: `use_locking`或`use_nesterov`不是bool。
+        ValueError: `loss_scale`或`eps`小于或等于0。
+        ValueError: `beta1`、`beta2`不在（0.0,1.0）范围内。
+        ValueError: `weight_decay`小于0。
+
+    支持平台：
+        ``Ascend`` ``GPU``  ``CPU``
+
+    示例：
+        >>> net = Net()
+        >>> #1) 所有参数使用相同的学习率和权重衰减
+        >>> optim = nn.Adam(params=net.trainable_params())
+        >>>
+        >>> #2) 使用参数组并设置不同的值
+        >>> conv_params = list(filter(lambda x: 'conv' in x.name, net.trainable_params()))
+        >>> no_conv_params = list(filter(lambda x: 'conv' not in x.name, net.trainable_params()))
+        >>> group_params = [{'params': conv_params, 'weight_decay': 0.01, 'grad_centralization':True},
+        ...                 {'params': no_conv_params, 'lr': 0.01},
+        ...                 {'order_params': net.trainable_params()}]
+        >>> optim = nn.Adam(group_params, learning_rate=0.1, weight_decay=0.0)
+        >>> # conv_params参数组将使用优化器中的学习率0.1、该组的权重衰减0.01、该组的梯度中心化配置True。
+        >>> # no_conv_params参数组将使用该组的学习率0.01、优化器中的权重衰减0.0、梯度中心化使用默认值False。
+        >>> # 优化器按照"order_params"配置的参数顺序更新参数。
+        >>>
+        >>> loss = nn.SoftmaxCrossEntropyWithLogits()
+        >>> model = Model(net, loss_fn=loss, optimizer=optim)
+    
+
+target
+
+        该属性用于指定在主机（host）上还是设备（device）上更新参数。输入类型为str，只能是'CPU'，'Ascend'或'GPU'。

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

@@ -0,0 +1,70 @@
+Class mindspore.nn.Metric
+
+    用于计算评估指标的基类。
+
+    在计算评估指标时需要调用`clear`、`update`和`eval`三个方法，在继承该类自定义评估指标时，也需要实现这三个方法。其中，`update`用于计算中间过程的内部结果，`eval`用于计算最终评估结果，`clear`用于重置中间结果。
+    请勿直接使用该类，需使用子类如:class:`mindspore.nn.MAE`、:class:`mindspore.nn.Recall`等。
+
+
+clear()
+
+        描述了清除内部评估结果的行为。
+
+        注：
+            所有子类都必须重写此接口。
+
+
+eval()
+
+        描述了计算最终评估结果的行为。
+
+        注：
+            所有子类都必须重写此接口。
+        
+
+indexes
+        获取当前的`indexes`值。默认为None，调用`set_indexes`可修改`indexes`值。
+
+
+set_indexes(indexes)
+
+        该接口用于重排`update`的输入。
+
+        给定(label0, label1, logits)作为`update`的输入，将`indexes`设置为[2, 1]，则最终使用(logits, label1)作为`update`的真实输入。
+
+        注：
+            在继承该类自定义评估函数时，需要用装饰器:func:`mindspore.nn.rearrange_inputs`修饰`update`方法，否则配置的`indexes`值不生效。
+            
+
+        参数：
+            indexes (List(int)): logits和标签的目标顺序。
+
+        输出：
+            :class:`Metric`，类实例本身。
+
+        示例：
+            >>> import numpy as np
+            >>> from mindspore import nn, Tensor
+            >>>
+            >>> x = Tensor(np.array([[0.2, 0.5], [0.3, 0.1], [0.9, 0.6]]))
+            >>> y = Tensor(np.array([1, 0, 1]))
+            >>> y2 = Tensor(np.array([0, 0, 1]))
+            >>> metric = nn.Accuracy('classification').set_indexes([0, 2])
+            >>> metric.clear()
+            >>> # indexes为[0, 2]，使用x作为预测值，y2作为真实标签
+            >>> metric.update(x, y, y2)
+            >>> accuracy = metric.eval()
+            >>> print(accuracy)
+            0.3333333333333333
+        
+
+update(*inputs)
+
+        描述了更新内部评估结果的行为。
+
+        注：
+            所有子类都必须重写此接口。
+
+        参数：
+            inputs：可变长度输入参数列表。通常是预测值和对应的真实标签。
+        

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

@@ -0,0 +1,99 @@
+Class mindspore.nn.Momentum(*args, **kwargs)
+
+    Momentum算法优化器。
+
+    有关更多详细信息，请参阅论文`On the importance of initialization and momentum in deep learning <https://dl.acm.org/doi/10.5555/3042817.3043064>`_。
+
+    .. math::
+            v_{t+1} = v_{t} \ast u + grad
+
+    如果`use_nesterov`为True：
+
+    .. math::
+            p_{t+1} =  p_{t} - (grad \ast lr + v_{t+1} \ast u \ast lr)
+
+    如果`use_nesterov`为False：
+
+    .. math::
+            p_{t+1} = p_{t} - lr \ast v_{t+1}
+
+    其中，:math:`grad`、:math:`lr`、:math:`p`、:math:`v`和:math:`u`分别表示梯度、学习率、参数、矩（Moment）和动量（Momentum）。
+
+    注：
+        在参数未分组时，优化器配置的`weight_decay`应用于名称含有"beta"或"gamma"的网络参数，通过网络参数分组可调整权重衰减策略。分组时，每组网络参数均可配置`weight_decay`，若未配置，则该组网络参数使用优化器中配置的`weight_decay`。
+
+    参数：
+        params (Union[list[Parameter], list[dict]]): 必须是`Parameter`组成的列表或字典组成的列表。当列表元素是字典时，字典的键可以是"params"、"lr"、"weight_decay"、"grad_centralization"和"order_params"：
+
+            - params: 必填。当前组别的权重，该值必须是`Parameter`列表。
+
+            - lr: 可选。如果键中存在"lr"，则使用对应的值作为学习率。
+              如果没有，则使用优化器中配置的`learning_rate`作为学习率。
+
+            - weight_decay: 可选。如果键中存在"weight_decay”，则使用对应的值作为权重衰减值。如果没有，则使用优化器中配置的`weight_decay`作为权重衰减值。
+
+            - grad_centralization: 可选。如果键中存在"grad_centralization"，则使用对应的值，该值必须为布尔类型。如果没有，则认为`grad_centralization`为False。
+              该参数仅适用于卷积层。
+
+            - order_params: 可选。对应值是预期的参数更新顺序。当使用参数分组功能时，通常使用该配置项保持`parameters`的顺序以提升性能。
+              如果键中存在"order_params"，则会忽略该组配置中的其他键。"order_params"中的参数必须在某一组`params`参数中。
+
+        learning_rate (Union[float, int, Tensor, Iterable, LearningRateSchedule]):
+
+            - float: 固定的学习率。必须大于等于零。
+
+            - int: 固定的学习率。必须大于等于零。整数类型会被转换为浮点数。
+
+            - Tensor: 可以是标量或一维向量。标量是固定的学习率。一维向量是动态的学习率，第i步将取向量中第i个值作为学习率。
+
+            - Iterable: 动态的学习率。第i步将取迭代器第i个值作为学习率。
+
+            - LearningRateSchedule: 动态的学习率。在训练过程中，优化器将使用步数（step）作为输入，调用`LearningRateSchedule`实例来计算当前学习率。
+
+        momentum (float): 浮点数类型的超参，表示移动平均的动量。
+            必须等于或大于0.0。
+
+        weight_decay (int, float): 权重衰减（L2 penalty）值。必须大于等于0.0。默认值：0.0。
+
+        loss_scale (float): 梯度缩放系数，必须大于0。如果`loss_scale`是整数，它将被转换为浮点数。通常使用默认值，仅当训练时使用了`FixedLossScaleManager`，且`FixedLossScaleManager`的`drop_overflow_update`属性配置为False时，此值需要与`FixedLossScaleManager`中的`loss_scale`相同。有关更多详细信息，请参阅class：`mindspore.FixedLossScaleManager`。
+            默认值：1.0。
+
+        use_nesterov (bool): 是否使用Nesterov Accelerated Gradient (NAG)算法更新梯度。默认值：False。
+
+    输入：
+        - **gradients** (tuple[Tensor]) - `params`的梯度，形状（shape）与`params`相同。
+
+    输出：
+        tuple[bool]，所有元素都为True。
+
+    异常：
+        TypeError: `learning_rate`不是int、float、Tensor、Iterable或LearningRateSchedule。
+        TypeError: `parameters`的元素不是`Parameter`或字典。
+        TypeError: `loss_scale`或`momentum`不是float。
+        TypeError: `weight_decay`不是float或int。
+        TypeError: `use_nesterov`不是bool。
+        ValueError: `loss_scale`小于或等于0。
+        ValueError: `weight_decay`或`momentum`小于0。
+
+    支持的平台：
+        ``Ascend`` ``GPU`` ``CPU``
+
+    示例：
+        >>> net = Net()
+        >>> #1) 所有参数使用相同的学习率和权重衰减
+        >>> optim = nn.Momentum(params=net.trainable_params(), learning_rate=0.1, momentum=0.9)
+        >>>
+        >>> #2) 使用参数分组并设置不同的值
+        >>> conv_params = list(filter(lambda x: 'conv' in x.name, net.trainable_params()))
+        >>> no_conv_params = list(filter(lambda x: 'conv' not in x.name, net.trainable_params()))
+        >>> group_params = [{'params': conv_params, 'weight_decay': 0.01, 'grad_centralization':True},
+        ...                 {'params': no_conv_params, 'lr': 0.01},
+        ...                 {'order_params': net.trainable_params()}]
+        >>> optim = nn.Momentum(group_params, learning_rate=0.1, momentum=0.9, weight_decay=0.0)
+        >>> # conv_params参数组将使用优化器中的学习率0.1、该组的权重衰减0.01、该组的梯度中心化配置True。
+        >>> # no_conv_params参数组将使用该组的学习率0.01、优化器中的权重衰减0.0、梯度中心化使用默认值False。
+        >>> # 优化器按照"order_params"配置的参数顺序更新参数。
+        >>>
+        >>> loss = nn.SoftmaxCrossEntropyWithLogits()
+        >>> model = Model(net, loss_fn=loss, optimizer=optim, metrics=None)
+    

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

@@ -0,0 +1,145 @@
+Class mindspore.nn.Optimizer(learning_rate, parameters, weight_decay=0.0, loss_scale=1.0)
+
+    用于参数更新的优化器基类。不要直接使用这个类，请实例化它的一个子类。
+
+    优化器支持参数分组。当参数分组时，每组参数均可配置不同的学习率（`lr`）、权重衰减（`weight_decay`）和梯度中心化（`grad_centralization`）策略。
+
+    注：
+        在参数未分组时，优化器配置的`weight_decay`应用于名称含有"beta"或"gamma"的网络参数，通过网络参数分组可调整权重衰减策略。分组时，每组网络参数均可配置`weight_decay`，若未配置，则该组网络参数使用优化器中配置的`weight_decay`。
+
+    参数：
+        learning_rate (Union[float, int, Tensor, Iterable, LearningRateSchedule]):
+
+            - float: 固定的学习率。必须大于等于零。
+
+            - int: 固定的学习率。必须大于等于零。整数类型会被转换为浮点数。
+
+            - Tensor: 可以是标量或一维向量。标量是固定的学习率。一维向量是动态的学习率，第i步将取向量中第i个值作为学习率。
+
+            - Iterable: 动态的学习率。第i步将取迭代器第i个值作为学习率。
+
+            - LearningRateSchedule: 动态的学习率。在训练过程中，优化器将使用步数（step）作为输入，调用`LearningRateSchedule`实例来计算当前学习率。
+
+        parameters (Union[list[Parameter], list[dict]]): 必须是`Parameter`组成的列表或字典组成的列表。当列表元素是字典时，字典的键可以是"params"、"lr"、"weight_decay"、"grad_centralization"和"order_params"：
+
+            - params: 必填。当前组别的权重，该值必须是`Parameter`列表。
+
+            - lr: 可选。如果键中存在"lr"，则使用对应的值作为学习率。
+              如果没有，则使用优化器中配置的`learning_rate`作为学习率。
+
+            - weight_decay: 可选。如果键中存在"weight_decay”，则使用对应的值作为权重衰减值。如果没有，则使用优化器中配置的`weight_decay`作为权重衰减值。
+
+            - grad_centralization: 可选。如果键中存在"grad_centralization"，则使用对应的值，该值必须为布尔类型。如果没有，则认为`grad_centralization`为False。
+              该参数仅适用于卷积层。
+
+            - order_params: 可选。对应值是预期的参数更新顺序。当使用参数分组功能时，通常使用该配置项保持`parameters`的顺序以提升性能。
+              如果键中存在"order_params"，则会忽略该组配置中的其他键。"order_params"中的参数必须在某一组`params`参数中。
+
+        weight_decay (Union[float, int]): 权重衰减的整数或浮点值。
+            必须等于或大于0。
+            如果`weight_decay`是整数，它将被转换为浮点数。默认值：0.0。
+
+        loss_scale (float): 梯度缩放系数，必须大于0。如果`loss_scale`是整数，它将被转换为浮点数。通常使用默认值，仅当训练时使用了`FixedLossScaleManager`，且`FixedLossScaleManager`的`drop_overflow_update`属性配置为False时，此值需要与`FixedLossScaleManager`中的`loss_scale`相同。有关更多详细信息，请参阅class：`mindspore.FixedLossScaleManager`。
+            默认值：1.0。
+
+    异常：
+        TypeError: `learning_rate`不是int、float、Tensor、Iterable或LearningRateSchedule。
+        TypeError: `parameters`的元素不是Parameter或字典。
+        TypeError: `loss_scale`不是float。
+        TypeError: `weight_decay`不是float或int。
+        ValueError: `loss_scale`小于或等于0。
+        ValueError: `weight_decay`小于0。
+        ValueError: `learning_rate`是一个Tensor，但是Tensor的维度大于1。
+
+    支持的平台：
+        ``Ascend`` ``GPU`` ``CPU``
+
+
+broadcast_params(optim_result)
+
+        按参数组的顺序进行参数广播。
+
+        参数：
+            optim_result (bool): 参数更新结果。该输入用来保证参数更新完成后才执行参数广播。
+
+        返回：
+             bool，状态标志。
+
+
+decay_weight(gradients)
+
+        衰减权重。
+
+        一种减少深度学习神经网络模型过拟合的方法。继承 :class:`mindspore.nn.Optimizer`自定义优化器时，可调用该接口进行权重衰减。
+
+        参数：
+            gradients (tuple[Tensor]): 网络参数的梯度，形状（shape）与网络参数相同。
+
+        返回：
+            tuple[Tensor]，衰减权重后的梯度。
+
+
+get_lr()
+
+        优化器调用该接口获取当前步骤（step）的学习率。继承 :class:`mindspore.nn.Optimizer`自定义优化器时，可在参数更新前调用该接口获取学习率。
+
+        返回：
+            float，当前步骤的学习率。
+
+
+get_lr_parameter(param)
+
+        用于在使用网络参数分组功能，且为不同组别配置不同的学习率时，获取指定参数的学习率。
+
+        参数：
+            param (Union[Parameter, list[Parameter]]): `Parameter`或`Parameter`列表。
+
+        返回：
+            Parameter，单个`Parameter`或`Parameter`列表。如果使用了动态学习率，返回用于计算学习率的`LearningRateSchedule`或`LearningRateSchedule`列表。
+
+        示例：
+            >>> from mindspore import nn
+            >>> net = Net()
+            >>> conv_params = list(filter(lambda x: 'conv' in x.name, net.trainable_params()))
+            >>> no_conv_params = list(filter(lambda x: 'conv' not in x.name, net.trainable_params()))
+            >>> group_params = [{'params': conv_params, 'lr': 0.05},
+            ...                 {'params': no_conv_params, 'lr': 0.01}]
+            >>> optim = nn.Momentum(group_params, learning_rate=0.1, momentum=0.9, weight_decay=0.0)
+            >>> conv_lr = optim.get_lr_parameter(conv_params)
+            >>> print(conv_lr[0].asnumpy())
+            0.05
+
+
+gradients_centralization(gradients)
+
+        梯度中心化。
+
+        一种优化卷积层参数以提高深度学习神经网络模型训练速度的方法。继承 :class:`mindspore.nn.Optimizer`自定义优化器时，可调用该接口进行梯度中心化。
+
+        参数：
+            gradients (tuple[Tensor]): 网络参数的梯度，形状（shape）与网络参数相同。
+
+        返回：
+            tuple[Tensor]，梯度中心化后的梯度。
+
+
+scale_grad(gradients)
+
+        用于在混合精度场景还原梯度。
+
+        继承:class:`mindspore.nn.Optimizer`自定义优化器时，可调用该接口还原梯度。
+
+        参数：
+            gradients (tuple[Tensor]): 网络参数的梯度，形状（shape）与网络参数相同。
+
+        返回：
+            tuple[Tensor]，还原后的梯度。
+
+
+target
+
+        该属性用于指定在主机（host）上还是设备（device）上更新参数。输入类型为str，只能是'CPU'，'Ascend'或'GPU'。
+
+
+unique
+        该属性表示是否在优化器中进行梯度去重，通常用于稀疏网络。如果梯度是稀疏的则设置为True。如果前向稀疏网络已对权重去重，即梯度是稠密的，则设置为False。未设置时默认值为True。