飞桨API的设计和命名规范¶

总体原则¶

1. 单一职责，每个API应只完成单一的任务

2. 接口设计应考虑通用性，避免只适用于某些单一场景

3. 符合行业标准，综合参考开源深度学习框架的接口设计，借鉴各框架的优点；除非飞桨API设计有明确优势的情况下可保留自有特色，否则需要符合行业标准

4. 功能类似的接口，参数名和行为需要保持一致，比如，lstm和gru

5. 优先保证清晰，然后考虑简洁，避免使用不容易理解的缩写

6. 历史一致，如无必要原因，应避免接口修改

7. 动静统一，如无特殊原因，动态图和静态图下的API输入、输出要求一致。开发者使用相同的代码，均可以在动态图和静态图模式下执行

动态图与静态图模式¶

关于飞桨框架支持的开发模式，为了便于用户理解，代码和API均采用“动态图”和“静态图”的说法；文档优先使用“动态图”和“静态图”的说法，不推荐使用“命令式编程”和“声明式编程”的说法。

API目录结构规范¶

• 公开API代码应该放置到以下列出的对应位置目录/文件中，并添加到目录下__init__.py的 all列表中。非公开API不能添加到all列表中

• 常用的API可以在更高层级建立别名，当前规则如下：

  1. paddle.tensor目录下的API，均在paddle根目录建立别名，其他所有API在paddle根目录下均没有别名。

  2. paddle.nn目录下除了functional目录以外的所有API，在paddle.nn目录下均有别名。

     paddle.nn.functional.mse_loss # functional下的函数不建立别名，使用完整名称
     paddle.nn.Conv2D # 为paddle.nn.layer.conv.Conv2D建立的别名
     

  3. 一些特殊情况比如特别常用的API会直接在paddle下建立别名

     paddle.tanh # 为常用函数paddle.tensor.math.tanh建立的别名
     paddle.linspace# 为常用函数paddle.fluid.layers.linspace建立的别名
     

API行为定义规范¶

• 动静统一要求。除了paddle.static目录中的API外，其他目录的所有API原则上均需要支持动态图和静态图模式下的执行，且输入、输出要求一致。开发者使用相同的代码，可以在动态图和静态图模式下执行。

  #静态图专用
  paddle.fluid.gradients(targets, inputs, target_gradients=None, no_grad_set=None)
  #动态图专用
  paddle.fluid.dygraph.grad(outputs, inputs, grad_outputs=None, retain_graph=None, create_graph=False, only_inputs=True, allow_unused=False, no_grad_vars=None, backward_strategy=None)
  #动、静态图通用
  paddle.nn.functional.conv2d(x, weight, bias=None, padding=0, stride=1, dilation=1, groups=1, use_cudnn=True, act=None, data_format="NCHW", name=None)
  paddle.nn.Conv2D(num_channels, num_filters, filter_size, padding=0, stride=1, dilation=1, groups=1, param_attr=None, bias_attr=None, use_cudnn=True, act=None, data_format="NCHW", dtype='float32')
  

• API不需要用户指定执行硬件，框架可以自动根据当前配置，选择执行的库。

• 设置缺省参数类型 组网类API去除dtype参数，比如Linear, Conv2d等，通过使用paddle.set_default_dtype和paddle.get_default_dtype设置全局的数据类型。

• 数据类型转换规则

  1. 不支持Tensor和Tensor之间的隐式数据类型转换，隐藏类型转换虽然方便，但风险很高，很容易出现转换错误。如果发现类型不匹配，进行隐式类型转换，一旦转换造成精度损失，会导致模型的精度降低，由于没有任何提示，问题非常难以追查；而如果直接向用户报错或者警告，用户确认后，修改起来会很容易。避免了出错的风险。

     import paddle
     a = paddle.randn([3, 1, 2, 2], dtype='float32')
     b = paddle.randint(0, 10, [3, 1, 2, 2], dtype='int32')
     c = a + b
     # 执行后会出现以下类型不匹配警告：
     # ......\paddle\fluid\dygraph\math_op_patch.py:239: UserWarning: The dtype of left and right variables are not the same, left dtype is paddle.float32, but right dtype is paddle.int32, the right dtype will convert to paddle.float32 format(lhs_dtype, rhs_dtype, lhs_dtype))
     

  2. 支持Tensor和python Scalar之间的隐式类型转换，当 Tensor 的数据类型和 python Scalar 是同一类的数据类型时（都是整型，或者都是浮点型），或者 Tensor 是浮点型而 python Scalar 是 整型的，默认会将 python Scalar 转换成 Tensor 的数据类型。而如果 Tensor 的数据类型是整型而 python Scalar 是浮点型时，计算结果会是 float32 类型的。

     import paddle
     a = paddle.to_tensor([1.0], dtype='float32')
     b = a + 1  # 由于python scalar默认采用int64, 转换后b的类型为'float32'
     c = a + 1.0  # 虽然 python scalar 是 float64, 但计算结果c的类型为'float32'
     a = paddle.to_tensor([1], dtype='int32')
     b = a + 1.0  # 虽然 python scalar 是 float64, 但计算结果b的类型为 'float32
     c = a + 1  # 虽然 python scalar 是 int64, 但计算结果c的类型为'int32'
     

