fix gradient clip doc for new gradient clipping strategy,test=develop (#1942)

doc/fluid/api_cn/clip_cn/GradientClipByGlobalNorm_cn.rst

@@ -3,13 +3,19 @@
 GradientClipByGlobalNorm
 -------------------------------
 
-.. py:class:: paddle.fluid.clip.GradientClipByGlobalNorm(clip_norm, group_name='default_group')
+.. py:class:: paddle.fluid.clip.GradientClipByGlobalNorm(clip_norm, group_name='default_group', need_clip=None)
  
-通过多个 Tensor 的范数之和的比率，来剪切（clip）多个 Tensor （ Tensor 不是从该类传入， 通过 ``fluid.program_guard`` 的 ``main_program`` 参数传入，即公式中的 :math:`t\_list` 见代码实例）。
+将一个 Tensor列表 :math:`t\_list` 中所有Tensor的L2范数之和，限定在 ``clip_norm`` 范围内。
 
-给定一个 Tensor 列表 :math:`t\_list` 和一个剪切比率 ``clip_norm`` ，返回该类的实例作为 ``set_gradient_clip`` 方法的第一个参数， ``set_gradient_clip`` 第二个参数是用来计算被剪切的 Tensor 列表（该值默认为 ``None`` 会基于所有 Tensor 列表来计算全局范数 ``global_norm`` 。
+- 如果范数之和大于 ``clip_norm`` ，则所有 Tensor 会乘以一个系数进行压缩
 
-剪切过程如下：
+- 如果范数之和小于或等于 ``clip_norm`` ，则不会进行任何操作。
+
+输入的 Tensor列表 不是从该类里传入， 而是默认会选择 ``Program`` 中全部的梯度，如果 ``need_clip`` 不为None，则可以只选择部分参数进行梯度裁剪。
+
+该类需要在 ``optimizer.minimize(grad_clip)`` 进行设置后才能生效，可参看 ``optimizer`` 文档(例如： :ref:`cn_api_fluid_optimizer_SGDOptimizer` )。
+
+裁剪公式如下：
 
 .. math::
             \\t\_list[i]=t\_list[i]∗\frac{clip\_norm}{max(global\_norm,clip\_norm)}\\
@@ -21,67 +27,73 @@ GradientClipByGlobalNorm
 
 
 参数:
- - **clip_norm** (float) - 范数最大值
+ - **clip_norm** (float) - 所允许的范数最大值
  - **group_name** (str, optional) - 剪切的组名
+ - **need_clip** (function, optional) - 类型: 函数。用于指定需要梯度裁剪的参数，该函数接收一个 ``Parameter`` ，返回一个 ``bool`` (True表示需要裁剪，False不需要裁剪)。默认为None，此时会裁剪网络中全部参数。
   
-**代码示例**
+**代码示例1：静态图**
  
 .. code-block:: python
-        
-    import paddle.fluid as fluid
-    import paddle.fluid.core as core
+            
     import paddle
-
-    place = core.CPUPlace()
-    prog = fluid.framework.Program()
-    startup_program = fluid.framework.Program()
+    import paddle.fluid as fluid
+    import numpy as np
+                
+    main_prog = fluid.Program()
+    startup_prog = fluid.Program()
     with fluid.program_guard(
-            main_program=prog, startup_program=startup_program):
-        image = fluid.layers.data(name='x', shape=[784], dtype='float32')
-        label = fluid.layers.data(name='y', shape=[1], dtype='int64')
-        hidden1 = fluid.layers.fc(input=image, size=128, act='relu')
-        hidden2 = fluid.layers.fc(input=hidden1, size=64, act='relu')
-        predict = fluid.layers.fc(input=hidden2, size=10, act='softmax')
-        cost = fluid.layers.cross_entropy(input=predict, label=label)
-        avg_cost = fluid.layers.mean(cost)
-
-    prog_clip = prog.clone()
-    avg_cost_clip = prog_clip.block(0).var(avg_cost.name)
-
-    p_g = fluid.backward.append_backward(loss=avg_cost)
-    p_g_clip = fluid.backward.append_backward(loss=avg_cost_clip)
-
-    with fluid.program_guard(main_program=prog_clip, startup_program=startup_program):
-        fluid.clip.set_gradient_clip(
-            fluid.clip.GradientClipByGlobalNorm(clip_norm=2.0))
-        p_g_clip = fluid.clip.append_gradient_clip_ops(p_g_clip)
-
-    grad_list = [elem[1] for elem in p_g]
-    grad_clip_list = [elem[1] for elem in p_g_clip]
-
-    train_reader = paddle.batch(
-        paddle.reader.shuffle(
-            paddle.dataset.mnist.train(), buf_size=8192),
-        batch_size=128)
-
-    exe = fluid.Executor(place)
-    feeder = fluid.DataFeeder(feed_list=[image, label], place=place)
-    exe.run(startup_program)
-
-    count = 0
-    for data in train_reader():
-        count += 1
-        print("count:%s" % count)
-        if count > 5:
-            break
-        out = exe.run(prog, feed=feeder.feed(data), fetch_list=grad_list)
-        out_clip = exe.run(prog_clip,
-                           feed=feeder.feed(data),
-                           fetch_list=grad_clip_list)
-
+            main_program=main_prog, startup_program=startup_prog):
+        image = fluid.data(
+            name='x', shape=[-1, 2], dtype='float32')
+        predict = fluid.layers.fc(input=image, size=3, act='relu') #Trainable parameters: fc_0.w.0, fc_0.b.0
+        loss = fluid.layers.mean(predict)
+        
+        # 裁剪网络中全部参数：
+        clip = fluid.clip.GradientClipByGlobalNorm(clip_norm=1.0)
+        
+        # 仅裁剪参数fc_0.w_0时：
+        # 为need_clip参数传入一个函数fileter_func，fileter_func接收参数的类型为Parameter，返回类型为bool
+        # def fileter_func(Parameter):
+        # # 可以较为方便的通过Parameter.name判断（name可以在fluid.ParamAttr中设置，默认为fc_0.w_0、fc_0.b_0）
+        #   return Parameter.name=="fc_0.w_0"
+        # clip = fluid.clip.GradientClipByGlobalNorm(clip_norm=1.0, need_clip=fileter_func)
 
+        sgd_optimizer = fluid.optimizer.SGDOptimizer(learning_rate=0.1)
+        sgd_optimizer.minimize(loss, grad_clip=clip)
 
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+    x = np.random.uniform(-100, 100, (10, 2)).astype('float32')
+    exe.run(startup_prog)
+    out = exe.run(main_prog, feed={'x': x}, fetch_list=loss)
 
 
+**代码示例2：动态图**
 
+.. code-block:: python
 
+    import paddle
+    import paddle.fluid as fluid
+    
+    with fluid.dygraph.guard():
+        linear = fluid.dygraph.Linear(10, 10)  #可训练参数: linear_0.w.0, linear_0.b.0
+        inputs = fluid.layers.uniform_random([32, 10]).astype('float32')
+        out = linear(fluid.dygraph.to_variable(inputs))
+        loss = fluid.layers.reduce_mean(out)
+        loss.backward()
+
+        # 裁剪网络中全部参数：
+        clip = fluid.clip.GradientClipByGlobalNorm(clip_norm=1.0)
+
+        # 仅裁剪参数linear_0.w_0时：
+        # 为need_clip参数传入一个函数fileter_func，fileter_func接收参数的类型为ParamBase，返回类型为bool
+        # def fileter_func(ParamBase):
+        # # 可以通过ParamBase.name判断（name可以在fluid.ParamAttr中设置，默认为linear_0.w_0、linear_0.b_0）
+        #   return ParamBase.name == "linear_0.w_0"
+        # # 注：linear.weight、linear.bias能分别返回dygraph.Linear层的权重与偏差，也可以此来判断
+        #   return ParamBase.name == linear.weight.name
+        # clip = fluid.clip.GradientClipByGlobalNorm(clip_norm=1.0, need_clip=fileter_func)
+
+        sgd_optimizer = fluid.optimizer.SGD(
+        learning_rate=0.1, parameter_list=linear.parameters())
+        sgd_optimizer.minimize(loss, grad_clip=clip)
\ No newline at end of file

doc/fluid/api_cn/clip_cn/GradientClipByNorm_cn.rst

@@ -3,11 +3,19 @@
 GradientClipByNorm
 -------------------------------
 
-.. py:class:: paddle.fluid.clip.GradientClipByNorm(clip_norm)
+.. py:class:: paddle.fluid.clip.GradientClipByNorm(clip_norm, need_clip=None)
 
-将输入多维Tensor :math:`X` 转换为L2范数不超过给定的二范数最大值（ ``clip_norm`` ）的多维Tensor。（多维Tensor不是从该类传入， 而是通过 ``fluid.program_guard`` 的 ``main_program`` 参数传入）。
+将输入的多维Tensor :math:`X` 的L2范数限制在 ``clip_norm`` 范围之内。
 
-该类限制了输入多维Tensor :math:`X` 的L2范数不会超过 ``clip_norm`` 。
+- 如果L2范数大于 ``clip_norm`` ，则该 Tensor 会乘以一个系数进行压缩
+
+- 如果L2范数小于或等于 ``clip_norm`` ，则不会进行任何操作。
+
+输入的 Tensor 不是从该类里传入， 而是默认会选择 ``Program`` 中全部的梯度，如果 ``need_clip`` 不为None，则可以只选择部分参数进行梯度裁剪。
+
+该类需要在 ``optimizer.minimize(grad_clip)`` 进行设置后才能生效，可参看 ``optimizer`` 文档(例如： :ref:`cn_api_fluid_optimizer_SGDOptimizer` )。
+
+裁剪公式如下：
 
 .. math::
 
@@ -26,54 +34,72 @@ GradientClipByNorm
   \\norm(X) = (\sum_{i=1}^{n}|x_i|^2)^{\frac{1}{2}}\\
 
 参数:
- - **clip_norm** (float) - 二范数最大值
-
+ - **clip_norm** (float) - 所允许的二范数最大值。
+ - **need_clip** (function, optional) - 类型: 函数。用于指定需要梯度裁剪的参数，该函数接收一个 ``Parameter`` ，返回一个 ``bool`` (True表示需要裁剪，False不需要裁剪)。默认为None，此时会裁剪网络中全部参数。
 
-**代码示例**
+**代码示例1：静态图**
+ 
+.. code-block:: python
+            
+    import paddle
+    import paddle.fluid as fluid
+    import numpy as np
+                
+    main_prog = fluid.Program()
+    startup_prog = fluid.Program()
+    with fluid.program_guard(
+            main_program=main_prog, startup_program=startup_prog):
+        image = fluid.data(
+            name='x', shape=[-1, 2], dtype='float32')
+        predict = fluid.layers.fc(input=image, size=3, act='relu') #可训练参数: fc_0.w.0, fc_0.b.0
+        loss = fluid.layers.mean(predict)
+        
+        # 裁剪网络中全部参数：
+        clip = fluid.clip.GradientClipByNorm(clip_norm=1.0)
+        
+        # 仅裁剪参数fc_0.w_0时：
+        # 为need_clip参数传入一个函数fileter_func，fileter_func接收参数的类型为Parameter，返回类型为bool
+        # def fileter_func(Parameter):
+        # # 可以较为方便的通过Parameter.name判断（name可以在fluid.ParamAttr中设置，默认为fc_0.w_0、fc_0.b_0）
+        #   return Parameter.name=="fc_0.w_0"
+        # clip = fluid.clip.GradientClipByNorm(clip_norm=1.0, need_clip=fileter_func)
+
+        sgd_optimizer = fluid.optimizer.SGDOptimizer(learning_rate=0.1)
+        sgd_optimizer.minimize(loss, grad_clip=clip)
+
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+    x = np.random.uniform(-100, 100, (10, 2)).astype('float32')
+    exe.run(startup_prog)
+    out = exe.run(main_prog, feed={'x': x}, fetch_list=loss)
+
+
+**代码示例2：动态图**
 
 .. code-block:: python
 
-  import paddle.fluid as fluid
-  import paddle.fluid.core as core
-  import paddle
-  place = core.CPUPlace()
-  prog = fluid.framework.Program()
-  startup_program = fluid.framework.Program()
-  with fluid.program_guard(
-              main_program=prog, startup_program=startup_program):
-      image = fluid.layers.data(name='x', shape=[784], dtype='float32')
-      label = fluid.layers.data(name='y', shape=[1], dtype='int64')
-      hidden1 = fluid.layers.fc(input=image, size=128, act='relu')
-      hidden2 = fluid.layers.fc(input=hidden1, size=64, act='relu')
-      predict = fluid.layers.fc(input=hidden2, size=10, act='softmax')
-      cost = fluid.layers.cross_entropy(input=predict, label=label)
-      avg_cost = fluid.layers.mean(cost)
-  prog_clip = prog.clone()
-  avg_cost_clip = prog_clip.block(0).var(avg_cost.name)
-  p_g = fluid.backward.append_backward(loss=avg_cost)
-  p_g_clip = fluid.backward.append_backward(loss=avg_cost_clip)
-  with fluid.program_guard(main_program=prog_clip, startup_program=startup_program):
-      fluid.clip.set_gradient_clip(
-          fluid.clip.GradientClipByNorm(clip_norm=2.0))
-      p_g_clip = fluid.clip.append_gradient_clip_ops(p_g_clip)
-  grad_list = [elem[1] for elem in p_g]
-  grad_clip_list = [elem[1] for elem in p_g_clip]
-  train_reader = paddle.batch(
-      paddle.reader.shuffle(
-          paddle.dataset.mnist.train(), buf_size=8192),
-      batch_size=128)
-
-  exe = fluid.Executor(place)
-  feeder = fluid.DataFeeder(feed_list=[image, label], place=place)
-  exe.run(startup_program)
-
-  count = 0
-  for data in train_reader():
-      count += 1
-      print("count:%s" % count)
-      if count > 5:
-         break
-      out = exe.run(prog, feed=feeder.feed(data), fetch_list=grad_list)
-      out_clip = exe.run(prog_clip,
-                         feed=feeder.feed(data),
-                         fetch_list=grad_clip_list)
+    import paddle
+    import paddle.fluid as fluid
+    
+    with fluid.dygraph.guard():
+        linear = fluid.dygraph.Linear(10, 10)  #可训练参数: linear_0.w.0, linear_0.b.0
+        inputs = fluid.layers.uniform_random([32, 10]).astype('float32')
+        out = linear(fluid.dygraph.to_variable(inputs))
+        loss = fluid.layers.reduce_mean(out)
+        loss.backward()
+
+        # 裁剪网络中全部参数：
+        clip = fluid.clip.GradientClipByNorm(clip_norm=1.0)
+
+        # 仅裁剪参数linear_0.w_0时：
+        # 为need_clip参数传入一个函数fileter_func，fileter_func接收参数的类型为ParamBase，返回类型为bool
+        # def fileter_func(ParamBase):
+        # # 可以通过ParamBase.name判断（name可以在fluid.ParamAttr中设置，默认为linear_0.w_0、linear_0.b_0）
+        #   return ParamBase.name == "linear_0.w_0"
+        # # 注：linear.weight、linear.bias能分别返回dygraph.Linear层的权重与偏差，也可以此来判断
+        #   return ParamBase.name == linear.weight.name
+        # clip = fluid.clip.GradientClipByNorm(clip_norm=1.0, need_clip=fileter_func)
+
+        sgd_optimizer = fluid.optimizer.SGD(
+        learning_rate=0.1, parameter_list=linear.parameters())
+        sgd_optimizer.minimize(loss, grad_clip=clip)
\ No newline at end of file

doc/fluid/api_cn/clip_cn/GradientClipByValue_cn.rst

@@ -3,10 +3,14 @@
 GradientClipByValue
 -------------------------------
 
-.. py:class:: paddle.fluid.clip.GradientClipByValue(max, min=None)
+.. py:class:: paddle.fluid.clip.GradientClipByValue(max, min=None, need_clip=None)
 
-将梯度值(gradient values)的范围压缩到 [min, max]。
 
+将输入的多维Tensor :math:`X` 的值限制在 [min, max] 范围。
+
+输入的 Tensor 不是从该类里传入， 而是默认会选择 ``Program`` 中全部的梯度，如果 ``need_clip`` 不为None，则可以只选择部分参数进行梯度裁剪。
+
+该类需要在 ``optimizer.minimize(grad_clip)`` 进行设置后才能生效，可参看 ``optimizer`` 文档(例如： :ref:`cn_api_fluid_optimizer_SGDOptimizer` )。
 
 给定一个 Tensor  ``t`` ，该操作将它的值压缩到 ``min`` 和 ``max`` 之间
 
@@ -16,25 +20,75 @@ GradientClipByValue
 
 参数:
  - **max** (foat) - 要修剪的最大值。
- - **min** (float，optional) - 要修剪的最小值。如果用户没有设置，将被 ``framework`` 设置为 ``-max`` 。
+ - **min** (float，optional) - 要修剪的最小值。如果用户没有设置，将被自动设置为 ``-max`` （此时 ``max`` 必须大于0）。
+ - **need_clip** (function, optional) - 类型: 函数。用于指定需要梯度裁剪的参数，该函数接收一个 ``Parameter`` ，返回一个 ``bool`` (True表示需要裁剪，False不需要裁剪)。默认为None，此时会裁剪网络中全部参数。
   
