Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update Embedding doc #6806

Open
wants to merge 3 commits into
base: develop
Choose a base branch
from
Open

Update Embedding doc #6806

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e61b346
add weight and density options for histogram
AndPuQing Jul 11, 2024
977b997
Merge branch 'develop' of https://github.com/PaddlePaddle/docs into d…
AndPuQing Aug 2, 2024
57f7751
fix embedding doc
AndPuQing Aug 3, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/api/paddle/nn/Embedding_cn.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
Embedding
-------------------------------

.. py:class:: paddle.nn.Embedding(num_embeddings, embedding_dim, padding_idx=None, sparse=False, weight_attr=None, name=None)
.. py:class:: paddle.nn.Embedding(num_embeddings, embedding_dim, padding_idx=None, max_norm=None, norm_type=2.0, sparse=False, weight_attr=None, name=None)

嵌入层(Embedding Layer)，用于构建 ``Embedding`` 的一个可调用对象，具体用法参照 ``代码示例``。其根据 ``x`` 中的 id 信息从 embedding 矩阵中查询对应 embedding 信息，并会根据输入的 size (num_embeddings, embedding_dim)和 weight_attr 自动构造一个二维 embedding 矩阵。

Expand Down Expand Up @@ -38,6 +38,8 @@ Embedding
- **num_embeddings** (int) - 嵌入字典的大小，input 中的 id 必须满足 ``0 <= id < num_embeddings`` 。
- **embedding_dim** (int) - 每个嵌入向量的维度。
- **padding_idx** (int|long|None，可选) - padding_idx 的配置区间为 ``[-weight.shape[0], weight.shape[0]]``，如果配置了 padding_idx，那么在训练过程中遇到此 id 时，其参数及对应的梯度将会以 0 进行填充。
- **max_norm** (float，可选) - 如果给定，则每个范数大于 max_norm 的嵌入向量都会被重新规范化为具有范数 max_norm。注意，在动态图模式下，将会原位修改权重。默认值：None。
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

有一个其他Bug，不影响本文档合入。

在静态图下，是否会导致梯度无法计算，因为返回了一个新的weight。这个应该写为：

    if max_norm:
        embedding_renorm_(
            x, weight, max_norm=max_norm, norm_type=norm_type
        )

保证是原来的weight参与组网计算与反向传播，返回一个新的weight，当前weight就从网络中分离了。这个静态图的问题需要修一下 @AndPuQing

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

这样的话，静态图的renorm 是不是就失效了

