diff --git a/rfcs/APIs/20230917_api_design_for_bernoulli_lognormal.md b/rfcs/APIs/20230917_api_design_for_bernoulli_lognormal.md new file mode 100644 index 000000000..684755c7f --- /dev/null +++ b/rfcs/APIs/20230917_api_design_for_bernoulli_lognormal.md @@ -0,0 +1,67 @@ + +|API名称 | bernoulli_ / log_normal_ / log_normal | +|---|---| +|提交作者 | [您的名字] | +|提交时间 | 2023-09-17 | +|版本号 | V1.0 | +|依赖飞桨版本 | develop版本 | +|文件名 | 20230917_api_design_for_bernoulli_lognormal.md | + +# 一、概述 + +## 1、相关背景 +随着深度学习技术的广泛应用,统计分布,特别是伯努利和对数正态分布,在模型初始化、正则化和其他场景中都有广泛的应用。为了让Paddle用户更方便地实现这些功能,我们提议添加这些API。 + +## 2、功能目标 +1. 实现指定概率p的伯努利分布。 +2. 实现指定均值和方差的对数正态分布。 +3. 两种分布都需要提供in-place和非in-place版本。 + +## 3、意义 +- 提供更丰富的概率分布工具,满足广泛的应用需求。 +- 对齐其他主流深度学习框架的功能,增强Paddle的竞争力。 + +# 二、飞桨现状 +Paddle目前支持一系列的随机分布生成API,但伯努利和对数正态分布仍然缺失。尽管可以通过组合其他API间接实现,但直接的支持将更加方便。 + +# 三、业内方案调研 + +在业界的其他主流深度学习框架中,伯努利分布和对数正态分布API都是标准的组成部分,具体如下: + +## TensorFlow +- TensorFlow提供了`tf.random.bernoulli`函数来生成伯努利分布。该函数允许用户指定概率和输出张量的形状。 +- 对于对数正态分布,TensorFlow提供了`tf.random.log_normal`函数。用户可以指定均值、标准差以及输出张量的形状。 + +## PyTorch +- PyTorch通过`torch.bernoulli`函数支持伯努利分布的生成。该函数可以接收一个张量作为概率参数,并返回一个同形状的输出张量。 +- 对于对数正态分布,PyTorch提供了`torch.distributions.LogNormal`类。这是一个更加复杂的API,不仅可以生成随机数,还提供了其他统计功能如PDF和CDF计算。 + +### 应用情况 +在实际应用中,伯努利分布和对数正态分布被用于多种场景,如模型初始化、数据增强和特定类型的噪音注入。考虑到这些API在TensorFlow和PyTorch中的广泛使用,它们被认为是深度学习库中的基本组件。 + + +# 四、对比分析 +与TensorFlow和PyTorch相比,Paddle的API设计通常更加灵活和高效。通过新增这些API,Paddle可以提供与其他主流框架相当的功能,并在性能和易用性上可能有所优势。 + +# 五、设计思路与实现方案 + +## 命名与参数设计 +- `paddle.bernoulli_`: 伯努利分布的in-place版本。 +- `paddle.Tensor.bernoulli_`: Tensor方法版本。 +- `paddle.log_normal_`: 对数正态分布的in-place版本。 +- `paddle.Tensor.log_normal_`: Tensor方法版本。 +- `paddle.log_normal`: 对数正态分布的非in-place版本。 + +## 底层OP设计 +- `bernoulli_`可以通过`paddle.uniform_`来实现。 +- `log_normal_`和`log_normal`可以通过`paddle.normal_`和`paddle.exp_`组合来实现。 + +## API实现方案 +- 在`paddle/tensor/random.py`中实现Python API。 +- 在`paddle/fluid/operators`中实现底层C++ OP。 + +# 六、测试和验收的考量 +- 对所有新API进行严格的单元测试。 +- 对性能进行基准测试,确保与其他框架相当或更好。 +- 提供详细的API文档和示例。 +