-**代码示例**
+**代码示例1：静态图**
  
 .. code-block:: python
+            
+    import paddle
+    import paddle.fluid as fluid
+    import numpy as np
+                
+    main_prog = fluid.Program()
+    startup_prog = fluid.Program()
+    with fluid.program_guard(
+            main_program=main_prog, startup_program=startup_prog):
+        image = fluid.data(
+            name='x', shape=[-1, 2], dtype='float32')
+        predict = fluid.layers.fc(input=image, size=3, act='relu') #可训练参数: fc_0.w.0, fc_0.b.0
+        loss = fluid.layers.mean(predict)
+        
+        # 裁剪网络中全部参数：
+        clip = fluid.clip.GradientClipByValue(min=-1, max=1)
         
-     import paddle.fluid as fluid
-     w_param_attrs = fluid.ParamAttr(name=None,
-                                     initializer=fluid.initializer.UniformInitializer(low=-1.0, high=1.0, seed=0),
-                                     learning_rate=1.0,
-                                     regularizer=fluid.regularizer.L1Decay(1.0),
-                                     trainable=True,
-                                     gradient_clip=fluid.clip.GradientClipByValue(-1.0, 1.0))
-     x = fluid.layers.data(name='x', shape=[10], dtype='float32')
-     y_predict = fluid.layers.fc(input=x, size=1, param_attr=w_param_attrs)
-     
+        # 仅裁剪参数fc_0.w_0时：
+        # 为need_clip参数传入一个函数fileter_func，fileter_func接收参数的类型为Parameter，返回类型为bool
+        # def fileter_func(Parameter):
+        # # 可以较为方便的通过Parameter.name判断（name可以在fluid.ParamAttr中设置，默认为fc_0.w_0、fc_0.b_0）
+        #   return Parameter.name=="fc_0.w_0"
+        # clip = fluid.clip.GradientClipByValue(min=-1, max=1, need_clip=fileter_func)
+
+        sgd_optimizer = fluid.optimizer.SGDOptimizer(learning_rate=0.1)
+        sgd_optimizer.minimize(loss, grad_clip=clip)
+
+    place = fluid.CPUPlace()
+    exe = fluid.Executor(place)
+    x = np.random.uniform(-100, 100, (10, 2)).astype('float32')
+    exe.run(startup_prog)
+    out = exe.run(main_prog, feed={'x': x}, fetch_list=loss)
+
+
+**代码示例2：动态图**
+
+.. code-block:: python
+
+    import paddle
+    import paddle.fluid as fluid
+    
+    with fluid.dygraph.guard():
+        linear = fluid.dygraph.Linear(10, 10)  #可训练参数: linear_0.w.0, linear_0.b.0
+        inputs = fluid.layers.uniform_random([32, 10]).astype('float32')
+        out = linear(fluid.dygraph.to_variable(inputs))
+        loss = fluid.layers.reduce_mean(out)
+        loss.backward()
 
+        # 裁剪网络中全部参数：
+        clip = fluid.clip.GradientClipByValue(min=-1, max=1)
 
+        # 仅裁剪参数linear_0.w_0时：
+        # 为need_clip参数传入一个函数fileter_func，fileter_func接收参数的类型为ParamBase，返回类型为bool
+        # def fileter_func(ParamBase):
+        # # 可以通过ParamBase.name判断（name可以在fluid.ParamAttr中设置，默认为linear_0.w_0、linear_0.b_0）
+        #   return ParamBase.name == "linear_0.w_0"
+        # # 注：linear.weight、linear.bias能分别返回dygraph.Linear层的权重与偏差，可以此来判断
+        #   return ParamBase.name == linear.weight.name
+        # clip = fluid.clip.GradientClipByValue(min=-1, max=1, need_clip=fileter_func)
 
+        sgd_optimizer = fluid.optimizer.SGD(
+        learning_rate=0.1, parameter_list=linear.parameters())
+        sgd_optimizer.minimize(loss, grad_clip=clip)
 
 
 

doc/fluid/api_cn/clip_cn/set_gradient_clip_cn.rst

@@ -7,12 +7,17 @@ set_gradient_clip
 
 .. py:function:: paddle.fluid.clip.set_gradient_clip(clip, param_list=None, program=None)
 
