UAPI使用文档
更新时间:2024-03-25
UAPI使用文档
1 简介
UAPI是飞桨模型超高层开发接口,提供统一的开发API,覆盖10+任务和40+模型,支持快速创建、训练、压缩、部署模型,具有一站式、高效率、标准化的开发体验。
UAPI具有如下特性:
- 统一接口:提供简明统一的开发接口,学习成本低,可以快速上手
- 多任务模型:支持10+任务,接入40+模型,真正一站式开发体验
- 全流程能力:整合飞桨核心训压推开发能力,标准化全流程开发方式
- 兼容套件:配置文件、模型等和开发套件兼容,轻松切换使用UAPI
2 核心接口
UAPI中关键类模块:
- Config类与Model类:UAPI遵循『配置-执行』的使用范式,即首先进行参数配置,然后根据配置信息实际执行。对应的两个类是Config与Model:Config类负责更新配置信息,Model类负责执行模型训压推。
- Predictor类:Model类提供了模型推理能力,但是可能无法满足实际场景的需求。Predictor类提供强化版的静态图模型推理能力,功能强大、全程可控、支持自定义前后处理,非常适合多个模型串联推理。
UAPI主要提供接口:
-
uapi.Config
- 接受模型名称和配置文件作为输入参数(配置文件非必须),用于初始化创建Config类对象。
- Config类提供一组方法,用于设置常见参数配置,例如
config.update_dataset
更新数据集路径、config.update_learning_rate
更新基准学习率。
-
uapi.PaddleModel
- 接受一个Config类对象作为输入参数,用于创建Model类对象。
- Model类提供一组方法,每个方法对应一个模型开发阶段。例如:
model.check_dataset
用于执行数据集校验,model.train
用于执行模型训练,model.evaluate
用于执行模型精度验证,model.predict
用于执行动态图模型推理,model.export
用于导出静态图模型,model.infer
用于执行静态图模型的推理。
-
uapi.infer.Predictor
- 接受模型名称和静态图模型路径作为输入参数,也支持设置前后处理操作,用于创建Predictor类对象。
- Predictor类提供run方法对输入数据执行预测,并返回结果。
3 快速上手
UAPI的典型用法如下:
- 使用
uapi.Config
创建Config类对象,需要传入支持的”模型名称“或者“模型名称+配置文件”; - 调用Config接口设置数据集路径等配置项;
- 基于Config,使用
uapi.PaddleModel
创建Model类对象; - 调用Model接口执行模型训练、验证、导出、推理等;
- 调用Predictor接口执行静态图模型的推理。
UAPI的开发接口,既追求统一性,也具备可扩展性,可以兼容特定任务模型的差异。例如,针对特定任务模型,Config类可以提供接口用于设置专有的参数配置,Model类可以在训压推接口中新增输入参数。因此,请参考不同任务模型的API文档,了解具体接口细节,以便顺利完成开发工作。
3.1 模型训练 - 简单示例
from uapi import PaddleModel, Config
from uapi import download_and_extract
# 下载并解压示例数据集
# 请注意,download_and_extract不对下载的数据做安全性检查,因此只应该被用于信任的数据源
download_and_extract(
"https://paddle-model-ecology.bj.bcebos.com/uapi/data/seg_optic_examples.tar",
'data', 'seg_optic_examples')
# 通过模型名称创建Config
config = Config('PP-LiteSeg-Tiny')
# 或者,基于模型名称和的配置文件创建Config,后续以配置文件中的信息为准进行训压推
# config = Config('PP-LiteSeg-Tiny', config_path="path/to/custom-config.yaml")
# 更新类别数
config.update_num_classes(2)
# 更新数据集路径
config.update_dataset("data/seg_optic_examples")
# 通过Config创建Model
model = PaddleModel(config=config)
# 执行模型训练
model.train(
epochs_iters=1000,
save_dir="output")
# 执行模型精度验证
model.evaluate(weight_path="output/best_model/model.pdparams")
3.2 模型训压推 - 详细示例
from uapi import PaddleModel, Config
from uapi import download_and_extract
# 下载并解压示例数据集
# 请注意,download_and_extract不对下载的数据做安全性检查,因此只应该被用于信任的数据源
download_and_extract(
"https://paddle-model-ecology.bj.bcebos.com/uapi/data/seg_optic_examples.tar",
'data', 'seg_optic_examples')
# 通过模型名称创建Config
config = Config('PP-LiteSeg-Tiny')
# 或者,基于模型名称和的配置文件创建Config,后续以配置文件中的信息为准进行训压推
# config = Config('PP-LiteSeg-Tiny', config_path="path/to/custom-config.yaml")
# 调用Config接口更新必要的配置项
# 更新类别数
config.update_num_classes(2)
# 更新数据集路径
config.update_dataset("data/seg_optic_examples")
# 通过Config创建Model
model = PaddleModel(config=config)
# 调用Model接口执行数据集校验
ds_meta = model.check_dataset(
# 指定数据集路径
dataset_dir="data/seg_optic_examples",
# 指定数据集类型,'SegDataset'是PaddleX定义的一种分割数据集规范格式
dataset_type='SegDataset',
# 指定数据集校验模式,'fast'表示快速校验(只检查最关键的部分),'full'表示完整校验
mode='fast')
assert ds_meta['res_flag'], "数据集校验未通过"
# 调用Model接口执行模型训练
model.train(
# 指定mini-batch大小
batch_size=4,
# 指定初始学习率大小
learning_rate=0.001,
# 指定训练总迭代数
epochs_iters=1000,
# 指定使用的设备,'gpu'表示GPU单机单卡
device='gpu',
# 启用动转静训练
dy2st=False,
# 使用O1等级的自动混合精度训练
amp='OFF',
# 指定训练过程中输出文件存储路径
save_dir="output")
# 调用Model接口执行模型精度验证
model.evaluate(
# 指定要加载的模型权重文件路径
weight_path="output/best_model/model.pdparams",
# 指定使用的设备,'gpu:0,1'表示GPU单机2卡(使用编号为0和1的GPU)
device='gpu:0,1',
# 指定用于数据读取的子进程数量
num_workers=2)
# 调用Model接口执行模型的预测
model.predict(
# 指定要加载的模型权重文件路径
weight_path="output/best_model/model.pdparams",
# 指定使用的设备,'cpu'表示使用CPU
device='cpu',
# 指定输入图像路径
input_path="data/seg_optic_examples/JPEGImages/P0088.jpg",
# 指定预测结果存储路径
save_dir="output/pred")
# 调用Model接口导出静态图模型
model.export(
# 指定要加载的模型权重文件路径
weight_path="output/best_model/model.pdparams",
# 指定导出结果存储路径
save_dir="output/export",
# Seg Suite模型特有参数,指定输入张量的形状
input_shape=[1, 3, 512, 512])
# 调用Model接口加载静态图模型进行推理
model.infer(
# 指定静态图模型的存储路径
model_dir="output/export",
# 指定输入图像路径
input_path="data/seg_optic_examples/JPEGImages/P0088.jpg",
# 指定预测结果存储路径
save_dir="output/infer")
3.3 模型推理 - 简单示例
from uapi.infer import Predictor
from uapi.infer import Transform as T
from uapi import download, download_and_extract
# 下载示例图片
download(
"https://paddle-model-ecology.bj.bcebos.com/uapi/data/infer/cityscapes_demo.png",
"data/cityscapes_demo.png")
# 下载并解压静态图模型
# 请注意,download_and_extract不对下载的数据做安全性检查,因此只应该被用于信任的数据源
download_and_extract(
"https://paddle-model-ecology.bj.bcebos.com/uapi/infer_fd/pp_liteseg_stdc1/model.zip",
'data', 'PP-LiteSeg-Tiny')
# 创建模型预处理和后处理操作
pre_transforms = None # 使用默认的预处理操作
post_transforms = [
# 生成伪彩色图像
T.seg.GeneratePCMap(),
# 保存分割结果
T.seg.SaveSegResults(
save_dir="output", save_pc_map=True)
]
# 创建Predictor
predictor = Predictor(
model_name='PP-LiteSeg-Tiny',
model_dir="data/PP-LiteSeg-Tiny",
prd_config={'device': 'gpu'},
pre_transforms=pre_transforms,
post_transforms=post_transforms)
# 设置单张图像输入信息
data = {'image_path': "data/cityscapes_demo.png"}
# 执行单张图像推理
pred = predictor.run(data)
# 设置多张图像输入信息
batch_data = [{'image_path': "data/cityscapes_demo.png"} for _ in range(4)]
# 执行批量推理
batch_pred = predictor.run(data, batch_size=4)
4 支持的任务与模型
任务 | 模型名称 |
---|---|
图像分类 | CLIP_vit_base_patch16_224, MobileNetV3_small_x1_0, PPHGNet_small, PP-HGNetv2-B0, PP-HGNetv2-B4, PP-HGNetv2-B6, PPLCNet_x1_0, ResNet50, SwinTransformer_base_patch4_window7_224 |
识图 | PPLCNetV2_base_ShiTu |
文本检测 | ch_PP-OCRv4_det, ch_PP-OCRv4_det_server |
文本识别 | ch_PP-OCRv4_rec, ch_PP-OCRv4_rec_server |
表格识别 | slanet |
目标检测 | PP-PicoDet_s_320_LCNet, PP-PicoDet_l_640_LCNet, PP-YOLOE+_crn_l_80e, PP-YOLOE+_crn_s_80e, RT-DETR-L, RT-DETR-H,pp_shituv2_det, picodet_layout_1x |
语义分割 | OCRNet_HRNetW48, PP-LiteSeg-Tiny |
多视角3D目标检测 | PETRv1_v99, PETRv2_v99 |
单目图像3D目标检测 | CaDDN_ocrnet_hrnet_w18 |
点云3D目标检测 | CenterPoint_pillars_02voxel |
长时序预测 | PP-TS, TiDE, TimesNet, PatchTST, DLinear, NLinear, RLinear, Nonstationary, XGBoost |
时序分类 | TimesNet_CLS |
时序异常检测 | TimesNet_AD |