p47068915
/
mindspore
forked from mindspore-Ecosystem/mindspore
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

!27023 modify api annotation 

Merge pull request !27023 from xumengjuan1/master
This commit is contained in:
i-robot 2021-12-01 04:03:32 +00:00 committed by Gitee
parent 8623310442 43e572a91f
commit 3160fe8ee4
19 changed files with 1096 additions and 1139 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

295
docs/api/api_python/mindspore.common.initializer.rst
View File

@ -1,159 +1,138 @@
mindspore.common.initializer mindspore.common.initializer
============================= =============================
初始化神经元参数。 初始化神经元参数。
.. py:class:: mindspore.common.initializer.Initializer(**kwargs) .. py:class:: mindspore.common.initializer.Initializer(**kwargs)
初始化器的抽象基类。 初始化器的抽象基类。
**参数：** **参数：**
- **kwargs** (`dict`) – **Initializer** 的关键字参数。 **kwargs** (`dict`) – **Initializer** 的关键字参数。
.. py:method:: mindspore.common.initializer.initializer(init, shape=None, dtype=mstype.float32)
.. py:method:: mindspore.common.initializer.initializer(init, shape=None, dtype=mstype.float32)
创建并初始化一个Tensor。
创建并初始化一个Tensor。
**参数：**
**参数：**
- **init** (`Union[Tensor, str, Initializer, numbers.Number]`) – 初始化方式。
- **init** (`Union[Tensor, str, Initializer, numbers.Number]`) – 初始化方式。
- **str** - `init` 是继承自 Initializer 的类的别名，实际使用时会调用相应的类。`init` 的值可以是"normal"、"ones"或"zeros"等。
- *str*：`init` 是继承自 Initializer 的类的别名，实际使用时会调用相应的类。`init` 的值可以是"normal"、"ones"或"zeros"等。 - **Initializer** - `init` 是继承自Initializer，用于初始化Tensor的类。
- *Initializer*：`init` 是继承自Initializer，用于初始化Tensor的类。 - **numbers.Number** - 调用常量来初始化张量。
- *numbers.Number*：调用常量来初始化张量。
- **shape** (`Union[[tuple, list, int]`) - 被初始化的Tensor的shape，默认值为None。
- **shape** (`Union[[tuple, list, int]`) - 被初始化的Tensor的shape，默认值为None。 - **dtype** (`mindspore.dtype`) – 被初始化的Tensor的数据类型，默认值为 `mindspore.float32` 。
- **dtype** (`mindspore.dtype`) – 被初始化的Tensor的数据类型，默认值为 `mindspore.float32` 。 **返回：**
**返回：** Tensor，返回一个张量对象。
Tensor，返回一个张量对象。 **异常：**
**异常：** - **TypeError** - 参数 `init` 的类型不正确。
TypeError: 参数`init`的类型不正确。 - **ValueError** - 通过 `init` 传入的Tensor的shape和作为参数传入的shape不一致。
ValueError: 通过`init`传入的Tensor的shape和作为参数传入的shape不一致。
**样例：**
**样例：**
>>> import mindspore
.. code-block:: >>> from mindspore.common.initializer import initializer, One
>>> tensor = initializer('ones', [1, 2, 3], mindspore.float32)
>>> import mindspore >>> tensor = initializer(One(), [1, 2, 3], mindspore.float32)
>>> from mindspore.common.initializer import initializer, One >>> tensor = initializer(0, [1, 2, 3], mindspore.float32)
>>> tensor = initializer('ones', [1, 2, 3], mindspore.float32)
>>> tensor = initializer(One(), [1, 2, 3], mindspore.float32) .. py:class:: mindspore.common.initializer.TruncatedNormal(sigma=0.01)
>>> tensor = initializer(0, [1, 2, 3], mindspore.float32)
生成一个数组用于初始化Tensor，数组中的数值从截断正态分布中采样得到。
.. py:class:: mindspore.common.initializer.TruncatedNormal(sigma=0.01)
**参数：**
生成一个数组用于初始化Tensor，数组中的数值从截断正态分布中采样得到。
**sigma** (`float`) - 截断正态分布的标准差，默认值为0.01。
**参数：**
.. py:class:: mindspore.common.initializer.Normal(sigma=0.01, mean=0.0)
- **sigma** (`float`) - 截断正态分布的标准差，默认值为0.01。
生成一个数组用于初始化Tensor，数组中的数值从正态分布N(sigma, mean)中采样得到。
.. py:class:: mindspore.common.initializer.Normal(sigma=0.01, mean=0.0) .. math::
f(x) = \frac{1} {\sqrt{2*π} * sigma}exp(-\frac{(x - mean)^2} {2*{sigma}^2})
生成一个数组用于初始化Tensor，数组中的数值从正态分布N(sigma, mean)中采样得到。
**参数：**
.. math::
f(x) = \frac{1} {\sqrt{2*π} * sigma}exp(-\frac{(x - mean)^2} {2*{sigma}^2}) - **sigma** (`float`) - 正态分布的标准差，默认值为0.01。
- **mean** (`float`) - 正态分布的均值，默认值为0.0。
**参数：**
.. py:class:: mindspore.common.initializer.Uniform(scale=0.07)
- **sigma** (`float`) - 正态分布的标准差，默认值为0.01。
生成一个数组用于初始化Tensor，数组中的数值从均匀分布U(-scale, scale)中采样得到。
- **mean** (`float`) - 正态分布的均值，默认值为0.0。
**参数：**
**scale** (`float`) - 均匀分布的边界，默认值为0.07。
.. py:class:: mindspore.common.initializer.Uniform(scale=0.07)
.. py:class:: mindspore.common.initializer.HeUniform(negative_slope=0, mode="fan_in", nonlinearity="leaky_relu")
生成一个数组用于初始化Tensor，数组中的数值从均匀分布U(-scale, scale)中采样得到。
生成一个数组用于初始化Tensor，数组中的数值从HeKaiming均匀分布U[-boundary,boundary]中采样得到，其中
**参数：**
.. math::
- **scale** (`float`) - 均匀分布的边界，默认值为0.07。 boundary = \sqrt{\frac{6}{(1 + a^2) \times \text{fan_in}}}
是HeUniform分布的边界。
.. py:class:: mindspore.common.initializer.HeUniform(negative_slope=0, mode="fan_in", nonlinearity="leaky_relu")
**参数：**
生成一个数组用于初始化Tensor，数组中的数值从HeKaiming均匀分布U[-boundary,boundary]中采样得到，其中
- **negative_slope** (`int, float, bool`) - 本层激活函数的负数区间斜率（仅适用于非线性激活函数"leaky_relu"），默认值为0。
.. math:: - **mode** (`str`) - 可选"fan_in"或"fan_out"，"fan_in"会保留前向传递中权重方差的量级，"fan_out"会保留反向传递的量级，默认为"fan_in"。
boundary = \sqrt{\frac{6}{(1 + a^2) \times \text{fan_in}}} - **nonlinearity** (`str`) - 非线性激活函数，推荐使用"relu"或"leaky_relu"，默认为"leaky_relu"。
是HeUniform分布的边界。 .. py:class:: mindspore.common.initializer.HeNormal(negative_slope=0, mode="fan_in", nonlinearity="leaky_relu")
**参数：** 生成一个数组用于初始化Tensor，数组中的数值从HeKaiming正态分布N(0, sigma^2)中采样得到，其中
- **negative_slope** (`int, float, bool`) - 本层激活函数的负数区间斜率（仅适用于非线性激活函数"leaky_relu"），默认值为0。 .. math::
sigma = \frac{gain} {\sqrt{N}}
- **mode** (`str`) - 可选"fan_in"或"fan_out"，"fan_in"会保留前向传递中权重方差的量级，"fan_out"会保留反向传递的量级，默认为"fan_in"。
其中，gain是一个可选的缩放因子。如果mode是"fan_in"， N是权重Tensor中输入单元的数量，如果mode是"fan_out"， N是权重Tensor中输出单元的数量。
- **nonlinearity** (`str`) - 非线性激活函数，推荐使用"relu"或"leaky_relu"，默认为"leaky_relu"。
HeUniform 算法的详细信息，请查看 https://arxiv.org/abs/1502.01852。
**参数：**
.. py:class:: mindspore.common.initializer.HeNormal(negative_slope=0, mode="fan_in", nonlinearity="leaky_relu")
- **negative_slope** (`int, float, bool`) - 本层激活函数的负数区间斜率（仅适用于非线性激活函数"leaky_relu"），默认值为0。
生成一个数组用于初始化Tensor，数组中的数值从HeKaiming正态分布N(0, sigma^2)中采样得到，其中 - **mode** (`str`) - 可选"fan_in"或"fan_out"，"fan_in"会保留前向传递中权重方差的量级，"fan_out"会保留反向传递的量级，默认为"fan_in"。
- **nonlinearity** (`str`) - 非线性激活函数，推荐使用"relu"或"leaky_relu"，默认为"leaky_relu"。
.. math::
sigma = \frac{gain} {\sqrt{N}} .. py:class:: mindspore.common.initializer.XavierUniform(gain=1)
其中，gain是一个可选的缩放因子。如果mode是"fan_in"， N是权重Tensor中输入单元的数量，如果mode是"fan_out"， N是权重Tensor中输出单元的数量。 生成一个数组用于初始化Tensor，数组中的数值从Xarvier均匀分布U[-boundary,boundary]中采样得到，其中
HeUniform 算法的详细信息，请查看 https://arxiv.org/abs/1502.01852。 .. math::
boundary = gain * \sqrt{\frac{6}{n_{in} + n_{out}}}
**参数：**
- `gain` 是一个可选的缩放因子。
- **negative_slope** (`int, float, bool`) - 本层激活函数的负数区间斜率（仅适用于非线性激活函数"leaky_relu"），默认值为0。 - `n_{in}` 为权重Tensor中输入单元的数量。
- `n_{out}` 为权重Tensor中输出单元的数量。
- **mode** (`str`) - 可选"fan_in"或"fan_out"，"fan_in"会保留前向传递中权重方差的量级，"fan_out"会保留反向传递的量级，默认为"fan_in"。
有关 XavierUniform 算法的详细信息，请查看 http://proceedings.mlr.press/v9/glorot10a.html。
- **nonlinearity** (`str`) - 非线性激活函数，推荐使用"relu"或"leaky_relu"，默认为"leaky_relu"。
**参数：**
.. py:class:: mindspore.common.initializer.XavierUniform(gain=1) **gain** (`float`) - 可选的缩放因子，默认值为1。
生成一个数组用于初始化Tensor，数组中的数值从Xarvier均匀分布U[-boundary,boundary]中采样得到，其中 .. py:class:: mindspore.common.initializer.One(**kwargs)
.. math:: 生成一个值全为1的常量数组用于初始化Tensor。
boundary = gain * \sqrt{\frac{6}{n_{in} + n_{out}}} .. py:class:: mindspore.common.initializer.Zero(**kwargs)
- `gain` 是一个可选的缩放因子。 生成一个值全为0的常量数组用于初始化Tensor。
- `n_{in}` 为权重Tensor中输入单元的数量。
- `n_{out}` 为权重Tensor中输出单元的数量。 .. py:class:: mindspore.common.initializer.Constant(value)
有关 XavierUniform 算法的详细信息，请查看 http://proceedings.mlr.press/v9/glorot10a.html。 生成一个常量数组用于初始化Tensor。
**参数：** **参数：**
- **gain** (`float`) - 可选的缩放因子，默认值为1。 **value** (`Union[int, numpy.ndarray]`) - 用于初始化的常数值或者数组。
.. py:class:: mindspore.common.initializer.One(**kwargs)
生成一个值全为1的常量数组用于初始化Tensor。
.. py:class:: mindspore.common.initializer.Zero(**kwargs)
生成一个值全为0的常量数组用于初始化Tensor。
.. py:class:: mindspore.common.initializer.Constant(value)
生成一个常量数组用于初始化Tensor。
**参数：**
- **value** (`Union[int, numpy.ndarray]`) - 用于初始化的常数值或者数组。