- **norm_type** (float，可选) - 规范化的范数类型，默认为 2.0，即 L2 范数。默认值：2.0。
- **sparse** (bool，可选) - 是否使用稀疏更新，在词嵌入权重较大的情况下，使用稀疏更新能够获得更快的训练速度及更小的内存/显存占用。
- **weight_attr** (ParamAttr|None，可选) - 指定嵌入向量的配置，包括初始化方法，具体用法请参见 :ref:`api_guide_ParamAttr`，一般无需设置，默认值为 None。
- **name** (str|None，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
Expand Down
4 changes: 3 additions & 1 deletion docs/api/paddle/nn/functional/embedding_cn.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
embedding
-------------------------------

.. py:function:: paddle.nn.functional.embedding(x, weight, padding_idx=None, sparse=False, name=None)
.. py:function:: paddle.nn.functional.embedding(x, weight, padding_idx=None, max_norm=None, norm_type=2.0, sparse=False, name=None)



Expand Down Expand Up @@ -41,6 +41,8 @@ embedding

- **input** (Tensor) - 存储 id 信息的 Tensor，数据类型必须为：int32/int64。input 中的 id 必须满足 ``0 =< id < size[0]`` 。
- **weight** (Tensor) - 存储词嵌入权重参数的 Tensor，形状为(num_embeddings, embedding_dim)。
- **max_norm** (float，可选) - 如果给定，则每个范数大于 max_norm 的嵌入向量都会被重新规范化为具有范数 max_norm。注意，在动态图模式下，将会原位修改权重。默认值：None。
- **norm_type** (float，可选) - 规范化的范数类型，默认为 2.0，即 L2 范数。默认值：2.0。
- **sparse** (bool，可选) - 是否使用稀疏更新，在词嵌入权重较大的情况下，使用稀疏更新（即设置为 True）能够获得更快的训练速度及更小的内存/显存占用。但是一些优化器不支持稀疏更新，例如 :ref:`cn_api_paddle_optimizer_Adadelta` ， :ref:`cn_api_paddle_optimizer_Adamax` ， :ref:`cn_api_paddle_optimizer_Lamb` 。在这些情况下，稀疏必须为 False。默认值：False。
- **padding_idx** (int|long|None，可选) - padding_idx 的配置区间为 ``[-weight.shape[0], weight.shape[0]``，如果配置了 padding_idx，那么在训练过程中遇到此 id 时，其参数及对应的梯度将会以 0 进行填充。如果 padding_idx < 0 ，则 padding_idx 将自动转换到 ``weight.shape[0] + padding_idx`` 。如果设置为 "None"，则不会对输出产生影响。默认值：None。
- **name** (str，可选) - 具体用法请参见 :ref:`api_guide_Name`，一般无需设置，默认值为 None。
Expand Down
6 changes: 3 additions & 3 deletions ...convert_from_pytorch/api_difference/functional/torch.nn.functional.embedding.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ torch.nn.functional.embedding(input, weight, padding_idx=None, max_norm=None, no
### [paddle.nn.functional.embedding](https://www.paddlepaddle.org.cn/documentation/docs/zh/api/paddle/nn/functional/embedding_cn.html#embedding)

```python
paddle.nn.functional.embedding(x, weight, padding_idx=None, sparse=False, name=None)
paddle.nn.functional.embedding(x, weight, padding_idx=None, max_norm=None, norm_type=2.0, sparse=False, name=None)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

分类类别：torch参数更多->仅参数名不一致

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

这个的话，scale_grad_by_freq参数暂时还不支持，应该不用修改吧

```

PyTorch 相比 Paddle 支持更多其他参数，具体如下：
Expand All @@ -21,7 +21,7 @@ PyTorch 相比 Paddle 支持更多其他参数，具体如下：
| input | x | 输入 Tensor，仅参数名不同。 |
| weight | weight | 嵌入矩阵权重。 |
| padding_idx | padding_idx | 视为填充的下标，参数完全一致。 |
| max_norm | - | 重新归一化的最大范数，参数不一致，暂无转写方式。 |
| norm_type | - | Paddle 无此参数，参数不一致，暂无转写方式。 |
| max_norm | max_norm | 重新归一化的最大范数，参数完全一致。 |
| norm_type | norm_type | 范数计算方式，默认为 L2 范数，参数完全一致。 |
| scale_grad_by_freq | - | 按词频进行梯度缩放的比例，参数不一致，暂无转写方式。 |
| sparse | sparse | 是否使用稀疏更新。 |
6 changes: 4 additions & 2 deletions ...ides/model_convert/convert_from_pytorch/api_difference/nn/torch.nn.Embedding.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@ torch.nn.Embedding(num_embeddings,
paddle.nn.Embedding(num_embeddings,
embedding_dim,
padding_idx=None,
max_norm=None,
norm_type=2.0,
sparse=False,
weight_attr=None,
name=None)
Expand All @@ -29,8 +31,8 @@ PyTorch 相比 Paddle 支持更多其他参数，具体如下：
| num_embeddings | num_embeddings | 表示嵌入字典的大小。 |
| embedding_dim | embedding_dim | 表示每个嵌入向量的维度。 |
| padding_idx | padding_idx | 在此区间内的参数及对应的梯度将会以 0 进行填充 |
| max_norm | - | 如果给定，Embeddding 向量的范数（范数的计算方式由 norm_type 决定）超过了 max_norm 这个界限，就要再进行归一化，Paddle 无此参数，暂无转写方式。 |
| norm_type | - | 为 maxnorm 选项计算 p-范数的 p。默认值 2，Paddle 无此参数，暂无转写方式。 |
| max_norm | max_norm | 如果给定，Embeddding 向量的范数（范数的计算方式由 norm_type 决定）超过了 max_norm 这个界限，就要再进行归一化。 |
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

分类类别：torch参数更多->仅参数名不一致

| norm_type | norm_type | 为 maxnorm 选项计算 p-范数的 p。默认值 2。 |
| scale_grad_by_freq | - | 是否根据单词在 mini-batch 中出现的频率，对梯度进行放缩，Paddle 无此参数，暂无转写方式。 |
| sparse | sparse | 表示是否使用稀疏更新。 |
| - | weight_attr | 指定权重参数属性的对象，PyTorch 无此参数，Paddle 保持默认即可。 |