+.. warning::
+    此API对位置使用的要求较高，其必须位于组建网络之后， ``minimize`` 之前，因此在未来版本中可能被删除，故不推荐使用。推荐使用 ``minimize(loss, grad_clip=clip)`` 做梯度裁剪。
+    有三种裁剪策略： :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByValue` 。
+    如果 ``set_gradient_clip(clip)`` 与 ``minimize(loss, grad_clip=clip)`` 被同时使用，``set_gradient_clip`` 将不会生效。
+
 给指定参数做梯度裁剪。
 
 参数:
-    - **clip** (BaseGradientClipAttr) - BaseGradientClipAttr子类的实例，如 :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` 等，用于描述具体的裁剪方法和属性。
+    - **clip** (GradientClipBase) - 梯度裁剪的策略，如 :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` 等，用于描述具体的裁剪方法和属性。
     - **param_list** (list(Variable)，可选) - 需要裁剪的参数列表，可以是参数或参数名称列表。默认值为None，表示裁剪 ``program`` 中的所有参数。
-    - **program** (Program，可选) - 参数所在的Program。默认值为None，表示使用 :ref:`cn_api_fluid_default_main_program`。
+    - **program** (Program，可选) - 参数所在的Program。默认值为None，表示使用 :ref:`cn_api_fluid_default_main_program` 。
 
 返回: 无。
 
@@ -59,3 +64,17 @@ set_gradient_clip
             param_list=[param_var1, param_var2])
         sgd = fluid.optimizer.SGD(learning_rate=1e-3)
         sgd.minimize(loss)
+
+    # network 4: use set_gradient_clip and minimize(grad_clip=clip) together
+    with fluid.program_guard(fluid.Program(), fluid.Program()):
+        loss = network()
+        param_var1 = fluid.default_main_program().global_block().var("fc1_param")
+        param_var2 = fluid.default_main_program().global_block().var("fc2_param")
+        clip1 = fluid.clip.GradientClipByValue(min=-1.0, max=1.0), param_list=[param_var1, param_var2])
+        clip2 = fluid.clip.GradientClipByNorm(clip_norm=1.0), param_list=[param_var1, param_var2])
+        # 设置梯度裁剪策略：clip1
+        fluid.clip.set_gradient_clip(clip1)
+        sgd = fluid.optimizer.SGD(learning_rate=1e-3)
+        # 设置梯度裁剪策略：clip2
+        sgd.minimize(loss, grad_clip=clip2)
+        # 有设置冲突时，set_gradient_clip将不会生效，将以clip2的策略进行梯度裁剪

doc/fluid/api_cn/fluid_cn/ParamAttr_cn.rst

@@ -5,7 +5,11 @@ ParamAttr
 -------------------------------
 
 
-.. py:class:: paddle.fluid.ParamAttr(name=None, initializer=None, learning_rate=1.0, regularizer=None, trainable=True, gradient_clip=None, do_model_average=False)
+.. py:class:: paddle.fluid.ParamAttr(name=None, initializer=None, learning_rate=1.0, regularizer=None, trainable=True, do_model_average=False)
+
+.. note::
+    该类中的 ``gradient_clip`` 属性在2.0版本会废弃，推荐使用 ``minimize(loss, grad_clip=clip)`` 做梯度裁剪。共有三种裁剪策略： :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` 、 
+    :ref:`cn_api_fluid_clip_GradientClipByNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByValue` 。
 
 创建一个参数属性对象，用户可设置参数的名称、初始化方式、学习率、正则化规则、是否需要训练、梯度裁剪方式、是否做模型平均等属性。
 
@@ -15,7 +19,6 @@ ParamAttr
     - **learning_rate** (float) - 参数的学习率。实际参数的学习率等于全局学习率乘以参数的学习率，再乘以learning rate schedule的系数。
     - **regularizer** (WeightDecayRegularizer，可选) - 正则化因子。默认值为None，表示没有正则化因子。
     - **trainable** (bool) - 参数是否需要训练。默认值为True，表示需要训练。
-    - **gradient_clip** (BaseGradientClipAttr，可选) - 梯度裁剪方式。默认值为None，表示不需要梯度裁剪。
     - **do_model_average** (bool) - 是否做模型平均。默认值为False，表示不做模型平均。
 
 返回: 表示参数属性的对象。

doc/fluid/api_cn/fluid_cn/WeightNormParamAttr_cn.rst

@@ -5,8 +5,11 @@ WeightNormParamAttr
 
 **注意：该API仅支持【静态图】模式**
 
-.. py:class:: paddle.fluid.WeightNormParamAttr(dim=None, name=None, initializer=None, learning_rate=1.0, regularizer=None, trainable=True, gradient_clip=None, do_model_average=False)
+.. py:class:: paddle.fluid.WeightNormParamAttr(dim=None, name=None, initializer=None, learning_rate=1.0, regularizer=None, trainable=True, do_model_average=False)
 
+.. note::
+    该类中的 ``gradient_clip`` 属性在2.0版本会废弃，推荐使用 ``minimize(loss, grad_clip=clip)`` 做梯度裁剪。共有三种裁剪策略： :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` 、 
+    :ref:`cn_api_fluid_clip_GradientClipByNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByValue` 。
 
 该类定义了权重归一化(Weight Normalization)的参数。权重归一化可以将神经网络中权重向量的长度与其方向解耦，详细的定义与实现可以参考论文：`Weight Normalization: A Simple Reparameterization to Accelerate Training of Deep Neural Networks <https://arxiv.org/pdf/1602.07868.pdf>`_
 
@@ -17,7 +20,6 @@ WeightNormParamAttr
   - **learning_rate** (float32) - 学习率，优化过程 :math:`global\_lr∗parameter\_lr∗scheduler\_factor` 的学习速率，默认为1.0。
   - **regularizer** (WeightDecayRegularizer) - 正则化方法，例如 ``regularizer = fluid.regularizer.L2DecayRegularizer(regularization_coeff=0.1)`` 。默认为None，如果为None则对权重不做正则化。
   - **trainable** (bool) - 可选，指明参数是否可训练，默认为True。
-  - **gradient_clip** - 梯度裁剪(Gradient Clipping)的方法，例如 ``gradient_clip = fluid.clip.GradientClipByNorm(clip_norm=2.0))`` 。默认为None，如果为None则对权重不做裁剪。
   - **do_model_average** (bool) - 可选，指明参数是否需要模型平均化操作(Model Average)，默认为False。
 
 
@@ -36,7 +38,6 @@ WeightNormParamAttr
                                 learning_rate=1.0,
                                 regularizer=fluid.regularizer.L2DecayRegularizer(regularization_coeff=0.1),
                                 trainable=True,
-                                gradient_clip=fluid.clip.GradientClipByNorm(clip_norm=2.0),
                                 do_model_average=False))
 
 

doc/fluid/api_cn/optimizer_cn/AdadeltaOptimizer_cn.rst

@@ -49,7 +49,8 @@ Adadelta优化器，具体细节可参考论文 `ADADELTA: AN ADAPTIVE LEARNING
     - **startup_program** (Program，可选) – 参数所在的startup program。默认值为None，表示 :ref:`cn_api_fluid_default_startup_program` 。
     - **parameter_list** (list，可选) – 待更新的Parameter或者Parameter.name组成的列表。默认值为None，表示所有参数均需要更新。
     - **no_grad_set** (set，可选) – 不需要更新的Parameter或者Parameter.name组成的集合。默认值为None。
-    - **grad_clip** (GradClipBase，可选) – 梯度裁剪的策略，目前仅在动态图模式下有效。
+    - **grad_clip** (GradientClipBase, 可选) – 梯度裁剪的策略，支持三种裁剪策略： :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByValue` 。
+      默认值为None，此时将不进行梯度裁剪。
 
 返回: tuple(optimize_ops, params_grads)，其中optimize_ops为参数优化OP列表；param_grads为由(param, param_grad)组成的列表，其中param和param_grad分别为参数和参数的梯度。
 

doc/fluid/api_cn/optimizer_cn/AdagradOptimizer_cn.rst

@@ -59,8 +59,9 @@ Adaptive Gradient 优化器(自适应梯度优化器，简称Adagrad)可以针
     - **startup_program** (Program, 可选) – 用于初始化parameter_list中参数的 :ref:`cn_api_fluid_Program` , 默认值为None，此时将使用 :ref:`cn_api_fluid_default_startup_program` 
     - **parameter_list** (list, 可选) – 待更新的Parameter或者Parameter.name组成的列表， 默认值为None，此时将更新所有的Parameter
     - **no_grad_set** (set, 可选) – 不需要更新的Parameter或者Parameter.name组成的集合。默认值为None
-    - **grad_clip** (GradClipBase, 可选) – 梯度裁剪的策略，静态图模式不需要使用本参数，当前本参数只支持在dygraph模式下的梯度裁剪，未来本参数可能会调整，默认值为None
-
+    - **grad_clip** (GradientClipBase, 可选) – 梯度裁剪的策略，支持三种裁剪策略： :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByValue` 。
+      默认值为None，此时将不进行梯度裁剪。
+        
 返回： (optimize_ops, params_grads)，数据类型为(list, list)，其中optimize_ops是minimize接口为网络添加的OP列表，params_grads是一个由(param, grad)变量对组成的列表，param是Parameter，grad是该Parameter对应的梯度值
 
 返回类型： tuple

doc/fluid/api_cn/optimizer_cn/AdamOptimizer_cn.rst

@@ -129,8 +129,9 @@ Adam优化器出自 `Adam论文 <https://arxiv.org/abs/1412.6980>`_ 的第二节
     - **startup_program** (Program, 可选) – 用于初始化parameter_list中参数的 :ref:`cn_api_fluid_Program` , 默认值为None，此时将使用 :ref:`cn_api_fluid_default_startup_program` 
     - **parameter_list** (list, 可选) – 待更新的Parameter或者Parameter.name组成的列表， 默认值为None，此时将更新所有的Parameter
     - **no_grad_set** (set, 可选) – 不需要更新的Parameter或者Parameter.name组成的集合，默认值为None
-    - **grad_clip** (GradClipBase, 可选) – 梯度裁剪的策略，静态图模式不需要使用本参数，当前本参数只支持在dygraph模式下的梯度裁剪，未来本参数可能会调整，默认值为None
-
+    - **grad_clip** (GradientClipBase, 可选) – 梯度裁剪的策略，支持三种裁剪策略： :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByValue` 。
+      默认值为None，此时将不进行梯度裁剪。
+         
 返回： (optimize_ops, params_grads)，数据类型为(list, list)，其中optimize_ops是minimize接口为网络添加的OP列表，params_grads是一个由(param, grad)变量对组成的列表，param是Parameter，grad是该Parameter对应的梯度值
 
 返回类型： tuple

doc/fluid/api_cn/optimizer_cn/AdamaxOptimizer_cn.rst

@@ -73,8 +73,9 @@ Adamax优化器是参考 `Adam论文 <https://arxiv.org/abs/1412.6980>`_ 第7节
     - **startup_program** (Program, 可选) – 用于初始化parameter_list中参数的 :ref:`cn_api_fluid_Program` , 默认值为None，此时将使用 :ref:`cn_api_fluid_default_startup_program` 
     - **parameter_list** (list, 可选) – 待更新的Parameter或者Parameter.name组成的列表， 默认值为None，此时将更新所有的Parameter
     - **no_grad_set** (set, 可选) – 不需要更新的Parameter或者Parameter.name组成集合，默认值为None
-    - **grad_clip** (GradClipBase, 可选) – 梯度裁剪的策略，静态图模式不需要使用本参数，当前本参数只支持在dygraph模式下的梯度裁剪，未来本参数可能会调整，默认值为None
-
+    - **grad_clip** (GradientClipBase, 可选) – 梯度裁剪的策略，支持三种裁剪策略： :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByValue` 。
+      默认值为None，此时将不进行梯度裁剪。
+        
 返回： (optimize_ops, params_grads)，数据类型为(list, list)，其中optimize_ops是minimize接口为网络添加的OP列表，params_grads是一个由(param, grad)变量对组成的列表，param是Parameter，grad是该Parameter对应的梯度值
 
 **代码示例**：

doc/fluid/api_cn/optimizer_cn/DGCMomentumOptimizer_cn.rst

@@ -119,8 +119,9 @@ DGC还使用动量因子掩藏（momentum factor masking）和预训练（warm-u
     - **startup_program** (Program) – 用于初始化在parameter_list中参数的startup_program
     - **parameter_list** (list) – 待更新的Variables组成的列表
     - **no_grad_set** (set|None) – 应该被无视的Variables集合
-    - **grad_clip** (GradClipBase|None) – 梯度裁剪的策略
-
+    - **grad_clip** (GradientClipBase, 可选) – 梯度裁剪的策略，支持三种裁剪策略： :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByValue` 。
+      默认值为None，此时将不进行梯度裁剪。
+       
 返回： (optimize_ops, params_grads)，分别为附加的算子列表；一个由(param, grad) 变量对组成的列表，用于优化
 
 返回类型：   tuple

