fix Layer、guard、Embedding apis, test=develop (#1488)

* fix apis, test=develop

* drop WeightedAverage_cn.rst, test=develop

* update layer api, test=develop

* fix dtype, test=develop

doc/fluid/api_cn/dygraph_cn/Embedding_cn.rst

@@ -5,23 +5,64 @@ Embedding
 
 .. py:class:: paddle.fluid.dygraph.Embedding(name_scope, size, is_sparse=False, is_distributed=False, padding_idx=None, param_attr=None, dtype='float32')
 
-Embedding层
-
-该层用于在查找表中查找 ``input`` 中的ID对应的embeddings。查找的结果是input里每个ID对应的embedding。
-所有的输入变量都作为局部变量传入LayerHelper构造器
+嵌入层(Embedding Layer)
+
+该接口用于构建 ``Embedding`` 的一个可调用对象，具体用法参照 ``代码示例`` 。其根据input中的id信息从embedding矩阵中查询对应embedding信息，并会根据输入的size (vocab_size, emb_size)和dtype自动构造一个二维embedding矩阵。
+
+要求input的最后一维必须等于1，输出的Tensor的shape是将输入Tensor shape的最后一维的1替换为emb_size。
+
+注：input中的id必须满足 ``0 =< id < size[0]``，否则程序会抛异常退出。
+
+
+::
+
+    Case 1:
+
+    input是Tensor, 且padding_idx = -1
+        input.data = [[[1], [3]], [[2], [4]], [[4], [127]]]
+        input.shape = [3, 2, 1]
+    若size = [128, 16]
+    输出为Tensor:
+        out.shape = [3, 2, 16]
+        out.data = [[[0.129435295, 0.244512452, ..., 0.436322452],
+                     [0.345421456, 0.524563927, ..., 0.144534654]],
+
+                    [[0.345249859, 0.124939536, ..., 0.194353745],
+                     [0.945345345, 0.435394634, ..., 0.435345365]],
+                     
+                    [[0.945345345, 0.435394634, ..., 0.435345365],
+                     [0.0,         0.0,         ..., 0.0        ]]]  # padding data
+    输入的padding_idx小于0，则自动转换为padding_idx = -1 + 128 = 127, 对于输入id为127的词，进行padding处理。
+    
+    Case 2:
+
+    input是lod level 为1的LoDTensor, 且padding_idx = 0
+        input.lod = [[2, 3]]
+        input.data = [[1], [3], [2], [4], [0]]
+        input.shape = [5, 1]
+    若size = [128, 16]
+    输出为LoDTensor:
+        out.lod = [[2, 3]]
+        out.shape = [5, 16]
+        out.data = [[0.129435295, 0.244512452, ..., 0.436322452],
+                    [0.345421456, 0.524563927, ..., 0.144534654],
+                    [0.345249859, 0.124939536, ..., 0.194353745],
+                    [0.945345345, 0.435394634, ..., 0.435345365],
+                    [0.0,         0.0,         ..., 0.0        ]]  # padding data
+    输入的padding_idx = 0，则对于输入id为0的词，进行padding处理。
 
 参数：
     - **name_scope** (str)-该类的名称。
-    - **size** (tuple|list)-查找表参数的维度。应当有两个参数，一个代表嵌入矩阵字典的大小，一个代表每个嵌入向量的大小。
-    - **is_sparse** (bool)-代表是否用稀疏更新的标志。
-    - **is_distributed** (bool)-是否从远程参数服务端运行查找表。
-    - **padding_idx** (int|long|None)-如果为 ``None`` ，对查找结果无影响。如果 ``padding_idx`` 不为空，表示一旦查找表中找到input中对应的 ``padding_idx``，则用0填充输出结果。如果 ``padding_idx`` <0 ,则在查找表中使用的 ``padding_idx`` 值为 :math:`size[0]+dim` 。默认：None。
-    - **param_attr** (ParamAttr)-该层参数。默认为None。
-    - **dtype** (np.dtype|core.VarDesc.VarType|str)-数据类型：float32,float_16,int等。默认:‘float32’
+    - **size** (tuple|list) - embedding矩阵的维度。必须包含两个元素，第一个元素为vocab_size(词表大小), 第二个为emb_size（embedding层维度）。
+    - **is_sparse** (bool) - 是否使用稀疏的更新方式，这个参数只会影响反向的梯度更新的性能，sparse更新速度更快，推荐使用稀疏更新的方式。但某些optimizer不支持sparse更新，比如 :ref:`cn_api_fluid_optimizer_AdadeltaOptimizer` 、 :ref:`cn_api_fluid_optimizer_AdamaxOptimizer` 、 :ref:`cn_api_fluid_optimizer_DecayedAdagradOptimizer` 、 :ref:`cn_api_fluid_optimizer_FtrlOptimizer` 、 :ref:`cn_api_fluid_optimizer_LambOptimizer` 、:ref:`cn_api_fluid_optimizer_LarsMomentumOptimizer` ，此时is_sparse必须为False。默认为False。
+    - **is_distributed** (bool) - 是否使用分布式的方式存储embedding矩阵，仅在多机分布式cpu训练中使用。默认为False。
+    - **padding_idx** (int|long|None) - padding_idx需在区间[-vocab_size, vocab_size)，否则不生效，padding_idx<0时，padding_idx会被改成vocab_size + padding_idx，input中等于padding_index的id对应的embedding信息会被设置为0，且这部分填充数据在训练时将不会被更新。如果为None，不作处理，默认为None。
+    - **param_attr** (ParamAttr) - 指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。此外，可以通过 ``param_attr`` 参数加载用户自定义或预训练的词向量。只需将本地词向量转为numpy数据格式，且保证本地词向量的shape和embedding的 ``size`` 参数一致，然后使用 :ref:`cn_api_fluid_initializer_NumpyArrayInitializer` 进行初始化，即可实现加载自定义或预训练的词向量。详细使用方法见代码示例2。
+    - **dtype** (str|core.VarDesc.VarType) - 输出Tensor或LoDTensor的数据类型，数据类型必须为：float32或float64，默认为float32。
 
-返回：张量，存储已有输入的嵌入矩阵。
+返回：input映射后得到的Embedding Tensor或LoDTensor，数据类型和dtype定义的类型一致。
 
-返回类型：变量(Variable)
+返回类型：Variable
 
 **代码示例**
 
@@ -31,6 +72,7 @@ Embedding层
     import paddle.fluid.dygraph.base as base
     import numpy as np
 
+    # 示例 1
     inp_word = np.array([[[1]]]).astype('int64')
     dict_size = 20
     with fluid.dygraph.guard():
@@ -41,7 +83,18 @@ Embedding层
             is_sparse=False)
         static_rlt3 = emb(base.to_variable(inp_word))
 
