From 74099051a01edfad53d40b687b0fc5287d2dde44 Mon Sep 17 00:00:00 2001 From: Aurelius84 Date: Tue, 24 Sep 2019 16:36:36 +0800 Subject: [PATCH] improve embeding cn doc (#1168) * improve embeding cn doc test=document_preview * refine text format test=document_preview * refine return type test=document_preview * add data example test=document_preview * refine warining and return type * refine param_attr * modify warning * add warning * modify x into input * refine return doc * add padding data update doc * add np.dtype --- doc/fluid/api_cn/layers_cn/embedding_cn.rst | 66 +++++++++++++++++---- 1 file changed, 55 insertions(+), 11 deletions(-) diff --git a/doc/fluid/api_cn/layers_cn/embedding_cn.rst b/doc/fluid/api_cn/layers_cn/embedding_cn.rst index 8f8c180bc..009c86276 100644 --- a/doc/fluid/api_cn/layers_cn/embedding_cn.rst +++ b/doc/fluid/api_cn/layers_cn/embedding_cn.rst @@ -7,21 +7,65 @@ embedding 嵌入层(Embedding Layer) -该层用于查找由输入提供的id在查找表中的嵌入矩阵。查找的结果是input里每个ID对应的嵌入矩阵。 -所有的输入变量都作为局部变量传入LayerHelper构造器 +**注意：此OP将在未来的版本中被移除！该OP要求输入Tensor shape的最后一维必须为1。推荐使用fluid.** :ref:`cn_api_fluid_embedding` 。 + +该OP根据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处理。 + 参数： - - **input** (Variable) - 包含IDs信息的int64的张量变量。输入IDs的值应该(0<= id < size[0])。 - - **size** (tuple|list) - 查找表参数的维度。应当有两个参数，一个代表嵌入矩阵字典的大小，一个代表每个嵌入向量的大小。 - - **is_sparse** (bool) - 代表是否用稀疏更新的标志 - - **is_distributed** (bool) - 是否从远程参数服务端运行查找表 - - **padding_idx** (int|long|None) - 只要查找发现（padding_idx）在ids中，就会输出全0填充的数据，如果为 ``None`` ，对输出结果无影响。如果（padding_idx<0），则（padding_idx<0）会自动转换为（size[0] + padding_idx）,默认为None。 - - **param_attr** (ParamAttr) - 该层参数 - - **dtype** (np.dtype|core.VarDesc.VarType|str) - 数据类型：float32,float_16,int等。 + - **input** (Variable) - 存储id信息，数据类型必须为：int64，输入的shape最后一维须为1。 + - **size** (tuple|list) - embedding矩阵的维度。必须包含两个元素，第一个元素为vocab_size(词表大小), 第二个为emb_size（embedding 层维度）。 + - **is_sparse** (bool) - 是否使用稀疏的更新方式，这个参数只会影响反向的梯度更新的性能，sparse更新速度更快。但某些optimizer不支持sparse更新，比如 :ref:`cn_api_fluid_optimizer_Adadelta` ，此时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` 。 + - **dtype** (str|np.dtype|core.VarDesc.VarType) - 输出Tensor或LoDTensor的数据类型，数据类型必须为：float32或float64，默认为float32。 -返回：张量，存储已有输入的嵌入矩阵。 +返回：input映射后得到的Embedding Tensor或LoDTensor，数据类型和dtype定义的类型一致。 -返回类型：变量(Variable) +返回类型：Variable **代码示例**: -- GitLab