Polish the Chinese API documentation of ModelAverage (#1207)

* polish model average zh doc api

* polish details

* polish based review commment

* fix indent

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)