-
-
-
+    # 示例 2: 加载用户自定义或预训练的词向量
+    weight_data = np.random.random(size=(128, 100))  # numpy格式的词向量数据
+    w_param_attrs = fluid.ParamAttr(
+        name="emb_weight",
+        learning_rate=0.5,
+        initializer=fluid.initializer.NumpyArrayInitializer(weight_data),
+        trainable=True)
+    with fluid.dygraph.guard():
+        emb = fluid.dygraph.Embedding(
+            name_scope='embedding',
+            size=[128, 100],
+            param_attr= w_param_attrs,
+            is_sparse=False)
+        static_rlt3 = emb(base.to_variable(inp_word))
 

doc/fluid/api_cn/dygraph_cn/Layer_cn.rst

@@ -5,91 +5,94 @@ Layer
 
 .. py:class:: paddle.fluid.dygraph.Layer(name_scope, dtype=VarType.FP32)
 
-由多个算子组成的层。
+基于OOD实现的动态图Layer， 包含该Layer的参数、前序运行的结构等信息。
 
 参数：
-    - **name_scope** - 层为其参数命名而采用的名称前缀。如果前缀为“my_model/layer_1”，在一个名为MyLayer的层中，参数名为“my_model/layer_1/MyLayer/w_n”，其中w是参数的基础名称，n为自动生成的具有唯一性的后缀。
-    - **dtype** - 层中变量的数据类型
+    - **name_scope** (str) - 为Layer内部参数命名而采用的名称前缀。如果前缀为“my_model/layer_1”，在一个类名为MyLayer的Layer中，参数名为“my_model/layer_1/MyLayer/w_n”，其中w是参数的名称，n为自动生成的具有唯一性的后缀。
+    - **dtype** (core.VarDesc.VarType) - Layer中参数数据类型，默认值为core.VarDesc.VarType.FP32。
 
+返回：无
 
 .. py:method:: full_name()
 
-层的全名。
+Layer的全名。组成方式为： ``name_scope`` + “/” + MyLayer.__class__.__name__ 。
 
-组成方式如下：
-
-name_scope + “/” + MyLayer.__class__.__name__
-
-返回：  层的全名
+返回：Layer的全名
 
+返回类型：str
 
 .. py:method:: create_parameter(attr, shape, dtype, is_bias=False, default_initializer=None)
 
-为层(layers)创建参数。
+为Layer创建参数。
 
 参数：