doc/fluid/api_cn/optimizer_cn/DecayedAdagradOptimizer_cn.rst

@@ -53,8 +53,9 @@ Decayed Adagrad优化器，可以看做是引入了衰减率的 `Adagrad <http:/
     - **startup_program** (Program, 可选) – 用于初始化parameter_list中参数的 :ref:`cn_api_fluid_Program` , 默认值为None，此时将使用 :ref:`cn_api_fluid_default_startup_program`
     - **parameter_list** (list, 可选) – 待更新的Parameter或者Parameter.name组成的列表， 默认值为None，此时将更新所有的Parameter
     - **no_grad_set** (set, 可选) – 不需要更新的Parameter或者Parameter.name组成的集合，默认值为None
-    - **grad_clip** (GradClipBase, 可选) – 梯度裁剪的策略，静态图模式不需要使用本参数，当前本参数只支持在dygraph模式下的梯度裁剪，未来本参数可能会调整，默认值为None
-
+    - **grad_clip** (GradientClipBase, 可选) – 梯度裁剪的策略，支持三种裁剪策略： :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByValue` 。
+      默认值为None，此时将不进行梯度裁剪。
+        
 返回： (optimize_ops, params_grads)，数据类型为(list, list)，其中optimize_ops是minimize接口为网络添加的OP列表，params_grads是一个由(param, grad)变量对组成的列表，param是Parameter，grad是该Parameter对应的梯度值
 
 返回类型： tuple

doc/fluid/api_cn/optimizer_cn/DpsgdOptimizer_cn.rst

@@ -63,8 +63,9 @@ Dpsgd优化器是参考CCS16论文 `《Deep Learning with Differential Privacy
     - **startup_program** (Program， 可选) – 用于初始化parameter_list中参数的 :ref:`cn_api_fluid_Program` ， 默认值为None，此时将使用 :ref:`cn_api_fluid_default_startup_program`
     - **parameter_list** (list， 可选) – 待更新的Parameter或者Parameter.name组成的列表， 默认值为None，此时将更新所有的Parameter
     - **no_grad_set** (set， 可选) – 不需要更新的Parameter或者Parameter.name组成集合，默认值为None
-    - **grad_clip** (GradClipBase， 可选) – 梯度裁剪的策略，静态图模式不需要使用本参数，当前本参数只支持在dygraph模式下的梯度裁剪，未来本参数可能会调整，默认值为None
-
+    - **grad_clip** (GradientClipBase, 可选) – 梯度裁剪的策略，支持三种裁剪策略： :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByValue` 。
+      默认值为None，此时将不进行梯度裁剪。
+         
 返回： (optimize_ops, params_grads)，数据类型为(list, list)，其中optimize_ops是minimize接口为网络添加的OP列表，params_grads是一个由(param, grad)变量对组成的列表，param是Parameter，grad是该Parameter对应的梯度值
 
 **代码示例**：

doc/fluid/api_cn/optimizer_cn/FtrlOptimizer_cn.rst