14
docs/api/api_python/mindspore.nn/mindspore.nn.WarmUpLR.rst
View File

@ -41,11 +41,11 @@ mindspore.nn.WarmUpLR
**样例：** **样例：**
>>> learning_rate = 0.1 >>> learning_rate = 0.1
>>> warmup_steps = 2 >>> warmup_steps = 2
>>> global_step = Tensor(2, mstype.int32) >>> global_step = Tensor(2, mstype.int32)
>>> warmup_lr = nn.WarmUpLR(learning_rate, warmup_steps) >>> warmup_lr = nn.WarmUpLR(learning_rate, warmup_steps)
>>> result = warmup_lr(global_step) >>> result = warmup_lr(global_step)
>>> print(result) >>> print(result)
0.1 0.1

128
docs/api/api_python/mindspore.DatasetHelper.txt → docs/api/api_python/mindspore/mindspore.DatasetHelper.rst
View File

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

106
docs/api/api_python/mindspore.DynamicLossScaleManager.txt → docs/api/api_python/mindspore/mindspore.DynamicLossScaleManager.rst
View File

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

118
docs/api/api_python/mindspore.FixedLossScaleManager.txt → docs/api/api_python/mindspore/mindspore.FixedLossScaleManager.rst
View File

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

50
docs/api/api_python/mindspore.LossScaleManager.txt → docs/api/api_python/mindspore/mindspore.LossScaleManager.rst
View File

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

24
docs/api/api_python/mindspore/mindspore.Parameter.rst
View File

@ -44,7 +44,6 @@
>>> print(net(x)) >>> print(net(x))
[[0.]] [[0.]]
.. py:method:: cache_enable .. py:method:: cache_enable
:property: :property:
@ -67,7 +66,6 @@
`Parameter` ，返回克隆的新参数。 `Parameter` ，返回克隆的新参数。
.. py:method:: comm_fusion .. py:method:: comm_fusion
:property: :property:
@ -75,7 +73,6 @@
在 `AUTO_PARALLEL` 和 `SEMI_AUTO_PARALLEL` 模式下，一些用于参数或梯度聚合的通信算子将自动插入。fusion的值必须大于等于0。当fusion的值为0时，算子不会融合在一起。 在 `AUTO_PARALLEL` 和 `SEMI_AUTO_PARALLEL` 模式下，一些用于参数或梯度聚合的通信算子将自动插入。fusion的值必须大于等于0。当fusion的值为0时，算子不会融合在一起。
.. py:method:: data .. py:method:: data
:property: :property:
@ -89,28 +86,25 @@
- **layout** (Union[None, tuple])：参数的layout信息。layout[dev_mat, tensor_map, slice_shape, filed_size, uniform_split, opt_shard_group]：默认值：None。仅在 `SEMI_AUTO_PARALLEL` 或 `AUTO_PARALLEL` 模式下layout不是None。 - **layout** (Union[None, tuple])：参数的layout信息。layout[dev_mat, tensor_map, slice_shape, filed_size, uniform_split, opt_shard_group]：默认值：None。仅在 `SEMI_AUTO_PARALLEL` 或 `AUTO_PARALLEL` 模式下layout不是None。
- **dev_mat** (list(int))：该参数的设备矩阵。 - **dev_mat** (list(int))：该参数的设备矩阵。
- **tensor_map** (list(int))：该参数的张量映射。 - **tensor_map** (list(int))：该参数的张量映射。
- **slice_shape** (list(int))：该参数的切片shape。 - **slice_shape** (list(int))：该参数的切片shape。
- **filed_size** (int)：该权重的行数。 - **filed_size** (int)：该权重的行数。
- **uniform_split** (bool)：该参数是否进行均匀切分。 - **uniform_split** (bool)：该参数是否进行均匀切分。
- **opt_shard_group** (str)：该参数进行优化器切分时的group。 - **opt_shard_group** (str)：该参数进行优化器切分时的group。
- **set_sliced** (bool)：参数初始化时被设定为分片，则为True。默认值：False。 - **set_sliced** (bool)：参数初始化时被设定为分片，则为True。默认值：False。
**异常：** **异常：**
- **RuntimeError：** 参数使用 `Initializer` 模块进行初始化，初始化后并行模式发生更改。 - **RuntimeError：** 参数使用 `Initializer` 模块进行初始化，初始化后并行模式发生更改。
- **ValueError：** `layout` 长度小于6。 - **ValueError：** `layout` 长度小于6。
- **TypeError：** `layout` 不是元组。 - **TypeError：** `layout` 不是元组。
**返回：** **返回：**
初始化数据后的 `Parameter` 。如果当前 `Parameter` 已初始化，则更新 `Parameter` 数据。 初始化数据后的 `Parameter` 。如果当前 `Parameter` 已初始化，则更新 `Parameter` 数据。
.. py:method:: is_init .. py:method:: is_init
:property: :property:
@ -118,7 +112,6 @@
此属性仅在GE（Graph Engine）中有效，在其他后端将设为False。 此属性仅在GE（Graph Engine）中有效，在其他后端将设为False。
.. py:method:: layerwise_parallel .. py:method:: layerwise_parallel
:property: :property:
@ -126,7 +119,6 @@
在 `DATA_PARALLEL` 和 `HYBRID_PARALLEL` 模式下，如果 `layerwise_parallel` 为True，则广播和gradients通信将不会应用到参数。 在 `DATA_PARALLEL` 和 `HYBRID_PARALLEL` 模式下，如果 `layerwise_parallel` 为True，则广播和gradients通信将不会应用到参数。
.. py:method:: name .. py:method:: name
:property: :property:
@ -139,7 +131,6 @@
用于在 `AUTO_PARALLEL` 和 `SEMI_AUTO_PARALLEL` 模式下过滤权重切分操作。当在 `mindspore.context.set_auto_parallel_context()` 中启用优化器并行时，它才有效。 用于在 `AUTO_PARALLEL` 和 `SEMI_AUTO_PARALLEL` 模式下过滤权重切分操作。当在 `mindspore.context.set_auto_parallel_context()` 中启用优化器并行时，它才有效。
.. py:method:: parallel_optimizer_comm_recompute .. py:method:: parallel_optimizer_comm_recompute
:property: :property:
@ -151,7 +142,6 @@
- 仅支持 `Graph` 模式。 - 仅支持 `Graph` 模式。
- 建议使用(cell.recompute(parallel_optimizer_comm_recompute=True/False)去配置由优化器并行生成的 :class:`mindspore.ops.AllGather` 算子，而不是直接使用该接口。 - 建议使用(cell.recompute(parallel_optimizer_comm_recompute=True/False)去配置由优化器并行生成的 :class:`mindspore.ops.AllGather` 算子，而不是直接使用该接口。
.. py:method:: requires_grad .. py:method:: requires_grad
:property: :property:
@ -170,7 +160,6 @@
完成数据设置的新参数。 完成数据设置的新参数。
.. py:method:: set_param_fl(push_to_server=False, pull_from_server=False, requires_aggr=True) .. py:method:: set_param_fl(push_to_server=False, pull_from_server=False, requires_aggr=True)
设置参数和服务器的互动方式。 设置参数和服务器的互动方式。
@ -181,7 +170,6 @@
- **pull_from_server** (bool)：表示是否应从服务器中拉取参数。默认值：False。 - **pull_from_server** (bool)：表示是否应从服务器中拉取参数。默认值：False。
- **requires_aggr** (bool)：表示是否应在服务器中聚合参数。默认值：True。 - **requires_aggr** (bool)：表示是否应在服务器中聚合参数。默认值：True。
.. py:method:: set_param_ps(init_in_server=False) .. py:method:: set_param_ps(init_in_server=False)
表示可训练参数是否由参数服务器更新，以及可训练参数是否在服务器上初始化。 表示可训练参数是否由参数服务器更新，以及可训练参数是否在服务器上初始化。

1
docs/api/api_python/mindspore/mindspore.ParameterTuple.rst
View File

@ -7,7 +7,6 @@ mindspore.ParameterTuple
.. note::该类把网络参数存储到参数元组集合中。 .. note::该类把网络参数存储到参数元组集合中。
.. py:method:: clone(prefix, init='same') .. py:method:: clone(prefix, init='same')
按元素克隆 `ParameterTuple` 中的数值，以生成新的 `ParameterTuple` 。 按元素克隆 `ParameterTuple` 中的数值，以生成新的 `ParameterTuple` 。

2
docs/api/api_python/mindspore/mindspore.Tensor.rst
View File

@ -44,7 +44,6 @@ mindspore.Tensor
返回转置后的张量。 返回转置后的张量。
.. py:method:: abs() .. py:method:: abs()
返回每个元素的绝对值。 返回每个元素的绝对值。
@ -65,7 +64,6 @@ mindspore.Tensor
>>> print(output) >>> print(output)
[1.1 2.1] [1.1 2.1]
.. py:method:: all(axis=(), keep_dims=False) .. py:method:: all(axis=(), keep_dims=False)
检查在指定轴上所有元素是否均为True。 检查在指定轴上所有元素是否均为True。

78
docs/api/api_python/mindspore.connect_network_with_dataset.txt → docs/api/api_python/mindspore/mindspore.connect_network_with_dataset.rst
View File

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

11
docs/api/api_python/mindspore/mindspore.model.rst
View File

@ -7,15 +7,15 @@
.. note:: 同一批次数据应放在一个张量中。 .. note:: 同一批次数据应放在一个张量中。
**参数** ： **参数：**
**predict_data** (`Tensor`) – 单个或多个张量的预测数据。 **predict_data** (`Tensor`) – 单个或多个张量的预测数据。
**返回** ： **返回：**
Dict，用于加载分布式checkpoint的参数layout字典。它总是作为 `load_distributed_checkpoint()` 函数的一个入参。 Dict，用于加载分布式checkpoint的参数layout字典。它总是作为 `load_distributed_checkpoint()` 函数的一个入参。
**异常** : **异常：**
**RuntimeError** – 如果不是图模式（GRAPH_MODE）。 **RuntimeError** – 如果不是图模式（GRAPH_MODE）。
@ -43,14 +43,13 @@
.. note:: 这是一个预编译函数。参数必须与model.train()函数相同。 .. note:: 这是一个预编译函数。参数必须与model.train()函数相同。
**参数** ： **参数：**
- **train_dataset** (`Dataset`) – 一个训练数据集迭代器。如果没有损失函数（loss_fn），返回一个包含多个数据的元组（data1, data2, data3, ...）并传递给网络。否则，返回一个元组（data, label），数据和标签将被分别传递给网络和损失函数。 - **train_dataset** (`Dataset`) – 一个训练数据集迭代器。如果没有损失函数（loss_fn），返回一个包含多个数据的元组（data1, data2, data3, ...）并传递给网络。否则，返回一个元组（data, label），数据和标签将被分别传递给网络和损失函数。
- **dataset_sink_mode** (`bool`) – 决定是否以数据集下沉模式进行训练。默认值：True。配置项是PyNative模式或CPU时，训练模型流程使用的是数据不下沉（non-sink）模式。默认值：True。 - **dataset_sink_mode** (`bool`) – 决定是否以数据集下沉模式进行训练。默认值：True。配置项是PyNative模式或CPU时，训练模型流程使用的是数据不下沉（non-sink）模式。默认值：True。
- **sink_size** (`int`) – 控制每次数据下沉的数据量，如果 `sink_size` =-1，则每一次epoch下沉完整数据集。如果 `sink_size` >0，则每一次epoch下沉数据量为 `sink_size` 的数据集。如果 `dataset_sink_mode` 为False，则设置 `sink_size` 为无效。默认值：-1。 - **sink_size** (`int`) – 控制每次数据下沉的数据量，如果 `sink_size` =-1，则每一次epoch下沉完整数据集。如果 `sink_size` >0，则每一次epoch下沉数据量为 `sink_size` 的数据集。如果 `dataset_sink_mode` 为False，则设置 `sink_size` 为无效。默认值：-1。
**返回：**
**返回** ：
Dict，用于加载分布式checkpoint的参数layout字典。 Dict，用于加载分布式checkpoint的参数layout字典。

172
docs/api/api_python/nn/mindspore.nn.Adagrad.txt → docs/api/api_python/nn/mindspore.nn.Adagrad.rst
View File

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

202
docs/api/api_python/nn/mindspore.nn.Adam.txt → docs/api/api_python/nn/mindspore.nn.Adam.rst
View File

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

0
docs/api/api_python/nn/mindspore.nn.Jvp.txt → docs/api/api_python/nn/mindspore.nn.Jvp.rst
View File

150
docs/api/api_python/nn/mindspore.nn.Metric.txt → docs/api/api_python/nn/mindspore.nn.Metric.rst
View File

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

180
docs/api/api_python/nn/mindspore.nn.Momentum.txt → docs/api/api_python/nn/mindspore.nn.Momentum.rst
View File

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

284
docs/api/api_python/nn/mindspore.nn.Optimizer.txt → docs/api/api_python/nn/mindspore.nn.Optimizer.rst
View File

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

0
docs/api/api_python/nn/mindspore.nn.Vjp.txt → docs/api/api_python/nn/mindspore.nn.Vjp.rst
View File

420
docs/api/api_python/nn/mindspore.nn.cell.rst
View File

@ -3,388 +3,382 @@
.. py:class:: mindspore.nn.Cell(auto_prefix=True, flags=None) .. py:class:: mindspore.nn.Cell(auto_prefix=True, flags=None)
所有神经网络的基类。 所有神经网络的基类。
一个 `Cell` 可以是单一的神经网络单元，如 :class:`mindspore.nn.Conv2d`, :class:`mindspore.nn.ReLU, :class:`mindspore.nn.BatchNorm`等，也可以是组成网络的 `Cell` 的结合体。 一个 `Cell` 可以是单一的神经网络单元，如 :class:`mindspore.nn.Conv2d`, :class:`mindspore.nn.ReLU, :class:`mindspore.nn.BatchNorm`等，也可以是组成网络的 `Cell` 的结合体。
.. note:: 一般情况下，自动微分 (AutoDiff) 算法会自动调用梯度函数，但是如果使用反向传播方法 (bprop method)，梯度函数将会被反向传播方法代替。反向传播函数会接收一个包含损失对输出的梯度张量 `dout` 和一个包含前向传播结果的张量 `out` 。反向传播过程需要计算损失对输入的梯度，损失对参数变量的梯度目前暂不支持。反向传播函数必须包含自身参数。 .. note::
一般情况下，自动微分 (AutoDiff) 算法会自动调用梯度函数，但是如果使用反向传播方法 (bprop method)，梯度函数将会被反向传播方法代替。反向传播函数会接收一个包含损失对输出的梯度张量 `dout` 和一个包含前向传播结果的张量 `out` 。反向传播过程需要计算损失对输入的梯度，损失对参数变量的梯度目前暂不支持。反向传播函数必须包含自身参数。
**参数** ： **参数：**
- **auto_prefix** (`Cell`) – 递归地生成作用域。默认值：True。 - **auto_prefix** (`Cell`) – 递归地生成作用域。默认值：True。
- **flags** (`dict`) - Cell的配置信息，目前用于绑定Cell和数据集。用户也通过该参数自定义Cell属性。默认值：None。 - **flags** (`dict`) - Cell的配置信息，目前用于绑定Cell和数据集。用户也通过该参数自定义Cell属性。默认值：None。
**支持平台**： **支持平台**：
``Ascend`` ``GPU`` ``CPU`` ``Ascend`` ``GPU`` ``CPU``
**样例** : **样例** :
.. code-block:: >>> import mindspore.nn as nn
>>> import mindspore.ops as ops
>>> class MyCell(nn.Cell):
... def __init__(self):
... super(MyCell, self).__init__()
... self.relu = ops.ReLU()
...
... def construct(self, x):
... return self.relu(x)
>>> import mindspore.nn as nn .. py:method:: add_flags(**flags)
>>> import mindspore.ops as ops
>>> class MyCell(nn.Cell):
... def __init__(self):
... super(MyCell, self).__init__()
... self.relu = ops.ReLU()
...
... def construct(self, x):
... return self.relu(x)
.. py:method:: add_flags(**flags)
为Cell添加自定义属性。 为Cell添加自定义属性。
在实例化Cell类时，如果入参flags不为空，会调用此方法。 在实例化Cell类时，如果入参flags不为空，会调用此方法。
**参数：**
**flags** (`dict`) - Cell的配置信息，目前用于绑定Cell和数据集。用户也通过该参数自定义Cell属性。默认值：None。
**参数** ： .. py:method:: add_flags_recursive(**flags)
**flags** (`dict`) - Cell的配置信息，目前用于绑定Cell和数据集。用户也通过该参数自定义Cell属性。默认值：None。
.. py:method:: add_flags_recursive(**flags)
如果Cell含有多个子Cell，此方法会递归得给所有子Cell添加自定义属性。 如果Cell含有多个子Cell，此方法会递归得给所有子Cell添加自定义属性。
**参数** ： **参数：**
**flags** (`dict`) - Cell的配置信息，目前用于绑定Cell和数据集。用户也通过该参数自定义Cell属性。默认值：None。 **flags** (`dict`) - Cell的配置信息，目前用于绑定Cell和数据集。用户也通过该参数自定义Cell属性。默认值：None。
.. py:method:: cast_inputs(inputs, dst_type)
.. py:method:: cast_inputs(inputs, dst_type)
将输入转换为指定类型。 将输入转换为指定类型。
**参数** ： **参数：**
**inputs** (`tuple[Tensor]`) - 输入。 - **inputs** (`tuple[Tensor]`) - 输入。
**dst_type** (`mindspore.dtype`) - 指定的数据类型。 - **dst_type** (`mindspore.dtype`) - 指定的数据类型。
**返回**： **返回：**
tuple[Tensor]类型，转换类型后的结果。 tuple[Tensor]类型，转换类型后的结果。
.. py:method:: cast_param(param) .. py:method:: cast_param(param)
在PyNative模式下，根据自动混合精度的精度设置转换Cell中参数的类型。 在PyNative模式下，根据自动混合精度的精度设置转换Cell中参数的类型。
该接口目前在自动混合精度场景下使用。 该接口目前在自动混合精度场景下使用。
**参数**： **参数：**
**param** (`Parameter`) – Parameter类型，需要被转换类型的输入参数。 **param** (`Parameter`) – Parameter类型，需要被转换类型的输入参数。
**返回**： **返回：**
Parameter类型，转换类型后的参数。 Parameter类型，转换类型后的参数。
.. py:method:: cells() .. py:method:: cells()
返回当前Cell的子Cell的迭代器。 返回当前Cell的子Cell的迭代器。
**返回：**
**返回**： Iteration类型，Cell的子Cell。
Iteration类型，Cell的子Cell。 .. py:method:: cells_and_names(cells=None, name_prefix="")
.. py:method:: cells_and_names(cells=None, name_prefix="") 递归地获取当前Cell及输入 `cells` 的所有子Cell的迭代器，包括Cell的名称及其本身。
递归地获取当前Cell及输入 `cells` 的所有子Cell的迭代器，包括Cell的名称及其本身。 **参数：**
**参数**： - **cell** (`str`) – 需要进行迭代的Cell。默认值：None。
- **name_prefix** (`str`) – 作用域。默认值：''。
- **cell** (`str`) – 需要进行迭代的Cell。默认值：None。 **返回：**
- **name_prefix** (`str`) – 作用域。默认值：''。
**返回**： Iteration类型，当前Cell及输入 `cells` 的所有子Cell和相对应的名称。
Iteration类型，当前Cell及输入 `cells` 的所有子Cell和相对应的名称。 **样例：**
**样例** : >>> n = Net()
>>> names = []
>>> for m in n.cells_and_names():
... if m[0]:
... names.append(m[0])
.. py:method:: check_names()
.. code-block:: 检查Cell中的网络参数名称是否重复。
>>> n = Net() .. py:method:: compile(*inputs)
>>> names = []
>>> for m in n.cells_and_names():
... if m[0]:
... names.append(m[0])
.. py:method:: check_names() 编译Cell。
检查Cell中的网络参数名称是否重复。 **参数：**
**inputs** (`tuple`) – Cell的输入。
.. py:method:: compile(*inputs) .. py:method:: compile_and_run(*inputs)
编译Cell。 编译并运行Cell。
**参数**： **参数：**
**inputs** (`tuple`) – Cell的输入。 **inputs** (`tuple`) – Cell的输入。
.. py:method:: compile_and_run(*inputs) **返回：**
编译并运行Cell。 Object类型，执行的结果。
**参数**： .. py:method:: construct(*inputs, **kwargs)
**inputs** (`tuple`) – Cell的输入。 定义要执行的计算逻辑。所有子类都必须重写此方法。
**返回**： **返回：**
Object类型，执行的结果。 Tensor类型，返回计算结果。
.. py:method:: construct(*inputs, **kwargs) .. py:method:: exec_checkpoint_graph()
定义要执行的计算逻辑。所有子类都必须重写此方法。 保存checkpoint图。
**返回**： .. py:method:: extend_repr()
设置Cell的扩展表示形式。
Tensor类型，返回计算结果。 若需要在print时输出个性化的扩展信息，请在您的网络中重新实现此方法。
.. py:method:: exec_checkpoint_graph() .. py:method:: generate_scope()
保存checkpoint图。 为网络中的每个Cell对象生成作用域。
.. py:method:: extend_repr() .. py:method:: get_flags()
设置Cell的扩展表示形式。 获取该Cell的自定义属性。自定义属性通过 `add_flags` 方法添加。
若需要在print时输出个性化的扩展信息，请在您的网络中重新实现此方法。 .. py:method:: get_func_graph_proto()
.. py:method:: generate_scope() 返回图的二进制原型。
为网络中的每个Cell对象生成作用域。 .. py:method:: get_parameters(expand=True)
.. py:method:: get_flags() 返回一个该Cell中parameter的迭代器。
获取该Cell的自定义属性。自定义属性通过 `add_flags` 方法添加。 **参数：**
.. py:method:: get_func_graph_proto() **expand** (`bool`) – 如果为True，则递归地获取当前Cell和所有子Cell的parameter。否则，只生成当前Cell的子Cell的parameter。默认值：True。
返回图的二进制原型。 **返回：**
.. py:method:: get_parameters(expand=True) Iteration类型，Cell的parameter。
返回一个该Cell中parameter的迭代器。 **样例：**
**参数**： >>> n = Net()
>>> parameters = []
>>> for item in net.get_parameters():
... parameters.append(item)
**expand** (`bool`) – 如果为True，则递归地获取当前Cell和所有子Cell的parameter。否则，只生成当前Cell的子Cell的parameter。默认值：True。 .. py:method:: get_scope()
**返回**： 返回Cell的作用域。
Iteration类型，Cell的parameter。 **返回：**
**样例** : String类型，网络的作用域。
.. code-block:: .. py:method:: insert_child_to_cell(child_name, child_cell)
>>> n = Net() 将一个给定名称的子Cell添加到当前Cell。
>>> parameters = []
>>> for item in net.get_parameters():
... parameters.append(item)
.. py:method:: get_scope() **参数：**
返回Cell的作用域。 - **child_name** (`str`) – 子Cell名称。
- **child_cell** (`Cell`) – 要插入的子Cell。
**返回**： **异常：**
String类型，网络的作用域。 - **KeyError** – 如果子Cell的名称不正确或与其他子Cell名称重复。
- **TypeError** – 如果子Cell的类型不正确。
.. py:method:: insert_param_to_cell(param_name, param, check_name=True)
.. py:method:: insert_child_to_cell(child_name, child_cell) 向当前Cell添加参数。
将一个给定名称的子Cell添加到当前Cell。 将指定名称的参数插入Cell。目前在 `mindspore.nn.Cell.__setattr__` 中使用。
**参数**： **参数：**
- **child_name** (`str`) – 子Cell名称。 - **param_name** (`str`) – 参数名称。
- **child_cell** (`Cell`) – 要插入的子Cell。 - **param** (`Parameter`) – 要插入到Cell的参数。
- **check_name** (`bool`) – 是否对 `param_name` 中的"."进行检查。默认值：True。
**异常**： **异常：**
- **KeyError** – 如果子Cell的名称不正确或与其他子Cell名称重复。 - **KeyError** – 如果参数名称为空或包含"."。
- **TypeError** – 如果子Cell的类型不正确。 - **TypeError** – 如果参数的类型不是Parameter。
.. py:method:: insert_param_to_cell(param_name, param, check_name=True) .. py:method:: name_cells()
向当前Cell添加参数。 递归地获取一个Cell中所有子Cell的迭代器。
将指定名称的参数插入Cell。目前在 `mindspore.nn.Cell.__setattr__` 中使用。 包括Cell名称和Cell本身。
**参数**： **返回：**
- **param_name** (`str`) – 参数名称。 Dict[String, Cell]，Cell中的所有子Cell及其名称。
- **param** (`Parameter`) – 要插入到Cell的参数。
- **check_name** (`bool`) – 是否对`param_name`中的"."进行检查。默认值：True。
**异常**： .. py:method:: parameters_and_names(name_prefix='', expand=True)
- **KeyError** – 如果参数名称为空或包含"."。
- **TypeError** – 如果参数的类型不是Parameter。
.. py:method:: name_cells()
递归地获取一个Cell中所有子Cell的迭代器。
包括Cell名称和Cell本身。
**返回**：
Dict[String, Cell]，Cell中的所有子Cell及其名称。
.. py:method:: parameters_and_names(name_prefix='', expand=True)
返回Cell中parameter的迭代器。 返回Cell中parameter的迭代器。
包含参数名称和参数本身。 包含参数名称和参数本身。
**参数**: **参数：**
name_prefix (str): 作用域。默认值： ''。
expand (bool): 如果为True，则递归地获取当前Cell和所有子Cell的参数及名称；如果为False，只生成当前Cell的子Cell的参数及名称。默认值：True.
**返回**: - **name_prefix** (str): 作用域。默认值： ''。
迭代器，Cell的名称和Cell本身。 - **expand** (bool): 如果为True，则递归地获取当前Cell和所有子Cell的参数及名称；如果为False，只生成当前Cell的子Cell的参数及名称。默认值：True.
**样例**: **返回：**
>>> n = Net()
>>> names = []
>>> for m in n.parameters_and_names():
... if m[0]:
... names.append(m[0])
.. py:property:: param_prefix 迭代器，Cell的名称和Cell本身。
当前Cell的子Cell的参数名前缀。 **样例：**
.. py:method:: parameters_dict(recurse=True) >>> n = Net()
>>> names = []
>>> for m in n.parameters_and_names():
... if m[0]:
... names.append(m[0])
获取此Cell的parameter字典。 .. py:method:: param_prefix
:property:
**参数**： 当前Cell的子Cell的参数名前缀。
**recurse** (`bool`) – 是否递归得包含所有子Cell的parameter。默认值：True。 .. py:method:: parameters_dict(recurse=True)
**返回**： 获取此Cell的parameter字典。
OrderedDict类型，返回参数字典。 **参数：**
.. py:method:: remove_redundant_parameters() **recurse** (`bool`) – 是否递归得包含所有子Cell的parameter。默认值：True。
删除冗余参数。 **返回：**
这个接口通常不需要显式调用。 OrderedDict类型，返回参数字典。
.. py:method:: set_comm_fusion(fusion_type, recurse=True) .. py:method:: remove_redundant_parameters()
为Cell中的参数设置融合类型。请参考 :class:`mindspore.Parameter.comm_fusion` 的描述。 删除冗余参数。
.. note:: 当函数被多次调用时，此属性值将被重写。 这个接口通常不需要显式调用。
**参数**： .. py:method:: set_comm_fusion(fusion_type, recurse=True)
- **fusion_type** (`int`) – Parameter的`comm_fusion` 属性的设置值。 为Cell中的参数设置融合类型。请参考 :class:`mindspore.Parameter.comm_fusion` 的描述。
- **recurse** (`bool`) – 是否递归地设置子Cell的可训练参数。默认值：True。
.. py:method:: set_grad(requires_grad=True) .. note:: 当函数被多次调用时，此属性值将被重写。
Cell的梯度设置。在PyNative模式下，该参数指定Cell是否需要梯度。如果为True，则在执行正向网络时，将生成需要计算梯度的反向网络。 **参数：**
**参数**： - **fusion_type** (`int`) – Parameter的 `comm_fusion` 属性的设置值。
- **recurse** (`bool`) – 是否递归地设置子Cell的可训练参数。默认值：True。
**requires_grad** (`bool`) – 指定网络是否需要梯度，如果为True，PyNative模式下Cell将构建反向网络。默认值：True。 .. py:method:: set_grad(requires_grad=True)
**返回**： Cell的梯度设置。在PyNative模式下，该参数指定Cell是否需要梯度。如果为True，则在执行正向网络时，将生成需要计算梯度的反向网络。
Cell类型，Cell本身。 **参数：**
.. py:method:: set_train(mode=True) **requires_grad** (`bool`) – 指定网络是否需要梯度，如果为True，PyNative模式下Cell将构建反向网络。默认值：True。
将Cell设置为训练模式。 **返回：**
设置当前Cell和所有子Cell的训练模式。对于训练和预测具有不同结构的网络层(如 `BatchNorm`)，将通过这个属性区分分支。如果设置为True，则执行训练分支，否则执行另一个分支。 Cell类型，Cell本身。
**参数**： .. py:method:: set_train(mode=True)
**mode** (`bool`) – 指定模型是否为训练模式。默认值：True。 将Cell设置为训练模式。
**返回**： 设置当前Cell和所有子Cell的训练模式。对于训练和预测具有不同结构的网络层(如 `BatchNorm`)，将通过这个属性区分分支。如果设置为True，则执行训练分支，否则执行另一个分支。
Cell类型，Cell本身。 **参数：**
.. py:method:: to_float(dst_type) **mode** (`bool`) – 指定模型是否为训练模式。默认值：True。
在Cell和所有子Cell的输入上添加类型转换，以使用特定的浮点类型运行。 **返回：**
如果 `dst_type` 是 `mindspore.dtype.float16` ，Cell的所有输入(包括作为常量的input， Parameter， Tensor)都会被转换为float16。请参考 `mindspore.build_train_network` 的源代码中的用法。 Cell类型，Cell本身。
.. note:: 多次调用将产生覆盖。 .. py:method:: to_float(dst_type)
**参数**： 在Cell和所有子Cell的输入上添加类型转换，以使用特定的浮点类型运行。
**dst_type** (`mindspore.dtype`) – Cell转换为 `dst_type` 类型运行。 `dst_type` 可以是 `mindspore.dtype.float16` 或者 `mindspore.dtype.float32` 。 如果 `dst_type` 是 `mindspore.dtype.float16` ，Cell的所有输入(包括作为常量的input， Parameter， Tensor)都会被转换为float16。请参考 `mindspore.build_train_network` 的源代码中的用法。
**返回**： .. note:: 多次调用将产生覆盖。
Cell类型，Cell本身。 **参数：**
**异常**： **dst_type** (`mindspore.dtype`) – Cell转换为 `dst_type` 类型运行。 `dst_type` 可以是 `mindspore.dtype.float16` 或者 `mindspore.dtype.float32` 。
**ValueError** – 如果 `dst_type` 不是 `mindspore.dtype.float32` ，也不是`mindspore.dtype.float16`。 **返回：**
.. py:method:: trainable_params(recurse=True) Cell类型，Cell本身。
返回Cell的可训练参数。 **异常：**
返回一个可训练参数的列表。 **ValueError** – 如果 `dst_type` 不是 `mindspore.dtype.float32` ，也不是 `mindspore.dtype.float16`。
**参数**： .. py:method:: trainable_params(recurse=True)
**recurse** (`bool`) – 是否递归地包含当前Cell的所有子Cell的可训练参数。默认值：True。 返回Cell的可训练参数。
**返回**： 返回一个可训练参数的列表。
List类型，可训练参数列表。 **参数：**
.. py:method:: untrainable_params(recurse=True) **recurse** (`bool`) – 是否递归地包含当前Cell的所有子Cell的可训练参数。默认值：True。
返回Cell的不可训练参数。 **返回：**
返回一个不可训练参数的列表。 List类型，可训练参数列表。
**参数**： .. py:method:: untrainable_params(recurse=True)
**recurse** (`bool`) – 是否递归地包含当前Cell的所有子Cell的不可训练参数。默认值：True。 返回Cell的不可训练参数。
**返回**： 返回一个不可训练参数的列表。
List类型，不可训练参数列表。 **参数：**
.. py:method:: update_cell_prefix() **recurse** (`bool`) – 是否递归地包含当前Cell的所有子Cell的不可训练参数。默认值：True。
递归地更新所有子Cell的 `param_prefix` 。 **返回：**
在调用此方法后，可以通过Cell的 `param_prefix` 属性获取该Cell的所有子Cell的名称前缀。 List类型，不可训练参数列表。
.. py:method:: update_cell_type(cell_type) .. py:method:: update_cell_prefix()
量化感知训练网络场景下，更新当前Cell的类型。 递归地更新所有子Cell的 `param_prefix` 。
此方法将Cell类型设置为 `cell_type` 。 在调用此方法后，可以通过Cell的 `param_prefix` 属性获取该Cell的所有子Cell的名称前缀。
**参数**： .. py:method:: update_cell_type(cell_type)
**cell_type** (str) – 被更新的类型，`cell_type` 可以是"quant"或"second-order"。 量化感知训练网络场景下，更新当前Cell的类型。
.. py:method:: update_parameters_name(prefix="", recurse=True) 此方法将Cell类型设置为 `cell_type` 。
给网络参数名称添加 `prefix` 前缀字符串。 **参数：**
**参数**： **cell_type** (str) – 被更新的类型，`cell_type` 可以是"quant"或"second-order"。
- **prefix** (`str`) – 前缀字符串。默认值：''。 .. py:method:: update_parameters_name(prefix="", recurse=True)
- **recurse** (`bool`) – 是否递归地包含所有子Cell的参数。默认值：True。
给网络参数名称添加 `prefix` 前缀字符串。
**参数：**
- **prefix** (`str`) – 前缀字符串。默认值：''。
- **recurse** (`bool`) – 是否递归地包含所有子Cell的参数。默认值：True。