数据类型规范¶

• 参数数据类型

  对于loss类API，比如cross_entropy, bce_loss等，输入的label需要支持[int32, int64, float32, float64]数据类型。

• 返回值数据类型

  实现需要返回下标indices的API，比如argmax、argmin、argsort、topk、unique等接口时，需要提供dtype参数，用于控制返回值类型是int32或者int64，默认使用dtype=’int64’（与numpy, tf, pytorch保持一致），主要目的是当用户在明确输入数据不超过int32表示范围时，可以手动设置dtype=’int32’来减少显存的占用；对于dtype=’int32’设置，需要对输入数据的下标进行检查，如果超过int32表示范围，通过报错提示用户使用int64数据类型。

类名与方法名的规范¶

• 类名的命名应采用驼峰命名法，通常采用名词形式

  paddle.nn.Conv2D
  paddle.nn.BatchNorm
  paddle.nn.Embedding
  paddle.nn.LogSoftmax
  paddle.nn.SmoothL1Loss
  paddle.nn.LeakyReLU
  paddle.nn.Linear
  paddle.optimizer.lr.LambdaDecay
  

• 由多个单词组成的类名，最后一个单词应表示类型

  # SimpleRNNCell 继承自 RNNCellBase
  paddle.nn.SimpleRNNCell
  # BrightnessTransform 继承 BaseTransform
  paddle.vision.BrightnessTransform
  

• 函数的名称应采用全小写，单词之间采用下划线分割

  # 使用小写
  paddle.nn.functional.conv2d
  paddle.nn.functional.embedding
  # 如果由多个单词构成应使用下划线连接
  paddle.nn.functional.mse_loss
  paddle.nn.functional.batch_norm
  paddle.nn.functional.log_softmax
  

• 但一些约定俗成的例子可以保持不加下划线

  paddle.isfinite
  paddle.isnan
  paddle.isinf
  paddle.argsort
  paddle.cumsum
  

• API命名时，缩写的使用不应引起歧义或误解；在容易引起歧义或误解的情况下，需要使用全称，比如

  # pytorch使用ge,lt之类的缩写，可读性较差，应保留全称，与numpy和paddle保持一致
  paddle.tensor.greater_equal
  paddle.tensor.less_than
  # optimizer 不使用缩写
  paddle.optimizer.SGD
  # parameter 不使用缩写 
  paddle.nn.create_parameter
  

• 在用于API命名时，常见的缩写列表如下：

  conv、max、min、prod、norm、gru、lstm、add、func、op、num、cond
  

• 在用于API命名时，以下建议使用全称，不推荐使用缩写

  | 不规范命名 | 规范命名 | | :-------- | :----------- | | div | divide | | mul | multiply | | sub | subtract | | floor_div | floor_divide | | lr | learning_rate | | act | activation | | eps | epsilon | | val | value | | var | varible | | param | parameter | | prog | program | | idx | index | | exe | executor | | buf | buffer | | trans | transpose | | img | image | | loc | location | | len | length |

• API命名不应包含版本号

  # 不使用版本号
  paddle.nn.multiclass_nms2
  

• 常见的数学计算API中的逐元素操作不需要加上elementwise前缀，按照某一轴操作不需要加上reduce前缀，一些例子如下

  | paddle2.0之前 | pytorch | numpy | tensorflow | paddle2.0之后 | | :------------- | :----- | :------ | :--------- | :--------------- | | elementwise_add | add | add | add | add | | elementwise_sub | sub | subtract | subtract | subract | | elementwise_mul | mul | multiply | multiply | multiply | | elementwise_div | div | divide | divide | divide | | elementwise_min | min | minimum | minimum | minimum | | elementwise_max | max | maximum | maximum | maximum | | reduce_sum | sum | sum | reduce_sum | sum | | reduce_prod | prod | prod | reduce_prod | prod | | reduce_min | min | min | reduce_min | min | | reduce_max | max | max | reduce_max | max | | reduce_all | all | all | reduce_all | all | | reduce_any | any | any | reduce_any | any | | reduce_mean | mean | mean | reduce_mean | mean |

• 整数取模和取余

  目前整除和取余取模运算机器运算符重载在不同的语言和库中对应关系比较复杂混乱（取余运算中余数和被除数同号，取模运算中模和除数同号。取余整除是对商向 0 取整，取模整除是对商向负取整）

| 库         | 取余整除                 | 取余                  | 取模整除         | 取模                                |
| ---------- | :----------------------- | :-------------------- | :--------------- | :---------------------------------- |
| tf         | truncatediv              | truncatemod           | //或floordiv     | %或floormod                         |
| torch      | //或floor_divide         | fmod                  | 无               | %或remainder                        |
| math       | 无                       | math.fmod             | 无               | math.remainder                      |
| python     | 无                       | 无                    | //               | %                                   |
| numpy      | 无                       | 无                    | //或floor_divide | %或mod remainder                    |
| paddle     | //或elementwise_div(int) | %或elemtwise_mod(int) | 无               | %或elemtwise_mod(float)             |
| paddle 2.0 | truncate_divide(int)     | %或truncate_mod(int)  | //或floor_divide | %或floor_mod(float)或mod或remainder |

|          | paddle2.0之前            | torch           | numpy             | tensorflow    | math           | python | paddle2.0之后                       |
| :------: | :----------------------- | :-------------- | :---------------- | :------------ | :------------- | :----- | :---------------------------------- |
| 取余整除 | //或elementwise_div(int) | //或floor_divid | 无                | truncatediv   | -              | 无     | truncate_divide(int)                |
|   取余   | %或elemtwise_mod(int)    | fmod            | 无                | truncatemod   | math.fmod      | 无     | %或truncate_mod(int)                |
| 取模整除 | -                        | -               | floor_divide      | //或floordiv- | -              | //     | //或floor_divide                    |
|   取模   | %或elemtwise_mod(float)  | %或remainder    | %或mod或remainder | %或floormod   | math.remainder | %      | %或floor_mod(float)或mod或remainder |

• 常用组网API命名规范

  # 卷积：
  paddle.nn.Conv2D #采用2D后缀，2D表示维度时通常大写
  paddle.nn.Conv2DTranspose
  paddle.nn.functional.conv2d
  paddle.nn.functional.conv2d_transpose
  # 池化：
  paddle.nn.MaxPool2D
  paddle.nn.AvgPool2D
  paddle.nn.MaxUnpool2D
  paddle.nn.functional.max_pool2d
  paddle.nn.functional.avg_pool2d
  paddle.nn.functional.max_unpool2d
  # 归一化：
  paddle.nn.BatchNorm2D
  paddle.nn.functional.batch_norm
  

参数命名规范¶

• 参数名称全部使用小写

  paddle.nn.functional.mse_loss: def mse_loss(input, label, reduction='mean', name=None):
  

• 参数名可以区分单复数形态，单数表示输入参数是一个或多个变量，复数表示输入明确是含有多个变量的列表

  paddle.nn.Softmax(axis=-1) # axis明确为一个int数
  paddle.squeeze(x, axis=None, dtype=None, keepdim=False, name=None): # axis可以为一数也可以为多个
  paddle.strided_slice(x, axes, starts, ends, strides, name=None) #axis明确是多个数，则参数用复数形式axes
  

• 函数操作只有一个待操作的张量参数时，用x命名；如果有2个待操作的张量参数时，且含义明确时，用x, y命名

  paddle.sum(x, axis=None, dtype=None, keepdim=False, name=None)
  paddle.divide(x, y, name=None)
  

• 原则上所有的输入都用x表示，包括functional下的linear, conv2d, lstm, batch_norm等

• 原则上都要具备name参数，用于标记layer，方便调试和可视化

• loss类的函数，使用input 表示输入，使用label 表示真实预测值/类别，部分情况下，为了更好的便于用户理解，可以选用其他更恰当的参数名称。如softmax_with_logits时，输入参数名可用logits

  paddle.nn.functional.mse_loss(input, label, reduction='mean', name=None)
  paddle.nn.functional.cross_entropy(input,
                                     label,
                                     weight=None,
                                     ignore_index=-100,
                                     reduction='mean',
                                     soft_label=False,
                                     axis=-1,
                                     name=None):
  

• Tensor名称和操作

• 常用参数表