-    - **attr** (ParamAttr)- 参数的参数属性
-    - **shape** - 参数的形状
-    - **dtype** - 参数的数据类型
-    - **is_bias** - 是否为偏置bias参数      
-    - **default_initializer** - 设置参数的默认初始化方法
+    - **attr** (ParamAttr) - 指定权重参数属性的对象。默认值为None，表示使用默认的权重参数属性。具体用法请参见 :ref:`cn_api_fluid_ParamAttr` 。
+    - **shape** (list) - 参数的形状。列表中的数据类型必须为int。
+    - **dtype** (float|int|core.VarDesc.VarType) - 参数的数据类型。
+    - **is_bias** (bool, 可选) - 是否使用偏置参数。默认值：False。
+    - **default_initializer** (Initializer, 可选) - 默认的参数初始化方法。默认值：None。
 
-返回：    创建的参数变量
+返回：创建的参数变量
 
+返回类型：Variable
 
 .. py:method:: create_variable(name=None, persistable=None, dtype=None, type=VarType.LOD_TENSOR)
 
-为层创建变量
+为Layer创建变量。
 
 参数：
-    - **name** - 变量名
-    - **persistable** - 是否为持久性变量
-    - **dtype** - 变量中的数据类型
-    - **type** - 变量类型   
+    - **name** (str, 可选) - 变量名。默认值：None。
+    - **persistable** (bool, 可选) - 是否为持久性变量，后续会被移出。默认值：None。
+    - **dtype** (core.VarDesc.VarType, 可选) - 变量中的数据类型。默认值：None。
+    - **type** (core.VarDesc.VarType, 可选) - 变量类型。默认值：core.VarDesc.VarType.LOD_TENSOR。
 
-返回： 创建的变量(Variable)
+返回：创建的 ``Tensor`` 
 
+返回类型：Variable
 
 .. py:method:: parameters(include_sublayers=True)
 
-返回一个由当前层及其子层的参数组成的列表。
+返回一个由当前层及其子层的所有参数组成的列表。
 
 参数：
-    - **include_sublayers** - 如果为True，返回的列表中包含子层的参数
-
-返回：  一个由当前层及其子层的参数组成的列表
+    - **include_sublayers** (bool, 可选) - 是否返回子层的参数。如果为True，返回的列表中包含子层的参数。默认值：True。
 
+返回：一个由当前层及其子层的所有参数组成的列表，列表中的元素类型为Parameter(Variable)。
 
+返回类型：list
 
 .. py:method:: sublayers(include_sublayers=True)
 
 返回一个由所有子层组成的列表。
 
 参数：
-    - **include_sublayers** - 如果为True，则包括子层中的各层
+    - **include_sublayers** (bool, 可选) - 是否返回子层中各个子层。如果为True，则包括子层中的各个子层。默认值：True。
 
-返回： 一个由所有子层组成的列表
+返回： 一个由所有子层组成的列表，列表中的元素类型为Layer。
 
+返回类型：list
 
 .. py:method:: add_sublayer(name, sublayer)
 
-添加子层实例。被添加的子层实例的访问方式和self.name类似。
+添加子层实例。可以通过self.name的方式来使用sublayer。
 
 参数：
-    - **name** - 该子层的命名
-    - **sublayer** - Layer实例
+    - **name** (str) - 子层名。
+    - **sublayer** (Layer) - Layer实例。
 
-返回：   传入的子层
+返回：添加的子层
 
+返回类型：Layer
 
 .. py:method:: add_parameter(name, parameter)
 
-添加参数实例。被添加的参数实例的访问方式和self.name类似。
+添加参数实例。可以通过self.name的方式来使用parameter。
 
 参数：
-    - **name** - 该子层的命名
-    - **parameter** - Parameter实例
+    - **name** (str) - 参数名。
+    - **parameter** (Parameter) - Parameter实例。
 
-返回：   传入的参数实例   
+返回：传入的参数实例
 
+返回类型：Parameter(Variable)
 

doc/fluid/api_cn/dygraph_cn/guard_cn.rst

@@ -5,10 +5,10 @@ guard
 
 .. py:function:: paddle.fluid.dygraph.guard(place=None)
 
-创建一个dygraph上下文，用于运行dygraph。
+通过with语句创建一个dygraph运行的context，执行context代码。
 
 参数：
-    - **place** (fluid.CPUPlace|fluid.CUDAPlace|None) – 执行场所
+    - **place** (fluid.CPUPlace|fluid.CUDAPlace, 可选) –  动态图执行的设备，可以选择cpu，gpu，如果用户未制定，则根据用户paddle编译的方式来选择运行的设备，如果编译的cpu版本，则在cpu上运行，如果是编译的gpu版本，则在gpu上运行。默认值：None。
 
 返回： None