From dcf40fa52f3cee95789dfdc8da6c5209c636ad66 Mon Sep 17 00:00:00 2001 From: Bobholamovic Date: Sat, 13 Aug 2022 01:57:26 +0800 Subject: [PATCH] Update training API doc --- docs/apis/train.md | 262 +++++++++++++++++++++--------- paddlers/tasks/object_detector.py | 2 +- 2 files changed, 187 insertions(+), 77 deletions(-) diff --git a/docs/apis/train.md b/docs/apis/train.md index 5a320a6..0bf2df5 100644 --- a/docs/apis/train.md +++ b/docs/apis/train.md @@ -1,6 +1,6 @@ # PaddleRS训练API说明 -训练器封装了模型训练、验证、量化以及动态图推理等逻辑，定义在`paddlers/tasks/`目录下的文件中。为了方便用户使用，PaddleRS为所有支持的模型均提供了继承自父类[`BaseModel`](https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/tasks/base.py)的训练器，并对外提供数个API。变化检测、场景分类、图像分割以及目标检测任务对应的训练器类型分别为`BaseChangeDetector`、`BaseClassifier`、`BaseDetector`和`BaseSegmenter`。本文档介绍训练器的初始化函数以及`train()`、`evaluate()` API。 +**训练器**封装了模型训练、验证、量化以及动态图推理等逻辑，定义在`paddlers/tasks/`目录下的文件中。为了方便用户使用，PaddleRS为所有支持的模型均提供了继承自父类[`BaseModel`](https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/tasks/base.py)的训练器，并对外提供数个API。变化检测、场景分类、图像分割以及目标检测任务对应的训练器类型分别为`BaseChangeDetector`、`BaseClassifier`、`BaseDetector`和`BaseSegmenter`。本文档介绍训练器的初始化函数以及`train()`、`evaluate()` API。 ## 初始化训练器 @@ -8,43 +8,48 @@ ### 初始化`BaseChangeDetector`子类对象 -一般支持设置`num_classes`、`use_mixed_loss`以及`in_channels`参数，分别表示模型输出类别数、是否使用预置的混合损失以及输入通道数。部分子类如`DSIFN`暂不支持对`in_channels`参数的设置。`use_mixed_loss`参将在未来被弃用，因此不建议使用。不同的子类支持与模型相关的输入参数，详情请参考[模型定义](https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/rs_models/cd)和[训练器定义](https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/tasks/change_detector.py)。 +- 一般支持设置`num_classes`、`use_mixed_loss`以及`in_channels`参数，分别表示模型输出类别数、是否使用预置的混合损失以及输入通道数。部分子类如`DSIFN`暂不支持对`in_channels`参数的设置。 +- `use_mixed_loss`参将在未来被弃用，因此不建议使用。 +- 不同的子类支持与模型相关的输入参数，详情请参考[模型定义](https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/rs_models/cd)和[训练器定义](https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/tasks/change_detector.py)。 ### 初始化`BaseClassifier`子类对象 -一般支持设置`num_classes`和`use_mixed_loss`参数，分别表示模型输出类别数以及是否使用预置的混合损失。`use_mixed_loss`参将在未来被弃用，因此不建议使用。不同的子类支持与模型相关的输入参数，详情请参考[模型定义](https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/rs_models/clas)和[训练器定义](https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/tasks/classifier.py)。 +- 一般支持设置`num_classes`和`use_mixed_loss`参数，分别表示模型输出类别数以及是否使用预置的混合损失。 +- `use_mixed_loss`参将在未来被弃用，因此不建议使用。 +- 不同的子类支持与模型相关的输入参数，详情请参考[模型定义](https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/rs_models/clas)和[训练器定义](https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/tasks/classifier.py)。 ### 初始化`Baseetector`子类对象 -一般支持设置`num_classes`和`backbone`参数，分别表示模型输出类别数以及所用的骨干网络类型。相比其它任务，目标检测任务的训练器支持设置的初始化参数较多，囊括网络结构、损失函数、后处理策略等方面。不同的子类支持与模型相关的输入参数，详情请参考[模型定义](https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/rs_models/det)和[训练器定义](https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/tasks/object_detector.py)。 +- 一般支持设置`num_classes`和`backbone`参数，分别表示模型输出类别数以及所用的骨干网络类型。相比其它任务，目标检测任务的训练器支持设置的初始化参数较多，囊括网络结构、损失函数、后处理策略等方面。 +- 不同的子类支持与模型相关的输入参数，详情请参考[模型定义](https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/rs_models/det)和[训练器定义](https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/tasks/object_detector.py)。 ### 初始化`BaseSegmenter`子类对象 -一般支持设置`input_channel`、`num_classes`以及`use_mixed_loss`参数，分别表示输入通道数、输出类别数以及是否使用预置的混合损失。部分模型如`FarSeg`暂不支持对`input_channel`参数的设置。`use_mixed_loss`参将在未来被弃用，因此不建议使用。不同的子类支持与模型相关的输入参数，详情请参考[模型定义](https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/rs_models/seg)和[训练器定义](https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/tasks/segmentor.py)。 +- 一般支持设置`input_channel`、`num_classes`以及`use_mixed_loss`参数，分别表示输入通道数、输出类别数以及是否使用预置的混合损失。部分模型如`FarSeg`暂不支持对`input_channel`参数的设置。 +- `use_mixed_loss`参将在未来被弃用，因此不建议使用。 +- 不同的子类支持与模型相关的输入参数，详情请参考[模型定义](https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/rs_models/seg)和[训练器定义](https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/tasks/segmentor.py)。 ## `train()` ### `BaseChangeDetector.train()` -方法定义如下： - ```python def train(self, - num_epochs, - train_dataset, - train_batch_size=2, - eval_dataset=None, - optimizer=None, - save_interval_epochs=1, - log_interval_steps=2, - save_dir='output', - pretrain_weights=None, - learning_rate=0.01, - lr_decay_power=0.9, - early_stop=False, - early_stop_patience=5, - use_vdl=True, - resume_checkpoint=None): + num_epochs, + train_dataset, + train_batch_size=2, + eval_dataset=None, + optimizer=None, + save_interval_epochs=1, + log_interval_steps=2, + save_dir='output', + pretrain_weights=None, + learning_rate=0.01, + lr_decay_power=0.9, + early_stop=False, + early_stop_patience=5, + use_vdl=True, + resume_checkpoint=None): ``` 其中各参数的含义如下： @@ -69,25 +74,23 @@ def train(self, ### `BaseClassifier.train()` -方法定义如下： - ```python def train(self, - num_epochs, - train_dataset, - train_batch_size=2, - eval_dataset=None, - optimizer=None, - save_interval_epochs=1, - log_interval_steps=2, - save_dir='output', - pretrain_weights='IMAGENET', - learning_rate=0.1, - lr_decay_power=0.9, - early_stop=False, - early_stop_patience=5, - use_vdl=True, - resume_checkpoint=None): + num_epochs, + train_dataset, + train_batch_size=2, + eval_dataset=None, + optimizer=None, + save_interval_epochs=1, + log_interval_steps=2, + save_dir='output', + pretrain_weights='IMAGENET', + learning_rate=0.1, + lr_decay_power=0.9, + early_stop=False, + early_stop_patience=5, + use_vdl=True, + resume_checkpoint=None): ``` 其中各参数的含义如下： @@ -112,30 +115,28 @@ def train(self, ### `BaseDetector.train()` -方法定义如下： - ```python def train(self, - num_epochs, - train_dataset, - train_batch_size=64, - eval_dataset=None, - optimizer=None, - save_interval_epochs=1, - log_interval_steps=10, - save_dir='output', - pretrain_weights='IMAGENET', - learning_rate=.001, - warmup_steps=0, - warmup_start_lr=0.0, - lr_decay_epochs=(216, 243), - lr_decay_gamma=0.1, - metric=None, - use_ema=False, - early_stop=False, - early_stop_patience=5, - use_vdl=True, - resume_checkpoint=None): + num_epochs, + train_dataset, + train_batch_size=64, + eval_dataset=None, + optimizer=None, + save_interval_epochs=1, + log_interval_steps=10, + save_dir='output', + pretrain_weights='IMAGENET', + learning_rate=.001, + warmup_steps=0, + warmup_start_lr=0.0, + lr_decay_epochs=(216, 243), + lr_decay_gamma=0.1, + metric=None, + use_ema=False, + early_stop=False, + early_stop_patience=5, + use_vdl=True, + resume_checkpoint=None): ``` 其中各参数的含义如下： @@ -167,21 +168,21 @@ def train(self, ```python def train(self, - num_epochs, - train_dataset, - train_batch_size=2, - eval_dataset=None, - optimizer=None, - save_interval_epochs=1, - log_interval_steps=2, - save_dir='output', - pretrain_weights='CITYSCAPES', - learning_rate=0.01, - lr_decay_power=0.9, - early_stop=False, - early_stop_patience=5, - use_vdl=True, - resume_checkpoint=None): + num_epochs, + train_dataset, + train_batch_size=2, + eval_dataset=None, + optimizer=None, + save_interval_epochs=1, + log_interval_steps=2, + save_dir='output', + pretrain_weights='CITYSCAPES', + learning_rate=0.01, + lr_decay_power=0.9, + early_stop=False, + early_stop_patience=5, + use_vdl=True, + resume_checkpoint=None): ``` 其中各参数的含义如下： @@ -208,8 +209,117 @@ def train(self, ### `BaseChangeDetector.evaluate()` +```python +def evaluate(self, eval_dataset, batch_size=1, return_details=False): +``` + +输入参数如下： + +|参数名称|类型|参数说明|默认值| +|-------|----|--------|-----| +|`eval_dataset`|`paddlers.datasets.CDDataset`|评估数据集。|| +|`batch_size`|`int`|评估时使用的batch size（多卡训练时，为所有设备合计batch size）。|`1`| +|`return_details`|`bool`|是否返回详细信息。|`False`| + +当`return_details`为`False`（默认行为）时，输出为一个`collections.OrderedDict`对象。对于二类变化检测任务，输出包含如下键值对： + +``` +{"iou": 变化类的IoU指标， +"f1": 变化类的F1分数， +"oacc": 总体精度（准确率）， +"kappa": kappa系数} +``` + +对于多类变化检测任务，输出包含如下键值对： + +``` +{"miou": mIoU指标， +"category_iou": 各类的IoU指标， +"oacc": 总体精度（准确率）， +"category_acc": 各类精确率， +"kappa": kappa系数， +"category_F1score": 各类F1分数} +``` + +当`return_details`为`True`时，返回一个由两个字典构成的二元组，其中第一个元素为上述评价指标，第二个元素为仅包含一个key的字典，其`'confusion_matrix'`键对应值为以Python built-in list存储的混淆矩阵。 + ### `BaseClassifier.evaluate()` +```python +def evaluate(self, eval_dataset, batch_size=1, return_details=False): +``` + +输入参数如下： + +|参数名称|类型|参数说明|默认值| +|-------|----|--------|-----| +|`eval_dataset`|`paddlers.datasets.ClasDataset`|评估数据集。|| +|`batch_size`|`int`|评估时使用的batch size（多卡训练时，为所有设备合计batch size）。|`1`| +|`return_details`|`bool`|*当前版本请勿手动设置此参数。*|`False`| + +输出为一个`collections.OrderedDict`对象，包含如下键值对： + +``` +{"top1": top1准确率， +"top5": `top5准确率} +``` + ### `BaseDetector.evaluate()` +```python +def evaluate(self, + eval_dataset, + batch_size=1, + metric=None, + return_details=False): +``` + +输入参数如下： + +|参数名称|类型|参数说明|默认值| +|-------|----|--------|-----| +|`eval_dataset`|`paddlers.datasets.COCODetDataset` \| `paddlers.datasets.VOCDetDataset`|评估数据集。|| +|`batch_size`|`int`|评估时使用的batch size（多卡训练时，为所有设备合计batch size）。|`1`| +|`metric`|`str` \| `None`|评价指标，可以为`'VOC'`、`COCO`或`None`。若为`Nnoe`，则根据数据集格式自动确定使用的评价指标。|`None`| +|`return_details`|`bool`|是否返回详细信息。|`False`| + +当`return_details`为`False`（默认行为）时，输出为一个`collections.OrderedDict`对象，包含如下键值对： + +``` +{"bbox_mmap": 预测结果的mAP值} +``` + +当`return_details`为`True`时，返回一个由两个字典构成的二元组，其中第一个字典为上述评价指标，第二个字典包含如下3个键值对： + +``` +{"gt": 数据集标注信息， +"bbox": 预测得到的目标框信息， +"mask": 预测得到的掩模图信息} +``` + ### `BaseSegmenter.evaluate()` + +```python +def evaluate(self, eval_dataset, batch_size=1, return_details=False): +``` + +输入参数如下： + +|参数名称|类型|参数说明|默认值| +|-------|----|--------|-----| +|`eval_dataset`|`paddlers.datasets.SegDataset`|评估数据集。|| +|`batch_size`|`int`|评估时使用的batch size（多卡训练时，为所有设备合计batch size）。|`1`| +|`return_details`|`bool`|是否返回详细信息。|`False`| + +当`return_details`为`False`（默认行为）时，输出为一个`collections.OrderedDict`对象，包含如下键值对： + +``` +{"miou": mIoU指标， +"category_iou": 各类的IoU指标， +"oacc": 总体精度（准确率）， +"category_acc": 各类精确率， +"kappa": kappa系数， +"category_F1score": 各类F1分数} +``` + +当`return_details`为`True`时，返回一个由两个字典构成的二元组，其中第一个元素为上述评价指标，第二个元素为仅包含一个key的字典，其`'confusion_matrix'`键对应值为以Python built-in list存储的混淆矩阵。 diff --git a/paddlers/tasks/object_detector.py b/paddlers/tasks/object_detector.py index 125efed..dd43e31 100644 --- a/paddlers/tasks/object_detector.py +++ b/paddlers/tasks/object_detector.py @@ -460,7 +460,7 @@ class BaseDetector(BaseModel): Returns: collections.OrderedDict with key-value pairs: - {"mAP(0.50, 11point)":`mean average precision`}. + {"bbox_mmap":`mean average precision (0.50, 11point)`}. """ if metric is None: