Skip to content

Fix PaddleDocs function pad #7300

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.

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

Merged
merged 1 commit into from
May 26, 2025
Merged

Fix PaddleDocs function pad #7300

merged 1 commit into from
May 26, 2025

Conversation

Echo-Nie
Copy link
Contributor

@Echo-Nie Echo-Nie commented May 6, 2025

Description

issue: #7299

pad函数文档描述如下:

  1. mode='constant':根据官方文档,pad 长度应为偶数。
    但根据实际测试,奇数长度也能被接受,只是不会对结果产生影响。如果 pad 长度超过 2*N,不会报错,但超出部分可能不会起作用。

  2. mode='reflect'、replicate 或 circular:根据官方文档,长度有严格检查,不符合规定的输入,会抛出异常。

constant测试结果

  • 奇数长度的 padmode='constant' 时,官方文档提到 pad 的长度应为偶数,但奇数长度的 pad 也是OK的。测试输入 pad=[0, 0, 0, 0, 2]

    Result: [[[0. 0. 0.]]
             [[0. 0. 0.]]
             [[1. 2. 3.]]]
    Shape: [3, 1, 3]
    
  • 超出最大长度的 padpad 的长度超过 2*N时,Paddle 不会报错,但多余的填充不会起作用。例如,pad=[0, 0, 0, 0, 2, 3, 4, 5] 的结果与 pad=[0, 0, 0, 0, 2, 3, 4] 的结果相同:

    Result: [[[0. 0. 0.]]
             [[0. 0. 0.]]
             [[1. 2. 3.]]
             [[0. 0. 0.]]
             [[0. 0. 0.]]
             [[0. 0. 0.]]]
    Shape: [6, 1, 3]
    

    所以 Paddle 在内部处理时应该是只使用了前 2*N 个值,多余的填充值直接就被忽略吧(?)

reflect、replicate、circular测试结果

测试结果显示,当 modereflectreplicatecircular 时,pad 的长度有严格要求,符合 原官方文档 说明。

错误信息如下:

Error: (InvalidArgument) Size of paddings should be equal to 6, but received 10.

这表明 Paddle 对这三种模式的 pad 长度有严格的检查,所以相关文档无需修改。

Note

constant的奇数和偶数的填充方式好像不同?

偶数长度的 pad:填充会均匀地分布在指定的维度两侧。比如说pad=[0, 0, 0, 0, 2, 3] 会在最后一个维度的前面填充 2 个值,后面填充 3 个值。
奇数长度的 pad: 会自动扩展 pad 的长度到 2*N,并在前面补零。如果pad=[0, 0, 0, 0, 2] 会被扩展为 [0, 0, 0, 0, 2, 0],然后进行填充,相当于把奇数变成偶数再填充的意思。

源码位置:pad源码
对应文档:pad文档

这里是否需要在文档中补充一下? @sunzhongkai588 @DrRyanHuang

Copy link

paddle-bot bot commented May 6, 2025

感谢你贡献飞桨文档,文档预览构建中,Docs-New 跑完后即可预览,预览链接:http://preview-pr-7300.paddle-docs-preview.paddlepaddle.org.cn/documentation/docs/zh/api/index_cn.html
预览工具的更多说明,请参考:飞桨文档预览工具

@luotao1 luotao1 added the HappyOpenSource 快乐开源活动issue与PR label May 8, 2025
@DrRyanHuang
Copy link
Collaborator

DrRyanHuang commented May 15, 2025

这部分展开说说,再补充两个例子吧,参数 pad_from_left_axis 也在控制这个填充的方向

偶数长度的 pad:填充会均匀地分布在指定的维度两侧。比如说pad=[0, 0, 0, 0, 2, 3] 会在最后一个维度的前面填充 2 个值,后面填充 3 个值。
奇数长度的 pad: 会自动扩展 pad 的长度到 2*N,并在前面补零。如果pad=[0, 0, 0, 0, 2] 会被扩展为 [0, 0, 0, 0, 2, 0],然后进行填充,相当于把奇数变成偶数再填充的意思。

(不过其实还是不建议 pad 参数为奇数

@Echo-Nie
Copy link
Contributor Author

这部分展开说说,再补充两个例子吧,参数 pad_from_left_axis 也在控制这个填充的方向

pad_from_left_axis 参数在第二点里提到了~ 如下图:

image

(不过其实还是不建议 pad 参数为奇数

是的!奇数的自动填充可能会有一些问题,所以在文档里重新说明了一下

@Echo-Nie
Copy link
Contributor Author

Echo-Nie commented May 16, 2025

sorry最近在处理别的事情所以这条PR没来得及及时追踪,刚刚仔细看了一下。

  1. 文档设计的时候应该就已经考虑了奇偶数的问题,因为奇数的自动补0可能会导致一些不可知的问题比如 填充效果和预期维度不符 ,填充混淆等,所以只提到了偶数。
  2. 但是根据paddle的源码,奇数也不被拒绝,所以可能导致部分用户对于文档中的 小于等于2*N的偶数 会有疑惑,所以这里对奇偶数进行补充说明。但是最后加粗建议使用偶数,可能更友好些。

@sunzhongkai588 pls review

@Echo-Nie
Copy link
Contributor Author

预览:pad

image

@sunzhongkai588 pls reveiw

fix according review. Supplemented the explanation of odd and even numbers.
@luotao1 luotao1 merged commit 2f138d6 into PaddlePaddle:develop May 26, 2025
2 checks passed
@Echo-Nie Echo-Nie deleted the fix7299 branch May 27, 2025 10:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
contributor HappyOpenSource 快乐开源活动issue与PR
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants