目标检测算法套件使用指导

本Notebook通过引导用户导入数据集、选择模型、训练并可视化推理，快速完成COCO数据集目标检测任务。

Step0 安装依赖包

!pip install ipywidgets==7.7.1
!pip install pillow==9.1.1
!pip install pandas==1.3.4

Step1 加载算法、样例数据集与预训练模型完成模型的微调和探索

经典的目标检测方法主要包括单阶段（YOLO、RetinaNet等）和多阶段算法（Faster RCNN、Cascade RCNN等），本案例以fcos算法模型为例，fcos算法属于anchor free的一阶段目标检测算法，具有训练速度快、超参数少等特点。本小节以"mmdetection:fcos/fcos_r50_caffe_fpn_gn-head_1x_coco"模型为例，演示如何下载预训练模型。

1. 选择预训练模型

#@title Install pretrained model  
from ma_cau.apis import EnvManager
env = EnvManager()
env.init_env()          # initialize environment


algo_name = "mmdetection" #@param {type:"string", dropdown}
model_name = "mmdetection:fcos/fcos_r50_caffe_fpn_gn-head_1x_coco" #@param {type:"string", dropdown}
dataset_name = "coco2017_sample" #@param {type:"string"}

# 安装算法套件，首次安装时可能需要restart kernel用以使用更新后的依赖包
env.install(mode="algorithm", asset_name=algo_name, version="2.17.0")

首次安装完套件需要restart kernel，重启后重新执行第一个cell，然后就可以直接执行下面一个cell，不需要再执行安装算法套件步骤

def restart_kernel():
    import os
    status = input("Restart Kernel【只需要在第一次安装算法套件时才需要重启kernel，重启后重新执行第一个cell】[y/n(default)]: ") or "n"
    if status.lower() == "y":
        os._exit(00)

restart_kernel()    

# 安装样例数据集，数据集会下载到./{project_dir}/data/raw/
env.install(mode="dataset", asset_name=dataset_name)  # 从AI Gallery下载 coco2017_sample 数据集
# 安装预训练模型，模型会下载到./{project_dir}/model_zoo/
env.install(mode="model", asset_name=model_name)  # 从openmmlab网站下载预训练模型

2. 构建数据集DataBlock对象

DataBlock支持自动统计数据集信息，比如目标、尺寸等信息，帮助用户更好的理解数据集，同时还可以动态查看每一个batch经过pipeline之后的输入图像，确保数据增强的正确性。

detblock.plot_dataset_stats() 可以绘制数据集的统计信息，图像的显示大小可以由figsize参数控制；
detblock.print_dataset_stats() 能够打印出具体的统计信息数值；
datablock.show_batch() 可以动态展示内存中的经过增强后的图片信息，可以通过rows（显示行数）和figsize（显示大小）来控制输出。

DetDataBlock主要接收如下入参：

env: EnvManager对象batch_size: 批处理大小
data_type: 数据集类型，目前只支持“coco”，其他数据集格式可以通过CocoConverter进行转换
data_root: 数据集路径
seed：随机数种子，和数据集batch加载顺序相关
num_classes：类别数
categories：类别信息列表，默认为None表示使用所有类别，否则只加载对应类别
train_img_prefix：训练集图片路径，相对于data_root
train_ann_file：训练集标注文件路径，相对于data_root
val_img_prefix：验证集集图片路径，相对于data_root，可缺省
val_ann_file：验证集标注文件路径，相对于data_root，可缺省
test_img_prefix：测试集图片路径，相对于data_root，可缺省
test_ann_file：测试集标注文件路径，相对于data_root，可缺省
model_name：模型名称

#@title Build DataBlock 
from ma_cau.apis import DetDataBlock

num_classes = 80 #@param {type:"integer"}
data_root = "./data/raw/coco2017_sample" #@param {type:"string"}
train_img_prefix = "val2017" #@param {type:"string"}
train_ann_file = "annotations/instances_val2017.json" #@param {type:"string"}
val_img_prefix = "val2017" #@param {type:"string"}
val_ann_file = "annotations/instances_val2017.json" #@param {type:"string"}
batch_size = 4 #@param {type:"slider", min:1, max:10, step:1}


db = DetDataBlock(env,
                  batch_size=batch_size,
                  data_root=data_root, 
                  seed=0,
                  num_classes=num_classes,
                  train_img_prefix=train_img_prefix, 
                  train_ann_file=train_ann_file,
                  val_img_prefix=val_img_prefix, 
                  val_ann_file=val_ann_file,
                  model_name=model_name
                 )

2.1 可视化数据集

plotter = db.show_batch(rows=2, figsize=(14, 8))

next(plotter)

2.2 绘制数据集分布图

db.plot_dataset_stats(figsize=(14, 8))

2.3 打印数据集分布结果

db.print_dataset_stats()

3. 构建模型Model对象

Model主要接收如下入参：

env: EnvManager对象
model_name：模型名称
num_classes：类别数
checkpoint：预训练模型文件路径，默认为None（随机初始化网络权重）
load_default_backbone: 是否加载预训练backbone，默认为False。当指定checkpoint参数后，该参数可设置为False

请手动选择一个路径，加载预训练模型，如"model_zoo/mmdetection/2.17.0/fcos/fcos_r50_caffe_fpn_gn-head_1x_coco-821213aa.pth"

import os
from ipyfilechooser import FileChooser
from ipywidgets import Layout

fc = FileChooser(path=os.getcwd(), layout=Layout(width="1000px"))
display(fc)

# Build Model
from ma_cau.apis import Model

ckpt_path = os.path.join(fc.selected_path, fc.selected_filename)
fcos_model = Model(env, model_name=model_name, num_classes=num_classes, checkpoint=ckpt_path)

4. 构建学习器Learner对象

Learner主要接收如下入参

model: model对象
datablock: datablock对象
work_dir: 训练输出路径
optimizer: 训练优化器，默认为SGD
momentum: 动量
pretrained_model: 预训练模型路径，当构建Model时指定该参数后，此参数可忽略
warmup_policy: warm up策略，如cosine
warmup_iters: warm up 步数， 默认为500
epoch_based_eval_interval: 每完成n个epoch训练后进行一次模型评估，用于检测等任务
iter_based_eval_interval: 每完成n个iteration训练后进行一次模型评估，用于分割等任务
save_ckpt_interval: 保存模型的间隔
no_validate: 训练中不进行评估操作，默认为False
log_params: 字典类型参数，训练日志类型，默认以表格形式输出训练和评估日志，具体参数如下
    log_type: 输出日志类型，默认为table
    table_highlight_method: 当log_type为table时，对训练结果的高亮方法，默认为best，即高亮最好的训练结果
    log_interval: 训练输出间隔，每完成n个训练迭代输出日志
launcher: 分布式作业启动类型，当前暂不支持

#@title Build Learner 
from ma_cau.apis import Learner

output_path = 'output'
log_interval = 11 #@param {type:"slider", min:1, max:100, step:10}
epoch_based_eval_interval = 1 #@param {type:"slider", min:1, max:10, step:1}
log_params = {
                'log_type': ['graph', 'table'], 
                'table_highlight_method':'best', 
                'log_interval':log_interval
             }
learner = Learner(fcos_model, db, output_path, log_params=log_params, epoch_based_eval_interval=epoch_based_eval_interval)

INFO:ma_cau:your work dir is automaticlly transformed to output/mmdetection/fcos/fcos_r50_caffe_fpn_gn-head_1x_coco.

learner.fit：

model: model对象
datablock: datablock对象
work_dir: 训练输出路径
optimizer: 训练优化器，默认为SGD
momentum: 动量
pretrained_model: 预训练模型路径，当构建Model时指定该参数后，此参数可忽略
warmup_policy: warm up策略，如cosine
warmup_iters: warm up 步数， 默认为500
epoch_based_eval_interval: 每完成n个epoch训练后进行一次模型评估，用于检测等任务
iter_based_eval_interval: 每完成n个iteration训练后进行一次模型评估，用于分割等任务
save_ckpt_interval: 保存模型的间隔
no_validate: 训练中不进行评估操作，默认为False
log_params: 字典类型参数，训练日志类型，默认以表格形式输出训练和评估日志，具体参数如下
    log_type: 输出日志类型，默认为table
    table_highlight_method: 当log_type为table时，对训练结果的高亮方法，默认为best，即高亮最好的训练结果
    log_interval: 训练输出间隔，每完成n个训练迭代输出日志