@@ -85,8 +85,9 @@ FTRL 原始论文: ( `https://www.eecs.tufts.edu/~dsculley/papers/ad-click-predi
     - **startup_program** (Program, 可选) – 用于初始化parameter_list中参数的 :ref:`cn_api_fluid_Program` , 默认值为None，此时将使用 :ref:`cn_api_fluid_default_startup_program`
     - **parameter_list** (list, 可选) – 待更新的Parameter或者Parameter.name组成的列表， 默认值为None，此时将更新所有的Parameter
     - **no_grad_set** (set, 可选) – 不需要更新的Parameter或者Parameter.name组成的集合，默认值为None
-    - **grad_clip** (GradClipBase, 可选) – 梯度裁剪的策略，静态图模式不需要使用本参数，当前本参数只支持在dygraph模式下的梯度裁剪，未来本参数可能会调整，默认值为None
-
+    - **grad_clip** (GradientClipBase, 可选) – 梯度裁剪的策略，支持三种裁剪策略： :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByValue` 。
+      默认值为None，此时将不进行梯度裁剪。
+         
 返回： (optimize_ops, params_grads)，数据类型为(list, list)，其中optimize_ops是minimize接口为网络添加的OP列表，params_grads是一个由(param, grad)变量对组成的列表，param是Parameter，grad是该Parameter对应的梯度值
 
 返回类型： tuple

doc/fluid/api_cn/optimizer_cn/LambOptimizer_cn.rst

@@ -61,8 +61,9 @@ Deep Learning: Training BERT in 76 minutes <https://arxiv.org/pdf/1904.00962.pdf
     - **startup_program** (Program, 可选) – 用于初始化parameter_list中参数的 :ref:`cn_api_fluid_Program` , 默认值为None，此时将使用 :ref:`cn_api_fluid_default_startup_program` 
     - **parameter_list** (list, 可选) – 待更新的Parameter或者Parameter.name组成的列表， 默认值为None，此时将更新所有的Parameter
     - **no_grad_set** (set, 可选) – 不需要更新的Parameter或者Parameter.name组成的的集合，默认值为None
-    - **grad_clip** (GradClipBase, 可选) – 梯度裁剪的策略，静态图模式不需要使用本参数，当前本参数只支持在dygraph模式下的梯度裁剪，未来本参数可能会调整，默认值为None
-
+    - **grad_clip** (GradientClipBase, 可选) – 梯度裁剪的策略，支持三种裁剪策略： :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByValue` 。
+      默认值为None，此时将不进行梯度裁剪。
+         
 返回： (optimize_ops, params_grads)，数据类型为(list, list)，其中optimize_ops是 ``minimize()`` 接口为网络添加的OP列表，params_grads是一个由(param, grad)变量对组成的列表，param是Parameter，grad是该Parameter对应的梯度值
 
 返回类型： tuple

doc/fluid/api_cn/optimizer_cn/LarsMomentumOptimizer_cn.rst

@@ -60,8 +60,9 @@ LarsMomentumOptimizer
     - **startup_program** (Program, 可选) – 用于初始化parameter_list中参数的 :ref:`cn_api_fluid_Program` , 默认值为None，此时将使用 :ref:`cn_api_fluid_default_startup_program`
     - **parameter_list** (list, 可选) – 待更新的Parameter或者Parameter.name组成的列表， 默认值为None，此时将更新所有的Parameter
     - **no_grad_set** (set, 可选) – 不需要更新的Parameter或者Parameter.name组成的的集合，默认值为None
-    - **grad_clip** (GradClipBase, 可选) – 梯度裁剪的策略，静态图模式不需要使用本参数，当前本参数只支持在dygraph模式下的梯度裁剪，未来本参数可能会调整，默认值为None
-
+    - **grad_clip** (GradientClipBase, 可选) – 梯度裁剪的策略，支持三种裁剪策略： :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByValue` 。
+      默认值为None，此时将不进行梯度裁剪。
+        
 返回： (optimize_ops, params_grads)，数据类型为(list, list)，其中optimize_ops是minimize接口为网络添加的OP列表，params_grads是一个由(param, grad)变量对组成的列表，param是Parameter，grad是该Parameter对应的梯度值
 
 返回类型： tuple

doc/fluid/api_cn/optimizer_cn/MomentumOptimizer_cn.rst

@@ -63,8 +63,9 @@ MomentumOptimizer
     - **startup_program** (Program, 可选) – 用于初始化parameter_list中参数的 :ref:`cn_api_fluid_Program` , 默认值为None，此时将使用 :ref:`cn_api_fluid_default_startup_program` 
     - **parameter_list** (list, 可选) – 待更新的Parameter或者Parameter.name组成的列表， 默认值为None，此时将更新所有的Parameter
     - **no_grad_set** (set, 可选) – 不需要更新的Parameter或者Parameter.name组成的集合，默认值为None
-    - **grad_clip** (GradClipBase, 可选) – 梯度裁剪的策略，静态图模式不需要使用本参数，当前本参数只支持在dygraph模式下的梯度裁剪，未来本参数可能会调整，默认值为None
-
+    - **grad_clip** (GradientClipBase, 可选) – 梯度裁剪的策略，支持三种裁剪策略： :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByValue` 。
+      默认值为None，此时将不进行梯度裁剪。
+        
 返回： (optimize_ops, params_grads)，数据类型为(list, list)，其中optimize_ops是minimize接口为网络添加的OP列表，params_grads是一个由(param, grad)变量对组成的列表，param是Parameter，grad是该Parameter对应的梯度值
 
 返回类型： tuple

doc/fluid/api_cn/optimizer_cn/RMSPropOptimizer_cn.rst

@@ -81,8 +81,9 @@ RMSPropOptimizer
     - **startup_program** (Program, 可选) – 用于初始化parameter_list中参数的 :ref:`cn_api_fluid_Program` , 默认值为None，此时将使用 :ref:`cn_api_fluid_default_startup_program` 
     - **parameter_list** (list, 可选) – 待更新的Parameter或者Parameter.name组成的列表， 默认值为None，此时将更新所有的Parameter
     - **no_grad_set** (set, 可选) – 不需要更新的Parameter或者Parameter.name组成的集合，默认值为None
-    - **grad_clip** (GradClipBase, 可选) – 梯度裁剪的策略，静态图模式不需要使用本参数，当前本参数只支持在dygraph模式下的梯度裁剪，未来本参数可能会调整，默认值为None
-
+    - **grad_clip** (GradientClipBase, 可选) – 梯度裁剪的策略，支持三种裁剪策略： :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByValue` 。
+      默认值为None，此时将不进行梯度裁剪。
+        
 返回： (optimize_ops, params_grads)，数据类型为(list, list)，其中optimize_ops是minimize接口为网络添加的OP列表，params_grads是一个由(param, grad)变量对组成的列表，param是Parameter，grad是该Parameter对应的梯度值
 
 返回类型： tuple

doc/fluid/api_cn/optimizer_cn/SGDOptimizer_cn.rst

@@ -58,8 +58,9 @@ SGDOptimizer
     - **startup_program** (Program, 可选) – 用于初始化parameter_list中参数的 :ref:`cn_api_fluid_Program` , 默认值为None，此时将使用 :ref:`cn_api_fluid_default_startup_program` 
     - **parameter_list** (list, 可选) – 待更新的Parameter或者Parameter.name组成的列表， 默认值为None，此时将更新所有的Parameter
     - **no_grad_set** (set, 可选) – 不需要更新的Parameter或者Parameter.name组成的集合，默认值为None
-    - **grad_clip** (GradClipBase, 可选) – 梯度裁剪的策略，静态图模式不需要使用本参数，当前本参数只支持在dygraph模式下的梯度裁剪，未来本参数可能会调整，默认值为None
-
+    - **grad_clip** (GradientClipBase, 可选) – 梯度裁剪的策略，支持三种裁剪策略： :ref:`cn_api_fluid_clip_GradientClipByGlobalNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByNorm` 、 :ref:`cn_api_fluid_clip_GradientClipByValue` 。
+      默认值为None，此时将不进行梯度裁剪。
+        
 返回： (optimize_ops, params_grads)，数据类型为(list, list)，其中optimize_ops是minimize接口为网络添加的OP列表，params_grads是一个由(param, grad)变量对组成的列表，param是Parameter，grad是该Parameter对应的梯度值
 
 返回类型： tuple