diff --git a/docs/zh_CN/community/add_new_algorithm.md b/docs/zh_CN/community/add_new_algorithm.md new file mode 100644 index 0000000000000000000000000000000000000000..746423a658e4614d4139fc2e52c728b79ac4e1b6 --- /dev/null +++ b/docs/zh_CN/community/add_new_algorithm.md @@ -0,0 +1,365 @@ +# 添加新算法 + +PaddleClas 将一个算法分解为以下几个部分，并对各部分进行模块化处理，方便快速组合出新的算法。 +- [1. 添加算法可能改动的模块](#1) + -[1.1 数据加载和处理](#1) + -[1.2. 网络](#2) + -[1.3. 后处理](#3) + -[1.4. 损失函数](#4) + -[1.5. 指标评估](#5) + -[1.6. 优化器](#6) +- [2. 合入PaddleClas套件必须新增的模块](#2) + -[2.1 文档](#2.1) + -[2.2 TIPC](#2.2) + + + + +## 1. 添加算法可能改动的模块 + + + + +### 1.1 数据加载和处理 + +数据加载和处理由不同的模块(module)组成，其完成了图片的读取、数据增强和label的制作。这一部分在[ppcls/data](../../../ppcls/data)下。 各个文件及文件夹作用说明如下: + +```bash +ppcls/data/ +├── dataloader # 数据读取、采样模块 +│   ├── xxx_dataset.py # 数据读取模块 +│   ├── xxx_sampler.py # 数据采样模块 +│   ├── ...... +├── __init__.py +├── postprocess # 模型后处理 +│   ├── threshoutput.py # 对结果的卡阈值后处理 +│   ├── topk.py # Topk后处理 +│   ├── ...... +├── preprocess # 模型前处理，通常指数据预处理 +│   ├── batch_ops # batch 维度图像预处理 +│   │   ├── batch_operators.py +│   │   └── __init__.py +│   ├── __init__.py +│   └── ops # 数据增强模块 +│   ├── operators.py # 常见的数据预处理 +│   ├── randaugment.py # 随机增强预处理 +│   └── ...... +└── utils + └── get_image_list.py # 将文件夹中的图片文件转换为img list +``` + +PaddleClas 内置了大量图像操作相关模块，对于没有内置的模块可通过如下步骤添加: + +1. 如果只涉及单个图像的操作，在 [ppcls/data/preprocess/ops](../../../ppcls/data/preprocess/ops) 文件夹下新建文件，如果设计整个batch的图像操作，需要在 [ppcls/data/preprocess/batch_ops](../../../ppcls/data/preprocess/batch_ops) 文件夹下新建文件，如my_module.py。 +2. 在 my_module.py 文件内添加相关代码，示例代码如下: + +```python +class MyModule: + def __init__(self, *args, **kwargs): + # your init code + pass + + def __call__(self, img): + # your process code + return img +``` + +3. 在 [ppcls/data/preprocess/\_\_init\_\_.py](../../../ppcls/data/preprocess/__init__.py) 文件内导入添加的模块。 + +数据处理的所有处理步骤由不同的模块顺序执行而成，在config文件中按照列表的形式组合并执行。如: + +```yaml +# angle class data process +transforms: + - DecodeImage: # load image + img_mode: BGR + channel_first: False + - MyModule: + args1: args1 + args2: args2 +``` + + + +### 1.2 网络 + +网络部分完成了网络的组网操作，，这一部分在[ppcls/arch/](../../../ppcls/arch/)下。 进入网络的数据将按照顺序(transforms->backbones-> +necks->heads)依次通过这四个部分。其中，非特征模型的neck和head为空。 + +```bash +ppcls/arch/ +├── backbone +│   ├── base # PaddleClas精选模型继承的基类，负责对网络结构的自定义后处理修改 +│   │   └── theseus_layer.py +│   ├── legendary_models # PaddleClas 精选的backbone +│   │   ├── pp_lcnet.py +│   │   ├── resnet.py +│   │   ├── swin_transformer.py +│   │   ├── ... +│   ├── model_zoo # PaddleClas 常见的 backbone +│   │   ├── alexnet.py +│   │   ├── efficientnet.py +│   │   ├── ...... +│   └── variant_models # 模型变种模块 +│   ├── pp_lcnetv2_variant.py +│   └── vgg_variant.py +├── distill # 蒸馏模块 +│   └── afd_attention.py +├── gears # 识别模型的neck、head 模块 +│   ├── arcmargin.py +│   └── ...... +├── slim # 模型压缩模块 +└── utils.py +``` + +PaddleClas内置了大量的常见的backbone、识别模型的neck、head模块，对于没有内置的模块可通过如下步骤添加，所有模块添加步骤相似，以backbone为例: + +1. 在 [ppcls/arch/backbone/model_zoo/](../../../ppcls/arch/backbone/model_zoo/) 文件夹下新建文件，如my_backbone.py。 +2. 在 my_backbone.py 文件内添加相关代码，示例代码如下: + +```python +import paddle +import paddle.nn as nn +import paddle.nn.functional as F + + +class MyBackbone(nn.Layer): + def __init__(self, *args, **kwargs): + super(MyBackbone, self).__init__() + # your init code + self.conv = nn.xxxx + + def forward(self, inputs): + # your network forward + y = self.conv(inputs) + return y +``` + +3. 在 [ppcls/arch/backbone/\_\_init\_\_.py](../../../ppcls/arch/backbone/__init__.py)文件内导入添加的模块。 + +在完成网络的模块添加之后，只需要配置文件中进行配置即可使用，如: + +```yaml +# model architecture +Arch: + name: MyBackbone + class_num: your_class_num +``` + + + +### 1.3 后处理 + +后处理实现对模型结果的输出处理。这一部分在[ppcls/data/postprocess/](../../../ppcls/data/postprocess/)下。 +PaddleClas内置了topk、threshoutput、attr_rec等后处理模块，对于没有内置的组件可通过如下步骤添加: + +1. 在 [ppcls/data/postprocess/](../../../ppcls/data/postprocess/) 文件夹下新建文件，如 my_postprocess.py。 +2. 在 my_postprocess.py 文件内添加相关代码，示例代码如下: + +```python +import paddle + + +class MyPostProcess: + def __init__(self, *args, **kwargs): + # your init code + pass + + def __call__(self, preds, label=None, *args, **kwargs): + if isinstance(preds, paddle.Tensor): + preds = preds.numpy() + # you preds decode code + preds = self.decode_preds(preds) + if label is None: + return preds + # you label decode code + label = self.decode_label(label) + return preds, label + + def decode_preds(self, preds): + # you preds decode code + pass + + def decode_label(self, preds): + # you label decode code + pass +``` + +3. 在 [ppcls/data/postprocess/\_\_init\_\_.py](../../../ppcls/data/postprocess/__init__.py)文件内导入添加的模块。 + +在后处理模块添加之后，只需要配置文件中进行配置即可使用，如: + +```yaml +Infer: + PostProcess: + args1: args1 + args2: args2 + +``` + +**备注：** 该模块只在infer时使用。 + + + +### 1.4 损失函数 + +损失函数用于计算网络输出和label之间的距离。这一部分在[ppcls/loss/](../../../ppcls/loss/)下。 +PaddleClas内置了CE Loss、BCELoss、TripletLoss等十多种损失函数，对于没有内置的模块可通过如下步骤添加: + +1. 在 [ppcls/loss/](../../../ppcls/loss/) 文件夹下新建文件，如 my_loss.py。 +2. 在 my_loss.py 文件内添加相关代码，示例代码如下: + +```python +import paddle +from paddle import nn + + +class MyLoss(nn.Layer): + def __init__(self, **kwargs): + super().__init__() + # you init code + pass + + def loss(self, **kwargs): + your loss code + pass + + def forward(self, x, label): + loss = self.loss(input=predicts, label=label) + return {'your loss name': loss} +``` + +3. 在 [ppcls/loss/\__init\__.py](../../../ppcls/loss/__init__.py)文件内导入添加的模块。 + +在损失函数添加之后，只需要配置文件中进行配置即可使用，如: + +```yaml +Loss: + Train: + - MyLoss: + weight: 1.0 +``` + +**备注：** weight是指该Loss占总Loss的权重，此处支持多个Loss同时计算。 + + + +### 1.5 指标评估 + +指标评估用于计算网络在当前batch上的性能。这一部分在[ppcls/metric/](../../../ppcls/metric/)下。 PaddleClas内置了图像单标签分类、图像多标签分类、图像识别等算法相关的指标评估模块，对于没有内置的模块可通过如下步骤添加: + +1. 在 [ppcls/metric/](../../../ppcls/metric/) 文件夹下新建文件，如my_metric.py。 +2. 在 my_metric.py 文件内添加相关代码，示例代码如下: + +```python + +class MyMetric(nn.Layer): + def __init__(self, **kwargs): + super().__init__() + # you init code + pass + + def forward(self, preds, batch, *args, **kwargs): + metric = self.get_metric(preds, batch, *args, **kwargs) + return {'your metric name': metric} + + def get_metric(self, *args, **kwargs): + # you metric code + pass + +``` + +3. 在 [ppcls/metric/\_\_init\_\_.py](../../../ppcls/metric/__init__.py)文件内导入添加的模块。 + +在指标评估模块添加之后，只需要配置文件中进行配置即可使用，如: + +```yaml +Metric: + Train: + - MyMetric: + args: args + Eval: + - MyMetric: + args: args +``` + + + +### 1.6 优化器 + +优化器用于训练网络。优化器内部还包含了网络正则化和学习率衰减模块。 这一部分在[ppcls/optimizer/](../../ppcls/optimizer/)下。 PaddleClas内置了`Momentum`,`SGD` +,`Adam`和`AdamW`等常用的优化器模块，`Constant`、`Linear`,`Cosine`,`Step`和`Piecewise`等常用的学习率衰减模块。 + +对于没有内置的模块可通过如下步骤添加，以`optimizer`为例: + +1. 在 [ppcls/optimizer//optimizer.py](../../../ppcls/optimizer//optimizer.py) 文件内创建自己的优化器，示例代码如下: + +```python +from paddle import optimizer as optim + + +class MyOptim(object): + def __init__(self, learning_rate=0.001, *args, **kwargs): + super().__init__() + self.learning_rate = learning_rate + # you init code + pass + ： + def __call__(self, parameters): + # It is recommended to wrap the built-in optimizer of paddle + opt = optim.XXX( + learning_rate=self.learning_rate, + parameters=parameters) + return opt + +``` + +在优化器模块添加之后，只需要配置文件中进行配置即可使用，如: + +```yaml +Optimizer: + name: MyOptim + args1: args1 + args2: args2 + lr: + name: Cosine + learning_rate: 0.001 + regularizer: + name: 'L2' + factor: 0.0001 +``` + + + +## 2. 合入PaddleClas套件必须新增的模块 + + + +### 2.1 文档 + +PaddleClas 中的算法都有相对应的文档说明，当给 PaddleClas 提供新的算法时，需要增加相应的文档说明。文档的位置说明如下： + +算法类型|需要修改的文档地址|备注| +| --- | --- | --- | +| 骨干网络 |[文档地址1](../models/ImageNet1k)；[文档地址2](../models/ImageNet1k/README.md)|在文档地址1中新增模型介绍，在文档地址2中新增模型的精度等信息| +| PULC |[文档地址1](../models/PULC)；[文档地址2](../models/PULC/model_list.md)|在文档地址1中新增模型介绍，在文档地址2中新增模型的精度等信息| +| 知识蒸馏相关 |[文档地址](../training/advanced/knowledge_distillation.md)|-| +| 数据增强相关 |[文档地址1](../training/config_description/data_augmentation.md)；[文档地址2](../algorithm_introduction/data_augmentation.md)|-| +| 其他 |[文档地址1](../algorithm_introduction)；[文档地址2](../training)；[文档地址3](../models)|需要判断在文档地址1、文档地址2、文档地址3中添加相关的文档| + +**备注：** 如果在添加文档过程中遇到任何问题，欢迎给我们提[issue](https://github.com/PaddlePaddle/PaddleClas/issues)。 + + + +### 2.2 TIPC + +飞桨除了基本的模型训练和预测，还提供了支持多端多平台的高性能推理部署工具。PaddleClas中所有模型和算法需要通过飞桨训推一体认证 (Training and Inference Pipeline Certification(TIPC)) ，在您提供模型时，模型需要同时通过该认证。 + +TIPC 当前包含很多细的方向的认证，当前只需要通过新增模型只需要通过训练和推理的基础认证即可，详情可以参考：[Linux端基础训练预测功能测试](../../../test_tipc/docs/test_train_inference_python.md)，开发流程简述如下： + +- 1.新增 TIPC config，此处可以参考[DeiT](../../../test_tipc/configs/DeiT)的config配置。 +- 2.走通[Linux 端基础训练预测功能测试模式一](../../../test_tipc/docs/test_train_inference_python.md#22-功能测试)，检查输出没有报错即可。 + +**备注：** +- 当前只需要走通功能测试的模式一即可； +- 如果在添加TIPC过程中遇到任何问题，欢迎给我们提 [issue](https://github.com/PaddlePaddle/PaddleClas/issues)。 \ No newline at end of file diff --git a/docs/zh_CN/community/how_to_contribute.md b/docs/zh_CN/community/how_to_contribute.md index 681a7c7b012eab1978a3134626ccfda333e4bd52..a5b1cb2a09d0f6492a8bc7db674690e30edf256a 100644 --- a/docs/zh_CN/community/how_to_contribute.md +++ b/docs/zh_CN/community/how_to_contribute.md @@ -17,8 +17,9 @@ - [1.2.9 签署 CLA 协议和通过单元测试](#1.2.9) - [1.2.10 删除分支](#1.2.10) - [1.2.11 提交代码的一些约定](#1.2.11) -- [2. 总结](#2) -- [3. 参考文献](#3) +- [2. 如何新增算法](#2) +- [3. 总结](#3) +- [4. 参考文献](#4) ## 1. 如何贡献代码 @@ -28,12 +29,12 @@ PaddleClas 未来将维护 2 种分支，分别为： -* release/x.x 系列分支：为稳定的发行版本分支，会适时打 tag 发布版本，适配 Paddle 的 release 版本。当前最新的分支为 release/2.3 分支，是当前默认分支，适配 Paddle v2.1.0 。随着版本迭代， release/x.x 系列分支会越来越多，默认维护最新版本的 release 分支，前 1 个版本分支会修复 bug，其他的分支不再维护。 +* release/x.x 系列分支：为稳定的发行版本分支，会适时打 tag 发布版本，适配 PaddlePaddle 的 release 版本。当前最新的分支为 release/2.5 分支，是当前默认分支，适配 PaddlePaddle >= 2.2 。随着版本迭代， release/x.x 系列分支会越来越多，默认维护最新版本的 release 分支，前 1 个版本分支会修复 bug，其他的分支不再维护。 * develop 分支：为开发分支，适配 Paddle 的 develop 版本，主要用于开发新功能。如果有同学需要进行二次开发，请选择 develop 分支。为了保证 develop 分支能在需要的时候拉出 release/x.x 分支， develop 分支的代码只能使用 Paddle 最新 release 分支中有效的 api 。也就是说，如果 Paddle develop 分支中开发了新的 api，但尚未出现在 release 分支代码中，那么请不要在 PaddleClas 中使用。除此之外，对于不涉及 api 的性能优化、参数调整、策略更新等，都可以正常进行开发。 PaddleClas 的历史分支，未来将不再维护。考虑到一些同学可能仍在使用，这些分支还会继续保留： -* release/static 分支：这个分支曾用于静态图的开发与测试，目前兼容 >=1.7 版本的 Paddle 。如果有特殊需求，要适配旧版本的 Paddle，那还可以使用这个分支，但除了修复 bug 外不再更新代码。 +* release/static 分支：这个分支曾用于静态图的开发与测试，目前兼容 >=1.7 版本的 PaddlePaddle 。如果有特殊需求，要适配旧版本的 PaddlePaddle，那还可以使用这个分支，但除了修复 bug 外不再更新代码。 * dygraph-dev 分支：这个分支将不再维护，也不再接受新的代码，请使用的同学尽快迁移到 develop 分支。 @@ -242,11 +243,16 @@ git branch -D new_branch - 请采用 `start a review` 进行回复，而非直接回复的方式。原因是每个回复都会发送一封邮件，会造成邮件灾难。 -## 2. 总结 +## 2. 如何新增算法 -* 开源社区依赖于众多开发者与用户的贡献和反馈，在这里感谢与期待大家向 PaddleClas 提出宝贵的意见与 Pull Request，希望我们可以一起打造一个领先实用全面的图像识别代码仓库！ +PaddleClas的发展离不开广大开发者的贡献，为了快速帮助开发者开发新的算法，我们总结了在PaddleClas中新增算法的一些需要的操作，请参考[如何新增算法](add_new_algorithm.md)。 -## 3. 参考文献 +## 3. 总结 + +* 开源社区依赖于众多开发者与用户的贡献和反馈，在这里感谢与期待大家向 PaddleClas 提出宝贵的意见与 Pull Request，希望我们可以一起打造一个领先实用全面的图像识别代码仓库！ + + +## 4. 参考文献 1. [PaddlePaddle 本地开发指南](https://www.paddlepaddle.org.cn/documentation/docs/zh/develop/guides/08_contribution/index_cn.html) 2. [向开源框架提交 pr 的过程](https://blog.csdn.net/vim_wj/article/details/78300239)