launcher: 分布式作业启动类型，当前暂不支持

本步骤主要演示训练过程的loss值可视化功能，1 epoch 训练耗时约12分钟，训练1分钟后即可提前手动停止

#@title Fit parameters

weight_decay = 0.0005 #@param {type:"number"}
max_epochs = 1 #@param {type:"slider", min:0, max:20, step:1}
lr = 0.001 #@param {type:"slider", min:0.001, max:0.1, step:0.001}

learner.fit(lr=lr, max_epochs=max_epochs, weight_decay=weight_decay, gpu_ids=[0])

Step3 模型评估

1. 评估验证集

learner.validate： 用于模型评估，具体参数如下

data: 指定评估的数据集，只接受datablock类型的对象, 默认为None, 如果使用默认值则会使用已经定义好并传入Model中的datablock中的验证数据集进行评估
gpu_collect: 是否使用GPU进行评估，默认为True
checkpoint: 评估时使用的模型权重路径, 默认为None。当传入有效路径时，该处优先级最高。没有传入参数时，会按完成训练后的模型权重高于Model中指定的checpoint的优先级加载模型权重。如果均未指定checpoint且没有进行训练，则默认使用随机初始化的权重进行评估

# learner.validate() # 这步耗时较长，可跳过

2. 图片推理

learner.predict： 用于模型推理，具体参数如下

img_path: 指定需要推理的图片路径
model: 指定用于推理的模型，默认为None, 不填写该参数则默认使用Learner中的Model进行推理
checkpoint: 推理时使用的模型权重路径, 默认为None。当传入有效路径时，该处优先级最高。没有传入参数时，会按完成训练后的模型权重高于Model中指定的checpoint的优先级加载模型权重。如果均未指定checpoint且没有进行训练，则默认使用随机初始化的权重进行推理
device: 推理时的设备类型，默认为'cpu'，即使用cpu进行推理
score_thr: 模型logits判别阈值，默认为0.3
save_dir: 推理后的文件保存路径，默认为None

手动选择一张图片进行推理，比如"./data/raw/coco2017_sample/val2017/000000000139.jpg"

img_fc = FileChooser(path=os.getcwd(), layout=Layout(width="1000px"))
display(img_fc)

# 模型推理
result = learner.predict(os.path.join(img_fc.selected_path, img_fc.selected_filename))

Step4 交互式推理

本算法套件支持动态交互式推理方式，您可以通过鼠标勾选需要推理的图片、视频，并且可以选择不同的iou和score参数进行动态比较。

测试图片路径：default_ma_cau_project/data/raw/coco2017_sample/val2017/

测试视频路径：default_ma_cau_project/algorithms/mmdetection/algorithm/demo/demo.mp4

VisDetPlatform主要接收如下几个参数：

    learner: Learner对象，主要用于在线实时推理；
    stage：推理图片所属的数据集类别，"train"、"val"、"test"；
    ann_json: 标注文件路径，主要用于离线展示
    det_file: 验证输出的检测结果文件路径，主要用于离线展示
    det_box_color：实际检测框颜色 
    gt_box_color：GT检测框颜色
    without_gt：是否只查看数据集标注
    classes：关注的类别列表
    mask_palette：mask蒙版颜色列表，如果不设置，则使用随机颜色
    infer_param: 推理相关参数，如不指定则使用配置文件默认参数，与推理速度相关，主要包含
        1. nms_pre：nms操作前生成的bbox数量
        2. max_per_img：每张图片最大目标数
        3. img_scale：图像resize尺寸

from ma_cau.apis import VisDetPlatform

infer_param = {"nms_pre": 200, "max_per_img": 20, "img_scale": (800, 600)}
VisDetPlatform(learner, infer_param=infer_param, stage="val", det_box_color=(0, 0, 255))

如果您不清楚交互式推理的用法，请查看下方视频