diff --git a/doc/fluid/api_cn/optimizer_cn/ModelAverage_cn.rst b/doc/fluid/api_cn/optimizer_cn/ModelAverage_cn.rst index 195eae1e35b59a73b75629cd214b58b7352eac12..980e5a1d7c84776e1afc0a082f52707516575919 100644 --- a/doc/fluid/api_cn/optimizer_cn/ModelAverage_cn.rst +++ b/doc/fluid/api_cn/optimizer_cn/ModelAverage_cn.rst @@ -5,17 +5,27 @@ ModelAverage .. py:class:: paddle.fluid.optimizer.ModelAverage(average_window_rate, min_average_window=10000, max_average_window=10000, regularization=None, name=None) -在滑动窗口中累积参数的平均值。平均结果将保存在临时变量中，通过调用 ``apply()`` 方法可应用于当前模型的参数变量。使用 ``restore()`` 方法恢复当前模型的参数值。 +ModelAverage优化器，在训练过程中累积特定连续的历史Parameters，累积的历史范围可以用传入的average_window参数来控制，在预测时使用平均后的Parameters，通常可以提高预测的精度。 -平均窗口的大小由 ``average_window_rate`` ， ``min_average_window`` ， ``max_average_window`` 以及当前更新次数决定。 +在滑动窗口中累积Parameters的平均值，将结果将保存在临时变量中，通过调用 ``apply()`` 方法可应用于当前模型的Parameters，使用 ``restore()`` 方法恢复当前模型Parameters的值。 +计算平均值的窗口大小由 ``average_window_rate`` ， ``min_average_window`` ， ``max_average_window`` 以及当前Parameters更新次数(num_updates)共同决定。 + +累积次数（num_accumulates）大于特定窗口阈值(average_window)时，将累积的Parameters临时变量置为0.0，这几个参数的作用通过以下示例代码说明： + +.. code-block:: python + + if num_accumulates >= min_average_window and num_accumulates >= min(max_average_window, num_updates * average_window_rate): + num_accumulates = 0 + +上述条件判断语句中，num_accumulates表示当前累积的次数，可以抽象理解为累积窗口的长度，窗口长度至少要达到min_average_window参数设定的长度，并且不能超过max_average_window参数或者num_updates * average_window_rate规定的长度，其中num_updates表示当前Parameters更新的次数，average_window_rate是一个计算窗口长度的系数。 -参数: - - **average_window_rate** – 窗口平均速率 - - **min_average_window** – 平均窗口大小的最小值 - - **max_average_window** – 平均窗口大小的最大值 - - **regularization** – 正则化器，例如 ``fluid.regularizer.L2DecayRegularizer`` - - **name** – 可选的名称前缀 +参数： + - **average_window_rate** (float) – 相对于Parameters更新次数的窗口长度计算比率 + - **min_average_window** (int, 可选) – 平均值计算窗口长度的最小值，默认值为10000 + - **max_average_window** (int, 可选) – 平均值计算窗口长度的最大值，推荐设置为一轮训练中mini-batchs的数目，默认值为10000 + - **regularization** (WeightDecayRegularizer, 可选) – 正则化函数，用于减少泛化误差。例如可以是 :ref:`cn_api_fluid_regularizer_L2DecayRegularizer` ，默认值为None + - **name** (str, 可选)– 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，默认值为None **代码示例** @@ -41,12 +51,13 @@ ModelAverage # 构建ModelAverage优化器 model_average = fluid.optimizer.ModelAverage(0.15, min_average_window=10000, - max_average_window=20000) + max_average_window=12500) exe.run(startup_program) - x = numpy.random.random(size=(10, 1)).astype('float32') - outs = exe.run(program=train_program, - feed={'X': x}, - fetch_list=[loss.name]) + for i in range(12500): + x = numpy.random.random(size=(10, 1)).astype('float32') + outs = exe.run(program=train_program, + feed={'X': x}, + fetch_list=[loss.name]) # 应用ModelAverage with model_average.apply(exe): x = numpy.random.random(size=(10, 1)).astype('float32') @@ -57,173 +68,99 @@ ModelAverage .. py:method:: apply(executor, need_restore=True) -将平均值应用于当前模型的参数。 - -参数： - - **executor** (fluid.Executor) – 当前的执行引擎。 - - **need_restore** (bool) – 如果您最后需要实现恢复，将其设为True。默认值True。 - - -.. py:method:: restore(executor) - -恢复当前模型的参数值 +将累积Parameters的平均值应用于当前网络的Parameters。 参数： - - **executor** (fluid.Executor) – 当前的执行引擎。 + - **executor** (fluid.Executor) – 当前网络的执行器 + - **need_restore** (bool) – 恢复标志变量，设为True时，执行完成后会将网络的Parameters恢复为网络默认的值，设为False将不会恢复，默认值True - -.. py:method:: apply_gradients(params_grads) - -为给定的params_grads对附加优化算子，为minimize过程的第二步 - -参数： - - **params_grads** (list)- 用于优化的(param, grad)对组成的列表 - -返回： 附加在当前Program的算子组成的列表 - -返回类型： list +返回：无 **代码示例** .. code-block:: python - + import paddle.fluid as fluid - loss = network() - optimizer = fluid.optimizer.SGD(learning_rate=0.1) - params_grads = optimizer.backward(loss) - # you may append operations for params_grads here - # ... - optimizer.apply_gradients(params_grads) - - -.. py:method:: apply_optimize(loss, startup_program, params_grads) - -为给定的params_grads对附加优化算子，为minimize过程的第二步。 - -参数： - - **loss** (Variable) – 用于优化过程的损失值变量 - - **startup_program** (Program) – 用于初始化在parameter_list中参数的startup_program - - **params_grads** (list)- 用于优化的(param, grad)对组成的列表 + import numpy + + # 首先创建执行引擎 + place = fluid.CPUPlace() # fluid.CUDAPlace(0) + exe = fluid.Executor(place) + + train_program = fluid.Program() + startup_program = fluid.Program() + with fluid.program_guard(train_program, startup_program): + # 构建net + data = fluid.layers.data(name='X', shape=[1], dtype='float32') + hidden = fluid.layers.fc(input=data, size=10) + loss = fluid.layers.mean(hidden) + optimizer = fluid.optimizer.Momentum(learning_rate=0.2, momentum=0.1) + optimizer.minimize(loss) -返回： 附加在当前Program的算子组成的列表 + # 构建ModelAverage优化器 + model_average = fluid.optimizer.ModelAverage(0.15, + min_average_window=10000, + max_average_window=12500) + exe.run(startup_program) + for i in range(12500): + x = numpy.random.random(size=(10, 1)).astype('float32') + outs = exe.run(program=train_program, + feed={'X': x}, + fetch_list=[loss.name]) -返回类型： list + # 应用ModelAverage + with model_average.apply(exe): + x = numpy.random.random(size=(10, 1)).astype('float32') + exe.run(program=train_program, + feed={'X': x}, + fetch_list=[loss.name]) -.. py:method:: backward(loss, startup_program=None, parameter_list=None, no_grad_set=None, callbacks=None) +.. py:method:: restore(executor) -自动做diff来向当前program附加反向算子，为minimize过程的第一步。 +恢复当前网络的Parameters值 参数： - - **loss** (Variable) – 用于优化过程的损失值变量 - - **startup_program** (Program) – 用于初始化在parameter_list中参数的startup_program - - **parameter_list** (list) – 待更新的Variables组成的列表 - - **no_grad_set** (set|None) – 应该被无视的Variables集合 - - **callbacks** (list|None) – 当为某参数附加反向算子时所要运行的callables组成的列表 - -返回： 附加在当前Program的算子组成的列表 + - **executor** (fluid.Executor) – 当前网络的执行器 -返回类型： list - -**代码示例** - -详见apply_gradients的示例 - - -.. py:method:: load(stat_dict) - -在dygraph模式下，附带学习率衰减来加载优化器。 - -参数： - - **stat_dict** – load_persistable方法加载的dict +返回：无 **代码示例** .. code-block:: python - - from __future__ import print_function - import numpy as np - import paddle + import paddle.fluid as fluid - from paddle.fluid.optimizer import SGDOptimizer - from paddle.fluid.dygraph.nn import FC - from paddle.fluid.dygraph.base import to_variable - - class MLP(fluid.Layer): - def __init__(self, name_scope): - super(MLP, self).__init__(name_scope) - - self._fc1 = FC(self.full_name(), 10) - self._fc2 = FC(self.full_name(), 10) - - def forward(self, inputs): - y = self._fc1(inputs) - y = self._fc2(y) - return y - - with fluid.dygraph.guard(): - mlp = MLP('mlp') - optimizer2 = SGDOptimizer( - learning_rate=fluid.layers.natural_exp_decay( - learning_rate=0.1, - decay_steps=10000, - decay_rate=0.5, - staircase=True)) - - train_reader = paddle.batch( - paddle.dataset.mnist.train(), batch_size=128, drop_last=True) - - for batch_id, data in enumerate(train_reader()): - dy_x_data = np.array( - [x[0].reshape(1, 28, 28) for x in data]).astype('float32') - - y_data = np.array([x[1] for x in data]).astype('int64').reshape( - 128, 1) - - img = to_variable(dy_x_data) - label = to_variable(y_data) - label._stop_gradient = True - cost = mlp(img) - avg_loss = fluid.layers.reduce_mean(cost) - avg_loss.backward() - optimizer.minimize(avg_loss) - mlp.clear_gradients() - fluid.dygraph.save_persistables( - mlp.state_dict(), [optimizer, optimizer2], "save_dir_2") - if batch_id == 2: - break - - with fluid.dygraph.guard(): - mlp_load = MLP('mlp') - optimizer_load2 = SGDOptimizer( - learning_rate=fluid.layers.natural_exp_decay( - learning_rate=0.1, - decay_steps=10000, - decay_rate=0.5, - staircase=True)) - parameters, optimizers = fluid.dygraph.load_persistables( - "save_dir_2") - mlp_load.load_dict(parameters) - optimizer_load2.load(optimizers) - self.assertTrue(optimizer2._learning_rate.__dict__ == optimizer_load2._learning_rate.__dict__) - - -.. py:method:: minimize(loss, startup_program=None, parameter_list=None, no_grad_set=None, grad_clip=None) - - -通过更新parameter_list来添加操作，进而使损失最小化。 - -该算子相当于backward()和apply_gradients()功能的合体。 - -参数： - - **loss** (Variable) – 用于优化过程的损失值变量 - - **startup_program** (Program) – 用于初始化在parameter_list中参数的startup_program - - **parameter_list** (list) – 待更新的Variables组成的列表 - - **no_grad_set** (set|None) – 应该被无视的Variables集合 - - **grad_clip** (GradClipBase|None) – 梯度裁剪的策略 - -返回： (optimize_ops, params_grads)，分别为附加的算子列表；一个由(param, grad) 变量对组成的列表，用于优化 - -返回类型： tuple - + import numpy + + # 首先创建执行引擎 + place = fluid.CPUPlace() # fluid.CUDAPlace(0) + exe = fluid.Executor(place) + + train_program = fluid.Program() + startup_program = fluid.Program() + with fluid.program_guard(train_program, startup_program): + # 构建net + data = fluid.layers.data(name='X', shape=[1], dtype='float32') + hidden = fluid.layers.fc(input=data, size=10) + loss = fluid.layers.mean(hidden) + optimizer = fluid.optimizer.Momentum(learning_rate=0.2, momentum=0.1) + optimizer.minimize(loss) + # 构建ModelAverage优化器 + model_average = fluid.optimizer.ModelAverage(0.15, + min_average_window=10000, + max_average_window=12500) + exe.run(startup_program) + for i in range(12500): + x = numpy.random.random(size=(10, 1)).astype('float32') + outs = exe.run(program=train_program, + feed={'X': x}, + fetch_list=[loss.name]) + # 应用ModelAverage + with model_average.apply(exe, False): + x = numpy.random.random(size=(10, 1)).astype('float32') + exe.run(program=train_program, + feed={'X': x}, + fetch_list=[loss.name]) + # 恢复网络Parameters + model_average.restore(exe)