From d04a4d79e6b2ca009d7c3cfb7c7b1666c061369b Mon Sep 17 00:00:00 2001 From: Aurelius84 Date: Sun, 27 Sep 2020 18:50:10 +0800 Subject: [PATCH] [API 2.0]migrate example for gradients/append_backward/program_guard (#2685) * migrate 2.0 api doc * migrate program_guard * variable -> Tensor --- .../fluid/backward/append_backward_cn.rst | 65 ++++++++++--------- .../paddle/fluid/backward/gradients_cn.rst | 33 +++++----- .../fluid/framework/program_guard_cn.rst | 36 +++++----- 3 files changed, 71 insertions(+), 63 deletions(-) diff --git a/doc/paddle/api/paddle/fluid/backward/append_backward_cn.rst b/doc/paddle/api/paddle/fluid/backward/append_backward_cn.rst index 268349a2f33..02b31ad9585 100644 --- a/doc/paddle/api/paddle/fluid/backward/append_backward_cn.rst +++ b/doc/paddle/api/paddle/fluid/backward/append_backward_cn.rst @@ -4,70 +4,73 @@ append_backward ------------------------------- -.. py:function:: paddle.fluid.backward.append_backward(loss, parameter_list=None, no_grad_set=None, callbacks=None) +.. py:function:: paddle.static.append_backward(loss, parameter_list=None, no_grad_set=None, callbacks=None) -该接口将向主程序（``main_program``）追加反向部分 。 +该接口将向主程序（``main_program``）添加反向部分 。 -完整的神经网络训练由前向和反向传播组成。但是当我们配置网络时，我们只需要指定其前向部分。 +完整的神经网络训练由前向和反向传播两部分组成。但是当我们配置网络时，我们只需要指定其前向部分。 该接口使用链式法则，能够根据前向部分自动生成反向部分。 在大多数情况下，用户无需手动调用此接口，它将由优化器（``Optimizer``）的 ``minimize`` 函数自动调用。 参数： - - **loss** ( :ref:`api_guide_Variable` ) - 网络的损失变量。 - - **parameter_list** （list [Variable|str]，可选）- 指定优化器需要更新的参数或参数名称列表。如果为 ``None`` ，则将更新所有参数。默认值为 ``None``。 - - **no_grad_set** （set [Variable|str]，可选）- 在 `block0` ( :ref:`api_guide_Block` ) 中要忽略梯度的 :ref:`api_guide_Variable` 的名字的集合。所有的 :ref:`api_guide_Block` 中带有 ``stop_gradient = True`` 的所有 :ref:`api_guide_Variable` 的名字都会被自动添加到此集合中。如果该参数不为 ``None``，则会将该参数集合的内容添加到默认的集合中。默认值为 ``None``。 - - **callbacks** （list [callable object]，可选）- 回调函数列表。用于在反向传播构建中执行一些自定义作业。每次将新的梯度OP添加到程序中时，将调用其中的所有可调用对象。可调用对象必须有两个输入参数： :ref:`api_guide_Block` 和 ``context`` 。 :ref:`api_guide_Block` 是将被添加到新梯度算子的块。 ``context`` 是一个映射，其键是梯度 :ref:`api_guide_Variable` 名，值是对应的原始 :ref:`api_guide_Variable` 。除此之外， ``context`` 还有另一个特殊的键值对：键是字符串 ``__ current_op_desc__`` ，值是刚刚触发可调用对象的梯度OP的 ``op_desc`` 。默认值为 ``None``。 + - **loss** (Tensor) - 表示网络损失的 Tensor 。 + - **parameter_list** （list [Tensor|str]，可选）- 指定优化器需要更新的参数或参数名称列表。如果为 ``None`` ，则将更新所有参数。默认值为 ``None``。 + - **no_grad_set** （set [Tensor|str]，可选）- 在 `block0` ( :ref:`api_guide_Block` ) 中要忽略梯度的 Tensor 的名字的集合。所有的 :ref:`api_guide_Block` 中带有 ``stop_gradient = True`` 的所有 Tensor 的名字都会被自动添加到此集合中。如果该参数不为 ``None``，则会将该参数集合的内容添加到默认的集合中。默认值为 ``None``。 + - **callbacks** （list [callable object]，可选）- 回调函数列表。用于在反向传播构建中执行一些自定义作业。每次将新的梯度 OP 添加到程序中时，将调用其中的所有可调用对象。可调用对象必须有两个输入参数： :ref:`api_guide_Block` 和 ``context`` 。 :ref:`api_guide_Block` 是将被添加到新梯度算子的块。 ``context`` 是一个映射，其键是梯度 Tensor 名，值是对应的原始 Tensor 。除此之外， ``context`` 还有另一个特殊的键值对：键是字符串 ``__ current_op_desc__`` ，值是刚刚触发可调用对象的梯度 OP 的 ``op_desc`` 。默认值为 ``None``。 -返回： 参数及其梯度 :ref:`api_guide_Variable` 的元组的列表。元组的第一个值为参数，第二个值为该参数的梯度 :ref:`api_guide_Variable` 。 +返回： 参数及其梯度 Tensor 的元组的列表。元组的第一个值为参数，第二个值为该参数的梯度 Tensor 。 -返回类型： list[( :ref:`api_guide_Variable` , :ref:`api_guide_Variable` )] +返回类型： list[(Tensor , Tensor)] 抛出： - - ``AssertionError`` - 如果 loss 不是 :ref:`api_guide_Variable` 的实例。 + - ``AssertionError`` - 如果 loss 不是 Tensor 的实例。 **示例代码** .. code-block:: python - import paddle.fluid as fluid + import paddle + import paddle.nn.functional as F - x = fluid.data(name='x', shape=[None, 13], dtype='int64') - y = fluid.data(name='y', shape=[None, 1], dtype='float32') - x_emb = fluid.embedding(x, size=[100, 256]) - y_predict = fluid.layers.fc(input=x_emb, size=1, act=None, name='my_fc') - loss = fluid.layers.square_error_cost(input=y_predict, label=y) - avg_loss = fluid.layers.mean(loss) + paddle.enable_static() - # 获取main_program中所有weight参数, 不包括bias. - all_weights = [param for param in fluid.default_main_program().block(0).all_parameters() if 'w_' in param.name] + x = paddle.static.data(name='x', shape=[None, 13], dtype='int64') + y = paddle.static.data(name='y', shape=[None, 1], dtype='float32') + x_emb = paddle.static.nn.embedding(x, size=[100, 256]) + y_predict = paddle.static.nn.fc(input=x_emb, size=1, act=None, name='my_fc') + loss = F.square_error_cost(input=y_predict, label=y) + avg_loss = paddle.mean(loss) + + # Get all weights in main_program, not include bias. + all_weights = [param for param in paddle.static.default_main_program().block(0).all_parameters() if 'w_' in param.name] all_weights_name = [w.name for w in all_weights] - # 若parameter_list为默认值(None), 则返回包含所有param_grad的list - p_g_list1 = fluid.backward.append_backward(loss=avg_loss) + # return all param_grads needed to be updated if parameter_list set default None. + p_g_list1 = paddle.static.append_backward(loss=avg_loss) # output: [(embedding_0.w_0, embedding_0.w_0@GRAD), (my_fc.w_0, my_fc.w_0@GRAD), (my_fc.b_0, my_fc.b_0@GRAD)] - # 返回与传入parameter_list对应的param_grad的list, 传入的parameter_list可以是 param(Variable类型)的list - p_g_list2 = fluid.backward.append_backward(loss=avg_loss, parameter_list=all_weights) + # return the param_grads corresponding to parameter_list that can be list of param (Tensor). + p_g_list2 = paddle.static.append_backward(loss=avg_loss, parameter_list=all_weights) # output: [(embedding_0.w_0, embedding_0.w_0@GRAD), (my_fc.w_0, my_fc.w_0@GRAD)] - # 传入的parameter_list也可以是值为param.name(str类型)的list - p_g_list3 = fluid.backward.append_backward(loss=avg_loss, parameter_list=all_weights_name) + # parameter_list can be list of param.name (str). + p_g_list3 = paddle.static.append_backward(loss=avg_loss, parameter_list=all_weights_name) # output: [(embedding_0.w_0, embedding_0.w_0@GRAD), (my_fc.w_0, my_fc.w_0@GRAD)] - # no_grad_set可以是set[Variables]类型，表示梯度将在这些Variables处截断 - p_g_list4 = fluid.backward.append_backward(loss=avg_loss, no_grad_set=set([x_emb])) + # no_grad_set can be set of Tensors that means grad will be cut off from these Tensors. + p_g_list4 = paddle.static.append_backward(loss=avg_loss, no_grad_set=set([x_emb])) # output: [(my_fc.w_0, my_fc.w_0@GRAD), (my_fc.b_0, my_fc.b_0@GRAD)] - # no_grad_set也可以是set[Variable.names]类型。当参数Variable是在layers内部创建，且不方便显式地指定时，可以使用set[Variable.names] - p_g_list5 = fluid.backward.append_backward(loss=avg_loss, no_grad_set=set(['my_fc.b_0'])) + # no_grad_set can be set of Tensor.name when the Tensors is created inside layers and can't be specified explicitly. + p_g_list5 = paddle.static.append_backward(loss=avg_loss, no_grad_set=set(['my_fc.b_0'])) # output: [(embedding_0.w_0, embedding_0.w_0@GRAD), (my_fc.w_0, my_fc.w_0@GRAD)] - # 返回为[], 因为所有的param_grad均被传入的no_grad_set过滤掉了 - p_g_list6 = fluid.backward.append_backward(loss=avg_loss, parameter_list=all_weights, no_grad_set=set(all_weights)) + # return [] because all param_grads are filtered by no_grad_set. + p_g_list6 = paddle.static.append_backward(loss=avg_loss, parameter_list=all_weights, no_grad_set=set(all_weights)) diff --git a/doc/paddle/api/paddle/fluid/backward/gradients_cn.rst b/doc/paddle/api/paddle/fluid/backward/gradients_cn.rst index 4d1ca378661..2604704836b 100644 --- a/doc/paddle/api/paddle/fluid/backward/gradients_cn.rst +++ b/doc/paddle/api/paddle/fluid/backward/gradients_cn.rst @@ -4,35 +4,36 @@ gradients ------------------------------- -.. py:function:: paddle.fluid.backward.gradients(targets, inputs, target_gradients=None, no_grad_set=None) +.. py:function:: paddle.static.gradients(targets, inputs, target_gradients=None, no_grad_set=None) -将目标梯度反向传播到输入。 +将目标 Tensor 的梯度反向传播到输入 Tensor。 参数： - - **targets** (Variable|list[Variable]) – 目标变量 - - **inputs** (Variable|list[Variable]) – 输入变量 - - **target_gradients** (Variable|list[Variable]，可选) – 目标的梯度变量，应与目标变量形状相同；如果设置为None，则以1初始化所有梯度变量 - - **no_grad_set** (set[Variable|str]，可选) – 在 `block0` ( :ref:`api_guide_Block` ) 中要忽略梯度的 :ref:`api_guide_Variable` 的名字的集合。所有的 :ref:`api_guide_Block` 中带有 ``stop_gradient = True`` 的所有 :ref:`api_guide_Variable` 的名字都会被自动添加到此集合中。如果该参数不为 ``None``，则会将该参数集合的内容添加到默认的集合中。默认值为 ``None``。 + - **targets** (Tensor|list[Tensor]) – 目标 Tensor 或包含 Tensor 的列表 + - **inputs** (Tensor|list[Tensor]) – 输入 Tensor 或包含 Tensor 的列表 + - **target_gradients** (Tensor|list[Tensor]，可选) – 目标的梯度 Tensor，应与目标 Tensor 的形状相同；如果设置为None，则以 1 初始化所有梯度 Tensor + - **no_grad_set** (set[Tensor|str]，可选) – 在 `block0` ( :ref:`api_guide_Block` ) 中要忽略梯度的 Tensor 的名字的集合。所有的 :ref:`api_guide_Block` 中带有 ``stop_gradient = True`` 的所有 Tensor 的名字都会被自动添加到此集合中。如果该参数不为 ``None`` ，则会将该参数集合的内容添加到默认的集合中。默认值为 ``None`` 。 -返回：数组，包含与输入对应的梯度。如果一个输入不影响目标函数，则对应的梯度变量为None +返回：数组，包含与输入对应的梯度。如果一个输入不影响目标函数，则对应的梯度 Tensor 为 None 。 -返回类型：(list[Variable]) +返回类型：(list[Tensor]) **示例代码** .. code-block:: python - import paddle.fluid as fluid + import paddle + import paddle.nn.functional as F - x = fluid.data(name='x', shape=[None,2,8,8], dtype='float32') + paddle.enable_static() + + x = paddle.static.data(name='x', shape=[None, 2, 8, 8], dtype='float32') x.stop_gradient=False - y = fluid.layers.conv2d(x, 4, 1, bias_attr=False) - y = fluid.layers.relu(y) - y = fluid.layers.conv2d(y, 4, 1, bias_attr=False) - y = fluid.layers.relu(y) - z = fluid.gradients([y], x) - print(z) \ No newline at end of file + y = paddle.static.nn.conv2d(x, 4, 1, bias_attr=False) + y = F.relu(y) + z = paddle.static.gradients([y], x) + print(z) # [var x@GRAD : fluid.VarType.LOD_TENSOR.shape(-1L, 2L, 8L, 8L).astype(VarType.FP32)] \ No newline at end of file diff --git a/doc/paddle/api/paddle/fluid/framework/program_guard_cn.rst b/doc/paddle/api/paddle/fluid/framework/program_guard_cn.rst index 51d47cefc28..a511c290c16 100644 --- a/doc/paddle/api/paddle/fluid/framework/program_guard_cn.rst +++ b/doc/paddle/api/paddle/fluid/framework/program_guard_cn.rst @@ -4,39 +4,43 @@ program_guard ------------------------------- -.. py:function:: paddle.fluid.program_guard(main_program, startup_program=None) +.. py:function:: paddle.static.program_guard(main_program, startup_program=None) 该接口应配合使用python的 ``with`` 语句来将 ``with`` block 里的算子和变量添加进指定的全局主程序（main program）和启动程序（startup program）。 -``with`` 语句块中的fluid.layers下各接口将在新的main program（主程序）中添加operators（算子）和variables（变量）。 +``with`` 语句块下的各接口将在新的main program（主程序）中添加 operators（算子）和 Tensors（张量）。 参数： - - **main_program** (Program) – “with”语句中将使用的新的main program。 - - **startup_program** (Program，可选) – “with”语句中将使用的新的startup program。若传入 ``None`` 则不改变当前的启动程序，即仍使用default_startup_program。默认值为None。 + - **main_program** (Program) – ``with`` 语句中将使用的新的 main program。 + - **startup_program** (Program，可选) – ``with`` 语句中将使用的新的 startup program。若传入 ``None`` 则不改变当前的启动程序，即仍使用 default_startup_program。默认值为 None。 **代码示例** .. code-block:: python - import paddle.fluid as fluid - main_program = fluid.Program() - startup_program = fluid.Program() - with fluid.program_guard(main_program, startup_program): - data = fluid.data(name='image', shape=[None, 784, 784], dtype='float32') - hidden = fluid.layers.fc(input=data, size=10, act='relu') + import paddle + + paddle.enable_static() + main_program = paddle.static.Program() + startup_program = paddle.static.Program() + with paddle.static.program_guard(main_program, startup_program): + data = paddle.static.data(name='image', shape=[None, 784, 784], dtype='float32') + hidden = paddle.static.nn.fc(input=data, size=10, act='relu') -例如，当组的网不需要startup_program初始化各变量时，可以传入一个临时的program。 +例如，当组的网不需要 startup_program 初始化各变量时，可以传入一个临时的 program。 **代码示例** .. code-block:: python - import paddle.fluid as fluid - main_program = fluid.Program() - # 如果您不需要关心startup program,传入一个临时值即可 - with fluid.program_guard(main_program, fluid.Program()): - data = fluid.data(name='image', shape=[None, 784, 784], dtype='float32') + import paddle + + paddle.enable_static() + main_program = paddle.static.Program() + # does not care about startup program. Just pass a temporary value. + with paddle.static.program_guard(main_program, paddle.static.Program()): + data = paddle.static.data(name='image', shape=[None, 784, 784], dtype='float32')